@celestia-island/hikari 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkBoard.scss

@@ -0,0 +1,83 @@
+// HkBoard — the shared node-and-edge board surface.
+// Geometry semantics live in utils/boardCamera.ts + utils/boardEdges.ts;
+// this file only styles the layers (grid, world, edges, node shells,
+// minimap dock).
+
+.hk-board {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+  background: rgb(var(--color-surface));
+  // gestures own the surface: no native scroll/selection interference
+  touch-action: none;
+  user-select: none;
+}
+
+.hk-board-grid {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.hk-board-world {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: 0 0;
+  will-change: transform;
+}
+
+.hk-board-edges {
+  position: absolute;
+  top: 0;
+  left: 0;
+  overflow: visible;
+  pointer-events: none;
+}
+
+.hk-board-edge {
+  fill: none;
+  stroke-linecap: round;
+}
+
+.hk-board-node {
+  position: absolute;
+  box-sizing: border-box;
+
+  &--draggable {
+    cursor: grab;
+
+    &:active {
+      cursor: grabbing;
+    }
+  }
+}
+
+.hk-board-node-shell {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--space-6);
+  box-sizing: border-box;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--text-2xs);
+  color: rgb(var(--color-text));
+  background: rgb(var(--color-surface));
+  border: 1px solid rgb(var(--color-primary) / 45%);
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-elevated);
+}
+
+.hk-board-minimap {
+  position: absolute;
+  right: var(--space-10);
+  bottom: var(--space-10);
+  z-index: 6;
+  pointer-events: auto;
+}

package/src/components/HkBoard.tsx

