@sentropic/design-system-svelte 0.10.3 → 0.10.5

package/dist/ForceGraph.svelte

@@ -3,6 +3,18 @@
     | "category1" | "category2" | "category3" | "category4"
     | "category5" | "category6" | "category7" | "category8";
 
+  export type ForceGraphNodeShape =
+    | "dot" | "circle"
+    | "diamond"
+    | "star"
+    | "hexagon"
+    | "box" | "square"
+    | "roundedbox"
+    | "triangle";
+
+  /** Stroke dash style for typed edges. */
+  export type ForceGraphEdgeDash = "solid" | "dashed" | "dotted" | "long-dash";
+
   export type ForceGraphNode = {
     /** Stable identifier; referenced by edges. */
     id: string;
@@ -20,6 +32,11 @@
     /** Pin the node to a fixed position (ignored by the simulation). */
     fx?: number;
     fy?: number;
+    /**
+     * Visual shape for the node. Defaults to 'dot' (circle).
+     * Supported: 'dot'|'circle', 'diamond', 'star', 'hexagon', 'box'|'square', 'triangle'.
+     */
+    shape?: ForceGraphNodeShape;
   };
 
   export type ForceGraphEdge = {
@@ -32,9 +49,138 @@
     /**
      * When true the link renders as a dashed/faded "weak" link. Lets callers
      * map a confidence dimension onto link strength without extra props.
+     * Equivalent to `dash: "dashed"` plus a faded stroke (kept for back-compat).
+     */
+    weak?: boolean;
+    /**
+     * Typed dash pattern for the stroke. Independent of `weak`.
+     * "solid" = none, "dashed" = "6 4", "dotted" = "1 4", "long-dash" = "12 6".
+     * When omitted, falls back to the `weak` styling.
+     */
+    dash?: ForceGraphEdgeDash;
+    /**
+     * Emphasise the edge (e.g. a reconciliation/match relation) with a thicker,
+     * fully-opaque stroke. Defaults to false.
      */
+    emphasis?: boolean;
+    /** Explicit stroke width override in px. Takes precedence over `emphasis`. */
+    width?: number;
+  };
+
+  export type ForceGraphLegendEntry = {
+    /** Label shown in the legend. */
+    label: string;
+    /** Shape for this entry (node legend). Absent = line-style legend entry. */
+    shape?: ForceGraphNodeShape;
+    /** Tone for this entry. Defaults to category1. */
+    tone?: ForceGraphTone;
+    /** When true, renders as a dashed line (edge legend). */
     weak?: boolean;
+    /**
+     * Typed dash pattern for an edge legend swatch. Independent of `weak`.
+     * When set, the swatch line uses the matching dash-array.
+     */
+    dash?: ForceGraphEdgeDash;
   };
