@stephen-netu/design-system 0.1.0

package/src/n2-manifold-disk/ManifoldDisk.svelte

@@ -0,0 +1,314 @@
+<script lang="ts">
+  // N2 ManifoldDisk — Poincaré disk projection wrapping n1-flow-canvas
+  // κ = 1.0 fixed (standard Poincaré disk — no prop, YAGNI)
+  // Shares GraphState with FlowCanvas for instantaneous mode toggle
+  //
+  // When `agents` is provided, the disk renders live S³ agent orientations
+  // (quaternion → Poincaré disk via axis-angle) as glowing points with
+  // trailing history. Task topology is drawn behind the agents.
+
+  import { untrack } from 'svelte';
+  import { Canvas, Layer } from 'svelte-canvas';
+  import { getArrow } from 'perfect-arrows';
+  import type { GraphSnapshot } from '../n1-flow-canvas/types.js';
+  import { GraphState } from '../n1-flow-canvas/graph-state.svelte.js';
+  import { EDGE_REVEAL_STAGGER_MS } from '../n1-flow-canvas/types.js';
+  import { projectToDisk, quaternionToDisk } from './poincare.js';
+
+  // ── Props ────────────────────────────────────────────────────────────────────
+
+  /** Raw inhabitant wire type — mirrors InhabitantView from ryu/src/stores/manifoldStore. */
+  interface InhabitantView {
+    id: string;
+    orientation: [number, number, number, number]; // [w, i, j, k]
+    allay: number;
+  }
+
+  interface Props {
+    snapshot: GraphSnapshot;
+    state: GraphState;            // must be the same instance passed to FlowCanvas
+    width?: number;
+    height?: number;
+    selectedId?: string | null;  // Visual highlight — does NOT trigger Möbius transform
+    /** Raw S³ inhabitant orientations from the manifold store. Projected here at render time. */
+    inhabitants?: InhabitantView[];
+  }
+
+  // Destructure as `graphStateProp` to avoid conflict with the `$state` rune.
+  let { snapshot, state: graphStateProp, width = 800, height = 600, selectedId = null, inhabitants = [] }: Props = $props();
+
+  // ── Agent trail history ───────────────────────────────────────────────────────
+  // Ring buffer of recent disk-projected positions per agent (last TRAIL_LEN frames).
+  // Projection happens here — disk radius is known at render time.
+  const TRAIL_LEN = 12;
+
+  // Map<agentId, Array<{u, v}>> — normalized disk coords (×diskRadius at render).
+  let agentTrails = $state<Map<string, Array<{ u: number; v: number }>>>(new Map());
+
+  $effect(() => {
+    // Track `inhabitants` as the sole reactive dependency.
+    // `agentTrails` is read via untrack so writing it back does NOT re-trigger
+    // this effect — avoids the read→write→re-run infinite loop.
+    const snap = inhabitants;
+    agentTrails = untrack(() => {
+      const next = new Map(agentTrails);
+      for (const inh of snap) {
+        const [w, i, j, k] = inh.orientation;
+        const { u, v } = quaternionToDisk(w, i, j, k, 1.0);
+        const trail = next.get(inh.id) ?? [];
+        trail.push({ u, v });
+        if (trail.length > TRAIL_LEN) trail.shift();
+        next.set(inh.id, trail);
+      }
+      for (const id of next.keys()) {
+        if (!snap.find(a => a.id === id)) next.delete(id);
+      }
+      return next;
+    });
+  });
+
+  // Disk radius = half the smallest dimension, leaving some padding
+  const diskRadius = $derived(Math.min(width, height) / 2 - 24);
+  const diskCx     = $derived(width  / 2);
+  const diskCy     = $derived(height / 2);
+
+  // Project positions into Poincaré disk space
+  const projected = $derived(
+    projectToDisk(graphStateProp.positions, graphStateProp.focusCenterId, diskRadius)
+  );
+
+  // ── Edge reveal offsets (re-used from GraphState bfsOrder) ──────────────────
+
+  let edgeOffsets = $state<Map<string, number>>(new Map());
+
+  $effect(() => {
+    const bfsOrder = graphStateProp.bfsOrder;
+    const next = new Map<string, number>();
+    for (const e of snapshot.edges) next.set(e.id, 0.0);
+    edgeOffsets = next;
+
+    const nodeIndex = new Map<string, number>();
+    bfsOrder.forEach((id, i) => nodeIndex.set(id, i));
+
+    for (const edge of snapshot.edges) {
+      const idx = nodeIndex.get(edge.sourceId) ?? 0;
+      setTimeout(() => {
+        edgeOffsets = new Map(edgeOffsets).set(edge.id, 1.0);
+      }, idx * EDGE_REVEAL_STAGGER_MS);
+    }
+  });
+
+  // ── Design tokens ──────────────────────────────────────────────────────────
+
+  const COLORS = {
+    bg:         '#1a1a1a',
+    diskBg:     '#111111',
+    diskBorder: '#3a3020',
+    node:       '#2a2a2a',
+    nodeBorder: '#b87333',
+    nodeText:   '#e8e0d0',
+    edgeLine:   '#b87333',
+    edgeFade:   '#5a4a30',
+    focus:      '#d4943a',
+    grid:       '#1e1e1e',
+    selected:   '#d4943a',
+  };
+
+  // Column-based node fill colors — matches KOS brass/copper theme.
+  // Semi-transparent fills let the dark disk background show through.
+  const COLUMN_FILL: Record<string, string> = {
+    GO:      'rgba(184, 115, 51, 0.35)',   // brass — active
+    CONSULT: 'rgba(184, 115, 51, 0.18)',   // brass outline — advisory
+    WEED:    'rgba(200, 160, 50, 0.22)',   // warning amber
+    SPROUT:  'rgba(70,  130, 200, 0.20)', // info blue — growing
+    FREEZE:  'rgba(80,  110, 180, 0.16)', // cool blue — frozen
+    SEED:    'rgba(42,   42,  42, 0.60)', // muted — backlog
+  };
+
+  const COLUMN_BORDER: Record<string, string> = {
+    GO:      '#b87333',
+    CONSULT: 'rgba(184, 115, 51, 0.6)',
+    WEED:    '#c8a032',
+    SPROUT:  '#4682c8',
+    FREEZE:  '#506eb4',
+    SEED:    '#3a3a3a',
+  };
+
+  const NODE_RADIUS = 4;
+  const FONT = '11px var(--font-mono, monospace)';
+
+  // ── Render ──────────────────────────────────────────────────────────────────
+
+  function render({ context }: { context: CanvasRenderingContext2D }) {
+    const r = diskRadius;
+    const cx = diskCx, cy = diskCy;
+
+    context.clearRect(0, 0, width, height);
+
+    // Background
+    context.fillStyle = COLORS.bg;
+    context.fillRect(0, 0, width, height);
+
+    // Disk background + clip
+    context.save();
+    context.beginPath();
+    context.arc(cx, cy, r, 0, Math.PI * 2);
+    context.fillStyle = COLORS.diskBg;
+    context.fill();
+    context.strokeStyle = COLORS.diskBorder;
+    context.lineWidth = 1;
+    context.stroke();
+    context.clip();
+
+    // Subtle geodesic grid lines (3 concentric circles)
+    context.strokeStyle = COLORS.grid;
+    context.lineWidth = 0.5;
+    for (const fraction of [0.33, 0.66, 0.88]) {
+      context.beginPath();
+      context.arc(cx, cy, r * fraction, 0, Math.PI * 2);
+      context.stroke();
+    }
+
+    // Offset all positions to disk center
+    function toCanvas(x: number, y: number): [number, number] {
+      return [x - diskRadius + cx, y - diskRadius + cy];
+    }
+
+    // ── Edges ──
+    context.font = FONT;
+    for (const edge of snapshot.edges) {
+      const src = projected.get(edge.sourceId);
+      const tgt = projected.get(edge.targetId);
+      if (!src || !tgt) continue;
+
+      const progress = edgeOffsets.get(edge.id) ?? 0;
+      if (progress <= 0) continue;
+
+      const [sx, sy] = toCanvas(src.x + src.width  / 2, src.y + src.height / 2);
+      const [tx, ty] = toCanvas(tgt.x + tgt.width  / 2, tgt.y + tgt.height / 2);
+
+      const [ax, ay, pcx, pcy, ex, ey, ae] = getArrow(sx, sy, tx, ty, {
+        bow: 0.15,
+        stretch: 0.3,
+        padStart: src.width / 2 + 4,
+        padEnd:   tgt.width / 2 + 4,
+      });
+
+      const dx = ex - ax, dy = ey - ay;
+      const approxLen = Math.sqrt(dx * dx + dy * dy) * 1.2;
+      const dash = approxLen * progress;
+
+      context.save();
+      context.strokeStyle = progress >= 1.0 ? COLORS.edgeLine : COLORS.edgeFade;
+      context.lineWidth   = 1.5;
+      context.setLineDash([dash, approxLen]);
+      context.beginPath();
+      context.moveTo(ax, ay);
+      context.quadraticCurveTo(pcx, pcy, ex, ey);
+      context.stroke();
+      context.restore();
+
+      if (progress >= 1.0) {
+        context.save();
+        context.fillStyle = COLORS.edgeLine;
+        context.translate(ex, ey);
+        context.rotate(ae);
+        context.beginPath();
+        context.moveTo(0, 0);
+        context.lineTo(-7, -3);
+        context.lineTo(-7,  3);
+        context.closePath();
+        context.fill();
+        context.restore();
+      }
+    }
+
+    // ── Nodes ──
+    for (const node of snapshot.nodes) {
+      const pos = projected.get(node.id);
+      if (!pos) continue;
+
+      const column = (node.data?.column as string | undefined) ?? '';
+      const isSelected = node.id === selectedId;
+      const [px, py] = toCanvas(pos.x, pos.y);
+      const { width: w, height: h } = pos;
+
+      context.fillStyle   = isSelected ? COLORS.selected : (COLUMN_FILL[column] ?? COLORS.node);
+      context.strokeStyle = isSelected ? COLORS.selected : (COLUMN_BORDER[column] ?? COLORS.nodeBorder);
+      context.lineWidth   = isSelected ? 2 : 1;
+
+      context.beginPath();
+      context.roundRect(px, py, w, h, NODE_RADIUS);
+      context.fill();
+      context.stroke();
+
+      context.fillStyle    = COLORS.nodeText;
+      context.font         = FONT;
+      context.textAlign    = 'center';
+      context.textBaseline = 'middle';
+      const label = node.label.length > 16 ? node.label.slice(0, 14) + '…' : node.label;
+      context.fillText(label, px + w / 2, py + h / 2, w - 12);
+    }
+
+    // ── Inhabitants (S³ orientations) ────────────────────────────────────────
+    // Project each inhabitant quaternion to disk coords here (diskRadius known).
+    // Trails are in unit-disk space; scale by r to get pixel coords.
+    if (inhabitants.length > 0) {
+      for (const inh of inhabitants) {
+        const [w, i, j, k] = inh.orientation;
+        const agent = quaternionToDisk(w, i, j, k, 1.0); // unit coords; scaled by r below
+        const trail = agentTrails.get(inh.id) ?? [];
+
+        // Draw fading trail
+        if (trail.length > 1) {
+          for (let t = 0; t < trail.length - 1; t++) {
+            const alpha = (t / (trail.length - 1)) * 0.5;
+            const pt = trail[t];
+            const pn = trail[t + 1];
+            context.save();
+            context.strokeStyle = `rgba(212, 148, 58, ${alpha})`; // brass fade
+            context.lineWidth = 1.5;
+            context.beginPath();
+            context.moveTo(cx + pt.u * r, cy + pt.v * r);
+            context.lineTo(cx + pn.u * r, cy + pn.v * r);
+            context.stroke();
+            context.restore();
+          }
+        }
+
+        // Draw glowing agent dot
+        const ax = cx + agent.u * r;
+        const ay = cy + agent.v * r;
+        const dotR = 5;
+
+        // Outer glow
+        const glow = context.createRadialGradient(ax, ay, 0, ax, ay, dotR * 3);
+        glow.addColorStop(0, 'rgba(212, 148, 58, 0.6)');
+        glow.addColorStop(1, 'rgba(212, 148, 58, 0)');
+        context.fillStyle = glow;
+        context.beginPath();
+        context.arc(ax, ay, dotR * 3, 0, Math.PI * 2);
+        context.fill();
+
+        // Core dot
+        context.fillStyle = '#d4943a';
+        context.beginPath();
+        context.arc(ax, ay, dotR, 0, Math.PI * 2);
+        context.fill();
+
+        // Short ID label
+        context.fillStyle = 'rgba(232, 224, 208, 0.85)';
+        context.font = '9px var(--font-mono, monospace)';
+        context.textAlign = 'center';
+        context.textBaseline = 'top';
+        context.fillText(inh.id.slice(0, 6), ax, ay + dotR + 3);
+      }
+    }
+
+    context.restore(); // end clip
+  }
+</script>
+
+<Canvas {width} {height}>
+  <Layer {render} />
+</Canvas>

