@luciole-sh/flow-graph 0.0.0-stage → 0.1.0

package/src/components.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { RGBA, type BoxRenderable, type MouseEvent, type OptimizedBuffer } from "@opentui/core";
+import { absolutePositions, flowBounds, toFlow } from "./geometry.ts";
+import { useStore, useStoreVersion } from "./hooks.tsx";
+import { drawMiniMap, Grid, type BackgroundVariant, type Role } from "./raster.ts";
+import { roleColor, useFlowTheme } from "./theme.ts";
+import type { Rect, XY } from "./types.ts";
+
+const PANEL_Z = 100_000;
+const DEFAULT_GAP: XY = { x: 8, y: 4 };
+const MINIMAP_WIDTH = 24;
+const MINIMAP_HEIGHT = 8;
+
+/** Marks every `gap` flow cells, under the edges: dots, grid lines, or crosses. */
+export function Background({
+  variant = "dots",
+  gap = DEFAULT_GAP,
+  color,
+}: {
+  variant?: BackgroundVariant;
+  gap?: XY;
+  color?: string;
+}) {
+  const store = useStore();
+  const { x, y } = gap;
+  useEffect(() => {
+    store.setBackground({ variant, gap: { x, y }, color });
+    return () => store.setBackground(null);
+  }, [store, variant, x, y, color]);
+  return null;
+}
+
+export type PanelPosition =
+  | "top-left"
+  | "top-center"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-center"
+  | "bottom-right";
+
+/** Content over the canvas, in a corner or centered on an edge. */
+export function Panel({
+  position = "top-left",
+  children,
+}: {
+  position?: PanelPosition;
+  children: ReactNode;
+}) {
+  const [vertical, horizontal] = position.split("-");
+  const place = {
+    ...(vertical === "top" ? { top: 0 } : { bottom: 0 }),
+    ...(horizontal === "left"
+      ? { left: 0 }
+      : horizontal === "right"
+        ? { right: 0 }
+        : { left: 0, right: 0, alignItems: "center" as const }),
+  };
+  // A click on a panel is its own: it neither selects nor pans the canvas.
+  return (
+    <box
+      position="absolute"
+      zIndex={PANEL_Z}
+      flexDirection="column"
+      {...place}
+      onMouseDown={(event: MouseEvent) => event.stopPropagation()}
+    >
+      {children}
+    </box>
+  );
+}
+
+/** Zoom in, zoom out, fit, and the current level. */
+export function Controls({ position = "bottom-left" }: { position?: PanelPosition }) {
+  const store = useStoreVersion();
+  const theme = useFlowTheme();
+  const button = (label: string, action: () => void) => (
+    <text
+      selectable={false}
+      fg={theme.text}
+      bg={theme.labelBg}
+      onMouseDown={(event: MouseEvent) => {
+        event.stopPropagation();
+        action();
+      }}
+    >
+      {` ${label} `}
+    </text>
+  );
+  return (
+    <Panel position={position}>
+      <box flexDirection="row" gap={1} backgroundColor={theme.panelBg}>
+        {button("+", () => store.zoom(1))}
+        {button("-", () => store.zoom(-1))}
+        {button("fit", () => store.fitView())}
+        <text selectable={false} fg={theme.muted}>
+          {store.detail}
+        </text>
+      </box>
+    </Panel>
+  );
+}
+
+/**
+ * Every node in braille, and the part in view outlined. A click moves the view there.
+ */
+export function MiniMap({
+  position = "bottom-right",
+  width = MINIMAP_WIDTH,
+  height = MINIMAP_HEIGHT,
+}: {
+  position?: PanelPosition;
+  width?: number;
+  height?: number;
+}) {
+  const store = useStoreVersion();
+  const theme = useFlowTheme();
+  const box = useRef<BoxRenderable>(null);
+  const grid = new Grid(width, height);
+  const view: Rect = (() => {
+    const topLeft = toFlow({ x: 0, y: 0 }, store.viewport);
+    return {
+      ...topLeft,
+      width: store.size.width / store.viewport.zoom,
+      height: store.size.height / store.viewport.zoom,
+    };
+  })();
+  const nodes = flowBounds(store.nodes, store.full) ?? view;
+  // The world: every node and the view.
+  const x0 = Math.min(nodes.x, view.x);
+  const y0 = Math.min(nodes.y, view.y);
+  const world = {
+    x: x0,
+    y: y0,
+    width: Math.max(nodes.x + nodes.width, view.x + view.width) - x0,
+    height: Math.max(nodes.y + nodes.height, view.y + view.height) - y0,
+  };
+  const positions = absolutePositions(store.nodes);
+  const rects = store.nodes
+    .filter((n) => !n.hidden && n.type !== "group")
+    .map((n) => {
+      const position = positions.get(n.id) ?? n.position;
+      const one = flowBounds([{ ...n, parentId: undefined, position }], store.full);
+      const role: Role = n.selected ? "selected" : "edge";
+      return {
+        rect: one ?? { x: 0, y: 0, width: 0, height: 0 },
+        role,
+        color: n.selected ? undefined : n.color,
+      };
+    });
+  const toWorld = drawMiniMap(grid, world, rects, view);
+  useEffect(() => {
+    box.current?.requestRender();
+  });
+  return (
+    <Panel position={position}>
+      <box
+        ref={box}
+        width={width}
+        height={height}
+        backgroundColor={theme.panelBg}
+        onMouseDown={(event: MouseEvent) => {
+          event.stopPropagation();
+          const at = box.current;
+          if (!at) return;
+          store.setCenter(toWorld({ x: event.x - at.x, y: event.y - at.y }));
+        }}
+        renderAfter={function (this: { x: number; y: number }, buffer: OptimizedBuffer) {
+          for (const [x, y, cell] of grid.entries())
+            buffer.setCellWithAlphaBlending(
+              this.x + x,
+              this.y + y,
+              cell.char,
+              RGBA.fromHex(cell.color ?? roleColor(theme, cell.role)),
+              RGBA.fromHex(theme.panelBg),
+            );
+        }}
+      />
+    </Panel>
+  );
+}