@@ -0,0 +1,396 @@
+/**
+ * HkBoard — the shared node-and-edge board surface.
+ *
+ * ONE world-camera canvas that every graph-like page builds on (history
+ * topic maps, SCADA scenes, PLC panels, and whatever comes next). The
+ * board owns the motion feel and the chrome; the page owns the layout:
+ *
+ *  - CAMERA: 5% geometric zoom ladder with an ANIMATED settle (no snapping),
+ *    wheel zoom anchored at the pointer (desktop), two-finger pinch
+ *    (touch, continuous while pinching → animated rung on release),
+ *    clamped background pan, fit/reset;
+ *  - GRID: the engineering dot grid is always on and world-anchored —
+ *    it scales and translates with the camera so it doubles as an
+ *    alignment aid;
+ *  - NODES: DOM shells positioned in world coords, rendered through the
+ *    `node` scoped slot (a labeled shell is provided when the slot is
+ *    omitted). `draggable` nodes move in world coords and emit
+ *    `node-move`; `hidden` nodes paint NOTHING but still route edges —
+ *    that is how a page bakes a right-angle corner into its graph;
+ *  - EDGES: SVG paths with independently configurable anchor modes
+ *    (center / nearest / top / top-left / fan-天女散花) and route styles
+ *    (straight / bezier / orthogonal / spine), optionally routed through
+ *    `via` junction nodes (see utils/boardEdges.ts);
+ *  - MINIMAP: HkMinimap pinned bottom-right, wired to the same camera.
+ *
+ * The page supplies `nodes` (world rects, reactive) and `edges`; node
+ * LAYOUT stays the page's business — the board never forces an
+ * arrangement, it only standardizes how things connect and move.
+ */
+
+import {
+  computed,
+  defineComponent,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  toRef,
+  watch,
+  type PropType,
+  type Ref,
+} from "vue";
+
+import { useBoardCamera } from "../composables/useBoardCamera";
+import HkMinimap, { type MinimapBox } from "./HkMinimap";
+import {
+  boardBBox,
+  type BoardCamera,
+  type BoardPoint,
+  type BoardRect,
+  type BoardViewport,
+} from "../utils/boardCamera";
+import {
+  boardAnchor,
+  boardEdgePath,
+  boardViaPath,
+  type BoardAnchorMode,
+  type BoardEdgeStyle,
+} from "../utils/boardEdges";
+import "./HkBoard.scss";
+
+/** A node on the board. `hidden` nodes are junction-only (invisible). */
+export interface BoardNodeInput {
+  id: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  label?: string;
+  kind?: string;
+  /** Invisible junction node — routes edges, paints nothing. */
+  hidden?: boolean;
+  /** Opt in to pointer dragging (world-coord moves + `node-move` events). */
+  draggable?: boolean;
+  /** Page payload, handed back through the scoped slot. */
+  data?: Record<string, unknown>;
+}
+
+export interface BoardEdgeInput {
+  id: string;
+  from: string;
+  to: string;
+  /** Junction node ids the edge routes through (their centers). */
+  via?: string[];
+  style?: BoardEdgeStyle;
+  anchorFrom?: BoardAnchorMode;
+  anchorTo?: BoardAnchorMode;
+  ink?: string;
+  dashed?: boolean;
+  width?: number;
+}
+
+const DEFAULT_INK = "rgb(var(--color-primary) / 38%)";
+
+export default defineComponent({
+  name: "HkBoard",
+  props: {
+    nodes: { type: Array as PropType<BoardNodeInput[]>, default: () => [] },
+    edges: { type: Array as PropType<BoardEdgeInput[]>, default: () => [] },
+    /** Wire wheel / pinch / pan gestures (node clicks always work). */
+    interactive: { type: Boolean, default: true },
+    grid: { type: Boolean, default: true },
+    gridSize: { type: Number, default: 24 },
+    minimap: { type: Boolean, default: true },
+    minK: { type: Number, default: 0.2 },
+    maxK: { type: Number, default: 4 },
+    animated: { type: Boolean, default: true },
+    fitOnMount: { type: Boolean, default: true },
+  },
+  emits: {
+    nodeClick: (_node: BoardNodeInput) => true,
+    nodeMove: (_node: BoardNodeInput, _x: number, _y: number) => true,
+    viewportChange: (_cam: BoardCamera) => true,
+  },
+  setup(props, { emit, expose, slots }) {
+    const viewportRef = ref<HTMLElement | null>(null);
+    const viewportSize = ref<BoardViewport>({ w: 800, h: 600 });
+
+    /** Content bbox (world) — nodes plus a small margin. */
+    const content = computed<BoardRect>(() => {
+      const box = boardBBox(props.nodes.map((n) => ({ x: n.x, y: n.y, w: n.w, h: n.h })));
+      return { x: box.x - 20, y: box.y - 20, w: box.w + 40, h: box.h + 40 };
+    });
+
+    const cam: ReturnType<typeof useBoardCamera> = useBoardCamera({
+      viewportSize,
+      content,
+      minK: props.minK,
+      maxK: props.maxK,
+      animated: props.animated,
+    });
+    const camera = cam.camera as Ref<BoardCamera>;
+
+    // ── geometry ────────────────────────────────────────────────────────
+    const rectOf = computed(() => {
+      const map = new Map<string, BoardRect>();
+      for (const n of props.nodes) map.set(n.id, { x: n.x, y: n.y, w: n.w, h: n.h });
+      return map;
+    });
+
+    /** Edges sharing a `from` node fan across its border (天女散花). */
+    const fanOrdinal = computed(() => {
+      const counters = new Map<string, number>();
+      const ordinals = new Map<string, { index: number; count: number }>();
+      for (const e of props.edges) {
+        const next = (counters.get(e.from) ?? 0) + 1;
+        counters.set(e.from, next);
+        ordinals.set(e.id, { index: next - 1, count: counters.get(e.from)! });
+      }
+      return ordinals;
+    });
+
+    const edgePaths = computed(() => {
+      const rects = rectOf.value;
+      const out: { id: string; d: string; ink: string; dashed: boolean; width: number }[] = [];
+      for (const e of props.edges) {
+        const from = rects.get(e.from);
+        const to = rects.get(e.to);
+        if (!from || !to) continue;
+        const toCenter = { x: to.x + to.w / 2, y: to.y + to.h / 2 };
+        const fromCenter = { x: from.x + from.w / 2, y: from.y + from.h / 2 };
+        const fan = fanOrdinal.value.get(e.id) ?? { index: 0, count: 1 };
+        const a = boardAnchor(from, e.anchorFrom ?? "center", toCenter, fan.index, fan.count);
+        const b = boardAnchor(to, e.anchorTo ?? "center", fromCenter, fan.index, fan.count);
+        const viaCenters = (e.via ?? [])
+          .map((id) => rects.get(id))
+          .filter((r): r is BoardRect => Boolean(r))
+          .map((r) => ({ x: r.x + r.w / 2, y: r.y + r.h / 2 }));
+        out.push({
+          id: e.id,
+          d: boardViaPath(a, viaCenters, b, e.style ?? "orthogonal"),
+          ink: e.ink ?? DEFAULT_INK,
+          dashed: Boolean(e.dashed),
+          width: e.width ?? 1.5,
+        });
+      }
+      return out;
+    });
+
+    const contentBounds = computed(() => content.value);
+
+    const worldStyle = computed(() => ({
+      transform: `translate(${camera.value.x}px, ${camera.value.y}px) scale(${camera.value.k})`,
+      width: `${contentBounds.value.w}px`,
+      height: `${contentBounds.value.h}px`,
+    }));
+
+    const gridStyle = computed(() => {
+      if (!props.grid) return { display: "none" };
+      const s = props.gridSize * camera.value.k;
+      return {
+        backgroundImage: "radial-gradient(rgb(var(--color-text) / 12%) 1px, transparent 1px)",
+        backgroundSize: `${s}px ${s}px`,
+        backgroundPosition: `${camera.value.x}px ${camera.value.y}px`,
+      };
+    });
+
+    const minimapBoxes = computed<MinimapBox[]>(() =>
+      props.nodes
+        .filter((n) => !n.hidden)
+        .map((n) => ({
+          id: n.id,
+          bounds: { x: n.x, y: n.y, w: n.w, h: n.h },
+          color: "rgb(var(--color-primary) / 40%)",
+        })),
+    );
+
+    // ── gestures ────────────────────────────────────────────────────────
+    const pointers = new Map<number, { x: number; y: number }>();
+    let panState: { px: number; py: number } | null = null;
+    let pinchBase: { cam: BoardCamera; dist: number; mid: BoardPoint } | null = null;
+    let dragState: { node: BoardNodeInput; sx: number; sy: number; ox: number; oy: number; moved: boolean } | null = null;
+
+    const localPoint = (e: PointerEvent | WheelEvent): BoardPoint => {
+      const rect = viewportRef.value?.getBoundingClientRect();
+      return { x: e.clientX - (rect?.left ?? 0), y: e.clientY - (rect?.top ?? 0) };
+    };
+
+    function onWheel(e: WheelEvent): void {
+      if (!props.interactive) return;
+      e.preventDefault();
+      const factor = e.deltaY < 0 ? 1.05 : 1 / 1.05;
+      cam.zoomByFactor(factor, localPoint(e));
+    }
+
+    function refreshSize(): void {
+      const el = viewportRef.value;
+      if (!el) return;
+      viewportSize.value = { w: el.clientWidth, h: el.clientHeight };
+    }
+
+    let resizeObs: ResizeObserver | null = null;
+
+    function onPointerDown(e: PointerEvent): void {
+      if (!props.interactive) return;
+      pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+      if (pointers.size === 2) {
+        // pinch begins: snapshot camera + finger geometry
+        const [a, b] = [...pointers.values()];
+        pinchBase = {
+          cam: { ...camera.value },
+          dist: Math.hypot(a.x - b.x, a.y - b.y) || 1,
+          mid: localPoint(e),
+        };
+        panState = null;
+        return;
+      }
+      if (pointers.size === 1) {
+        panState = { px: e.clientX, py: e.clientY };
+        viewportRef.value?.setPointerCapture(e.pointerId);
+      }
+    }
+
+    function onPointerMove(e: PointerEvent): void {
+      if (!props.interactive) return;
+      if (pointers.has(e.pointerId)) pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+      if (pinchBase && pointers.size >= 2) {
+        const [a, b] = [...pointers.values()];
+        const dist = Math.hypot(a.x - b.x, a.y - b.y) || 1;
+        const mid = {
+          x: (a.x + b.x) / 2 - (viewportRef.value?.getBoundingClientRect().left ?? 0),
+          y: (a.y + b.y) / 2 - (viewportRef.value?.getBoundingClientRect().top ?? 0),
+        };
+        cam.pinchZoom(pinchBase.cam, dist / pinchBase.dist, mid);
+        return;
+      }
+      if (dragState) {
+        const k = camera.value.k || 1;
+        const dx = (e.clientX - dragState.sx) / k;
+        const dy = (e.clientY - dragState.sy) / k;
+        if (Math.abs(e.clientX - dragState.sx) + Math.abs(e.clientY - dragState.sy) > 3) dragState.moved = true;
+        dragState.node.x = Math.round(dragState.ox + dx);
+        dragState.node.y = Math.round(dragState.oy + dy);
+        emit("nodeMove", dragState.node, dragState.node.x, dragState.node.y);
+        return;
+      }
+      if (panState) {
+        cam.panBy(e.clientX - panState.px, e.clientY - panState.py);
+        panState = { px: e.clientX, py: e.clientY };
+      }
+    }
+
+    function onPointerUp(e: PointerEvent): void {
+      pointers.delete(e.pointerId);
+      if (pointers.size < 2 && pinchBase) {
+        pinchBase = null;
+        cam.settlePinch();
+      }
+      if (pointers.size === 0) panState = null;
+      if (dragState && !dragState.moved) emit("nodeClick", dragState.node);
+      dragState = null;
+    }
+
+    function onNodePointerDown(e: PointerEvent, node: BoardNodeInput): void {
+      if (!props.interactive || !node.draggable) return;
+      e.stopPropagation();
+      dragState = { node, sx: e.clientX, sy: e.clientY, ox: node.x, oy: node.y, moved: false };
+      viewportRef.value?.setPointerCapture(e.pointerId);
+    }
+
+    watch(() => camera.value, (c) => emit("viewportChange", { ...c }), { deep: true });
+    watch(toRef(props, "nodes"), () => {
+      // content growth invalidates clamping — re-clamp against the new bbox
+      cam.setCamera({ ...camera.value });
+    });
+
+    onMounted(() => {
+      refreshSize();
+      resizeObs = new ResizeObserver(refreshSize);
+      if (viewportRef.value) resizeObs.observe(viewportRef.value);
+      viewportRef.value?.addEventListener("wheel", onWheel, { passive: false });
+      if (props.fitOnMount) cam.fit();
+    });
+
+    onBeforeUnmount(() => {
+      resizeObs?.disconnect();
+      viewportRef.value?.removeEventListener("wheel", onWheel);
+    });
+
+    expose({
+      fit: () => cam.fit(),
+      zoomIn: () => cam.zoomIn(),
+      zoomOut: () => cam.zoomOut(),
+      zoomToPercent: (p: number, anchor?: BoardPoint) => cam.zoomToPercent(p, anchor),
+      reset: () => cam.fit(),
+      camera,
+    });
+
+    return () => (
+      <div
+        class="hk-board"
+        ref={viewportRef}
+        onPointerdown={onPointerDown}
+        onPointermove={onPointerMove}
+        onPointerup={onPointerUp}
+        onPointercancel={onPointerUp}
+      >
+        <div class="hk-board-grid" style={gridStyle.value} />
+        <div class="hk-board-world" style={worldStyle.value}>
+          <svg class="hk-board-edges" width={contentBounds.value.w} height={contentBounds.value.h}>
+            {edgePaths.value.map((e) => (
+              <path
+                key={e.id}
+                class="hk-board-edge"
+                d={e.d}
+                stroke={e.ink}
+                stroke-width={e.width}
+                stroke-dasharray={e.dashed ? "6 5" : undefined}
+                fill="none"
+                stroke-linecap="round"
+              />
+            ))}
+          </svg>
+          {props.nodes.filter((n) => !n.hidden).map((n) => (
+            <div
+              key={n.id}
+              class={[
+                "hk-board-node",
+                { "hk-board-node--draggable": Boolean(n.draggable) },
+                n.kind ? `hk-board-node--${n.kind}` : undefined,
+              ]}
+              style={{ left: `${n.x}px`, top: `${n.y}px`, width: `${n.w}px`, height: `${n.h}px` }}
+              onPointerdown={(e: PointerEvent) => onNodePointerDown(e, n)}
+            >
+              {slots.node
+                ? slots.node({ node: n })
+                : <div class="hk-board-node-shell">{n.label ?? ""}</div>}
+            </div>
+          ))}
+        </div>
+        {props.minimap && (
+          <div class="hk-board-minimap">
+            <HkMinimap
+              boxes={minimapBoxes.value}
+              zoom={camera.value.k}
+              panX={camera.value.x}
+              panY={camera.value.y}
+              viewportWidth={viewportSize.value.w}
+              viewportHeight={viewportSize.value.h}
+              contentBounds={contentBounds.value}
+              zoomPercent={Math.round(camera.value.k * 100)}
+              canZoomIn={camera.value.k < props.maxK}
+              canZoomOut={camera.value.k > props.minK}
+              zoomStepPercent={5}
+              minZoomPercent={Math.round(props.minK * 100)}
+              maxZoomPercent={Math.round(props.maxK * 100)}
+              showReset
+              onZoomTo={(percent: number) => cam.zoomToPercent(percent)}
+              onReset={() => cam.fit()}
+              onPanDelta={(dx: number, dy: number) => cam.panBy(dx, dy)}
+            />
+          </div>
+        )}
+      </div>
+    );
+  },
+});