package/src/n2-manifold-disk/index.ts

@@ -0,0 +1,6 @@
+// N2 Manifold Disk — Poincaré disk projection wrapping n1-flow-canvas
+// κ = 1.0 fixed (standard Poincaré disk, no prop)
+
+export { default as ManifoldDisk } from './ManifoldDisk.svelte';
+export { mobiusTransform, projectToDisk, poincareDistance, quaternionToDisk } from './poincare.js';
+export type { GraphStateApi, GraphSnapshot } from '../n1-flow-canvas/types.js';

package/src/n2-manifold-disk/poincare.ts

@@ -0,0 +1,184 @@
+// Poincaré disk projection — ~50 lines of pure math
+// κ = 1.0 fixed (standard Poincaré disk)
+// S-02: pure functions, no side effects, deterministic
+
+import type { NodeLayout } from '../n1-flow-canvas/types.js';
+
+// Complex number as [real, imag] tuple
+type Complex = readonly [number, number];
+
+// ── Complex arithmetic ────────────────────────────────────────────────────────
+
+function cadd(a: Complex, b: Complex): Complex {
+  return [a[0] + b[0], a[1] + b[1]];
+}
+
+function csub(a: Complex, b: Complex): Complex {
+  return [a[0] - b[0], a[1] - b[1]];
+}
+
+function cmul(a: Complex, b: Complex): Complex {
+  return [a[0] * b[0] - a[1] * b[1], a[0] * b[1] + a[1] * b[0]];
+}
+
+function cdiv(a: Complex, b: Complex): Complex {
+  const denom = b[0] * b[0] + b[1] * b[1];
+  return [(a[0] * b[0] + a[1] * b[1]) / denom, (a[1] * b[0] - a[0] * b[1]) / denom];
+}
+
+function cconj(a: Complex): Complex {
+  return [a[0], -a[1]];
+}
+
+function cabs(a: Complex): number {
+  return Math.sqrt(a[0] * a[0] + a[1] * a[1]);
+}
+
+// ── Möbius transform ──────────────────────────────────────────────────────────
+
+/**
+ * Möbius transform that moves z0 to the origin.
+ * f(z) = (z − z0) / (1 − conj(z0) · z)
+ * Preserves the unit disk: |z| ≤ 1 → |f(z)| ≤ 1
+ */
+export function mobiusTransform(z: Complex, z0: Complex): Complex {
+  const num = csub(z, z0);
+  const den = csub([1, 0], cmul(cconj(z0), z));
+  return cdiv(num, den);
+}
+
+/**
+ * Project Euclidean node positions onto the Poincaré disk.
+ *
+ * Steps:
+ * 1. Normalize all positions to [-1, 1]² using bounding box
+ * 2. Apply Möbius transform to center focusNodeId at origin
+ * 3. Scale to diskRadius
+ *
+ * Returns a new Map — does not mutate input.
+ */
+export function projectToDisk(
+  positions: Map<string, NodeLayout>,
+  focusNodeId: string | null,
+  diskRadius: number,
+): Map<string, { x: number; y: number; width: number; height: number }> {
+  if (positions.size === 0) return new Map();
+
+  // Bounding box
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const p of positions.values()) {
+    const cx = p.x + p.width  / 2;
+    const cy = p.y + p.height / 2;
+    if (cx < minX) minX = cx;
+    if (cy < minY) minY = cy;
+    if (cx > maxX) maxX = cx;
+    if (cy > maxY) maxY = cy;
+  }
+
+  const rangeX = maxX - minX || 1;
+  const rangeY = maxY - minY || 1;
+  const range  = Math.max(rangeX, rangeY);
+
+  // Normalize to Poincaré disk unit coords, then scale to 0.9 max radius
+  function toComplex(p: NodeLayout): Complex {
+    const cx = p.x + p.width  / 2;
+    const cy = p.y + p.height / 2;
+    return [
+      ((cx - minX) / range * 2 - rangeX / range) * 0.9,
+      ((cy - minY) / range * 2 - rangeY / range) * 0.9,
+    ];
+  }
+
+  // Focus center in normalized coords
+  const focusPos = focusNodeId ? positions.get(focusNodeId) : null;
+  const z0: Complex = focusPos ? toComplex(focusPos) : [0, 0];
+
+  const result = new Map<string, { x: number; y: number; width: number; height: number }>();
+
+  for (const [id, p] of positions) {
+    const z = toComplex(p);
+    const projected = mobiusTransform(z, z0);
+    // Clamp to unit disk (numerical safety)
+    const r = cabs(projected);
+    const clamped: Complex = r > 0.99 ? [projected[0] * 0.99 / r, projected[1] * 0.99 / r] : projected;
+
+    result.set(id, {
+      x: clamped[0] * diskRadius + diskRadius - p.width  / 2,
+      y: clamped[1] * diskRadius + diskRadius - p.height / 2,
+      width:  p.width,
+      height: p.height,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Poincaré distance between two points in the disk.
+ * d(u,v) = 2 * atanh(|u - v| / |1 - conj(u)v|)
+ */
+export function poincareDistance(u: Complex, v: Complex): number {
+  const num = cabs(csub(u, v));
+  const den = cabs(csub([1, 0], cmul(cconj(u), v)));
+  return 2 * Math.atanh(num / den);
+}
+
+// ── S³ quaternion projection ──────────────────────────────────────────────────
+
+/**
+ * A point on the Poincaré disk derived from a unit quaternion on S³.
+ *
+ * Fields:
+ * - `u`, `v` — disk coordinates in pixels, relative to disk centre
+ * - `id`     — inhabitant identifier
+ * - `allay`  — accumulated arc length (monotonically increasing)
+ */
+export interface AgentPosition {
+  id: string;
+  u: number;  // disk x, relative to centre
+  v: number;  // disk y, relative to centre
+  allay: number;
+}
+
+/**
+ * Project a unit quaternion [w, i, j, k] onto the Poincaré disk.
+ *
+ * Uses axis-angle parameterisation of S³:
+ *   θ = 2·acos(clamp(w, −1, 1))          — total rotation angle
+ *   axis = (i, j, k) / sin(θ/2)           — unit rotation axis
+ *   r = θ/π · 0.95 · diskRadius           — radial distance on disk
+ *   u = r · axis.i                         — Accumulation axis → disk X
+ *   v = r · axis.j                         — Actuation axis → disk Y
+ *
+ * Properties:
+ * - Identity quaternion (w=1) maps to disk centre — zero rotation.
+ * - Maximally rotated quaternion (w=−1, θ=2π) maps to boundary.
+ * - The rotation axis angle on disk reflects semantic orientation:
+ *   i=Accumulation (X), j=Actuation (Y), k=Relation (depth, ignored here).
+ *
+ * S-02: pure function, no side effects.
+ */
+export function quaternionToDisk(
+  w: number,
+  i: number,
+  j: number,
+  _k: number,
+  diskRadius: number,
+): { u: number; v: number } {
+  const wClamped = Math.max(-1, Math.min(1, w));
+  const theta = 2 * Math.acos(wClamped);
+
+  if (theta < 1e-9) {
+    // Identity — centre of disk
+    return { u: 0, v: 0 };
+  }
+
+  const sinHalf = Math.sin(theta / 2);
+  // r in [0, 0.95 * diskRadius]; maps θ=0 → centre, θ=π → boundary
+  const r = (theta / Math.PI) * 0.95 * diskRadius;
+
+  return {
+    u: r * (i / sinHalf),
+    v: r * (j / sinHalf),
+  };
+}

package/src/n3-force-graph/ForceGraph.svelte

@@ -0,0 +1,180 @@
+<script lang="ts">
+  // N3 ForceGraph — Canvas 2D force-directed graph wrapper (vasturiano/force-graph)
+  // wt-797: Accepts ForceGraphData, renders with health-aware node/edge callbacks
+  //
+  // S-02: No Math.random in rendering. Pulse tick is deterministic counter.
+  // S-05: Force simulation has cooldownTicks + cooldownTime bounds.
+  //       Component destroys graph instance on unmount.
+
+  import { onMount, onDestroy } from 'svelte';
+  import type { ForceGraphData, ForceGraphNode, ForceGraphLink, HealthNodeConfig, AnimatedEdgeConfig, TooltipPosition } from './types.js';
+  import { createHealthNodeRenderer, createHealthNodeAreaPaint, advancePulseTick } from './health-node.js';
+  import { createAnimatedEdgeRenderer } from './animated-edge.js';
+
+  // ── Props ────────────────────────────────────────────────────────────────────
+
+  interface Props {
+    /** Graph data: nodes + links */
+    data: ForceGraphData;
+    /** Container width. Default 800. */
+    width?: number;
+    /** Container height. Default 600. */
+    height?: number;
+    /** Health node rendering config */
+    nodeConfig?: HealthNodeConfig;
+    /** Animated edge rendering config */
+    edgeConfig?: AnimatedEdgeConfig;
+    /** Background color. Default '#1a1a1a'. */
+    backgroundColor?: string;
+    /** Callback when a node is clicked */
+    onNodeClick?: (node: ForceGraphNode) => void;
+    /** Callback when a node is hovered (null = hover left) */
+    onNodeHover?: (node: ForceGraphNode | null, position: TooltipPosition) => void;
+    /** Callback when a link is clicked */
+    onLinkClick?: (link: ForceGraphLink) => void;
+    /** Force simulation cooldown ticks. Default 300. S-05: bounded. */
+    cooldownTicks?: number;
+    /** D3 force charge strength. Default -120. */
+    chargeStrength?: number;
+    /** D3 force link distance. Default 80. */
+    linkDistance?: number;
+  }
+
+  let {
+    data,
+    width = 800,
+    height = 600,
+    nodeConfig,
+    edgeConfig,
+    backgroundColor = '#1a1a1a',
+    onNodeClick,
+    onNodeHover,
+    onLinkClick,
+    cooldownTicks = 300,
+    chargeStrength = -120,
+    linkDistance = 80,
+  }: Props = $props();
+
+  // ── Internal state ──────────────────────────────────────────────────────────
+
+  let container: HTMLDivElement;
+  let graph: any = null; // ForceGraph instance (untyped — library uses chainable API)
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+
+  onMount(async () => {
+    // Dynamic import: force-graph requires DOM
+    const ForceGraphLib = (await import('force-graph')).default;
+
+    // force-graph ships class-style TS types but is actually a factory function
+    graph = (ForceGraphLib as unknown as () => (el: HTMLElement) => any)()(container)
+      .width(width)
+      .height(height)
+      .backgroundColor(backgroundColor)
+      // Node rendering
+      .nodeCanvasObject(createHealthNodeRenderer(nodeConfig))
+      .nodeCanvasObjectMode(() => 'replace')
+      .nodePointerAreaPaint(createHealthNodeAreaPaint(nodeConfig))
+      // Edge rendering
+      .linkCanvasObject(createAnimatedEdgeRenderer(edgeConfig))
+      .linkCanvasObjectMode(() => 'replace')
+      // Link identifiers
+      .linkSource('source')
+      .linkTarget('target')
+      // Force parameters
+      .cooldownTicks(cooldownTicks)
+      // Interaction
+      .onNodeClick((node: ForceGraphNode) => {
+        onNodeClick?.(node);
+      })
+      .onNodeHover((node: ForceGraphNode | null) => {
+        // Change cursor
+        container.style.cursor = node ? 'pointer' : 'default';
+        // Emit hover with position
+        if (onNodeHover) {
+          const pos: TooltipPosition = node
+            ? { x: (node.x ?? 0), y: (node.y ?? 0), visible: true }
+            : { x: 0, y: 0, visible: false };
+          onNodeHover(node, pos);
+        }
+      })
+      .onLinkClick((link: ForceGraphLink) => onLinkClick?.(link))
+      // Drag to pin
+      .onNodeDragEnd((node: ForceGraphNode) => {
+        node.fx = node.x;
+        node.fy = node.y;
+      });
+
+    // Configure d3 forces after graph creation
+    graph.d3Force('charge')?.strength(chargeStrength);
+    graph.d3Force('link')?.distance(linkDistance);
+
+    // Engine tick hook for pulse animation
+    graph.onEngineTick(() => advancePulseTick());
+
+    // Initial data
+    graph.graphData({
+      nodes: data.nodes,
+      links: data.links,
+    });
+  });
+
+  onDestroy(() => {
+    if (graph) {
+      graph._destructor();
+      graph = null;
+    }
+  });
+
+  // ── Reactive updates ───────────────────────────────────────────────────────
+
+  $effect(() => {
+    if (!graph) return;
+    graph.graphData({
+      nodes: data.nodes,
+      links: data.links,
+    });
+  });
+
+  $effect(() => {
+    if (!graph) return;
+    graph.width(width).height(height);
+  });
+
+  // ── Public API (exposed via bind:this on wrapper) ──────────────────────────
+
+  export function zoomToFit(duration = 400, padding = 40) {
+    graph?.zoomToFit(duration, padding);
+  }
+
+  export function centerAt(x: number, y: number, duration = 400) {
+    graph?.centerAt(x, y, duration);
+  }
+
+  export function zoom(factor: number, duration = 400) {
+    graph?.zoom(factor, duration);
+  }
+
+  export function reheat() {
+    graph?.d3ReheatSimulation();
+  }
+</script>
+
+<div
+  bind:this={container}
+  class="n3-force-graph"
+  style:width="{width}px"
+  style:height="{height}px"
+></div>
+
+<style>
+  .n3-force-graph {
+    position: relative;
+    overflow: hidden;
+    border-radius: var(--radius-md, 8px);
+  }
+
+  .n3-force-graph :global(canvas) {
+    border-radius: var(--radius-md, 8px);
+  }
+</style>