+
+  /**
+   * Maps a dash style (or the legacy `weak` flag) to an SVG stroke-dasharray.
+   * Returns null for a solid stroke.
+   */
+  export function edgeDashArray(
+    dash: ForceGraphEdgeDash | undefined,
+    weak?: boolean
+  ): string | null {
+    const effective: ForceGraphEdgeDash | undefined =
+      dash ?? (weak ? "dashed" : undefined);
+    switch (effective) {
+      case "dashed": return "6 4";
+      case "dotted": return "1 4";
+      case "long-dash": return "12 6";
+      case "solid":
+      default: return null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // SVG path helpers for the various node shapes.
+  // All shapes are centered at (0,0). Each shape is scaled so its filled area
+  // matches that of the reference circle (π·r²) — this keeps equal-weight nodes
+  // visually balanced rather than letting squares/diamonds read as "bigger".
+  //
+  // Per-shape scale factors (closed-form, area = π·r²):
+  //   square / roundedbox : half-side  = (√π)/2 · r        ≈ 0.8862·r
+  //   diamond             : half-diag   = √(π/2) · r        ≈ 1.2533·r
+  //   triangle (equilat.) : circumradius= √(π/(3√3/4)) · r  ≈ 1.5551·r
+  //   hexagon (regular)   : circumradius= √(π/(3√3/2)) · r  ≈ 1.0996·r
+  //   star (5-pt, k=0.42) : outer radius= √(π/A₁) · r       ≈ 1.5953·r
+  //                          where A₁ is the unit-star area (≈1.2343).
+  // ---------------------------------------------------------------------------
+  const STAR_INNER_RATIO = 0.42;
+  const STAR_AREA_FACTOR = 1.5953498885642274; // √(π / unit-star-area)
+
+  // Format a coordinate: 4 dp, snapping floating-point near-zero (e.g. 9e-16)
+  // to a clean 0 so paths never contain scientific notation.
+  function fmt(n: number): string {
+    const v = Math.abs(n) < 1e-9 ? 0 : n;
+    return Number(v.toFixed(4)).toString();
+  }
+
+  export function nodeShapePath(shape: ForceGraphNodeShape | undefined, r: number): string | null {
+    const s = shape ?? "dot";
+    if (s === "dot" || s === "circle") return null; // use <circle>
+    if (s === "diamond") {
+      const d = Math.sqrt(Math.PI / 2) * r; // half-diagonal
+      return `M 0 ${fmt(-d)} L ${fmt(d)} 0 L 0 ${fmt(d)} L ${fmt(-d)} 0 Z`;
+    }
+    if (s === "star") {
+      const outer = STAR_AREA_FACTOR * r;
+      const inner = outer * STAR_INNER_RATIO;
+      const pts: string[] = [];
+      for (let i = 0; i < 10; i++) {
+        const angle = (i * Math.PI) / 5 - Math.PI / 2;
+        const rad = i % 2 === 0 ? outer : inner;
+        pts.push(`${fmt(rad * Math.cos(angle))},${fmt(rad * Math.sin(angle))}`);
+      }
+      return `M ${pts.join(" L ")} Z`;
+    }
+    if (s === "hexagon") {
+      const R = Math.sqrt(Math.PI / ((3 * Math.sqrt(3)) / 2)) * r; // circumradius
+      const pts: string[] = [];
+      for (let i = 0; i < 6; i++) {
+        const angle = (i * Math.PI) / 3 - Math.PI / 6;
+        pts.push(`${fmt(R * Math.cos(angle))},${fmt(R * Math.sin(angle))}`);
+      }
+      return `M ${pts.join(" L ")} Z`;
+    }
+    if (s === "box" || s === "square") {
+      const h = (Math.sqrt(Math.PI) / 2) * r; // half-side, area = (2h)² = π·r²
+      return `M ${fmt(-h)} ${fmt(-h)} L ${fmt(h)} ${fmt(-h)} L ${fmt(h)} ${fmt(h)} L ${fmt(-h)} ${fmt(h)} Z`;
+    }
+    if (s === "roundedbox") {
+      const h = (Math.sqrt(Math.PI) / 2) * r; // same footprint as square
+      const rx = h * 0.6; // ≈ r·0.3 rounding radius (h ≈ 0.886·r)
+      // Rounded rectangle via arcs, clockwise from top edge.
+      return (
+        `M ${fmt(-h + rx)} ${fmt(-h)} ` +
+        `L ${fmt(h - rx)} ${fmt(-h)} A ${fmt(rx)} ${fmt(rx)} 0 0 1 ${fmt(h)} ${fmt(-h + rx)} ` +
+        `L ${fmt(h)} ${fmt(h - rx)} A ${fmt(rx)} ${fmt(rx)} 0 0 1 ${fmt(h - rx)} ${fmt(h)} ` +
+        `L ${fmt(-h + rx)} ${fmt(h)} A ${fmt(rx)} ${fmt(rx)} 0 0 1 ${fmt(-h)} ${fmt(h - rx)} ` +
+        `L ${fmt(-h)} ${fmt(-h + rx)} A ${fmt(rx)} ${fmt(rx)} 0 0 1 ${fmt(-h + rx)} ${fmt(-h)} Z`
+      );
+    }
+    if (s === "triangle") {
+      // Equilateral, centred at centroid; circumradius h so apex is up.
+      const h = Math.sqrt(Math.PI / ((3 * Math.sqrt(3)) / 4)) * r;
+      const pts: string[] = [];
+      for (let i = 0; i < 3; i++) {
+        const angle = (i * 2 * Math.PI) / 3 - Math.PI / 2;
+        pts.push(`${fmt(h * Math.cos(angle))},${fmt(h * Math.sin(angle))}`);
+      }
+      return `M ${pts.join(" L ")} Z`;
+    }
+    return null;
+  }
 </script>
 
 <script lang="ts">
@@ -75,6 +221,22 @@
      * Fires with the node's stable id.
      */
     onOpenEntity?: (id: string) => void;
+    /**
+     * Called when the user hovers an edge.
+     * Fires with the edge object (source/target/relation/weak).
+     */
+    onEdgeHover?: (edge: ForceGraphEdge) => void;
+    /**
+     * Legend entries rendered as a corner overlay.
+     * Each entry has a label + optional shape (node) or weak (edge).
+     */
+    legend?: ForceGraphLegendEntry[];
+    /**
+     * Edge curvature, 0..1. 0 = straight <line> (back-compat). Larger values
+     * bow each edge into a quadratic <path>, offset perpendicular to the chord
+     * by `edgeCurve * dist * factor`. Defaults to a light 0.15.
+     */
+    edgeCurve?: number;
     class?: string;
   };
 
@@ -91,6 +253,9 @@
     focusId = null,
     onSelect,
     onOpenEntity,
+    onEdgeHover,
+    legend,
+    edgeCurve = 0.15,
     class: className
   }: ForceGraphProps = $props();
 