package/src/composables/useBoardCamera.ts

@@ -0,0 +1,218 @@
+/**
+ * useBoardCamera — reactive world camera + gesture primitives for HkBoard.
+ *
+ * Owns the camera state (`{x, y, k}`) and the motion rules:
+ *  - every zoom lands on the 5% geometric ladder (quantizeBoardK / quantizeBoardStep);
+ *  - zoom changes ANIMATE (~170ms ease-out, geometric k tween) instead of
+ *    snapping — an active pinch stays raw/continuous while the fingers
+ *    move and only animates to the nearest rung on release;
+ *  - wheel steps one rung per notch, anchored at the pointer;
+ *  - pan is clamped against the content bbox (half-viewport slack);
+ *  - reduced-motion (or `animated: false`) skips the tween and snaps.
+ *
+ * The component wires DOM events; this composable stays input-agnostic.
+ */
+import { computed, ref, toValue, type MaybeRefOrGetter, type Ref } from "vue";
+
+import {
+  BOARD_K_MAX,
+  BOARD_K_MIN,
+  BOARD_ZOOM_FACTOR,
+  type BoardCamera,
+  type BoardPoint,
+  type BoardRect,
+  type BoardViewport,
+  boardClampPan,
+  boardFit,
+  boardTweenCam,
+  boardZoomAt,
+  quantizeBoardK,
+} from "../utils/boardCamera";
+
+/** Animated transition duration, ms (wheel notch / minimap bar / pinch release). */
+const BOARD_ANIM_MS = 170;
+
+/** System reduced-motion preference — animations snap instead of tweening. */
+function prefersReducedMotion(): boolean {
+  return typeof window !== "undefined"
+    && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+
+export interface UseBoardCameraOptions {
+  /** The viewport element (screen space) — used for anchor math. */
+  viewportSize: MaybeRefOrGetter<BoardViewport>;
+  /** World bbox of the board content (nodes + padding). */
+  content: MaybeRefOrGetter<BoardRect>;
+  minK?: number;
+  maxK?: number;
+  /** Master animation switch; reduced-motion forces snapping regardless. */
+  animated?: boolean;
+}
+
+export interface UseBoardCameraReturn {
+  camera: Ref<BoardCamera>;
+  isAnimating: Ref<boolean>;
+  /** Screen↔world conversion at the CURRENT camera. */
+  screenToWorld: (p: BoardPoint) => BoardPoint;
+  worldToScreen: (p: BoardPoint) => BoardPoint;
+  /** Animated, ladder-quantized zoom keeping `anchor` (screen px) fixed. */
+  zoomByFactor: (factor: number, anchor?: BoardPoint) => void;
+  zoomToK: (targetK: number, anchor?: BoardPoint) => void;
+  zoomToPercent: (percent: number, anchor?: BoardPoint) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  /** Raw (unquantized, unanimated) pinch zoom — call per pointermove. */
+  pinchZoom: (base: BoardCamera, ratio: number, anchor: BoardPoint) => void;
+  /** Snap the post-pinch camera onto the nearest rung (animated). */
+  settlePinch: () => void;
+  panBy: (dx: number, dy: number) => void;
+  setCamera: (cam: BoardCamera, opts?: { animate?: boolean }) => void;
+  fit: () => void;
+  reset: () => void;
+}
+
+export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraReturn {
+  const {
+    viewportSize,
+    content,
+    minK = BOARD_K_MIN,
+    maxK = BOARD_K_MAX,
+    animated = true,
+  } = options;
+
+  const camera = ref<BoardCamera>({ x: 0, y: 0, k: 1 });
+  const isAnimating = ref(false);
+
+  let raf = 0;
+  let tweenFrom: BoardCamera = { x: 0, y: 0, k: 1 };
+  let tweenTo: BoardCamera = { x: 0, y: 0, k: 1 };
+  let tweenStart = 0;
+
+  const stopTween = (): void => {
+    if (raf) {
+      window.cancelAnimationFrame(raf);
+      raf = 0;
+    }
+    isAnimating.value = false;
+  };
+
+  const viewport = (): BoardViewport => toValue(viewportSize);
+  const contentRect = (): BoardRect => toValue(content);
+
+  const clampCam = (cam: BoardCamera): BoardCamera => {
+    const k = Math.min(maxK, Math.max(minK, cam.k));
+    return boardClampPan({ ...cam, k }, contentRect(), viewport());
+  };
+
+  function animateTo(target: BoardCamera): void {
+    const doSnap = !animated || prefersReducedMotion();
+    if (doSnap) {
+      stopTween();
+      camera.value = clampCam(target);
+      return;
+    }
+    tweenFrom = { ...camera.value };
+    tweenTo = target;
+    tweenStart = performance.now();
+    isAnimating.value = true;
+    if (raf) window.cancelAnimationFrame(raf);
+    const step = (now: number): void => {
+      const t = Math.min(1, (now - tweenStart) / BOARD_ANIM_MS);
+      camera.value = clampCam(boardTweenCam(tweenFrom, tweenTo, t));
+      if (t < 1) {
+        raf = window.requestAnimationFrame(step);
+      } else {
+        raf = 0;
+        isAnimating.value = false;
+      }
+    };
+    raf = window.requestAnimationFrame(step);
+  }
+
+  const anchorPoint = (anchor?: BoardPoint): BoardPoint => {
+    const vp = viewport();
+    return anchor ?? { x: vp.w / 2, y: vp.h / 2 };
+  };
+
+  function zoomByFactor(factor: number, anchor?: BoardPoint): void {
+    const next = boardZoomAt(camera.value, camera.value.k * factor, anchorPoint(anchor));
+    animateTo({ ...next, k: quantizeBoardK(next.k) });
+  }
+
+  function zoomToK(targetK: number, anchor?: BoardPoint): void {
+    const next = boardZoomAt(camera.value, targetK, anchorPoint(anchor));
+    animateTo({ ...next, k: quantizeBoardK(next.k) });
+  }
+
+  function zoomToPercent(percent: number, anchor?: BoardPoint): void {
+    zoomToK(Math.min(maxK, Math.max(minK, percent / 100)), anchor);
+  }
+
+  function zoomIn(): void {
+    zoomByFactor(BOARD_ZOOM_FACTOR);
+  }
+
+  function zoomOut(): void {
+    zoomByFactor(1 / BOARD_ZOOM_FACTOR);
+  }
+
+  function pinchZoom(base: BoardCamera, ratio: number, anchor: BoardPoint): void {
+    // Raw and continuous while the fingers move; quantized on release.
+    stopTween();
+    camera.value = clampCam(boardZoomAt(base, base.k * ratio, anchor));
+  }
+
+  function settlePinch(): void {
+    const settled = { ...camera.value, k: quantizeBoardK(camera.value.k) };
+    animateTo(settled);
+  }
+
+  function panBy(dx: number, dy: number): void {
+    stopTween();
+    camera.value = clampCam({ ...camera.value, x: camera.value.x + dx, y: camera.value.y + dy });
+  }
+
+  function setCamera(cam: BoardCamera, opts: { animate?: boolean } = {}): void {
+    if (opts.animate) animateTo(cam);
+    else {
+      stopTween();
+      camera.value = clampCam(cam);
+    }
+  }
+
+  function fit(): void {
+    animateTo(boardFit(contentRect(), viewport()));
+  }
+
+  function reset(): void {
+    fit();
+  }
+
+  function screenToWorld(p: BoardPoint): BoardPoint {
+    const c = camera.value;
+    return { x: (p.x - c.x) / c.k, y: (p.y - c.y) / c.k };
+  }
+
+  function worldToScreen(p: BoardPoint): BoardPoint {
+    const c = camera.value;
+    return { x: p.x * c.k + c.x, y: p.y * c.k + c.y };
+  }
+
+  return {
+    camera,
+    isAnimating,
+    screenToWorld,
+    worldToScreen,
+    zoomByFactor,
+    zoomToK,
+    zoomToPercent,
+    zoomIn,
+    zoomOut,
+    pinchZoom,
+    settlePinch,
+    panBy,
+    setCamera,
+    fit,
+    reset,
+  };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export { default as HAlert } from "./components/HkAlert";
 export { default as HAltSignIn } from "./components/HkAltSignIn";
 export { default as HAvatar } from "./components/HkAvatar";
 export { default as HBadge } from "./components/HkBadge";
+export { default as HBoard } from "./components/HkBoard";
 export { default as HBlockingToast } from "./components/HkBlockingToast";
 export { default as HBreadcrumb } from "./components/HkBreadcrumb";
 export { default as HButton } from "./components/HkButton";
@@ -105,6 +106,9 @@ export { default as HLogo } from "./components/HkLogo";
 
 // Component types
 export { type BadgeVariant } from "./components/HkBadge";
+export { type BoardNodeInput, type BoardEdgeInput } from "./components/HkBoard";
+export { type BoardAnchorMode, type BoardEdgeStyle, type BoardPoint } from "./utils/boardEdges";
+export { type BoardCamera, type BoardRect, type BoardViewport } from "./utils/boardCamera";
 export { type ModalAction } from "./components/HkModal";
 export { type TreeNode, type TreeSize, type TreeRowScope } from "./components/HkTree";
 export { type DragListItem } from "./components/HkDraggableList";

package/src/utils/boardCamera.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BOARD_FIT_CAP,
+  BOARD_ZOOM_FACTOR,
+  boardBBox,
+  boardClampPan,
+  boardEaseOutCubic,
+  boardFit,
+  boardLevelOf,
+  boardToScreen,
+  boardTweenCam,
+  boardToWorld,
+  boardZoomAt,
+  quantizeBoardK,
+  quantizeBoardStep,
+} from "./boardCamera";
+
+describe("boardCamera — 5% geometric ladder", () => {
+  it("snaps arbitrary zooms onto 1.05ⁿ rungs", () => {
+    expect(quantizeBoardK(1)).toBe(1);
+    expect(quantizeBoardK(1.02)).toBe(1);
+    expect(quantizeBoardK(1.04)).toBeCloseTo(1.05, 5);
+    expect(quantizeBoardK(BOARD_ZOOM_FACTOR ** 3)).toBeCloseTo(BOARD_ZOOM_FACTOR ** 3, 5);
+  });
+
+  it("clamps to the global zoom bounds", () => {
+    expect(quantizeBoardK(0.01)).toBeLessThanOrEqual(0.2);
+    expect(quantizeBoardK(99)).toBeGreaterThanOrEqual(4);
+  });
+
+  it("quantizes a pinch step relative to its base", () => {
+    const base = 0.8;
+    // a pinch whose raw target is exactly two rungs above the base lands
+    // there: base·1.05² (ratio = raw/base)
+    expect(quantizeBoardStep(base, 1.05 ** 2)).toBeCloseTo(base * BOARD_ZOOM_FACTOR ** 2, 5);
+    // a ratio inside the same rung stays on the base rung
+    expect(quantizeBoardStep(base, 1.02)).toBeCloseTo(base, 5);
+  });
+});
+
+describe("boardCamera — anchor zoom", () => {
+  it("keeps the world point under the screen anchor fixed", () => {
+    const cam = { x: 40, y: -20, k: 1 };
+    const anchor = { x: 300, y: 200 };
+    const worldBefore = boardToWorld(cam, anchor.x, anchor.y);
+    const zoomed = boardZoomAt(cam, 1.5, anchor);
+    const worldAfter = boardToWorld(zoomed, anchor.x, anchor.y);
+    expect(worldAfter.x).toBeCloseTo(worldBefore.x, 6);
+    expect(worldAfter.y).toBeCloseTo(worldBefore.y, 6);
+    expect(zoomed.k).toBe(1.5);
+  });
+
+  it("round-trips screen→world→screen", () => {
+    const cam = { x: -130, y: 88, k: 1.3 };
+    const p = boardToScreen(cam, 42, -7);
+    const w = boardToWorld(cam, p.x, p.y);
+    expect(w.x).toBeCloseTo(42, 6);
+    expect(w.y).toBeCloseTo(-7, 6);
+  });
+});
+
+describe("boardCamera — pan clamp + fit", () => {
+  const content = { x: 0, y: 0, w: 2000, h: 1200 };
+  const viewport = { w: 800, h: 600 };
+
+  it("keeps half a viewport of slack for oversized content", () => {
+    const cam = boardClampPan({ k: 1, x: 9999, y: -9999 }, content, viewport);
+    expect(cam.x).toBeLessThanOrEqual(400);
+    expect(cam.y).toBeGreaterThanOrEqual(-1200 - 300);
+  });
+
+  it("re-centers content smaller than the viewport", () => {
+    const small = { x: 0, y: 0, w: 200, h: 100 };
+    const cam = boardClampPan({ k: 1, x: -500, y: 999 }, small, viewport);
+    expect(cam.x).toBe((viewport.w - 200) / 2);
+    expect(cam.y).toBe((viewport.h - 100) / 2);
+  });
+
+  it("fits the whole board with padding and honors the cap", () => {
+    const cam = boardFit(content, viewport);
+    expect(cam.k).toBeCloseTo(Math.min((800 - 80) / 2000, (600 - 80) / 1200), 6);
+    const tiny = boardFit({ x: 0, y: 0, w: 60, h: 40 }, viewport);
+    expect(tiny.k).toBeLessThanOrEqual(BOARD_FIT_CAP);
+  });
+});
+
+describe("boardCamera — animated tween", () => {
+  it("interpolates k geometrically and eases the endpoints", () => {
+    const from = { x: 0, y: 0, k: 1 };
+    const to = { x: 100, y: -50, k: 1.05 ** 4 };
+    // t=0.5 eases to 0.875 — the geometric mid sits at that eased point
+    const half = boardTweenCam(from, to, 0.5);
+    const eased = boardEaseOutCubic(0.5);
+    expect(half.k).toBeCloseTo(from.k * (to.k / from.k) ** eased, 6);
+    expect(half.x).toBeGreaterThan(0);
+    const done = boardTweenCam(from, to, 1);
+    expect(done).toEqual(to);
+    const start = boardTweenCam(from, to, 0);
+    expect(start).toEqual(from);
+  });
+
+  it("reports the ladder level consistently", () => {
+    expect(boardLevelOf(1)).toBe(0);
+    expect(boardLevelOf(BOARD_ZOOM_FACTOR)).toBeCloseTo(1, 6);
+  });
+});
+
+describe("boardCamera — content bbox", () => {
+  it("unions rects and ignores empty ones", () => {
+    const box = boardBBox([
+      { x: 10, y: 10, w: 100, h: 50 },
+      { x: 200, y: 0, w: 50, h: 40 },
+      { x: 0, y: 0, w: 0, h: 0 },
+    ]);
+    expect(box).toEqual({ x: 10, y: 0, w: 240, h: 60 });
+  });
+
+  it("falls back to a default rect with no content", () => {
+    expect(boardBBox([]).w).toBeGreaterThan(0);
+  });
+});

package/src/utils/boardCamera.ts

@@ -0,0 +1,194 @@
+/**
+ * boardCamera.ts — pure world-camera math for HkBoard.
+ *
+ * A board lives in a fixed WORLD coordinate space; the camera maps
+ * world → screen (`screen = world·k + (x, y)`, `transform-origin: 0 0`).
+ * This module owns the rules that keep the viewport decoupled from the
+ * graph, so every consumer (topic maps, SCADA scenes, PLC panels, …)
+ * shares ONE motion feel:
+ *
+ *  - zoom is a GEOMETRIC 5% ladder (`k = 1.05ⁿ`): gestures accumulate
+ *    into a continuous level and the applied zoom snaps to the rung;
+ *  - `boardZoomAt` keeps the world point under a screen anchor (cursor /
+ *    pinch midpoint) visually fixed while k changes;
+ *  - pan is CLAMPED so the content bbox can never be pushed fully out of
+ *    view (half a viewport of slack on each side); content smaller than
+ *    the viewport re-centers;
+ *  - `boardFit` fits the whole bbox (pad + floor + cap);
+ *  - `boardTweenCam` eases between two cameras with an ease-out curve and
+ *    GEOMETRIC k interpolation (log-space lerp) so animated zooms still
+ *    land exactly on ladder rungs.
+ *
+ * Pure functions only — HkBoard / useBoardCamera supply state, timing and
+ * gestures. Semantics intentionally mirror the chest SCADA scene camera
+ * (the first consumer of this contract).
+ */
+
+export interface BoardCamera {
+  x: number;
+  y: number;
+  k: number;
+}
+
+export interface BoardRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface BoardPoint {
+  x: number;
+  y: number;
+}
+
+export interface BoardViewport {
+  w: number;
+  h: number;
+}
+
+/** One zoom step = ±5% (geometric). */
+export const BOARD_ZOOM_FACTOR = 1.05;
+export const BOARD_K_MIN = 0.2;
+export const BOARD_K_MAX = 4;
+/** fit() may shrink as far as needed to show the whole board. */
+export const BOARD_FIT_FLOOR = 0.2;
+/** fit() never blows above this (nearly-empty boards). */
+export const BOARD_FIT_CAP = 1.25;
+/** Padding around the bbox used by fit(), world px. */
+export const BOARD_FIT_PAD = 40;
+
+export const boardLevelOf = (k: number): number =>
+  Math.log(k) / Math.log(BOARD_ZOOM_FACTOR);
+
+export const boardKOf = (level: number): number =>
+  Math.pow(BOARD_ZOOM_FACTOR, level);
+
+export const boardClampK = (k: number): number =>
+  Math.min(BOARD_K_MAX, Math.max(BOARD_K_MIN, k));
+
+/** Clamp a raw zoom into the legal ladder, snapped to a 5% rung. */
+export function quantizeBoardK(k: number): number {
+  const clamped = boardClampK(k);
+  if (clamped <= BOARD_K_MIN) return BOARD_K_MIN;
+  if (clamped >= BOARD_K_MAX) return BOARD_K_MAX;
+  return boardKOf(Math.round(boardLevelOf(clamped)));
+}
+
+/**
+ * Quantize a zoom CHANGE (relative rung ladder anchored at `base`):
+ * base·ratio stays exactly on `base·1.05ⁿ`, so a pinch always feels like
+ * clean 5% steps from wherever the gesture started. Clamped to the
+ * global bounds.
+ */
+export function quantizeBoardStep(base: number, ratio: number): number {
+  const raw = base * ratio;
+  const level = Math.round(boardLevelOf(raw) - boardLevelOf(base));
+  return boardClampK(base * boardKOf(level));
+}
+
+export function boardToScreen(cam: BoardCamera, wx: number, wy: number): BoardPoint {
+  return { x: wx * cam.k + cam.x, y: wy * cam.k + cam.y };
+}
+
+export function boardToWorld(cam: BoardCamera, sx: number, sy: number): BoardPoint {
+  return { x: (sx - cam.x) / cam.k, y: (sy - cam.y) / cam.k };
+}
+
+/**
+ * Zoom while keeping the world point under the screen anchor visually
+ * fixed (cursor / pinch midpoint zoom). The result is NOT rung-quantized —
+ * callers quantize when they want the ladder (see quantizeBoardK).
+ */
+export function boardZoomAt(
+  cam: BoardCamera,
+  targetK: number,
+  anchorScreen: BoardPoint,
+): BoardCamera {
+  const k = boardClampK(targetK);
+  const world = boardToWorld(cam, anchorScreen.x, anchorScreen.y);
+  return { k, x: anchorScreen.x - world.x * k, y: anchorScreen.y - world.y * k };
+}
+
+/**
+ * Clamp the pan so the content bbox can never be dragged fully out of
+ * view: content larger than the viewport keeps half a viewport of slack
+ * on each side; content smaller than the viewport re-centers.
+ */
+export function boardClampPan(
+  cam: BoardCamera,
+  content: BoardRect,
+  viewport: BoardViewport,
+  slack = 0.5,
+): BoardCamera {
+  const clampAxis = (pan: number, view: number, size: number): number => {
+    const drawn = size * cam.k;
+    if (drawn <= view) return (view - drawn) / 2;
+    const slackPx = view * slack;
+    return Math.min(Math.max(pan, view - drawn - slackPx), slackPx);
+  };
+  return {
+    k: cam.k,
+    x: clampAxis(cam.x, viewport.w, content.w),
+    y: clampAxis(cam.y, viewport.h, content.h),
+  };
+}
+
+/**
+ * Fit the whole content bbox into the viewport (centered, padded). Wide
+ * boards shrink fully into view; tiny boards never blow up past the cap.
+ */
+export function boardFit(
+  content: BoardRect,
+  viewport: BoardViewport,
+  opts: { pad?: number; floor?: number; cap?: number } = {},
+): BoardCamera {
+  const pad = opts.pad ?? BOARD_FIT_PAD;
+  const floor = opts.floor ?? BOARD_FIT_FLOOR;
+  const cap = opts.cap ?? BOARD_FIT_CAP;
+  const kw = content.w > 0 ? (viewport.w - pad * 2) / content.w : cap;
+  const kh = content.h > 0 ? (viewport.h - pad * 2) / content.h : cap;
+  const k = Math.min(cap, Math.max(floor, Math.min(kw, kh)));
+  return {
+    k,
+    x: (viewport.w - content.w * k) / 2 - content.x * k,
+    y: (viewport.h - content.h * k) / 2 - content.y * k,
+  };
+}
+
+export const boardEaseOutCubic = (t: number): number => 1 - Math.pow(1 - t, 3);
+
+const clamp01 = (t: number): number => Math.min(1, Math.max(0, t));
+
+/**
+ * Interpolate between two cameras for an animated transition. Pan lerps
+ * linearly, k interpolates GEOMETRICALLY (log-space) so a tween between
+ * two ladder rungs passes through intermediate rungs, not linear noise.
+ * `t` is clamped to [0, 1] and eased with ease-out cubic.
+ */
+export function boardTweenCam(from: BoardCamera, to: BoardCamera, t: number): BoardCamera {
+  const e = boardEaseOutCubic(clamp01(t));
+  const k = from.k > 0 && to.k > 0 ? from.k * Math.pow(to.k / from.k, e) : to.k;
+  return {
+    k,
+    x: from.x + (to.x - from.x) * e,
+    y: from.y + (to.y - from.y) * e,
+  };
+}
+
+/** Union of rects (ignoring empty ones) — the content bbox for clamp/fit. */
+export function boardBBox(rects: BoardRect[]): BoardRect {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const r of rects) {
+    if (r.w <= 0 || r.h <= 0) continue;
+    minX = Math.min(minX, r.x);
+    minY = Math.min(minY, r.y);
+    maxX = Math.max(maxX, r.x + r.w);
+    maxY = Math.max(maxY, r.y + r.h);
+  }
+  if (!Number.isFinite(minX)) return { x: 0, y: 0, w: 1200, h: 800 };
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}