package/src/frame.ts

@@ -0,0 +1,203 @@
+/**
+ * One frame of the canvas under its nodes: edges, labels, markers, handles, the
+ * connection being made and the background, composed into a grid. And the reverse: what
+ * is at a canvas cell. Pure, so that a frame can be printed and compared in tests.
+ */
+import {
+  anchorsOf,
+  contains,
+  detailFor,
+  pickAnchor,
+  placeNodes,
+  type Anchor,
+  type Measured,
+  type Placed,
+  type Size,
+} from "./geometry.ts";
+import {
+  drawBackground,
+  drawEdge,
+  drawLabel,
+  Grid,
+  type BackgroundVariant,
+  type EdgeDraw,
+  type EdgeStyle,
+} from "./raster.ts";
+import type { Edge, HandleSpec, Node, Position, Viewport, XY } from "./types.ts";
+
+/**
+ * A custom edge type: the corner points of its path from the source anchor cell to the
+ * target's, drawn with box characters like a step edge.
+ */
+export type EdgeRoute = (params: {
+  edge: Edge;
+  source: XY;
+  sourcePosition: Position;
+  target: XY;
+  targetPosition: Position;
+}) => XY[];
+/** An edge type: a built-in style, or a route. */
+export type EdgeType = EdgeStyle | EdgeRoute;
+
+const BUILTIN_STYLES: ReadonlySet<string> = new Set(["smoothstep", "step", "straight", "bezier"]);
+export const CONNECTION_ID = "__connection";
+const SOURCE_HANDLE = "●";
+const TARGET_HANDLE = "○";
+
+export type FrameInput = {
+  size: Size;
+  viewport: Viewport;
+  nodes: readonly Node[];
+  edges: readonly Edge[];
+  measured: ReadonlyMap<string, Measured>;
+  handles?: ReadonlyMap<string, ReadonlyMap<string, HandleSpec>>;
+  background?: { variant: BackgroundVariant; gap: XY } | null;
+  connecting?: { source: Anchor; pointer?: XY; target?: string } | null;
+  edgeTypes?: Readonly<Record<string, EdgeType>>;
+  defaultEdgeType?: string;
+  /** Curves and slanted lines in braille; without, they are drawn as smoothstep edges. */
+  braille?: boolean;
+  /** Animation step: advances the dashes of animated edges. */
+  phase?: number;
+};
+
+export type Frame = {
+  grid: Grid;
+  placed: Placed[];
+  anchors: Map<string, Anchor[]>;
+};
+
+export function composeFrame(input: FrameInput): Frame {
+  const detail = detailFor(input.viewport.zoom);
+  const placed = placeNodes(input.nodes, input.viewport, input.measured);
+  const anchors = new Map(
+    placed.map((p) => [
+      p.node.id,
+      anchorsOf(p, [...(input.handles?.get(p.node.id)?.values() ?? [])], detail),
+    ]),
+  );
+  const grid = new Grid(input.size.width, input.size.height);
+  const labels: { at: XY; text: string; owner: string }[] = [];
+
+  // Selected edges last: their color wins where lines share a cell.
+  const rank = (e: Edge) => (e.selected ? 2 : e.animated ? 1 : 0);
+  const edges = [...input.edges].filter((e) => !e.hidden).sort((a, b) => rank(a) - rank(b));
+  for (const edge of edges) {
+    const source = pickAnchor(anchors.get(edge.source) ?? [], "source", edge.sourceHandle);
+    const target = pickAnchor(anchors.get(edge.target) ?? [], "target", edge.targetHandle);
+    if (!source || !target) continue;
+    const draw = edgeDraw(edge, source, target, input);
+    const at = drawEdge(grid, draw);
+    if (edge.label) labels.push({ at, text: edge.label, owner: edge.id });
+  }
+
+  const connecting = input.connecting;
+  if (connecting) {
+    const target = connecting.target
+      ? pickAnchor(anchors.get(connecting.target) ?? [], "target", null)
+      : undefined;
+    const pointer = connecting.pointer;
+    const end = target?.cell ?? pointer;
+    if (end) {
+      const targetPosition: Position =
+        target?.position ?? (end.x >= connecting.source.cell.x ? "left" : "right");
+      drawEdge(grid, {
+        id: CONNECTION_ID,
+        style: "smoothstep",
+        source: connecting.source.cell,
+        sourcePosition: connecting.source.position,
+        target: end,
+        targetPosition,
+        role: "handle",
+      });
+    }
+    // Where it can end: every other node's targets.
+    for (const [id, list] of anchors)
+      if (id !== connecting.source.nodeId)
+        for (const a of list)
+          if (a.type === "target" && !(target && a === target))
+            grid.set(a.cell.x, a.cell.y, { char: TARGET_HANDLE, role: "handle" });
+  }
+  // The selected nodes' sources: where a connection starts with the mouse.
+  for (const p of placed)
+    if (p.node.selected && p.node.connectable !== false)
+      for (const a of anchors.get(p.node.id) ?? [])
+        if (a.type === "source" && !grid.get(a.cell.x, a.cell.y))
+          grid.set(a.cell.x, a.cell.y, { char: SOURCE_HANDLE, role: "handle" });
+
+  for (const label of labels) drawLabel(grid, label.at, label.text, label.owner);
+  grid.resolve(input.phase ?? 0);
+  if (input.background)
+    drawBackground(grid, input.viewport, input.background.variant, input.background.gap);
+  return { grid, placed, anchors };
+}
+
+function edgeDraw(edge: Edge, source: Anchor, target: Anchor, input: FrameInput): EdgeDraw {
+  const name = edge.type ?? input.defaultEdgeType ?? "smoothstep";
+  const type = input.edgeTypes?.[name] ?? (BUILTIN_STYLES.has(name) ? name : "smoothstep");
+  const base = {
+    id: edge.id,
+    source: source.cell,
+    sourcePosition: source.position,
+    target: target.cell,
+    targetPosition: target.position,
+    label: edge.label,
+    animated: edge.animated,
+    selected: edge.selected,
+    markerEnd: edge.markerEnd !== "none",
+    markerStart: edge.markerStart === "arrow",
+    color: edge.color,
+  };
+  if (typeof type === "function")
+    return { ...base, style: "step", points: type({ edge, ...base }) };
+  const style: EdgeStyle =
+    type === "smoothstep" || type === "step" || type === "straight" || type === "bezier"
+      ? type
+      : "smoothstep";
+  // Without braille, curves fall back to the orthogonal path.
+  const curved = style === "bezier" || style === "straight";
+  return { ...base, style: curved && input.braille === false ? "smoothstep" : style };
+}
+
+export type Hit =
+  | { kind: "handle"; anchor: Anchor }
+  | { kind: "node"; node: Node }
+  | { kind: "edge"; id: string }
+  | { kind: "pane" };
+
+/** What is at canvas cell `at`: a source handle, a node (topmost first), an edge, or none. */
+export function hitTest(frame: Frame, at: XY): Hit {
+  for (const list of frame.anchors.values())
+    for (const anchor of list)
+      if (anchor.type === "source" && anchor.cell.x === at.x && anchor.cell.y === at.y) {
+        const node = frame.placed.find((p) => p.node.id === anchor.nodeId)?.node;
+        if (node?.connectable !== false) return { kind: "handle", anchor };
+      }
+  for (let i = frame.placed.length - 1; i >= 0; i--) {
+    const p = frame.placed[i];
+    if (p && contains(p.rect, at)) return { kind: "node", node: p.node };
+  }
+  const owner = frame.grid.get(at.x, at.y)?.owner;
+  if (owner && owner !== CONNECTION_ID) return { kind: "edge", id: owner };
+  return { kind: "pane" };
+}
+
+/** Where a connection dropped at `at` ends: a target handle, or a node's first target. */
+export function dropTarget(frame: Frame, at: XY, source: Anchor): Anchor | undefined {
+  for (const list of frame.anchors.values())
+    for (const anchor of list)
+      if (
+        anchor.type === "target" &&
+        anchor.nodeId !== source.nodeId &&
+        anchor.cell.x === at.x &&
+        anchor.cell.y === at.y
+      )
+        return anchor;
+  for (let i = frame.placed.length - 1; i >= 0; i--) {
+    const p = frame.placed[i];
+    if (!p || p.node.id === source.nodeId || !contains(p.rect, at)) continue;
+    if (p.node.type === "group") continue;
+    return pickAnchor(frame.anchors.get(p.node.id) ?? [], "target", null);
+  }
+  return undefined;
+}