@@ -229,9 +394,14 @@
         }
         node.x += node.vx;
         node.y += node.vy;
-        // Keep inside a padded viewport.
-        node.x = Math.max(nodeRadius * 2, Math.min(w - nodeRadius * 2, node.x));
-        node.y = Math.max(nodeRadius * 2, Math.min(h - nodeRadius * 2, node.y));
+        // Soft clamp: allow the layout to overflow the canvas so it keeps a
+        // natural shape (fit-to-content reframes it afterwards). The wide bound
+        // only guards against runaway coordinates, it no longer glues nodes to
+        // the four edges.
+        const padX = w * 0.5 + nodeRadius * 2;
+        const padY = h * 0.5 + nodeRadius * 2;
+        node.x = Math.max(-padX, Math.min(w + padX, node.x));
+        node.y = Math.max(-padY, Math.min(h + padY, node.y));
       }
       temperature *= cooling;
     }
@@ -262,35 +432,158 @@
   const positionedNodes = $derived.by(() =>
     nodes.map((n, i) => {
       const p = layout.get(n.id) ?? { x: width / 2, y: height / 2 };
+      const r = nodeRadius * Math.sqrt(Math.max(n.weight ?? 1, 0.25));
+      const shapePath = nodeShapePath(n.shape, r);
       return {
         node: n,
         i,
         x: p.x,
         y: p.y,
-        r: nodeRadius * Math.sqrt(Math.max(n.weight ?? 1, 0.25)),
+        r,
         tone: toneMap.get(n.id) ?? "category1",
-        title: n.label ?? n.id
+        title: n.label ?? n.id,
+        shapePath
       };
     })
   );
 
+  // Curvature offset factor: how far (relative to chord length) the control
+  // point bows out at edgeCurve=1. Kept modest so edgeCurve≈0.15 reads "light".
+  const CURVE_FACTOR = 0.5;
+
+  // ---------------------------------------------------------------------------
+  // Fit-to-content (Feature 5): after warmup the layout may extend beyond the
+  // nominal width/height. Compute the real content bounding-box (node centres
+  // ± radius) and frame it with an 8% margin on each side. The base viewBox is
+  // this frame (not the fixed 0,0,w,h), so the graph is centred and never
+  // clipped, whatever the aspect ratio. Zoom/pan stay relative to this frame.
+  // ---------------------------------------------------------------------------
+  const CONTENT_MARGIN = 0.08;
+  const contentBox = $derived.by(() => {
+    if (positionedNodes.length === 0) {
+      return { x: 0, y: 0, w: width, h: height };
+    }
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const p of positionedNodes) {
+      // Use the worst-case extent for non-circular shapes (area-scaled) so the
+      // glyph (and a little label room) is never clipped.
+      const ext = p.r * 1.7;
+      minX = Math.min(minX, p.x - ext);
+      minY = Math.min(minY, p.y - ext);
+      maxX = Math.max(maxX, p.x + ext);
+      maxY = Math.max(maxY, p.y + ext);
+    }
+    let w = maxX - minX;
+    let h = maxY - minY;
+    // Guard against a degenerate (single node / collinear) box.
+    if (!(w > 0)) { w = width; minX = maxX - w / 2; }
+    if (!(h > 0)) { h = height; minY = maxY - h / 2; }
+    const mx = w * CONTENT_MARGIN;
+    const my = h * CONTENT_MARGIN;
+    return { x: minX - mx, y: minY - my, w: w + 2 * mx, h: h + 2 * my };
+  });
+
   const positionedEdges = $derived.by(() => {
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const curve = Math.max(0, edgeCurve ?? 0);
     return edges
       .map((e, i) => {
         const a = layout.get(e.source);
         const b = layout.get(e.target);
         if (!a || !b) return null;
-        return { edge: e, i, x1: a.x, y1: a.y, x2: b.x, y2: b.y };
+        const srcNode = nodeById.get(e.source);
+        const tgtNode = nodeById.get(e.target);
+        const x1 = a.x, y1 = a.y, x2 = b.x, y2 = b.y;
+        // Quadratic control point: midpoint pushed perpendicular to the chord.
+        let path: string | null = null;
+        let cx = (x1 + x2) / 2;
+        let cy = (y1 + y2) / 2;
+        if (curve > 0) {
+          const dx = x2 - x1;
+          const dy = y2 - y1;
+          const dist = Math.sqrt(dx * dx + dy * dy) || 0.0001;
+          const off = curve * dist * CURVE_FACTOR;
+          // Unit perpendicular to the chord.
+          const px = -dy / dist;
+          const py = dx / dist;
+          cx = (x1 + x2) / 2 + px * off;
+          cy = (y1 + y2) / 2 + py * off;
+          path = `M ${x1} ${y1} Q ${cx} ${cy} ${x2} ${y2}`;
+        }
+        const dashArray = edgeDashArray(e.dash, e.weak);
+        const strokeWidth =
+          typeof e.width === "number" ? e.width : e.emphasis ? 2.5 : null;
+        return {
+          edge: e,
+          i,
+          x1, y1, x2, y2,
+          // Tooltip / label anchor follows the curve apex when curved.
+          midX: cx,
+          midY: cy,
+          path,
+          dashArray,
+          strokeWidth,
+          srcLabel: srcNode?.label ?? e.source,
+          tgtLabel: tgtNode?.label ?? e.target
+        };
       })
       .filter((e): e is NonNullable<typeof e> => e !== null);
   });
 