package/src/utils/boardEdges.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  boardAnchor,
+  boardEdgePath,
+  boardViaPath,
+  type BoardNodeRect,
+} from "./boardEdges";
+
+const rect: BoardNodeRect = { x: 100, y: 100, w: 120, h: 60 };
+const rightTarget = { x: 400, y: 130 };
+const belowTarget = { x: 160, y: 400 };
+
+describe("boardEdges — anchor modes", () => {
+  it("center exits through the facing border midpoint", () => {
+    const a = boardAnchor(rect, "center", rightTarget);
+    expect(a.y).toBe(130);
+    expect(a.x).toBe(220);
+  });
+
+  it("top pins to the top-border midpoint, top-left to the corner", () => {
+    expect(boardAnchor(rect, "top", belowTarget)).toEqual({ x: 160, y: 100 });
+    expect(boardAnchor(rect, "top-left", belowTarget)).toEqual({ x: 100, y: 100 });
+  });
+
+  it("nearest snaps to the closest perimeter point", () => {
+    const a = boardAnchor(rect, "nearest", { x: 500, y: 105 });
+    expect(a).toEqual({ x: 220, y: 105 });
+  });
+
+  it("fan spreads multiple edges along the exit border", () => {
+    const first = boardAnchor(rect, "fan", rightTarget, 0, 3);
+    const second = boardAnchor(rect, "fan", rightTarget, 1, 3);
+    const third = boardAnchor(rect, "fan", rightTarget, 2, 3);
+    expect(first.x).toBe(220);
+    expect(first.y).toBeLessThan(second.y);
+    expect(second.y).toBeLessThan(third.y);
+    expect(new Set([first.y, second.y, third.y]).size).toBe(3);
+  });
+});
+
+describe("boardEdges — route styles", () => {
+  const a = { x: 220, y: 130 };
+  const b = { x: 400, y: 260 };
+
+  it("straight is a single segment", () => {
+    expect(boardEdgePath(a, b, "straight")).toBe("M 220 130 L 400 260");
+  });
+
+  it("bezier is a horizontal-tangent cubic", () => {
+    const d = boardEdgePath(a, b, "bezier");
+    expect(d).toContain("C 310 130, 310 260, 400 260");
+  });
+
+  it("orthogonal elbows through the mid X", () => {
+    expect(boardEdgePath(a, b, "orthogonal")).toBe("M 220 130 H 310 V 260 H 400");
+  });
+
+  it("spine drops vertically first", () => {
+    expect(boardEdgePath(a, b, "spine")).toBe("M 220 130 V 195 H 400 V 260");
+  });
+});
+
+describe("boardEdges — via (empty corner nodes)", () => {
+  const a = { x: 0, y: 0 };
+  const corner = { x: 200, y: 200 };
+  const b = { x: 400, y: 200 };
+
+  it("chains orthogonal legs through the via point", () => {
+    const d = boardViaPath(a, [corner], b, "orthogonal");
+    // leg1: M 0 0 H 100 V 200 ; leg2: H 300 V 200 H 400 — a clean Z
+    expect(d).toContain("H 100 V 200");
+    expect(d).toContain("V 200 H 400");
+  });
+
+  it("chains straight legs as a polyline through the via point", () => {
+    const d = boardViaPath(a, [corner], b, "straight");
+    expect(d).toBe("M 0 0 L 200 200 L 400 200");
+  });
+
+  it("smooths multi-via bezier chains", () => {
+    const d = boardViaPath(a, [{ x: 100, y: 300 }, { x: 300, y: 300 }], b, "bezier");
+    expect(d.startsWith("M 0 0 C ")).toBe(true);
+    expect(d).toContain("400 200");
+  });
+});

