@kgdiff/renderer 0.0.0-stage → 0.2.0

package/src/draw/halos.ts

@@ -0,0 +1,101 @@
+/**
+ * Halo pass. Dark themes: soft radial glows blitted from one cached gradient sprite per color.
+ * Light themes: crisp offset rings at `r + 5` px.
+ */
+import type { FrameVisuals, Theme } from '@kgdiff/scene';
+import { parseColor, rgbaString } from '../color.js';
+import { type Ctx2D, NO_DASH, type Surface, type SurfaceFactory } from '../ctx.js';
+import type { FrameCache } from '../frame-cache.js';
+import { TAU } from '../math.js';
+import { CULL_MARGIN, HALO_RING_OFFSET, HALO_RING_WIDTH, NODE_MIN_R, type View } from './view.js';
+
+/** Glow falloff: (radius fraction, alpha) — a soft, roughly Gaussian profile. */
+const GLOW_STOPS: readonly (readonly [number, number])[] = [
+  [0, 1],
+  [0.3, 0.9],
+  [0.5, 0.6],
+  [0.7, 0.28],
+  [0.86, 0.08],
+  [1, 0],
+];
+const SPRITE_SIZE = 128;
+
+export class HaloSprites {
+  private readonly cache = new Map<string, Surface | null>();
+
+  constructor(private readonly factory: SurfaceFactory) {}
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  sprite(color: string): Surface | null {
+    let s = this.cache.get(color);
+    if (s === undefined) {
+      s = this.make(color);
+      if (this.cache.size > 64) this.cache.clear();
+      this.cache.set(color, s);
+    }
+    return s;
+  }
+
+  private make(color: string): Surface | null {
+    const s = this.factory(SPRITE_SIZE, SPRITE_SIZE);
+    if (!s) return null;
+    const h = SPRITE_SIZE / 2;
+    const g = s.ctx.createRadialGradient(h, h, 0, h, h, h);
+    const rgba = parseColor(color);
+    for (const [t, a] of GLOW_STOPS) {
+      g.addColorStop(t, rgba ? rgbaString(rgba, a) : a > 0 ? color : 'rgba(0, 0, 0, 0)');
+    }
+    s.ctx.fillStyle = g;
+    s.ctx.fillRect(0, 0, SPRITE_SIZE, SPRITE_SIZE);
+    return s;
+  }
+}
+
+export function drawHalos(
+  ctx: Ctx2D,
+  frame: FrameVisuals,
+  cache: FrameCache,
+  v: View,
+  theme: Theme,
+  sprites: HaloSprites,
+): void {
+  const { k, ox, oy } = v;
+  if (!theme.glow) {
+    ctx.lineWidth = HALO_RING_WIDTH;
+    ctx.setLineDash(NO_DASH);
+  }
+  for (const i of cache.halos) {
+    const n = frame.nodes[i]!;
+    const halo = n.halo!;
+    const a = halo.alpha * n.alpha;
+    if (a < 0.01) continue;
+    const x = n.x * k + ox;
+    const y = n.y * k + oy;
+    const r = Math.max(n.r * k, NODE_MIN_R);
+    // Light halos sit at r + 5 px, pushed outside a concentric ring when the node has one.
+    const ring = n.ring;
+    const ringOuter = ring ? r + ring.gap + ring.width / 2 : 0;
+    const base = Math.max(halo.radius * k, NODE_MIN_R); // light themes: radius = r
+    const lightR = Math.max(base + HALO_RING_OFFSET, ringOuter + 1.5 + HALO_RING_WIDTH / 2);
+    const hr = theme.glow ? Math.max(halo.radius * k, r * 1.6) : lightR + HALO_RING_WIDTH;
+    if (x + hr < v.x0 - CULL_MARGIN || x - hr > v.x1 + CULL_MARGIN) continue;
+    if (y + hr < v.y0 - CULL_MARGIN || y - hr > v.y1 + CULL_MARGIN) continue;
+    ctx.globalAlpha = a;
+    if (theme.glow) {
+      const s = sprites.sprite(halo.color);
+      if (s) ctx.drawImage(s.canvas, x - hr, y - hr, hr * 2, hr * 2);
+    } else {
+      ctx.strokeStyle = halo.color;
+      ctx.beginPath();
+      ctx.arc(x, y, lightR, 0, TAU);
+      ctx.stroke();
+    }
+  }
+}