-  let hoveredIndex: number | null = $state(null);
+  let hoveredNodeIndex: number | null = $state(null);
+  let hoveredEdgeIndex: number | null = $state(null);
 
   // Fast lookup sets — recomputed only when selectedIds/focusId props change,
   // never when nodes/edges change.
   const selectedSet = $derived(new Set<string>(selectedIds));
 
+  // Adjacency: id -> set of directly connected node ids. Used to keep the
+  // direct neighbours of selected/focused nodes fully visible (demand 6).
+  const adjacency = $derived.by(() => {
+    const adj = new Map<string, Set<string>>();
+    const add = (a: string, b: string) => {
+      let set = adj.get(a);
+      if (!set) { set = new Set(); adj.set(a, set); }
+      set.add(b);
+    };
+    for (const e of edges) {
+      add(e.source, e.target);
+      add(e.target, e.source);
+    }
+    return adj;
+  });
+
+  // True when a selection/focus is active — only then do we dim non-related
+  // nodes. The set of "active" ids = selected ∪ focus ∪ all their neighbours.
+  const hasActiveSelection = $derived(selectedSet.size > 0 || focusId != null);
+  const activeAndNeighbours = $derived.by(() => {
+    const active = new Set<string>(selectedSet);
+    if (focusId != null) active.add(focusId);
+    // Expand to direct neighbours so they stay fully visible.
+    const withNeighbours = new Set<string>(active);
+    for (const id of active) {
+      const nb = adjacency.get(id);
+      if (nb) for (const n of nb) withNeighbours.add(n);
+    }
+    return withNeighbours;
+  });
+
+  // A node is dimmed by selection when there IS an active selection and the
+  // node is neither selected/focused nor a direct neighbour of one.
+  function isSelectionDimmed(id: string): boolean {
+    if (!hasActiveSelection) return false;
+    return !activeAndNeighbours.has(id);
+  }
+
+  // An edge stays fully visible when at least one endpoint is in the
+  // selected/focused set (it is a connection of the selection).
+  function isEdgeSelectionDimmed(e: ForceGraphEdge): boolean {
+    if (!hasActiveSelection) return false;
+    const srcActive = selectedSet.has(e.source) || focusId === e.source;
+    const tgtActive = selectedSet.has(e.target) || focusId === e.target;
+    return !(srcActive || tgtActive);
+  }
+
   // Keyboard handler for a node circle: Space/Enter → onSelect, Enter → onOpenEntity.
   function handleNodeKeydown(id: string, e: KeyboardEvent) {
     if (e.key === "Enter" || e.key === " ") {
@@ -302,32 +595,168 @@
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Zoom + pan state (Feature 2), framed by the fit-to-content box (Feature 5).
+  // The base frame is `contentBox` (not 0,0,w,h). Zoom is a scale multiplier and
+  // pan is an offset in SVG coords, both relative to that base frame:
+  //   vbW = baseW / zoomScale,  vbH = baseH / zoomScale
+  //   vbX = baseX + panX,       vbY = baseY + panY
+  // ---------------------------------------------------------------------------
+  let zoomScale = $state(1);
+  let panX = $state(0);
+  let panY = $state(0);
+
+  let isPanning = $state(false);
+  let panStart = $state({ x: 0, y: 0, panX: 0, panY: 0 });
+  let svgEl: SVGSVGElement | null = $state(null);
+
+  // Base frame dimensions = fit-to-content box.
+  const baseW = $derived(contentBox.w);
+  const baseH = $derived(contentBox.h);
+  const baseX = $derived(contentBox.x);
+  const baseY = $derived(contentBox.y);
+
+  // Derived viewBox dimensions reflect the content frame + zoom/pan.
+  const vbW = $derived(baseW / zoomScale);
+  const vbH = $derived(baseH / zoomScale);
+  const vbX = $derived(baseX + panX);
+  const vbY = $derived(baseY + panY);
+
+  function resetView() {
+    zoomScale = 1;
+    panX = 0;
+    panY = 0;
+  }
+
+  function handleWheel(ev: WheelEvent) {
+    if (prefersReducedMotion) return;
+    ev.preventDefault();
+    // Zoom factor: ~10% per step.
+    const factor = ev.deltaY > 0 ? 0.9 : 1.1;
+    // Clamp zoom: 0.2x – 8x.
+    const newScale = Math.min(Math.max(zoomScale * factor, 0.2), 8);
+    // Anchor zoom around the cursor position in SVG coords.
+    if (svgEl) {
+      const rect = svgEl.getBoundingClientRect();
+      const curW = baseW / zoomScale;
+      const curH = baseH / zoomScale;
+      const cursorSvgX = vbX + ((ev.clientX - rect.left) / rect.width) * curW;
+      const cursorSvgY = vbY + ((ev.clientY - rect.top) / rect.height) * curH;
+      const newVbW = baseW / newScale;
+      const newVbH = baseH / newScale;
+      const ratioX = (cursorSvgX - vbX) / curW;
+      const ratioY = (cursorSvgY - vbY) / curH;
+      // New top-left so the cursor anchor stays put, then back out the pan term.
+      panX = cursorSvgX - ratioX * newVbW - baseX;
+      panY = cursorSvgY - ratioY * newVbH - baseY;
+    }
+    zoomScale = newScale;
+  }
+
+  function handleBgMouseDown(ev: MouseEvent) {
+    // Only start pan when clicking the background (not a node/edge element).
+    if ((ev.target as Element).closest(".st-forceGraph__node")) return;
+    if (prefersReducedMotion) return;
+    isPanning = true;
+    panStart = { x: ev.clientX, y: ev.clientY, panX, panY };
+  }
+
+  function handleMouseMove(ev: MouseEvent) {
+    if (!isPanning || !svgEl) return;
+    const rect = svgEl.getBoundingClientRect();
+    const dx = ((ev.clientX - panStart.x) / rect.width) * vbW;
+    const dy = ((ev.clientY - panStart.y) / rect.height) * vbH;
+    panX = panStart.panX - dx;
+    panY = panStart.panY - dy;
+  }
+
+  function handleMouseUp() {
+    isPanning = false;
+  }
+
+  const viewBox = $derived(`${vbX} ${vbY} ${vbW} ${vbH}`);
+  const isZoomed = $derived(zoomScale !== 1 || panX !== 0 || panY !== 0);
+
   const classes = () =>
     ["st-forceGraph", prefersReducedMotion ? "st-forceGraph--static" : null, className]
       .filter(Boolean)
       .join(" ");
 </script>
 
-<div class={classes()} role="img" aria-label={label}>
+<div
+  class={classes()}
+  role="img"
+  aria-label={label}
+>
   <svg
-    viewBox="0 0 {width} {height}"
+    bind:this={svgEl}
+    viewBox={viewBox}
     preserveAspectRatio="xMidYMid meet"
     width="100%"
     height="100%"
     focusable="false"
     aria-hidden="true"
+    class:st-forceGraph__svg--panning={isPanning}
+    onwheel={handleWheel}
+    onmousedown={handleBgMouseDown}
+    onmousemove={handleMouseMove}
+    onmouseup={handleMouseUp}
+    onmouseleave={handleMouseUp}
   >
     <!-- edges first so nodes paint on top -->
     <g class="st-forceGraph__edges">
       {#each positionedEdges as e (e.i)}
-        <line
-          class="st-forceGraph__edge"
-          class:st-forceGraph__edge--weak={e.edge.weak}
-          x1={e.x1}
-          y1={e.y1}
-          x2={e.x2}
-          y2={e.y2}
-        />
+        <!-- Invisible wider hit area for edge hover (follows the curve) -->
+        {#if e.path}
+          <path
+            class="st-forceGraph__edgeHit"
+            role="presentation"
+            d={e.path}
+            fill="none"
+            onmouseenter={() => { hoveredEdgeIndex = e.i; onEdgeHover?.(e.edge); }}
+            onmouseleave={() => { hoveredEdgeIndex = null; }}
+          />
+        {:else}
+          <line
+            class="st-forceGraph__edgeHit"
+            role="presentation"
+            x1={e.x1}
+            y1={e.y1}
+            x2={e.x2}
+            y2={e.y2}
+            onmouseenter={() => { hoveredEdgeIndex = e.i; onEdgeHover?.(e.edge); }}
+            onmouseleave={() => { hoveredEdgeIndex = null; }}
+          />
+        {/if}
+        {#if e.path}
+          <path
+            class="st-forceGraph__edge"
+            class:st-forceGraph__edge--weak={e.edge.weak}
+            class:st-forceGraph__edge--emphasis={e.edge.emphasis}
+            class:st-forceGraph__edge--hovered={hoveredEdgeIndex === e.i}
+            class:st-forceGraph__edge--dim={isEdgeSelectionDimmed(e.edge)}
+            d={e.path}
+            fill="none"
+            stroke-dasharray={e.dashArray}
+            stroke-width={e.strokeWidth}
+            pointer-events="none"
+          />
+        {:else}
+          <line
+            class="st-forceGraph__edge"
+            class:st-forceGraph__edge--weak={e.edge.weak}
+            class:st-forceGraph__edge--emphasis={e.edge.emphasis}
+            class:st-forceGraph__edge--hovered={hoveredEdgeIndex === e.i}
+            class:st-forceGraph__edge--dim={isEdgeSelectionDimmed(e.edge)}
+            x1={e.x1}
+            y1={e.y1}
+            x2={e.x2}
+            y2={e.y2}
+            stroke-dasharray={e.dashArray}
+            stroke-width={e.strokeWidth}
+            pointer-events="none"
+          />
+        {/if}
       {/each}
     </g>
 
@@ -335,26 +764,44 @@
       {#each positionedNodes as p (p.node.id)}
         <g
           class="st-forceGraph__node st-forceGraph__node--{p.tone}"
-          class:st-forceGraph__node--dim={hoveredIndex !== null && hoveredIndex !== p.i}
+          class:st-forceGraph__node--dim={(hoveredNodeIndex !== null && hoveredNodeIndex !== p.i) || isSelectionDimmed(p.node.id)}
           class:st-forceGraph__node--selected={selectedSet.has(p.node.id)}
           class:st-forceGraph__node--focus={focusId === p.node.id}
           transform="translate({p.x} {p.y})"
         >
-          <circle
-            class="st-forceGraph__dot"
-            r={p.r}
-            tabindex="0"
-            role="button"
-            aria-label="{p.title}{p.node.group !== undefined ? ` — ${p.node.group}` : ''}"
-            aria-pressed={selectedSet.has(p.node.id)}
-            onmouseenter={() => (hoveredIndex = p.i)}
-            onmouseleave={() => (hoveredIndex = null)}
-            onfocus={() => (hoveredIndex = p.i)}
-            onblur={() => (hoveredIndex = null)}
-            onclick={() => onSelect?.(p.node.id)}
-            ondblclick={() => onOpenEntity?.(p.node.id)}
-            onkeydown={(e) => handleNodeKeydown(p.node.id, e)}
-          />
+          {#if p.shapePath}
+            <path
+              class="st-forceGraph__dot"
+              d={p.shapePath}
+              tabindex="0"
+              role="button"
+              aria-label="{p.title}{p.node.group !== undefined ? `: ${p.node.group}` : ''}"
+              aria-pressed={selectedSet.has(p.node.id)}
+              onmouseenter={() => (hoveredNodeIndex = p.i)}
+              onmouseleave={() => (hoveredNodeIndex = null)}
+              onfocus={() => (hoveredNodeIndex = p.i)}
+              onblur={() => (hoveredNodeIndex = null)}
+              onclick={() => onSelect?.(p.node.id)}
+              ondblclick={() => onOpenEntity?.(p.node.id)}
+              onkeydown={(e) => handleNodeKeydown(p.node.id, e)}
+            />
+          {:else}
+            <circle
+              class="st-forceGraph__dot"
+              r={p.r}
+              tabindex="0"
+              role="button"
+              aria-label="{p.title}{p.node.group !== undefined ? `: ${p.node.group}` : ''}"
+              aria-pressed={selectedSet.has(p.node.id)}
+              onmouseenter={() => (hoveredNodeIndex = p.i)}
+              onmouseleave={() => (hoveredNodeIndex = null)}
+              onfocus={() => (hoveredNodeIndex = p.i)}
+              onblur={() => (hoveredNodeIndex = null)}
+              onclick={() => onSelect?.(p.node.id)}
+              ondblclick={() => onOpenEntity?.(p.node.id)}
+              onkeydown={(e) => handleNodeKeydown(p.node.id, e)}
+            />
+          {/if}
           {#if showLabels}
             <text class="st-forceGraph__label" x={p.r + 3} y="0" dominant-baseline="middle">{p.title}</text>
           {/if}
@@ -363,15 +810,16 @@
     </g>
   </svg>
 
-  {#if hoveredIndex !== null && positionedNodes[hoveredIndex]}
-    {@const p = positionedNodes[hoveredIndex]}
+  <!-- Node tooltip -->
+  {#if hoveredNodeIndex !== null && positionedNodes[hoveredNodeIndex]}
+    {@const p = positionedNodes[hoveredNodeIndex]}
     {@const relCount = positionedEdges.filter(
       (e) => e.edge.source === p.node.id || e.edge.target === p.node.id
     ).length}
     <div
       class="st-forceGraph__tooltip"
       role="presentation"
-      style="left: {(p.x / width) * 100}%; top: {(p.y / height) * 100}%"
+      style="left: {((p.x - vbX) / vbW) * 100}%; top: {((p.y - vbY) / vbH) * 100}%"
     >
       <span class="st-forceGraph__tooltipLabel">{p.title}</span>
       {#if p.node.group !== undefined}
@@ -382,6 +830,91 @@
       {/if}
     </div>
   {/if}
+
+  <!-- Edge tooltip -->
+  {#if hoveredEdgeIndex !== null}
+    {@const e = positionedEdges.find((pe) => pe.i === hoveredEdgeIndex)}
+    {#if e}
+      <div
+        class="st-forceGraph__tooltip st-forceGraph__tooltip--edge"
+        role="presentation"
+        style="left: {((e.midX - vbX) / vbW) * 100}%; top: {((e.midY - vbY) / vbH) * 100}%"
+      >
+        <span class="st-forceGraph__tooltipLabel">{e.srcLabel}</span>
+        {#if e.edge.relation}
+          <span class="st-forceGraph__tooltipRelation">{e.edge.relation}</span>
+        {/if}
+        <span class="st-forceGraph__tooltipLabel">{e.tgtLabel}</span>
+      </div>
+    {/if}
+  {/if}
+
+  <!-- Reset view button (only shown when zoomed/panned) -->
+  {#if isZoomed}
+    <button
+      class="st-forceGraph__resetBtn"
+      type="button"
+      aria-label="Reset view"
+      onclick={resetView}
+    >
+      ↺
+    </button>
+  {/if}
+
+  <!-- Legend overlay -->
+  {#if legend && legend.length > 0}
+    <div class="st-forceGraph__legend" aria-label="Graph legend">
+      {#each legend as entry}
+        {@const swatchPath = entry.shape !== undefined ? nodeShapePath(entry.shape, 7) : null}
+        {@const swatchTone = entry.tone ?? "category1"}
+        {@const swatchDash = entry.shape === undefined ? edgeDashArray(entry.dash, entry.weak) : null}
+        <div class="st-forceGraph__legendEntry">
+          {#if entry.shape !== undefined}
+            <!-- Node shape legend entry (viewBox widened for area-scaled glyphs) -->
+            <svg
+              class="st-forceGraph__legendSwatch"
+              viewBox="-13 -13 26 26"
+              width="16"
+              height="16"
+              aria-hidden="true"
+            >
+              {#if swatchPath}
+                <path
+                  d={swatchPath}
+                  class="st-forceGraph__legendShape st-forceGraph__legendShape--{swatchTone}"
+                />
+              {:else}
+                <circle
+                  r="7"
+                  class="st-forceGraph__legendShape st-forceGraph__legendShape--{swatchTone}"
+                />
+              {/if}
+            </svg>
+          {:else}
+            <!-- Edge style legend entry -->
+            <svg
+              class="st-forceGraph__legendSwatch"
+              viewBox="0 0 16 8"
+              width="16"
+              height="8"
+              aria-hidden="true"
+            >
+              <line
+                x1="0"
+                y1="4"
+                x2="16"
+                y2="4"
+                class="st-forceGraph__legendEdge"
+                class:st-forceGraph__legendEdge--weak={entry.weak}
+                stroke-dasharray={swatchDash}
+              />
+            </svg>
+          {/if}
+          <span class="st-forceGraph__legendLabel">{entry.label}</span>
+        </div>
+      {/each}
+    </div>
+  {/if}
 </div>
 
 <style>
@@ -395,18 +928,46 @@
 
   .st-forceGraph svg { display: block; overflow: visible; }
 
+  .st-forceGraph__svg--panning { cursor: grabbing; }
+
   .st-forceGraph__edge {
     stroke: var(--st-semantic-border-strong);
     stroke-width: 1;
     opacity: 0.55;
+    transition: opacity 120ms ease, stroke-width 120ms ease;
   }
 
   .st-forceGraph__edge--weak {
     stroke: var(--st-semantic-border-subtle);
-    stroke-dasharray: 3 3;
     opacity: 0.5;
   }
 
+  /* Emphasised edge (e.g. reconciliation match): thicker, fully opaque, on top. */
+  .st-forceGraph__edge--emphasis {
+    stroke: var(--st-semantic-border-interactive, var(--st-semantic-border-strong));
+    opacity: 0.95;
+  }
+
+  /* Hover: match the node hover (fully visible) so the edge is never paler
+     than the two nodes it connects. */
+  .st-forceGraph__edge--hovered {
+    opacity: 1;
+    stroke-width: 2;
+  }
+
+  /* Dimmed by an active selection (edge touches no selected/focused node). */
+  .st-forceGraph__edge--dim {
+    opacity: 0.12;
+  }
+
+  /* Invisible wide hit target for edge hover */
+  .st-forceGraph__edgeHit {
+    stroke: transparent;
+    stroke-width: 10;
+    fill: none;
+    cursor: crosshair;
+  }
+
   .st-forceGraph__node { transition: opacity 120ms ease; }
   .st-forceGraph__node--dim { opacity: 0.3; }
 
@@ -475,9 +1036,102 @@
 
   .st-forceGraph__tooltipLabel { font-weight: 600; }
   .st-forceGraph__tooltipMeta { opacity: 0.85; }
+  .st-forceGraph__tooltipRelation {
+    opacity: 0.75;
+    font-style: italic;
+    font-size: 0.6875rem;
+  }
+
+  /* Reset view button */
+  .st-forceGraph__resetBtn {
+    background: var(--st-semantic-surface-overlay, rgba(0,0,0,0.55));
+    border: none;
+    border-radius: var(--st-radius-sm, 0.25rem);
+    color: var(--st-semantic-text-inverse, #fff);
+    cursor: pointer;
+    font-size: 1rem;
+    line-height: 1;
+    padding: 0.25rem 0.5rem;
+    position: absolute;
+    bottom: 0.5rem;
+    right: 0.5rem;
+    opacity: 0.8;
+    transition: opacity 120ms ease;
+    z-index: 2;
+  }
+
+  .st-forceGraph__resetBtn:hover,
+  .st-forceGraph__resetBtn:focus-visible {
+    opacity: 1;
+  }
+
+  .st-forceGraph__resetBtn:focus-visible {
+    outline: 2px solid var(--st-semantic-border-interactive);
+    outline-offset: 2px;
+  }
+
+  /* Legend overlay */
+  .st-forceGraph__legend {
+    background: var(--st-semantic-surface-overlay, rgba(0,0,0,0.45));
+    border-radius: var(--st-radius-sm, 0.25rem);
+    color: var(--st-semantic-text-inverse, #fff);
+    display: flex;
+    flex-direction: column;
+    font-size: 0.6875rem;
+    gap: 0.25rem;
+    padding: 0.375rem 0.5rem;
+    pointer-events: none;
+    position: absolute;
+    bottom: 0.5rem;
+    left: 0.5rem;
+    z-index: 2;
+  }
+
+  .st-forceGraph__legendEntry {
+    align-items: center;
+    display: flex;
+    gap: 0.375rem;
+  }
+
+  .st-forceGraph__legendSwatch {
+    flex-shrink: 0;
+  }
+
+  .st-forceGraph__legendLabel {
+    white-space: nowrap;
+  }
+
+  .st-forceGraph__legendShape {
+    fill-opacity: 0.9;
+    stroke: var(--st-semantic-surface-default, #fff);
+    stroke-width: 1;
+  }
+
+  .st-forceGraph__legendShape--category1 { fill: var(--st-semantic-data-category1); }
+  .st-forceGraph__legendShape--category2 { fill: var(--st-semantic-data-category2); }
+  .st-forceGraph__legendShape--category3 { fill: var(--st-semantic-data-category3); }
+  .st-forceGraph__legendShape--category4 { fill: var(--st-semantic-data-category4); }
+  .st-forceGraph__legendShape--category5 { fill: var(--st-semantic-data-category5); }
+  .st-forceGraph__legendShape--category6 { fill: var(--st-semantic-data-category6); }
+  .st-forceGraph__legendShape--category7 { fill: var(--st-semantic-data-category7); }
+  .st-forceGraph__legendShape--category8 { fill: var(--st-semantic-data-category8); }
+
+  .st-forceGraph__legendEdge {
+    stroke: var(--st-semantic-border-strong, #888);
+    stroke-width: 1.5;
+    opacity: 0.8;
+  }
+
+  .st-forceGraph__legendEdge--weak {
+    stroke: var(--st-semantic-border-subtle, #aaa);
+    stroke-dasharray: 3 3;
+    opacity: 0.65;
+  }
 
   @media (prefers-reduced-motion: reduce) {
     .st-forceGraph__node,
-    .st-forceGraph__dot { transition: none; }
+    .st-forceGraph__dot,
+    .st-forceGraph__edge,
+    .st-forceGraph__resetBtn { transition: none; }
   }
 </style>