package/src/utils/boardEdges.ts

@@ -0,0 +1,185 @@
+/**
+ * boardEdges.ts — pure anchor + path geometry for HkBoard edges.
+ *
+ * Edges connect node rects. The two independently-configurable halves of
+ * that contract:
+ *
+ *  - ANCHOR MODE (`BoardAnchorMode`) — where on the node border an edge
+ *    attaches:
+ *      • "center"   — the border point the center→center ray exits through
+ *                     (the classic mind-map / graph look);
+ *      • "nearest"  — the border point closest to the other end;
+ *      • "top"      — top-border midpoint (top-aligned columns, SCADA-style
+ *                     vertical drops);
+ *      • "top-left" — the top-left corner (top-left aligned rows);
+ *      • "fan"      — 天女散花: when one node feeds SEVERAL edges, the
+ *                     attach points spread evenly across the exit border
+ *                     instead of stacking on one dot (pass index/count).
+ *
+ *  - ROUTE STYLE (`BoardEdgeStyle`) — how the two anchors join:
+ *      • "straight"   — a straight segment;
+ *      • "bezier"     — a horizontal-tangent cubic (flowing curve);
+ *      • "orthogonal" — strict elbow (H-V-H), the SCADA pipe discipline;
+ *      • "spine"      — vertical-first elbow (V-H), for tree rails.
+ *
+ * Edges may also route THROUGH empty corner nodes: `boardViaPath` chains
+ * the segment builders across the via points (the centers of invisible
+ * junction nodes), which is how consumers bake a right-angle turn into
+ * the graph itself.
+ *
+ * Pure functions only — path strings are world-space SVG `d` attributes.
+ */
+
+export interface BoardPoint {
+  x: number;
+  y: number;
+}
+
+export interface BoardNodeRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export type BoardAnchorMode = "center" | "nearest" | "top" | "top-left" | "fan";
+
+export type BoardEdgeStyle = "straight" | "bezier" | "orthogonal" | "spine";
+
+const r1 = (n: number): number => Math.round(n * 10) / 10;
+
+/** Border point of `rect` where the ray from rect center toward `to`
+ *  exits the rect. Falls back to the facing-border midpoint on degenerate
+ *  (zero-size) rects. */
+function centerExit(rect: BoardNodeRect, to: BoardPoint): BoardPoint {
+  const cx = rect.x + rect.w / 2;
+  const cy = rect.y + rect.h / 2;
+  const dx = to.x - cx;
+  const dy = to.y - cy;
+  if (dx === 0 && dy === 0) return { x: cx, y: rect.y };
+  const hw = rect.w / 2;
+  const hh = rect.h / 2;
+  const sx = dx !== 0 ? hw / Math.abs(dx) : Infinity;
+  const sy = dy !== 0 ? hh / Math.abs(dy) : Infinity;
+  const s = Math.min(sx, sy);
+  return { x: cx + dx * s, y: cy + dy * s };
+}
+
+/** Closest point of `rect` perimeter to `to`. */
+function nearestPoint(rect: BoardNodeRect, to: BoardPoint): BoardPoint {
+  const cx = rect.x + rect.w / 2;
+  const cy = rect.y + rect.h / 2;
+  const dx = to.x - cx;
+  const dy = to.y - cy;
+  if (dx === 0 && dy === 0) return { x: cx, y: rect.y };
+  const hw = rect.w / 2;
+  const hh = rect.h / 2;
+  const sx = dx !== 0 ? hw / Math.abs(dx) : Infinity;
+  const sy = dy !== 0 ? hh / Math.abs(dy) : Infinity;
+  if (sx < sy) {
+    return { x: cx + Math.sign(dx) * hw, y: Math.min(Math.max(to.y, rect.y), rect.y + rect.h) };
+  }
+  return { x: Math.min(Math.max(to.x, rect.x), rect.x + rect.w), y: cy + Math.sign(dy) * hh };
+}
+
+/**
+ * Resolve the anchor point on `rect` for an edge toward `to`.
+ * `index`/`count` only matter for "fan" (even spread along the exit
+ * border; no-ops when count ≤ 1).
+ */
+export function boardAnchor(
+  rect: BoardNodeRect,
+  mode: BoardAnchorMode,
+  to: BoardPoint,
+  index = 0,
+  count = 1,
+): BoardPoint {
+  switch (mode) {
+    case "top":
+      return { x: rect.x + rect.w / 2, y: rect.y };
+    case "top-left":
+      return { x: rect.x, y: rect.y };
+    case "nearest":
+      return nearestPoint(rect, to);
+    case "fan": {
+      const base = centerExit(rect, to);
+      if (count <= 1) return base;
+      // Spread along the exit border (whichever side centerExit left
+      // through) between 1/(count+1) and count/(count+1) of the side.
+      const t = (index + 1) / (count + 1);
+      const dx = to.x - (rect.x + rect.w / 2);
+      const dy = to.y - (rect.y + rect.h / 2);
+      const vertical = Math.abs(dy) * rect.w >= Math.abs(dx) * rect.h;
+      if (vertical) {
+        const x = rect.x + rect.w * t;
+        return { x, y: dy < 0 ? rect.y : rect.y + rect.h };
+      }
+      const y = rect.y + rect.h * t;
+      return { x: dx < 0 ? rect.x : rect.x + rect.w, y };
+    }
+    case "center":
+    default:
+      return centerExit(rect, to);
+  }
+}
+
+/** Segment WITHOUT the leading "M x y" — the drawable tail from `a` into
+ *  `b`, so multi-leg paths can chain tails end to end. */
+function segmentTail(a: BoardPoint, b: BoardPoint, style: BoardEdgeStyle): string {
+  switch (style) {
+    case "bezier": {
+      const dx = (b.x - a.x) / 2;
+      return `C ${r1(a.x + dx)} ${r1(a.y)}, ${r1(b.x - dx)} ${r1(b.y)}, ${r1(b.x)} ${r1(b.y)}`;
+    }
+    case "orthogonal": {
+      const midX = r1((a.x + b.x) / 2);
+      return `H ${midX} V ${r1(b.y)} H ${r1(b.x)}`;
+    }
+    case "spine": {
+      const midY = r1((a.y + b.y) / 2);
+      return `V ${midY} H ${r1(b.x)} V ${r1(b.y)}`;
+    }
+    case "straight":
+    default:
+      return `L ${r1(b.x)} ${r1(b.y)}`;
+  }
+}
+
+/** One edge between two anchor points. */
+export function boardEdgePath(a: BoardPoint, b: BoardPoint, style: BoardEdgeStyle): string {
+  return `M ${r1(a.x)} ${r1(a.y)} ${segmentTail(a, b, style)}`;
+}
+
+/**
+ * One edge routed THROUGH via points (the centers of empty corner/junction
+ * nodes). The style applies to every leg; orthogonal legs chain into clean
+ * right angles, straight legs chain into a polyline, bezier legs chain
+ * with smooth midpoints so long vias read as one flowing curve.
+ */
+export function boardViaPath(
+  a: BoardPoint,
+  via: BoardPoint[],
+  b: BoardPoint,
+  style: BoardEdgeStyle,
+): string {
+  const pts = [a, ...via, b];
+  if (pts.length < 2) return "";
+  if (style === "bezier" && pts.length > 2) {
+    // Smooth chain: cubic legs with tangents from the neighbor midpoints.
+    let d = `M ${r1(pts[0].x)} ${r1(pts[0].y)}`;
+    for (let i = 1; i < pts.length; i++) {
+      const prev = pts[i - 1];
+      const cur = pts[i];
+      const next = pts[Math.min(i + 1, pts.length - 1)];
+      const t1 = i === 1 ? prev : { x: (prev.x + cur.x) / 2, y: (prev.y + cur.y) / 2 };
+      const t2 = i === pts.length - 1 ? cur : { x: (cur.x + next.x) / 2, y: (cur.y + next.y) / 2 };
+      d += ` C ${r1(t1.x)} ${r1(t1.y)}, ${r1(t2.x)} ${r1(t2.y)}, ${r1(cur.x)} ${r1(cur.y)}`;
+    }
+    return d;
+  }
+  let d = `M ${r1(pts[0].x)} ${r1(pts[0].y)}`;
+  for (let i = 1; i < pts.length; i++) {
+    d += ` ${segmentTail(pts[i - 1], pts[i], style)}`;
+  }
+  return d;
+}