package/src/geometry.ts

@@ -0,0 +1,274 @@
+/**
+ * Where things are on the canvas: flow coordinates (cells at zoom 1) to canvas cells,
+ * semantic zoom, node rectangles, handle anchors, fitting the view. Pure functions.
+ */
+import type {
+  Detail,
+  HandleSpec,
+  HandleType,
+  Node,
+  Position,
+  Rect,
+  Viewport,
+  XY,
+} from "./types.ts";
+
+/** The zoom levels, from closest to farthest. Each draws nodes with less detail. */
+const HALF = 0.5;
+const QUARTER = 0.25;
+export const ZOOMS = [1, HALF, QUARTER] as const;
+const DETAILS: readonly Detail[] = ["full", "compact", "dot"];
+const FIT_PADDING = 2;
+/** A node that was never measured: its label in a bordered box. */
+const BORDER_AND_PADDING = 4;
+const DEFAULT_HEIGHT = 3;
+const MIN_LABEL = 4;
+
+export function detailFor(zoom: number): Detail {
+  const index = ZOOMS.findIndex((z) => zoom >= z);
+  return DETAILS[index < 0 ? DETAILS.length - 1 : index] ?? "dot";
+}
+
+/** The next zoom level in (`+1`) or out (`-1`), or the same one at either end. */
+export function stepZoom(zoom: number, direction: 1 | -1): number {
+  const index = ZOOMS.findIndex((z) => zoom >= z);
+  const current = index < 0 ? ZOOMS.length - 1 : index;
+  const next = Math.min(ZOOMS.length - 1, Math.max(0, current - direction));
+  return ZOOMS[next] ?? zoom;
+}
+
+/** Zooms to `zoom` keeping the flow point under canvas cell `anchor` where it is. */
+export function zoomAround(viewport: Viewport, zoom: number, anchor: XY): Viewport {
+  const flow = toFlow(anchor, viewport);
+  return {
+    x: Math.round(anchor.x - flow.x * zoom),
+    y: Math.round(anchor.y - flow.y * zoom),
+    zoom,
+  };
+}
+
+export const toCanvas = (point: XY, viewport: Viewport): XY => ({
+  x: Math.round(point.x * viewport.zoom + viewport.x),
+  y: Math.round(point.y * viewport.zoom + viewport.y),
+});
+export const toFlow = (point: XY, viewport: Viewport): XY => ({
+  x: (point.x - viewport.x) / viewport.zoom,
+  y: (point.y - viewport.y) / viewport.zoom,
+});
+
+export const labelOf = (node: Node) =>
+  typeof node.data.label === "string" ? node.data.label : node.id;
+
+/** Where each node is in flow coordinates, its parents' positions added. */
+export function absolutePositions(nodes: readonly Node[]): Map<string, XY> {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const positions = new Map<string, XY>();
+  const resolve = (node: Node, seen: Set<string>): XY => {
+    const known = positions.get(node.id);
+    if (known) return known;
+    const parent = node.parentId ? byId.get(node.parentId) : undefined;
+    // A cycle of parents is ignored rather than followed.
+    const origin =
+      parent && !seen.has(parent.id) ? resolve(parent, new Set(seen).add(node.id)) : { x: 0, y: 0 };
+    const position = { x: origin.x + node.position.x, y: origin.y + node.position.y };
+    positions.set(node.id, position);
+    return position;
+  };
+  for (const node of nodes) resolve(node, new Set([node.id]));
+  return positions;
+}
+
+export type Size = { width: number; height: number };
+/** A rendered size and the detail it was rendered at. */
+export type Measured = Size & { detail: Detail };
+
+/** The size a node takes at `detail` before it is measured. */
+export function estimateSize(node: Node, detail: Detail, zoom = 1): Size {
+  if (node.type === "group" || (node.width !== undefined && node.height !== undefined)) {
+    const width = node.width ?? MIN_LABEL;
+    const height = node.height ?? DEFAULT_HEIGHT;
+    return detail === "full"
+      ? { width, height }
+      : {
+          width: Math.max(2, Math.round(width * zoom)),
+          height: Math.max(1, Math.round(height * zoom)),
+        };
+  }
+  const label = Math.max(MIN_LABEL, labelOf(node).length);
+  if (detail === "dot") return { width: 1, height: 1 };
+  if (detail === "compact") return { width: label + 2, height: 1 };
+  return { width: label + BORDER_AND_PADDING, height: DEFAULT_HEIGHT };
+}
+
+export type Placed = {
+  node: Node;
+  /** In canvas cells. */
+  rect: Rect;
+  /** Drawing order: groups under their children, the selection over the rest. */
+  z: number;
+};
+
+const GROUP_Z = -1;
+const SELECTED_Z = 1000;
+
+/** Each visible node's rectangle on the canvas, in drawing order. */
+export function placeNodes(
+  nodes: readonly Node[],
+  viewport: Viewport,
+  measured: ReadonlyMap<string, Measured>,
+): Placed[] {
+  const detail = detailFor(viewport.zoom);
+  const positions = absolutePositions(nodes);
+  const placed: Placed[] = [];
+  for (const node of nodes) {
+    if (node.hidden) continue;
+    const at = toCanvas(positions.get(node.id) ?? node.position, viewport);
+    const size = measured.get(node.id);
+    const { width, height } =
+      size && size.detail === detail ? size : estimateSize(node, detail, viewport.zoom);
+    const z =
+      (node.zIndex ?? 0) + (node.type === "group" ? GROUP_Z : 0) + (node.selected ? SELECTED_Z : 0);
+    placed.push({ node, rect: { x: at.x, y: at.y, width, height }, z });
+  }
+  // Stable: equal z keeps the application's order.
+  return placed.sort((a, b) => a.z - b.z);
+}
+
+/** The flow-coordinate bounds of `nodes` at full detail, or null when there are none. */
+export function flowBounds(
+  nodes: readonly Node[],
+  measured: ReadonlyMap<string, Measured>,
+): Rect | null {
+  const positions = absolutePositions(nodes);
+  let bounds: { x0: number; y0: number; x1: number; y1: number } | null = null;
+  for (const node of nodes) {
+    if (node.hidden) continue;
+    const at = positions.get(node.id) ?? node.position;
+    const size = measured.get(node.id);
+    const { width, height } = size?.detail === "full" ? size : estimateSize(node, "full");
+    const box = { x0: at.x, y0: at.y, x1: at.x + width, y1: at.y + height };
+    bounds = bounds
+      ? {
+          x0: Math.min(bounds.x0, box.x0),
+          y0: Math.min(bounds.y0, box.y0),
+          x1: Math.max(bounds.x1, box.x1),
+          y1: Math.max(bounds.y1, box.y1),
+        }
+      : box;
+  }
+  return (
+    bounds && {
+      x: bounds.x0,
+      y: bounds.y0,
+      width: bounds.x1 - bounds.x0,
+      height: bounds.y1 - bounds.y0,
+    }
+  );
+}
+
+/** The closest zoom level at which `bounds` fits `canvas`, centered. */
+export function fitViewport(bounds: Rect | null, canvas: Size, padding = FIT_PADDING): Viewport {
+  if (!bounds) return { x: padding, y: padding, zoom: 1 };
+  const zoom =
+    ZOOMS.find(
+      (z) =>
+        bounds.width * z <= canvas.width - padding * 2 &&
+        bounds.height * z <= canvas.height - padding * 2,
+    ) ?? ZOOMS[ZOOMS.length - 1];
+  const z = zoom ?? 1;
+  return {
+    x: Math.round((canvas.width - bounds.width * z) / 2 - bounds.x * z),
+    y: Math.round((canvas.height - bounds.height * z) / 2 - bounds.y * z),
+    zoom: z,
+  };
+}
+
+/** The smallest pan that brings `rect` (canvas cells) into `canvas`, `margin` cells in. */
+export function panToShow(viewport: Viewport, rect: Rect, canvas: Size, margin = 1): Viewport {
+  const shift = (start: number, length: number, size: number) => {
+    if (length + margin * 2 > size) return -start + margin;
+    if (start < margin) return margin - start;
+    if (start + length > size - margin) return size - margin - (start + length);
+    return 0;
+  };
+  const dx = shift(rect.x, rect.width, canvas.width);
+  const dy = shift(rect.y, rect.height, canvas.height);
+  return dx === 0 && dy === 0 ? viewport : { ...viewport, x: viewport.x + dx, y: viewport.y + dy };
+}
+
+export const contains = (rect: Rect, point: XY) =>
+  point.x >= rect.x &&
+  point.x < rect.x + rect.width &&
+  point.y >= rect.y &&
+  point.y < rect.y + rect.height;
+
+export type Anchor = {
+  nodeId: string;
+  handle: string | null;
+  type: HandleType;
+  position: Position;
+  /** The cell just outside the node's border, where the edge starts or ends. */
+  cell: XY;
+};
+
+/**
+ * Each handle's anchor cell: `handles` as the node declared them, or one source and one
+ * target on the node's `sourcePosition`/`targetPosition`. Handles sharing a side are
+ * spread along it.
+ */
+export function anchorsOf(
+  placed: Placed,
+  handles: readonly HandleSpec[] | undefined,
+  detail: Detail,
+): Anchor[] {
+  const { node, rect } = placed;
+  const specs: readonly HandleSpec[] =
+    handles && handles.length > 0
+      ? handles
+      : [
+          ...(node.type === "input" || node.type === "group"
+            ? []
+            : [{ id: null, type: "target" as const, position: node.targetPosition ?? "left" }]),
+          ...(node.type === "output" || node.type === "group"
+            ? []
+            : [{ id: null, type: "source" as const, position: node.sourcePosition ?? "right" }]),
+        ];
+  // At `dot` the node is one cell: every handle is on it, whatever its side.
+  const bySide = new Map<Position, HandleSpec[]>();
+  for (const spec of specs) bySide.set(spec.position, [...(bySide.get(spec.position) ?? []), spec]);
+  const anchors: Anchor[] = [];
+  for (const [position, list] of bySide)
+    list.forEach((spec, index) => {
+      const along = (length: number) =>
+        detail === "dot" ? 0 : Math.floor(((index + 1) * length) / (list.length + 1) - 1 / 2);
+      const midX = rect.x + Math.max(0, Math.min(rect.width - 1, along(rect.width)));
+      const midY = rect.y + Math.max(0, Math.min(rect.height - 1, along(rect.height)));
+      const cell =
+        position === "left"
+          ? { x: rect.x - 1, y: midY }
+          : position === "right"
+            ? { x: rect.x + rect.width, y: midY }
+            : position === "top"
+              ? { x: midX, y: rect.y - 1 }
+              : { x: midX, y: rect.y + rect.height };
+      anchors.push({ nodeId: node.id, handle: spec.id, type: spec.type, position, cell });
+    });
+  return anchors;
+}
+
+/** The anchor an edge uses at one end: its named handle, else the first of that type. */
+export function pickAnchor(
+  anchors: readonly Anchor[],
+  type: HandleType,
+  handle: string | null | undefined,
+): Anchor | undefined {
+  const ofType = anchors.filter((a) => a.type === type);
+  return (handle ? ofType.find((a) => a.handle === handle) : undefined) ?? ofType[0];
+}
+
+export const opposite: Record<Position, Position> = {
+  left: "right",
+  right: "left",
+  top: "bottom",
+  bottom: "top",
+};