@matchina/viz-svg 0.1.0-alpha.1

package/src/elk-layout.ts

@@ -0,0 +1,279 @@
+// ELK layout adapter for MachineShape.
+// Uses LCA-based edge placement (edges live in their lowest common ancestor container).
+// Returns flat arrays with absolute positions — no ReactFlow dependency.
+
+import ELKConstructor from 'elkjs/lib/elk.bundled.js';
+import type { MachineShape } from 'matchina';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const elk = new (ELKConstructor as any)();
+
+export interface SvgNode {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  label: string;
+  isCompound: boolean;
+  path: string[];
+}
+
+export interface SvgEdge {
+  id: string;
+  event: string;
+  sourcePath: string[];
+  targetPath: string[];
+  sections: {
+    startPoint: { x: number; y: number };
+    endPoint: { x: number; y: number };
+    bendPoints?: { x: number; y: number }[];
+  }[];
+  label: { text: string; x: number; y: number; width: number; height: number } | null;
+}
+
+export interface SvgLayout {
+  nodes: SvgNode[];
+  edges: SvgEdge[];
+  width: number;
+  height: number;
+}
+
+export interface ElkLayoutOptions {
+  direction?: 'RIGHT' | 'DOWN';
+  edgeRouting?: 'ORTHOGONAL' | 'POLYLINE';
+  nodeSpacing?: number;
+  layerSpacing?: number;
+}
+
+// ELK parses dots in node IDs as "nodeId.portId", so sanitize them.
+function toElkId(fullKey: string): string { return fullKey.replace(/\./g, '|'); }
+function fromElkId(id: string): string { return id.replace(/\|/g, '.'); }
+
+function textWidth(text: string, charW = 7.2, pad = 24): number {
+  return Math.max(60, Math.ceil(text.length * charW) + pad);
+}
+
+function lcaPath(a: string[], b: string[]): string[] {
+  const out: string[] = [];
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i] === b[i]) out.push(a[i]);
+    else break;
+  }
+  return out;
+}
+
+type ElkNodeDraft = {
+  id: string;
+  labels: { text: string; width: number; height: number }[];
+  layoutOptions: Record<string, string | undefined>;
+  width?: number;
+  height?: number;
+  children?: ElkNodeDraft[];
+  edges?: ElkEdgeDraft[];
+  _meta: { path: string[]; isCompound: boolean };
+};
+
+type ElkEdgeDraft = {
+  id: string;
+  sources: string[];
+  targets: string[];
+  labels: { text: string; width: number; height: number }[];
+  _meta: { event: string; sourcePath: string[]; targetPath: string[] };
+};
+
+function buildElkNode(
+  fullKey: string,
+  shape: MachineShape,
+  nodeSpacing: number,
+  layerSpacing: number,
+  direction: string,
+): ElkNodeDraft {
+  const stateNode = shape.states.get(fullKey)!;
+  const label = stateNode.key;
+  const isCompound = stateNode.isCompound;
+  const path = fullKey.split('.');
+
+  const node: ElkNodeDraft = {
+    id: toElkId(fullKey),
+    labels: [{ text: label, width: textWidth(label, 7.5, 16), height: 18 }],
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': direction,
+      'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+      'elk.spacing.nodeNode': String(nodeSpacing),
+      'elk.spacing.edgeNode': String(nodeSpacing * 0.5),
+      'elk.layered.cycleBreaking.strategy': 'MODEL_ORDER',
+      'elk.layered.considerModelOrder': 'NODES_AND_EDGES',
+    },
+    _meta: { path, isCompound },
+  };
+
+  if (!isCompound) {
+    node.width = Math.max(textWidth(label, 8, 32), 92);
+    node.height = 44;
+  } else {
+    node.layoutOptions['elk.hierarchyHandling'] = 'INCLUDE_CHILDREN';
+    node.layoutOptions['elk.padding'] =
+      `[top=36,left=${nodeSpacing * 0.6},bottom=${nodeSpacing * 0.6},right=${nodeSpacing * 0.6}]`;
+
+    // Find children via hierarchy map
+    const children: string[] = [];
+    for (const [childKey, parentKey] of shape.hierarchy) {
+      if (parentKey === fullKey) children.push(childKey);
+    }
+    node.children = children.map(childKey =>
+      buildElkNode(childKey, shape, nodeSpacing, layerSpacing, direction),
+    );
+  }
+
+  return node;
+}
+
+function indexNodes(node: ElkNodeDraft, byId: Map<string, ElkNodeDraft>): void {
+  byId.set(node.id, node);
+  for (const child of node.children ?? []) indexNodes(child, byId);
+}
+
+export async function runElkLayout(
+  shape: MachineShape,
+  opts: ElkLayoutOptions = {},
+): Promise<SvgLayout> {
+  const nodeSpacing = opts.nodeSpacing ?? 40;
+  const layerSpacing = opts.layerSpacing ?? nodeSpacing + 20;
+  const direction = opts.direction ?? 'DOWN';
+  const edgeRouting = opts.edgeRouting ?? 'ORTHOGONAL';
+
+  // Root states: those without a parent
+  const rootKeys: string[] = [];
+  for (const [fullKey, parentKey] of shape.hierarchy) {
+    if (parentKey === undefined && fullKey !== '') rootKeys.push(fullKey);
+  }
+
+  const rootChildren = rootKeys.map(key =>
+    buildElkNode(key, shape, nodeSpacing, layerSpacing, direction),
+  );
+
+  // Build id → node index for LCA edge assignment
+  const byId = new Map<string, ElkNodeDraft>();
+  for (const child of rootChildren) indexNodes(child, byId);
+
+  // Assign edges to their LCA container
+  const rootEdges: ElkEdgeDraft[] = [];
+  for (const [sourceFullKey, eventMap] of shape.transitions) {
+    for (const [event, targetFullKey] of eventMap) {
+      if (!shape.states.has(targetFullKey)) continue;
+      if (!byId.has(toElkId(sourceFullKey)) || !byId.has(toElkId(targetFullKey))) continue;
+
+      const sourcePath = sourceFullKey.split('.');
+      const targetPath = targetFullKey.split('.');
+      const edge: ElkEdgeDraft = {
+        id: `e:${toElkId(sourceFullKey)}->${toElkId(targetFullKey)}:${event}`,
+        sources: [toElkId(sourceFullKey)],
+        targets: [toElkId(targetFullKey)],
+        labels: [{ text: event, width: textWidth(event, 6.6, 14), height: 16 }],
+        _meta: { event, sourcePath, targetPath },
+      };
+
+      const lca = lcaPath(sourcePath, targetPath);
+      const lcaKey = lca.join('.');
+      const owner = lcaKey ? byId.get(toElkId(lcaKey)) : null;
+      if (owner?.children) {
+        owner.edges = owner.edges ?? [];
+        owner.edges.push(edge);
+      } else {
+        rootEdges.push(edge);
+      }
+    }
+  }
+
+  const elkInput = {
+    id: 'root',
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': direction,
+      'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+      'elk.edgeRouting': edgeRouting,
+      'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+      'elk.spacing.nodeNode': String(nodeSpacing),
+      // Keep parallel edges visually separate — don't merge or collapse them.
+      'elk.layered.mergeEdges': 'false',
+      'elk.layered.mergeHierarchyEdges': 'false',
+      'elk.layered.cycleBreaking.strategy': 'MODEL_ORDER',
+      'elk.layered.considerModelOrder': 'NODES_AND_EDGES',
+      'elk.padding': `[top=${nodeSpacing * 0.6},left=${nodeSpacing * 0.6},bottom=${nodeSpacing * 0.6},right=${nodeSpacing * 0.6}]`,
+    },
+    children: rootChildren,
+    edges: rootEdges,
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await elk.layout(elkInput as any) as any;
+
+  // Flatten tree → absolute-positioned arrays
+  const nodes: SvgNode[] = [];
+  const edges: SvgEdge[] = [];
+  const absById = new Map<string, { x: number; y: number }>();
+  absById.set('root', { x: 0, y: 0 });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function walkNodes(node: any, ox: number, oy: number): void {
+    const ax = (node.x ?? 0) + ox;
+    const ay = (node.y ?? 0) + oy;
+    absById.set(node.id, { x: ax, y: ay });
+
+    if (node.id !== 'root' && node._meta) {
+      nodes.push({
+        id: fromElkId(node.id),
+        x: ax,
+        y: ay,
+        width: node.width ?? 92,
+        height: node.height ?? 44,
+        label: node.labels?.[0]?.text ?? node.id,
+        isCompound: node._meta.isCompound,
+        path: node._meta.path,
+      });
+    }
+    for (const child of (node.children ?? []) as typeof node[]) walkNodes(child, ax, ay);
+  }
+  walkNodes(result, 0, 0);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function walkEdges(node: any): void {
+    for (const edge of node.edges ?? []) {
+      const containerId: string = edge.container ?? node.id ?? 'root';
+      const off = absById.get(containerId) ?? { x: 0, y: 0 };
+      const label = edge.labels?.[0];
+      edges.push({
+        id: edge.id,
+        event: edge._meta?.event ?? '',
+        sourcePath: edge._meta?.sourcePath ?? [],
+        targetPath: edge._meta?.targetPath ?? [],
+        sections: (edge.sections ?? []).map((s: any) => ({
+          startPoint: { x: s.startPoint.x + off.x, y: s.startPoint.y + off.y },
+          endPoint: { x: s.endPoint.x + off.x, y: s.endPoint.y + off.y },
+          bendPoints: (s.bendPoints ?? []).map((b: any) => ({ x: b.x + off.x, y: b.y + off.y })),
+        })),
+        label: label
+          ? {
+              text: label.text,
+              x: (label.x ?? 0) + off.x,
+              y: (label.y ?? 0) + off.y,
+              width: label.width ?? 60,
+              height: label.height ?? 16,
+            }
+          : null,
+      });
+    }
+    for (const child of node.children ?? []) walkEdges(child);
+  }
+  walkEdges(result);
+
+  return {
+    nodes,
+    edges,
+    width: result.width ?? 800,
+    height: result.height ?? 600,
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { SvgInspector } from './SvgInspector.js';
+export type { SvgInspectorProps } from './SvgInspector.js';
+export { runElkLayout } from './elk-layout.js';
+export type { ElkLayoutOptions, SvgLayout, SvgNode, SvgEdge } from './elk-layout.js';
+export { layoutToSvg } from './layout-to-svg.js';
+export type { LayoutToSvgOptions } from './layout-to-svg.js';

package/src/layout-to-svg.ts

@@ -0,0 +1,203 @@
+// Pure SVG string generator from an ELK layout.
+// Mirrors the rendering logic of SvgInspector.tsx, but emits a string instead of React elements.
+// Use this for build-time SSR (e.g. from Astro frontmatter) where no React runtime is needed.
+
+import type { SvgLayout, SvgNode, SvgEdge } from './elk-layout.js';
+import { buildCurvedPath, pathAtT } from './svg-path.js';
+
+// CSS variable names with their default values (dark teal theme).
+// Match SvgInspector.tsx.
+const V = {
+  accent: 'var(--matchina-viz-accent, #2dd4bf)',
+  bg: 'var(--matchina-viz-bg, #0a0f17)',
+  node: 'var(--matchina-viz-node, rgba(28,38,54,0.95))',
+  nodeActive: 'var(--matchina-viz-node-active, rgba(20,90,82,0.85))',
+  nodeCompound: 'var(--matchina-viz-node-compound, rgba(20,28,40,0.7))',
+  border: 'var(--matchina-viz-border, rgba(148,163,184,0.25))',
+  text: 'var(--matchina-viz-text, rgba(226,232,240,0.92))',
+  textActive: 'var(--matchina-viz-text-active, #e6fffb)',
+  edge: 'var(--matchina-viz-edge, rgba(100,116,139,0.55))',
+  labelBg: 'var(--matchina-viz-label-bg, rgba(15,23,33,0.95))',
+  labelBgActive: 'var(--matchina-viz-label-bg-active, rgba(8,47,51,0.95))',
+  labelText: 'var(--matchina-viz-label-text, rgba(203,213,225,0.82))',
+} as const;
+
+const FONT = "var(--matchina-viz-font, 'JetBrains Mono', monospace)";
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function nodeSvg(node: SvgNode, isActive: boolean, isAncestor: boolean): string {
+  const stroke = isActive || isAncestor ? V.accent : V.border;
+  const strokeWidth = isActive ? 2 : isAncestor ? 1.5 : 1;
+  const fill = node.isCompound ? V.nodeCompound : isActive ? V.nodeActive : V.node;
+  const textFill = isActive ? V.textActive : isActive || isAncestor ? V.accent : V.text;
+
+  const rect = `<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="10" ry="10" style="fill:${fill};stroke:${stroke};stroke-width:${strokeWidth}" />`;
+
+  const label = node.isCompound
+    ? `<text x="${node.x + 14}" y="${node.y + 22}" style="fill:${isActive || isAncestor ? V.accent : V.text};font-family:${FONT};font-size:12px;font-weight:600;letter-spacing:0.06em">${esc(node.label)}</text>`
+    : `<text x="${node.x + node.width / 2}" y="${node.y + node.height / 2 + 5}" text-anchor="middle" style="fill:${textFill};font-family:${FONT};font-size:14px;font-weight:${isActive ? 600 : 500}">${esc(node.label)}</text>`;
+
+  const activeDot = isActive && !node.isCompound
+    ? `<circle cx="${node.x + node.width - 10}" cy="${node.y + 10}" r="4" style="fill:${V.accent}"><animate attributeName="opacity" values="1;0.35;1" dur="1.6s" repeatCount="indefinite" /></circle>`
+    : '';
+
+  return `<g data-node-id="${esc(node.id)}" data-active="${isActive}" data-ancestor="${isAncestor}">${rect}${label}${activeDot}</g>`;
+}
+
+function selfLoopSvg(edge: SvgEdge, node: SvgNode, isOutgoing: boolean, loopIndex: number): string {
+  const stroke = isOutgoing ? V.accent : V.edge;
+  const strokeWidth = isOutgoing ? 2 : 1.25;
+  const opacity = isOutgoing ? 1 : 0.65;
+  const markerId = isOutgoing ? 'matchina-svg-arrow-active' : 'matchina-svg-arrow';
+  const { label } = edge;
+
+  const hw = node.width / 2;
+  const hh = node.height / 2;
+  const sx = node.x + hw;
+  const sy = node.y + hh;
+  const loopRadius = 28 + loopIndex * 16;
+
+  const startX = sx + hw - 8 - loopIndex * 2;
+  const startY = sy - hh;
+  const endX = sx + hw;
+  const endY = sy - hh + 8 + loopIndex * 2;
+
+  const d = `M ${startX} ${startY} C ${startX} ${startY - loopRadius}, ${endX + loopRadius} ${endY}, ${endX} ${endY}`;
+  const labelX = sx + hw + loopRadius + 4;
+  const labelY = sy - hh - 10 + loopIndex * (label ? label.height + 8 : 24);
+
+  const path = `<path d="${d}" fill="none" style="stroke:${stroke};stroke-width:${strokeWidth};opacity:${opacity}" marker-end="url(#${markerId})" />`;
+
+  const labelMarkup = label
+    ? `<g transform="translate(${labelX}, ${labelY - label.height / 2})" style="opacity:${opacity}">
+        <rect x="-6" y="-2" width="${label.width + 12}" height="${label.height + 4}" rx="6" ry="6" style="fill:${isOutgoing ? V.labelBgActive : V.labelBg};stroke:${isOutgoing ? V.accent : 'rgba(100,116,139,0.45)'};stroke-width:${isOutgoing ? 1 : 0.75}" />
+        <text x="${label.width / 2}" y="${(label.height + 4) / 2 + 4}" text-anchor="middle" style="fill:${isOutgoing ? V.accent : V.labelText};font-family:${FONT};font-size:11px;font-weight:${isOutgoing ? 600 : 500};letter-spacing:0.04em">${esc(label.text)}</text>
+      </g>`
+    : '';
+
+  return `<g data-edge-id="${esc(edge.id)}" data-event="${esc(edge.event)}">${path}${labelMarkup}</g>`;
+}
+
+function edgeSvg(edge: SvgEdge, isOutgoing: boolean, labelT: number): string {
+  const section = edge.sections?.[0];
+  if (!section?.startPoint || !section?.endPoint) return '';
+
+  const d = buildCurvedPath(section);
+  const stroke = isOutgoing ? V.accent : V.edge;
+  const strokeWidth = isOutgoing ? 2 : 1.25;
+  const opacity = isOutgoing ? 1 : 0.65;
+  const { label } = edge;
+  const markerId = isOutgoing ? 'matchina-svg-arrow-active' : 'matchina-svg-arrow';
+  const mid = label ? pathAtT(section, labelT) : null;
+
+  const path = `<path d="${d}" fill="none" style="stroke:${stroke};stroke-width:${strokeWidth};opacity:${opacity}" marker-end="url(#${markerId})" />`;
+
+  const labelMarkup = label && mid
+    ? `<g transform="translate(${mid.x - label.width / 2}, ${mid.y - label.height / 2})" style="opacity:${opacity}">
+        <rect x="-6" y="-2" width="${label.width + 12}" height="${label.height + 4}" rx="6" ry="6" style="fill:${isOutgoing ? V.labelBgActive : V.labelBg};stroke:${isOutgoing ? V.accent : 'rgba(100,116,139,0.45)'};stroke-width:${isOutgoing ? 1 : 0.75}" />
+        <text x="${label.width / 2}" y="${(label.height + 4) / 2 + 4}" text-anchor="middle" style="fill:${isOutgoing ? V.accent : V.labelText};font-family:${FONT};font-size:11px;font-weight:${isOutgoing ? 600 : 500};letter-spacing:0.04em">${esc(label.text)}</text>
+      </g>`
+    : '';
+
+  return `<g data-edge-id="${esc(edge.id)}" data-event="${esc(edge.event)}">${path}${labelMarkup}</g>`;
+}
+
+export interface LayoutToSvgOptions {
+  /** Current active state value (dot-separated full key). */
+  value?: string;
+  /** @deprecated No longer used; the SVG is sized to exact content dimensions. */
+  padding?: number;
+}
+
+/**
+ * Produce a complete SVG markup string from a precomputed ELK layout.
+ * Output is sized to the layout's intrinsic dimensions plus padding,
+ * with a viewBox so it scales to its container via `width="100%" height="100%"`.
+ */
+export function layoutToSvg(layout: SvgLayout, opts: LayoutToSvgOptions = {}): string {
+  const { value = '' } = opts;
+  const padding = 0;
+
+  const activePath = value ? value.split('.') : [];
+  const activeLeafId = value;
+
+  const activeAncestorIds = new Set<string>();
+  for (let i = 0; i < activePath.length - 1; i++) {
+    activeAncestorIds.add(activePath.slice(0, i + 1).join('.'));
+  }
+
+  const activeSourceIds = new Set<string>();
+  for (let i = 1; i <= activePath.length; i++) {
+    activeSourceIds.add(activePath.slice(0, i).join('.'));
+  }
+
+  // Spread label positions for parallel edges, same heuristic as SvgInspector.
+  const pairTotal = new Map<string, number>();
+  for (const edge of layout.edges) {
+    const key = `${edge.sourcePath.join('.')}→${edge.targetPath.join('.')}`;
+    pairTotal.set(key, (pairTotal.get(key) ?? 0) + 1);
+  }
+  const pairNextIdx = new Map<string, number>();
+  const edgeLabelT = new Map<string, number>();
+  for (const edge of layout.edges) {
+    const key = `${edge.sourcePath.join('.')}→${edge.targetPath.join('.')}`;
+    const count = pairTotal.get(key) ?? 1;
+    const idx = pairNextIdx.get(key) ?? 0;
+    pairNextIdx.set(key, idx + 1);
+    const t = count === 1 ? 0.5 : 0.3 + (idx / (count - 1)) * 0.4;
+    edgeLabelT.set(edge.id, t);
+  }
+
+  const compounds = layout.nodes.filter((n) => n.isCompound);
+  const leaves = layout.nodes.filter((n) => !n.isCompound);
+
+  const nodeById = new Map(layout.nodes.map((n) => [n.id, n]));
+  const selfLoopIndexByNode = new Map<string, number>();
+
+  const edgeMarkup = layout.edges.map((edge) => {
+    const isSelf = edge.sourcePath.join('.') === edge.targetPath.join('.');
+    const isOutgoing = activeSourceIds.has(edge.sourcePath.join('.'));
+    if (isSelf) {
+      const nodeId = edge.sourcePath.join('.');
+      const node = nodeById.get(nodeId);
+      if (!node) return '';
+      const loopIndex = selfLoopIndexByNode.get(nodeId) ?? 0;
+      selfLoopIndexByNode.set(nodeId, loopIndex + 1);
+      return selfLoopSvg(edge, node, isOutgoing, loopIndex);
+    }
+    return edgeSvg(edge, isOutgoing, edgeLabelT.get(edge.id) ?? 0.5);
+  }).join('');
+
+  const compoundsMarkup = compounds
+    .map((n) => nodeSvg(n, n.id === activeLeafId, activeAncestorIds.has(n.id)))
+    .join('');
+  const leavesMarkup = leaves
+    .map((n) => nodeSvg(n, n.id === activeLeafId, activeAncestorIds.has(n.id)))
+    .join('');
+
+  const vw = layout.width + padding * 2;
+  const vh = layout.height + padding * 2;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 ${vw} ${vh}" preserveAspectRatio="xMidYMid meet" style="display:block;background:${V.bg}">
+    <defs>
+      <marker id="matchina-svg-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+        <path d="M 0 0 L 10 5 L 0 10 z" style="fill:rgba(100,116,139,0.7)" />
+      </marker>
+      <marker id="matchina-svg-arrow-active" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+        <path d="M 0 0 L 10 5 L 0 10 z" style="fill:${V.accent}" />
+      </marker>
+    </defs>
+    <g transform="translate(${padding}, ${padding})">
+      ${compoundsMarkup}
+      ${edgeMarkup}
+      ${leavesMarkup}
+    </g>
+  </svg>`;
+}

package/src/svg-path.ts

@@ -0,0 +1,75 @@
+// SVG path utilities for curved edge rendering.
+// Produces quadratic bézier rounded corners at each bend point.
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+export function pathAtT(
+  section: { startPoint: Point; endPoint: Point; bendPoints?: Point[] },
+  t: number,
+): Point {
+  const pts = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint];
+  const lengths: number[] = [];
+  let total = 0;
+  for (let i = 1; i < pts.length; i++) {
+    const l = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y);
+    lengths.push(l);
+    total += l;
+  }
+  let remaining = total * Math.max(0, Math.min(1, t));
+  for (let i = 0; i < lengths.length; i++) {
+    if (remaining <= lengths[i]) {
+      const s = remaining / lengths[i];
+      return {
+        x: pts[i].x + s * (pts[i + 1].x - pts[i].x),
+        y: pts[i].y + s * (pts[i + 1].y - pts[i].y),
+      };
+    }
+    remaining -= lengths[i];
+  }
+  return pts[pts.length - 1];
+}
+
+export function pathMidpoint(section: {
+  startPoint: Point;
+  endPoint: Point;
+  bendPoints?: Point[];
+}): Point {
+  return pathAtT(section, 0.5);
+}
+
+export function buildCurvedPath(
+  section: {
+    startPoint: Point;
+    endPoint: Point;
+    bendPoints?: Point[];
+  },
+  radius = 14,
+): string {
+  const pts = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint];
+  if (pts.length <= 2) {
+    return `M ${pts[0].x} ${pts[0].y} L ${pts[pts.length - 1].x} ${pts[pts.length - 1].y}`;
+  }
+
+  let d = `M ${pts[0].x} ${pts[0].y}`;
+  for (let i = 1; i < pts.length - 1; i++) {
+    const prev = pts[i - 1];
+    const cur = pts[i];
+    const next = pts[i + 1];
+    const v1x = cur.x - prev.x;
+    const v1y = cur.y - prev.y;
+    const v2x = next.x - cur.x;
+    const v2y = next.y - cur.y;
+    const len1 = Math.hypot(v1x, v1y) || 1;
+    const len2 = Math.hypot(v2x, v2y) || 1;
+    const r = Math.min(radius, len1 / 2, len2 / 2);
+    const p1 = { x: cur.x - (v1x / len1) * r, y: cur.y - (v1y / len1) * r };
+    const p2 = { x: cur.x + (v2x / len2) * r, y: cur.y + (v2y / len2) * r };
+    d += ` L ${p1.x} ${p1.y} Q ${cur.x} ${cur.y} ${p2.x} ${p2.y}`;
+  }
+  const last = pts[pts.length - 1];
+  d += ` L ${last.x} ${last.y}`;
+  return d;
+}