package/src/draw/labels.ts

@@ -0,0 +1,399 @@
+/**
+ * Label pass: collect visible labels (node primary + secondary blocks, edge labels at curve
+ * midpoints, glyph labels) and collapsed-group pills, place them greedily against node discs and
+ * badges, then draw the labels from the label atlas (or directly without offscreen surfaces).
+ * Placement runs before anything is drawn, so pills (drawn early, under edges) know whether
+ * they won their spot; a pill that collides is hidden at this zoom.
+ */
+import type { FrameVisuals, LabelVisual, Theme } from '@kgdiff/scene';
+import { ATLAS_PAD, type AtlasEntry, drawTextLine, type LabelAtlas } from '../atlas.js';
+import type { Ctx2D } from '../ctx.js';
+import type { FrameCache } from '../frame-cache.js';
+import {
+  type CollisionGrid,
+  createRequest,
+  type LabelClip,
+  type LabelRequest,
+  MODE_FIXED,
+  MODE_NODE,
+  MODE_POINT,
+  placeLabels,
+  SIDE_ABOVE,
+  SIDE_BELOW,
+  SIDE_CENTER,
+  SIDE_LEFT,
+  SIDE_RIGHT,
+} from '../labels.js';
+import { snap } from '../math.js';
+import { type Fonts, LABEL_MAX_WIDTH, lineHeight, type TextMeasurer } from '../text.js';
+import { pillRect } from './collapsed.js';
+import { isLoop } from './edges.js';
+import { SUGGESTION_MARK_R } from './glyphs.js';
+import { linkMidpoint, loopCenterY, loopRadius } from './link.js';
+import { NODE_MIN_R, type View } from './view.js';
+
+/** Labels whose anchor is this far (px) outside the region still compete for space. */
+export const LABEL_MARGIN = 160;
+/** Nodes at least this big (screen radius, px) keep labels off their disc. */
+export const OBSTACLE_MIN_R = 3;
+const MIN_ALPHA = 0.02;
+/**
+ * Collision priority of collapsed pills, on the scene's label scale: below changed-node labels
+ * (1 + importance; ties go to labels) and above neutral ones (importance < 1) and edge labels.
+ */
+export const PILL_PRIORITY = 1;
+
+const rect = new Float64Array(4);
+
+export interface LabelResources {
+  readonly fonts: Fonts;
+  readonly measurer: TextMeasurer;
+  readonly atlas: LabelAtlas | null;
+}
+
+/**
+ * LOD fade: fully visible from `minZoom` on (as specified), fading in over the 10% of zoom just
+ * below it, so labels never pop in or out while zooming.
+ */
+export function lodAlpha(minZoom: number, k: number): number {
+  if (!(minZoom > 0) || k >= minZoom) return 1;
+  const t = (k - 0.9 * minZoom) / (0.1 * minZoom);
+  return t <= 0 ? 0 : t * t * (3 - 2 * t);
+}
+
+function shown(l: LabelVisual | null, k: number, ownerAlpha: number): l is LabelVisual {
+  return (
+    l !== null && l.text.length > 0 && l.alpha * ownerAlpha * lodAlpha(l.minZoom, k) >= MIN_ALPHA
+  );
+}
+
+export class LabelPass {
+  private readonly pool: LabelRequest[] = [];
+  private readonly active: LabelRequest[] = [];
+  private readonly clip: LabelClip = { x0: 0, y0: 0, x1: 0, y1: 0, strictX: false };
+
+  /** Reset `grid` to the region and add node discs as obstacles. */
+  begin(frame: FrameVisuals, cache: FrameCache, v: View, grid: CollisionGrid): void {
+    const m = LABEL_MARGIN;
+    grid.reset(v.x0 - m, v.y0 - m, v.x1 - v.x0 + 2 * m, v.y1 - v.y0 + 2 * m);
+    const { k, ox, oy } = v;
+    if (cache.maxR * k < OBSTACLE_MIN_R) return;
+    for (const b of cache.nodeBuckets) {
+      for (const i of b.members) {
+        const n = frame.nodes[i]!;
+        const r = n.r * k;
+        if (r < OBSTACLE_MIN_R) continue;
+        const x = n.x * k + ox;
+        const y = n.y * k + oy;
+        if (x + r < v.x0 - m || x - r > v.x1 + m || y + r < v.y0 - m || y - r > v.y1 + m) continue;
+        grid.insert(x - r, y - r, 2 * r, 2 * r);
+      }
+    }
+  }
+
+  /**
+   * Collect labels and pills and place them against `grid` (call after `begin` and after badges
+   * registered their obstacles). Records which pills won a spot in `cache.pillShown`.
+   */
+  place(
+    frame: FrameVisuals,
+    cache: FrameCache,
+    v: View,
+    res: LabelResources,
+    grid: CollisionGrid,
+  ): void {
+    this.active.length = 0;
+    this.collectNodes(frame, v, res);
+    this.collectEdges(frame, v, res);
+    this.collectGlyphs(frame, cache, v, res);
+    this.collectPills(frame, v, res);
+    const pills = frame.collapsed.length;
+    if (cache.pillShown.length < pills) cache.pillShown = new Uint8Array(pills);
+    cache.pillShown.fill(0, 0, pills);
+    cache.pillsVersion = cache.version;
+    if (this.active.length === 0) return;
+    const clip = this.clip;
+    clip.x0 = v.x0;
+    clip.x1 = v.x1;
+    clip.y0 = v.y0;
+    clip.y1 = v.y1;
+    clip.strictX = v.strictX;
+    placeLabels(this.active, grid, clip);
+    for (const req of this.active) if (req.placed && req.pill >= 0) cache.pillShown[req.pill] = 1;
+  }
+
+  /** Draw the labels placed by `place`. Returns how many were drawn. */
+  draw(ctx: Ctx2D, v: View, theme: Theme, res: LabelResources): number {
+    let drawn = 0;
+    const bg = theme.canvas.background;
+    const atlas = res.atlas;
+    const source = atlas?.canvas ?? null;
+    for (const req of this.active) {
+      if (!req.placed || req.pill >= 0) continue;
+      drawn++;
+      if (req.primary) {
+        const x = alignX(req, req.wP);
+        drawLine(
+          ctx,
+          req,
+          req.primary,
+          req.textP,
+          req.fontP,
+          req.wP,
+          req.hP,
+          x,
+          req.by,
+          v,
+          bg,
+          atlas,
+          source,
+        );
+      }
+      if (req.secondary) {
+        const x = alignX(req, req.wS);
+        drawLine(
+          ctx,
+          req,
+          req.secondary,
+          req.textS,
+          req.fontS,
+          req.wS,
+          req.hS,
+          x,
+          req.by + req.dyS,
+          v,
+          bg,
+          atlas,
+          source,
+        );
+      }
+    }
+    return drawn;
+  }
+
+  private take(): LabelRequest {
+    const i = this.active.length;
+    let req = this.pool[i];
+    if (!req) {
+      req = createRequest();
+      this.pool.push(req);
+    }
+    this.active.push(req);
+    req.pill = -1;
+    return req;
+  }
+
+  private collectPills(frame: FrameVisuals, v: View, res: LabelResources): void {
+    const m = LABEL_MARGIN;
+    const groups = frame.collapsed;
+    for (let i = 0; i < groups.length; i++) {
+      const g = groups[i]!;
+      if (!(g.count > 0) || !Number.isFinite(g.x + g.y)) continue;
+      pillRect(g, v, res.fonts, res.measurer, rect);
+      const w = rect[2]!;
+      const h = rect[3]!;
+      const x = rect[0]! + w / 2;
+      const y = rect[1]! + h / 2;
+      if (x < v.x0 - m || x > v.x1 + m || y < v.y0 - m || y > v.y1 + m) continue;
+      const req = this.take();
+      req.pill = i;
+      req.x = x;
+      req.y = y;
+      req.r = 0;
+      req.w = w;
+      req.h = h;
+      req.offset = 0;
+      req.mode = MODE_FIXED;
+      req.priority = PILL_PRIORITY;
+      req.order = 3e7 + i;
+      req.placed = false;
+      req.primary = null;
+      req.secondary = null;
+    }
+  }
+
+  private collectNodes(frame: FrameVisuals, v: View, res: LabelResources): void {
+    const { k, ox, oy } = v;
+    const m = LABEL_MARGIN;
+    const nodes = frame.nodes;
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i]!;
+      if (!n.visible || n.alpha < MIN_ALPHA) continue;
+      const p = shown(n.label, k, n.alpha) ? n.label : null;
+      const s = shown(n.secondaryLabel, k, n.alpha) ? n.secondaryLabel : null;
+      if (!p && !s) continue;
+      const x = n.x * k + ox;
+      const y = n.y * k + oy;
+      if (x < v.x0 - m || x > v.x1 + m || y < v.y0 - m || y > v.y1 + m) continue;
+      const req = this.take();
+      req.x = x;
+      req.y = y;
+      req.r = Math.max(n.r * k, NODE_MIN_R);
+      req.mode = MODE_NODE;
+      req.order = i;
+      req.alpha = n.alpha;
+      this.fill(req, p, s, res);
+    }
+  }
+
+  private collectEdges(frame: FrameVisuals, v: View, res: LabelResources): void {
+    const { k, ox, oy } = v;
+    const m = LABEL_MARGIN;
+    const edges = frame.edges;
+    for (let i = 0; i < edges.length; i++) {
+      const e = edges[i]!;
+      if (e.label === null || !e.visible || e.progress < 0.999) continue;
+      if (!shown(e.label, k, e.alpha)) continue;
+      const x1 = e.x1 * k + ox;
+      const y1 = e.y1 * k + oy;
+      let x: number;
+      let y: number;
+      if (isLoop(e.x1, e.y1, e.x2, e.y2)) {
+        const r = Math.max(e.r1 * k, NODE_MIN_R);
+        const rho = loopRadius(r, e.curvature);
+        x = x1;
+        y = loopCenterY(y1, r, rho) - rho;
+      } else {
+        [x, y] = linkMidpoint(x1, y1, e.x2 * k + ox, e.y2 * k + oy, e.curvature);
+      }
+      if (x < v.x0 - m || x > v.x1 + m || y < v.y0 - m || y > v.y1 + m) continue;
+      const req = this.take();
+      req.x = x;
+      req.y = y;
+      req.r = 0;
+      req.mode = MODE_POINT;
+      req.order = 1e7 + i;
+      req.alpha = e.alpha;
+      this.fill(req, e.label, null, res);
+    }
+  }
+
+  private collectGlyphs(
+    frame: FrameVisuals,
+    cache: FrameCache,
+    v: View,
+    res: LabelResources,
+  ): void {
+    const { k, ox, oy } = v;
+    const m = LABEL_MARGIN;
+    for (const i of cache.glyphArcs) {
+      const g = frame.glyphs[i]!;
+      if (!shown(g.label, k, g.alpha) || g.progress < 0.999) continue;
+      const [x, y] = linkMidpoint(
+        g.x1 * k + ox,
+        g.y1 * k + oy,
+        g.x2 * k + ox,
+        g.y2 * k + oy,
+        g.curvature,
+      );
+      if (x < v.x0 - m || x > v.x1 + m || y < v.y0 - m || y > v.y1 + m) continue;
+      const req = this.take();
+      req.x = x;
+      req.y = y;
+      // Suggestions carry a `?` mark at the midpoint: place the label around it.
+      req.r = g.kind === 'suggestion' ? SUGGESTION_MARK_R : 0;
+      req.mode = g.kind === 'suggestion' ? MODE_NODE : MODE_POINT;
+      req.order = 2e7 + i;
+      req.alpha = g.alpha;
+      this.fill(req, g.label, null, res);
+    }
+  }
+
+  /** Measure and size the block for a primary and / or secondary line. */
+  private fill(
+    req: LabelRequest,
+    p: LabelVisual | null,
+    s: LabelVisual | null,
+    res: LabelResources,
+  ): void {
+    const { fonts, measurer } = res;
+    req.primary = p;
+    req.secondary = s;
+    req.placed = false;
+    req.dyS = 0;
+    if (p) {
+      req.fontP = fonts.get(p.size, p.weight);
+      req.textP = measurer.fit(req.fontP, p.text, LABEL_MAX_WIDTH);
+      req.wP = Math.ceil(measurer.width(req.fontP, req.textP));
+      req.hP = lineHeight(p.size);
+    }
+    if (s) {
+      req.fontS = fonts.get(s.size, s.weight);
+      req.textS = measurer.fit(req.fontS, s.text, LABEL_MAX_WIDTH);
+      req.wS = Math.ceil(measurer.width(req.fontS, req.textS));
+      req.hS = lineHeight(s.size);
+    }
+    if (p && s) {
+      req.dyS = Math.max(s.offset - p.offset, req.hP - 1);
+      req.w = Math.max(req.wP, req.wS);
+      req.h = req.dyS + req.hS;
+      req.offset = p.offset;
+      req.priority = Math.max(p.priority, s.priority);
+    } else if (p) {
+      req.w = req.wP;
+      req.h = req.hP;
+      req.offset = p.offset;
+      req.priority = p.priority;
+    } else if (s) {
+      req.w = req.wS;
+      req.h = req.hS;
+      req.offset = s.offset;
+      req.priority = s.priority;
+    }
+  }
+}
+
+/** Left x of one line inside its block (centred below / above, flush beside the node). */
+function alignX(req: LabelRequest, width: number): number {
+  switch (req.side) {
+    case SIDE_RIGHT:
+      return req.bx;
+    case SIDE_LEFT:
+      return req.bx + req.w - width;
+    case SIDE_BELOW:
+    case SIDE_ABOVE:
+    case SIDE_CENTER:
+      return req.bx + (req.w - width) / 2;
+    default:
+      return req.bx;
+  }
+}
+
+function drawLine(
+  ctx: Ctx2D,
+  req: LabelRequest,
+  label: LabelVisual,
+  text: string,
+  font: string,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  v: View,
+  bg: string,
+  atlas: LabelAtlas | null,
+  source: CanvasImageSource | null,
+): void {
+  const alpha = label.alpha * req.alpha * lodAlpha(label.minZoom, v.k);
+  const sx = snap(x, v.dpr);
+  const sy = snap(y, v.dpr);
+  const entry: AtlasEntry | null | undefined =
+    atlas && source ? atlas.get(text, font, label.color, label.strike, width, height) : null;
+  if (entry === undefined) return; // over this frame's raster budget: drawn next frame
+  if (entry && source) {
+    ctx.globalAlpha = alpha;
+    ctx.drawImage(
+      source,
+      entry.sx,
+      entry.sy,
+      entry.sw,
+      entry.sh,
+      sx - ATLAS_PAD,
+      sy - ATLAS_PAD,
+      entry.sw / v.dpr,
+      entry.sh / v.dpr,
+    );
+    return;
+  }
+  drawTextLine(ctx, text, font, label.color, bg, label.strike, sx, sy, width, height, alpha);
+}

package/src/draw/link.ts

@@ -0,0 +1,157 @@
+/**
+ * Geometry of one link (edge or glyph arc) in screen space: straight or quadratic, trimmed at
+ * the endpoint radii, partially drawn (`progress`), optionally ending in an arrowhead.
+ */
+import type { Ctx2D } from '../ctx.js';
+import { quadAt, quadSlope, quadTrim, TAU } from '../math.js';
+import { ARROW_LEN } from './view.js';
+
+export const LINK_NONE = 0;
+export const LINK_DRAWN = 1;
+export const LINK_ARROW = 2;
+
+/** Drawn fraction in [0, 1]; NaN draws nothing. */
+function progressOf(p: number): number {
+  if (!(p > 0)) return 0;
+  return Math.min(p, 1);
+}
+
+/**
+ * Append the visible part of the link (x1, y1) → (x2, y2) to the current path.
+ * `trim1` / `trim2` are px cut from each end; `progress` is the drawn fraction from the source
+ * (from the target when `fromTarget`). With `arrow`, the line stops short of the tip and the
+ * tip (x, y) and unit direction (ux, uy) are written to `tip`.
+ * Returns LINK_NONE, LINK_DRAWN or LINK_ARROW.
+ */
+export function linkPath(
+  ctx: Ctx2D,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  curvature: number,
+  trim1: number,
+  trim2: number,
+  progress: number,
+  fromTarget: boolean,
+  arrow: boolean,
+  tip: Float64Array,
+): number {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const len = Math.hypot(dx, dy);
+  const p = progressOf(progress);
+  if (!(len > 1e-6) || p <= 0) return LINK_NONE;
+
+  if (curvature === 0 || !Number.isFinite(curvature)) {
+    const ux = dx / len;
+    const uy = dy / len;
+    const a0 = trim1;
+    const a1 = len - trim2;
+    if (a1 - a0 < 0.5) return LINK_NONE;
+    let s0 = a0;
+    let s1 = a1;
+    if (p < 1) {
+      const span = (a1 - a0) * p;
+      if (fromTarget) s0 = a1 - span;
+      else s1 = a0 + span;
+    }
+    let end = s1;
+    const withArrow = arrow && s1 - s0 > ARROW_LEN * 1.2;
+    if (withArrow) {
+      end = s1 - (ARROW_LEN - 1);
+      tip[0] = x1 + ux * s1;
+      tip[1] = y1 + uy * s1;
+      tip[2] = ux;
+      tip[3] = uy;
+    }
+    ctx.moveTo(x1 + ux * s0, y1 + uy * s0);
+    ctx.lineTo(x1 + ux * end, y1 + uy * end);
+    return withArrow ? LINK_ARROW : LINK_DRAWN;
+  }
+
+  const cx = (x1 + x2) / 2 - dy * curvature;
+  const cy = (y1 + y2) / 2 + dx * curvature;
+  const ta = quadTrim(x1, y1, cx, cy, x2, y2, trim1, false);
+  const tb = quadTrim(x1, y1, cx, cy, x2, y2, trim2, true);
+  if (tb - ta < 0.01) return LINK_NONE;
+  let t0 = ta;
+  let t1 = tb;
+  if (p < 1) {
+    const span = (tb - ta) * p;
+    if (fromTarget) t0 = tb - span;
+    else t1 = ta + span;
+  }
+  let tEnd = t1;
+  let withArrow = false;
+  if (arrow) {
+    const sx = quadSlope(x1, cx, x2, t1);
+    const sy = quadSlope(y1, cy, y2, t1);
+    const speed = Math.hypot(sx, sy);
+    if (speed > 1e-6) {
+      const dt = (ARROW_LEN - 1) / speed;
+      if (t1 - t0 > dt * 1.2) {
+        withArrow = true;
+        tEnd = t1 - dt;
+        tip[0] = quadAt(x1, cx, x2, t1);
+        tip[1] = quadAt(y1, cy, y2, t1);
+        tip[2] = sx / speed;
+        tip[3] = sy / speed;
+      }
+    }
+  }
+  // Sub-curve [t0, tEnd]: control = B(t0) + (tEnd − t0) / 2 · B′(t0).
+  const px = quadAt(x1, cx, x2, t0);
+  const py = quadAt(y1, cy, y2, t0);
+  const h = (tEnd - t0) / 2;
+  ctx.moveTo(px, py);
+  ctx.quadraticCurveTo(
+    px + h * quadSlope(x1, cx, x2, t0),
+    py + h * quadSlope(y1, cy, y2, t0),
+    quadAt(x1, cx, x2, tEnd),
+    quadAt(y1, cy, y2, tEnd),
+  );
+  return withArrow ? LINK_ARROW : LINK_DRAWN;
+}
+
+/** Self-loop circle radius (px) for a node of screen radius `r`; |curvature| enlarges it. */
+export function loopRadius(r: number, curvature: number): number {
+  const c = Number.isFinite(curvature) ? Math.min(Math.abs(curvature), 1) : 0;
+  return Math.max(6, r * 0.8) * (1 + 2 * c);
+}
+
+/** Centre y of the self-loop circle above a node at screen y `y` with radius `r`. */
+export function loopCenterY(y: number, r: number, rho: number): number {
+  return y - r - rho * 0.5;
+}
+
+/** Append a self-loop above the node (x, y, r); `progress` sweeps the circle. */
+export function loopPath(
+  ctx: Ctx2D,
+  x: number,
+  y: number,
+  r: number,
+  curvature: number,
+  progress: number,
+): number {
+  const p = progressOf(progress);
+  if (p <= 0) return LINK_NONE;
+  const rho = loopRadius(r, curvature);
+  const cy = loopCenterY(y, r, rho);
+  const a0 = Math.PI / 2;
+  ctx.moveTo(x, cy + rho);
+  ctx.arc(x, cy, rho, a0, a0 + TAU * p);
+  return LINK_DRAWN;
+}
+
+/** Point on the link at its middle (t = 0.5), screen space. */
+export function linkMidpoint(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  curvature: number,
+): [number, number] {
+  const c = Number.isFinite(curvature) ? curvature : 0;
+  return [(x1 + x2) / 2 - ((y2 - y1) * c) / 2, (y1 + y2) / 2 + ((x2 - x1) * c) / 2];
+}