@visualli/react 0.1.7 → 0.2.1

package/src/design/containers.ts

@@ -0,0 +1,150 @@
+// ─── Containers ──────────────────────────────────────────────────────────────
+//
+// The design system's containers (geometry/container.ts, copied verbatim into
+// @visualli/core): a dashed hull around the member ideas (HULL.padX / HULL.padY
+// beyond their centres, more for large ideas: HULL_CLEAR) with HULL.radius corners, and the group's name as a pill straddling
+// the hull's edge. Where the pill goes is the design system's placeContainerLabel:
+// candidate spots along all four edges, scored against every idea on the layer
+// (with its outermost ring), every connector curve and the names placed before
+// it. The pill's look comes from .vi-map__group-label in css/spec.css
+// (CANVAS_STYLE.group). Hull and pill are painted by the two container layers.
+
+import {
+  CANVAS_STYLE,
+  RINGS,
+  connectorGeometry,
+  connectorSamples,
+  containerHull,
+  labelGrowth,
+  nodeRadii,
+  placeContainerLabel,
+  ringsFor,
+  type FlatNode,
+  type Hull,
+  type LabelBox,
+  type LabelSide,
+} from '@visualli/core';
+import type { Design } from './design';
+
+const PILL = CANVAS_STYLE.group;
+
+export interface ContainerInput { id: string; label?: string; nodeIds: string[] }
+export interface ConnectionInput { from: string; to: string }
+
+export interface PlacedPill { text: string; x: number; y: number; side: LabelSide; w: number; h: number }
+export interface PlacedContainer { id: string; hull: Hull; pill: PlacedPill | null }
+
+/** The pill's font at `px`: the note face (the UI face in readable type, via Design.fontNote). */
+export const pillFont = (d: Design, px: number): string => `${PILL.labelWeight} ${px}px ${d.fontNote}`;
+
+
+let measureCtx: CanvasRenderingContext2D | null = null;
+function measurer(): CanvasRenderingContext2D | null {
+  if (!measureCtx && typeof document !== 'undefined') measureCtx = document.createElement('canvas').getContext('2d');
+  return measureCtx;
+}
+
+/** The pill's box in world units for `text` (ellipsised past labelMaxWidth), with the text grown by `k`. */
+export function measurePill(text: string, d: Design, k: number, c: CanvasRenderingContext2D | null = measurer()): PlacedPill {
+  const px = PILL.labelSize * d.labelScale * k;
+  const padX = PILL.labelPadding.x, border = PILL.labelBorderWidth;
+  const room = PILL.labelMaxWidth - padX * 2 - border * 2;
+  let shown = text, tw = text.length * px * 0.5;
+  if (c) {
+    c.font = pillFont(d, px);
+    tw = c.measureText(text).width;
+    if (tw > room) {
+      // One-line ellipsis, like text-overflow: ellipsis.
+      let lo = 0, hi = text.length;
+      while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (c.measureText(text.slice(0, mid).trimEnd() + '…').width <= room) lo = mid; else hi = mid - 1; }
+      shown = text.slice(0, lo).trimEnd() + '…';
+      tw = c.measureText(shown).width;
+    }
+  }
+  return {
+    text: shown, x: 0, y: 0, side: 'bottom',
+    w: Math.min(PILL.labelMaxWidth, tw + padX * 2 + border * 2),
+    h: px * PILL.labelLineHeight + PILL.labelPadding.top + PILL.labelPadding.bottom + border * 2,
+  };
+}
+
+/** The box an idea occupies, its outermost ring included (what a container name must not cover). */
+function ideaBox(n: FlatNode): LabelBox {
+  const { rx, ry } = nodeRadii(n);
+  const rings = ringsFor(n.branchCount);
+  const s = rings.length ? RINGS[rings.length - 1]!.scale : 1;
+  return { x0: n.x - rx * s, x1: n.x + rx * s, y0: n.y - ry * s, y1: n.y + ry * s };
+}
+
+/**
+ * Hulls and name positions for a layer's containers, in file order (each name
+ * avoids the ones placed before it). Placement uses the names' size at 100%
+ * (k = 1), so they don't hop while zooming; they follow ideas that are dragged.
+ */
+export function layoutContainers(
+  containers: ReadonlyArray<ContainerInput>,
+  nodes: ReadonlyMap<string, FlatNode>,
+  connections: ReadonlyArray<ConnectionInput>,
+  d: Design,
+): PlacedContainer[] {
+  if (containers.length === 0) return [];
+  const ideas: LabelBox[] = [];
+  for (const n of nodes.values()) ideas.push(ideaBox(n));
+  const lines = connections.flatMap((c) => {
+    const a = nodes.get(c.from), b = nodes.get(c.to);
+    if (!a || !b) return [];
+    const g = connectorGeometry(a, b, d.metrics.edgeGap);
+    return [connectorSamples(g.a, g.mid, g.b)];
+  });
+  const placed: LabelBox[] = [];
+  const out: PlacedContainer[] = [];
+  for (const c of containers) {
+    const members = c.nodeIds.map((id) => nodes.get(id)).filter((n): n is FlatNode => !!n);
+    const hull = containerHull(members.map((n) => ({ x: n.x, y: n.y, ...nodeRadii(n) })));
+    if (!hull) continue;
+    let pill: PlacedPill | null = null;
+    if (c.label) {
+      const size = measurePill(c.label, d, 1);
+      const at = placeContainerLabel(hull, size, { ideas, connectors: lines, labels: placed });
+      pill = { ...size, x: at.x, y: at.y, side: at.side };
+      placed.push({ x0: at.x - size.w / 2, x1: at.x + size.w / 2, y0: at.y - size.h / 2, y1: at.y + size.h / 2 });
+    }
+    out.push({ id: c.id, hull, pill });
+  }
+  return out;
+}
+
+/** The dashed hull (beneath connectors and ideas). */
+export function drawHull(c: CanvasRenderingContext2D, h: Hull, d: Design): void {
+  c.save();
+  c.strokeStyle = d.tokens['line-strong']!;
+  c.lineWidth = PILL.strokeWidth;
+  c.setLineDash([...PILL.dash]);
+  c.beginPath();
+  c.roundRect(h.x0, h.y0, h.x1 - h.x0, h.y1 - h.y0, h.radius);
+  c.stroke();
+  c.restore();
+}
+
+/** The name pill (above connectors and ideas), its text growing like idea labels when zoomed out (labelGrowth). */
+export function drawPill(c: CanvasRenderingContext2D, p: PlacedPill, d: Design, zoom: number): void {
+  const k = labelGrowth(zoom).idea;
+  const size = k === 1 ? p : measurePill(p.text, d, k, c);
+  const contrast = d.theme.startsWith('contrast');
+  const bw = contrast ? PILL.contrastLabelBorderWidth : PILL.labelBorderWidth;
+  c.save();
+  c.beginPath();
+  c.roundRect(p.x - size.w / 2 + bw / 2, p.y - size.h / 2 + bw / 2, size.w - bw, size.h - bw, (size.h - bw) / 2);
+  c.fillStyle = d.tokens[PILL.labelFill]!;
+  c.fill();
+  c.lineWidth = bw;
+  c.strokeStyle = d.tokens[contrast ? PILL.contrastLabelBorder : PILL.labelBorder]!;
+  c.stroke();
+  c.font = pillFont(d, PILL.labelSize * d.labelScale * k);
+  c.fillStyle = d.tokens[PILL.labelInk]!;
+  c.textAlign = 'center';
+  c.textBaseline = 'middle';
+  // Centre of the text box: the padding is uneven (top < bottom), so nudge by half the difference.
+  c.fillText(size.text, p.x, p.y + (PILL.labelPadding.top - PILL.labelPadding.bottom) / 2);
+  c.restore();
+}

package/src/design/design.ts

@@ -0,0 +1,115 @@
+// ─── Design object ───────────────────────────────────────────────────────────
+//
+// Everything the canvas needs for one theme + comfort combination, resolved
+// once from the design-system tokens (no colour or font literals here).
+
+import {
+  CANVAS_STYLE,
+  TYPE_STYLES,
+  isContrastTheme,
+  isDarkTheme,
+  labelScale,
+  metricsFor,
+  resolveComfort,
+  resolveTheme,
+  type Comfort,
+  type Metrics,
+  type ResolvedComfort,
+  type ThemeInput,
+  type ThemeName,
+  TOKENS,
+} from '@visualli/core';
+
+export interface NodeShadow { x: number; y: number; blur: number; color: string }
+
+export interface Design {
+  theme: ThemeName;
+  comfort: ResolvedComfort;
+  tokens: Readonly<Record<string, string>>;
+  metrics: Metrics;
+  isDark: boolean;
+  /** CSS font stacks, already switched to the readable face when that comfort setting is on. */
+  fontHand: string;
+  fontNote: string;
+  fontUi: string;
+  /** Multiplier for label sizes (`--vi-label-scale`). */
+  labelScale: number;
+  /** Idea drop shadow for this theme; null when the theme turns it off (high contrast). */
+  nodeShadow: NodeShadow | null;
+  /** Attributes the spec CSS keys off; put them on the renderer's root element. */
+  attrs: Record<string, string>;
+  /** Canvas weight/size for connector labels (the readable face is smaller and bolder). */
+  edgeLabel: { weight: number; size: number };
+}
+
+/** Parse a CSS shadow like `0 6px 14px rgba(…)` as written in the design-system CSS. */
+function parseShadow(css: string): NodeShadow | null {
+  const m = /^(-?[\d.]+)(?:px)?\s+(-?[\d.]+)(?:px)?\s+([\d.]+)(?:px)?\s+(.+)$/.exec(css.trim());
+  return m ? { x: +m[1]!, y: +m[2]!, blur: +m[3]!, color: m[4]!.trim() } : null;
+}
+
+const cache = new Map<string, Design>();
+
+export function makeDesign(theme: ThemeName, comfortIn: ResolvedComfort): Design {
+  const key = `${theme}|${+comfortIn.readableType}${+comfortIn.largerText}${+comfortIn.reducedMotion}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+
+  const tokens = TOKENS[theme];
+  const ui = tokens['font-ui']!;
+  const d: Design = {
+    theme,
+    comfort: comfortIn,
+    tokens,
+    metrics: metricsFor(comfortIn),
+    isDark: isDarkTheme(theme),
+    fontHand: comfortIn.readableType ? ui : tokens['font-hand']!,
+    fontNote: comfortIn.readableType ? ui : tokens['font-note']!,
+    fontUi: ui,
+    labelScale: labelScale(comfortIn),
+    nodeShadow: isContrastTheme(theme) ? null : parseShadow(isDarkTheme(theme) ? CANVAS_STYLE.node.shadowDark : CANVAS_STYLE.node.shadowLight),
+    attrs: {
+      'data-theme': theme,
+      ...(comfortIn.readableType ? { 'data-type': 'readable' } : {}),
+      ...(comfortIn.largerText ? { 'data-scale': 'lg' } : {}),
+      ...(comfortIn.reducedMotion ? { 'data-motion': 'reduced' } : {}),
+    },
+    edgeLabel: comfortIn.readableType ? { weight: CANVAS_STYLE.edge.readableLabelWeight, size: CANVAS_STYLE.edge.readableLabelSize } : { weight: CANVAS_STYLE.edge.labelWeight, size: CANVAS_STYLE.edge.labelSize },
+  };
+  cache.set(key, d);
+  return d;
+}
+
+/** Canvas font shorthand for an idea label at its natural (unscaled) size. */
+export function ideaFont(d: Design, px: number): string {
+  const weight = TYPE_STYLES['node-label'].weight;
+  return `${weight} ${px}px ${d.fontHand}`;
+}
+
+export const DEFAULT_DESIGN: Design = makeDesign('light', { readableType: false, largerText: false, reducedMotion: false });
+
+export interface DesignProps {
+  /**
+   * One of the 8 design-system themes ('light', 'dark', 'focus-light', 'focus-dark',
+   * 'colorsafe-light', 'colorsafe-dark', 'contrast-light', 'contrast-dark'), a family
+   * ('focus' | 'colorsafe' | 'contrast') or 'auto' (follow the reader's colour scheme).
+   */
+  theme?: ThemeInput;
+  /** @deprecated use `theme`. Kept for one release: true -> 'dark', false -> 'light'. */
+  isDark?: boolean;
+  /** Readable type, larger text, reduced motion. */
+  comfort?: Comfort;
+  /** Switch to the matching high-contrast theme under forced-colors (Windows high contrast etc.). Default true. */
+  respectForcedColors?: boolean;
+}
+
+/** Resolve props + reader environment (colour scheme, forced colours, reduced motion) to a Design. */
+export function resolveDesign(props: DesignProps, env: { prefersDark: boolean; forcedColors: boolean; prefersReducedMotion: boolean }): Design {
+  const input: ThemeInput | undefined = props.theme ?? (props.isDark === undefined ? undefined : props.isDark ? 'dark' : 'light');
+  let theme = resolveTheme(input, { prefersDark: env.prefersDark, forcedColors: env.forcedColors });
+  // Forced colours override the reader's palette: honour that with the high-contrast theme of the same scheme.
+  if (env.forcedColors && props.respectForcedColors !== false && !isContrastTheme(theme)) {
+    theme = (isDarkTheme(theme) ? 'contrast-dark' : 'contrast-light') as ThemeName;
+  }
+  return makeDesign(theme, resolveComfort(props.comfort, { prefersReducedMotion: env.prefersReducedMotion }));
+}

package/src/design/drawing.ts

@@ -0,0 +1,303 @@
+// ─── Canvas drawing ──────────────────────────────────────────────────────────
+//
+// Draws ideas and connectors onto a native 2D context using the
+// design system's geometry and tokens. Konva owns the stage, layers, viewport
+// and layer transitions; these functions only paint.
+//
+// Performance notes:
+//  - Outlines are cached as Path2D per (shape, rx, ry): built once, reused every frame.
+//  - Label line breaks are cached per (font epoch, font, width, text).
+//  - No allocations on the per-idea hot path except the label array on a cache miss.
+
+import {
+  CANVAS_STYLE,
+  IDEA,
+  ideaDetail,
+  TYPE_STYLES,
+  blobPath,
+  ideaStyle,
+  labelGrowth,
+  nodeRadii,
+  ringsFor,
+  shapeOfLevel,
+  type ConnectorGeometry,
+  type FlatNode,
+} from '@visualli/core';
+import type { Design } from './design';
+import { fontsEpoch } from './runtime';
+import type { Arrival, EdgeArrival } from './choreography';
+
+const DEG = Math.PI / 180;
+
+// ── Path2D cache ──────────────────────────────────────────────────────────────
+
+const MAX_CACHED_PATHS = 4096;
+const pathCache = new Map<string, Path2D>();
+
+/** Outline of a blob centred on the origin, as a cached Path2D (SVG path data from the design system). */
+export function blobPath2D(shape: number, rx: number, ry: number): Path2D {
+  const key = `${shape}|${rx}|${ry}`;
+  let p = pathCache.get(key);
+  if (!p) {
+    if (pathCache.size >= MAX_CACHED_PATHS) pathCache.delete(pathCache.keys().next().value as string);
+    p = new Path2D(blobPath(shape, rx, ry));
+    pathCache.set(key, p);
+  }
+  return p;
+}
+
+/** Test hook. */
+export const _pathCacheSize = (): number => pathCache.size;
+
+const NO_DASH: number[] = [];
+const NO_RINGS: ReadonlyArray<never> = [];
+const dashCache = new Map<string, number[]>();
+function dashOf(spec: string): number[] {
+  if (!spec) return NO_DASH;
+  let d = dashCache.get(spec);
+  if (!d) { d = spec.split(/\s+/).map(Number); dashCache.set(spec, d); }
+  return d;
+}
+
+// ── Label layout ──────────────────────────────────────────────────────────────
+
+const lineCache = new Map<string, string[]>();
+const MAX_CACHED_LAYOUTS = 8192;
+
+/** Greedy word wrap at `maxWidth` (natural px), clamped to `maxLines` with an ellipsis (ideas pass Infinity: they are
+ *  sized to hold their whole label). */
+export function layoutLabel(c: CanvasRenderingContext2D, text: string, font: string, maxWidth: number, maxLines: number = Infinity): string[] {
+  const key = `${fontsEpoch()}|${font}|${maxWidth}|${text}`;
+  const hit = lineCache.get(key);
+  if (hit) return hit;
+  c.font = font;
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let cur = '';
+  const fit = (s: string) => c.measureText(s).width <= maxWidth;
+  for (const w of words) {
+    const next = cur ? `${cur} ${w}` : w;
+    if (fit(next)) { cur = next; continue; }
+    if (cur) lines.push(cur);
+    // A single word wider than the box is broken by characters.
+    let rest = w;
+    while (!fit(rest) && rest.length > 1) {
+      let n = rest.length - 1;
+      while (n > 1 && !fit(rest.slice(0, n))) n--;
+      lines.push(rest.slice(0, n));
+      rest = rest.slice(n);
+    }
+    cur = rest;
+  }
+  if (cur) lines.push(cur);
+  if (lines.length > maxLines) {
+    lines.length = maxLines;
+    let last = lines[maxLines - 1]! + '…';
+    while (last.length > 1 && !fit(last)) last = last.slice(0, -2) + '…';
+    lines[maxLines - 1] = last;
+  }
+  if (lineCache.size >= MAX_CACHED_LAYOUTS) lineCache.clear();
+  lineCache.set(key, lines);
+  return lines;
+}
+
+// ── Ideas ─────────────────────────────────────────────────────────────────────
+
+export interface IdeaState {
+  hovered: boolean;
+  pressed: boolean;
+  selected: boolean;
+  /** Keyboard focus (the accessible layer is focused on this idea). */
+  focused: boolean;
+  dimmed: boolean;
+  /** Hover/select progress (0 at rest, 1 raised) from the choreography; defaults to the boolean state when omitted. */
+  lift?: number;
+  ring?: number;
+  /** Arrival look mid-reveal (bloom); null/omitted once arrived. */
+  arrival?: Arrival | null;
+}
+export const IDLE: IdeaState = { hovered: false, pressed: false, selected: false, focused: false, dimmed: false };
+
+export interface IdeaOptions {
+  /** Drop shadows are skipped for big maps / while dragging. */
+  shadows: boolean;
+  /** Device pixels per world unit (canvas shadows are in device space). Computed once per frame by the caller; derived from the transform when omitted. */
+  k?: number;
+  /** Opacity of a dimmed idea (the design system's `.vi-node.is-dimmed` for the theme and layout); default the focus themes'. */
+  dimOpacity?: number;
+  /** The context's transform at the start of the frame. When given, ideas are placed with setTransform (no save/restore); the caller must restore it afterwards. */
+  base?: DOMMatrix;
+}
+
+/** Fill + ring an idea is drawn with in `d`'s theme: its topic's, or its custom colour as given (the design system's colour rule). */
+export const ideaColors = (d: Design, n: Pick<FlatNode, 'topic' | 'custom'>) => ideaStyle(d.theme, n);
+
+/** An idea's label size in natural px: the design system's size for its kind × the comfort label scale. */
+export const ideaLabelPx = (n: Pick<FlatNode, 'kind'>, d: Design): number => IDEA.labelSize[n.kind ?? 'node'] * d.labelScale;
+
+/**
+ * Paint one idea (rings, body, label) centred on node.x / node.y.
+ *
+ * With `opt.base` (the context's transform at the start of the frame) the idea is
+ * positioned with a single setTransform and no save/restore: the caller restores
+ * the base transform after the last idea. Without it, state is saved and restored.
+ */
+export function drawIdea(c: CanvasRenderingContext2D, node: FlatNode, d: Design, zoom: number, st: IdeaState, opt: IdeaOptions): void {
+  const { rx, ry } = nodeRadii(node);
+  const { fill, ring } = ideaColors(d, node);
+  const screenW = node.width * zoom;
+  const base = opt.base;
+
+  // Specks: one filled box, no transform changes.
+  // Level of detail (geometry/detail.ts): a speck below DETAIL.speckBelow, body only below DETAIL.bodyOnlyBelow.
+  const detail = ideaDetail(screenW, st.selected || st.focused || st.hovered);
+  if (detail === 'speck') {
+    const a = (st.dimmed ? opt.dimOpacity ?? CANVAS_STYLE.node.dimmedOpacityFocus : 1) * (st.arrival ? st.arrival.alpha : 1);
+    if (a !== 1) c.globalAlpha = a;
+    c.fillStyle = fill;
+    c.fillRect(node.x - rx, node.y - ry, rx * 2, ry * 2);
+    if (a !== 1) c.globalAlpha = 1;
+    return;
+  }
+
+  const detailed = detail === 'full';
+  const shape = shapeOfLevel(node.level);
+  const rings = detailed ? ringsFor(node.branchCount) : NO_RINGS;
+  const raised = st.hovered || st.pressed || st.selected;
+  const lift = st.lift ?? (raised ? 1 : 0);
+  const ringT = st.ring ?? (raised ? 1 : 0);
+  const arr = st.arrival;
+  const y = node.y + lift * CANVAS_STYLE.node.hoverLift + (arr ? arr.dy : 0);
+  const x = node.x + (arr ? arr.dx : 0);
+  let k = opt.k;
+  if (k === undefined) { const m = c.getTransform(); k = Math.hypot(m.a, m.b); } // device px per world unit
+
+  if (base) c.setTransform(base.a, base.b, base.c, base.d, base.e + base.a * x + base.c * y, base.f + base.b * x + base.d * y);
+  else { c.save(); c.translate(x, y); }
+  if (arr) c.scale(arr.scale, arr.scale);
+  c.lineJoin = 'round';
+  const baseAlpha = (st.dimmed ? opt.dimOpacity ?? CANVAS_STYLE.node.dimmedOpacityFocus : 1) * (arr ? arr.alpha : 1);
+  c.globalAlpha = baseAlpha;
+
+  // Rings, outermost first so the inner ones sit on top.
+  if (rings.length) {
+    const ringSpin = ringT * CANVAS_STYLE.node.hoverRingsRotate;
+    const ringGrow = 1 + ringT * (CANVAS_STYLE.node.hoverRingsScale - 1);
+    c.fillStyle = fill;
+    c.strokeStyle = ring;
+    let dashed = false;
+    for (let i = rings.length - 1; i >= 0; i--) {
+      const r = rings[i]!;
+      const angle = (r.rotate + ringSpin) * DEG;
+      c.rotate(angle);
+      c.globalAlpha = baseAlpha * r.opacity;
+      const path = blobPath2D(shape, rx * r.scale * ringGrow, ry * r.scale * ringGrow);
+      c.fill(path);
+      c.lineWidth = r.width;
+      if (r.dash) { c.setLineDash(dashOf(r.dash)); dashed = true; } else if (dashed) { c.setLineDash(NO_DASH); dashed = false; }
+      c.stroke(path);
+      c.rotate(-angle);
+    }
+    if (dashed) c.setLineDash(NO_DASH);
+    c.globalAlpha = baseAlpha;
+  }
+
+  // Body.
+  const body = blobPath2D(shape, rx, ry);
+  c.fillStyle = fill;
+  const shadow = detailed && opt.shadows ? d.nodeShadow : null;
+  if (shadow) {
+    c.shadowColor = shadow.color;
+    c.shadowBlur = shadow.blur * k;
+    c.shadowOffsetX = shadow.x * k;
+    c.shadowOffsetY = shadow.y * k;
+  }
+  c.fill(body);
+  if (shadow) { c.shadowColor = 'transparent'; c.shadowBlur = 0; c.shadowOffsetX = 0; c.shadowOffsetY = 0; }
+  c.strokeStyle = st.focused ? d.tokens['focus']! : st.selected ? d.tokens['ink']! : ring;
+  c.lineWidth = st.selected || st.focused ? CANVAS_STYLE.node.selectedStrokeWidth : d.metrics.nodeStroke;
+  c.stroke(body);
+
+  // Label.
+  // Label: the whole label (the idea is sized for it, idea.ts), growing up to LABEL_GROWTH.idea when zoomed out.
+  if (detailed && node.title) {
+    const px = ideaLabelPx(node, d);
+    const font = `${TYPE_STYLES['node-label'].weight} ${px}px ${d.fontHand}`;
+    const lines = layoutLabel(c, node.title, font, node.width - IDEA.labelInset);
+    const s = labelGrowth(zoom).idea;
+    const lh = px * IDEA.labelLineHeight;
+    c.scale(s, s);
+    c.font = font;
+    c.fillStyle = d.tokens['node-ink']!;
+    c.textAlign = 'center';
+    c.textBaseline = 'middle';
+    if (d.comfort.readableType && 'letterSpacing' in c) (c as unknown as { letterSpacing: string }).letterSpacing = `${(px * 0.02).toFixed(2)}px`;
+    const y0 = -((lines.length - 1) * lh) / 2;
+    for (let i = 0; i < lines.length; i++) c.fillText(lines[i]!, 0, y0 + i * lh);
+  }
+  if (base) c.globalAlpha = 1; else c.restore();
+}
+
+// ── Connectors ────────────────────────────────────────────────────────────────
+
+export interface PreparedConnector extends ConnectorGeometry {
+  path: Path2D;
+  arrowPath: Path2D;
+  /** Length of the curve in world units (for drawing it from source to target). */
+  len: number;
+}
+
+/** Length of the connector's cubic ("M x y C x y x y x y"), by sampling. */
+function cubicLength(d: string): number {
+  const v = d.match(/-?\d+(?:\.\d+)?/g)?.map(Number);
+  if (!v || v.length < 8) return 0;
+  const [x0, y0, x1, y1, x2, y2, x3, y3] = v as [number, number, number, number, number, number, number, number];
+  let len = 0, px = x0, py = y0;
+  for (let i = 1; i <= 16; i++) {
+    const t = i / 16, u = 1 - t;
+    const x = u * u * u * x0 + 3 * u * u * t * x1 + 3 * u * t * t * x2 + t * t * t * x3;
+    const y = u * u * u * y0 + 3 * u * u * t * y1 + 3 * u * t * t * y2 + t * t * t * y3;
+    len += Math.hypot(x - px, y - py); px = x; py = y;
+  }
+  return len;
+}
+
+export function prepareConnector(g: ConnectorGeometry): PreparedConnector {
+  return { ...g, path: new Path2D(g.d), arrowPath: new Path2D(g.arrow), len: cubicLength(g.d) };
+}
+
+/** Connectors shorter than this on screen, and labels smaller than LABEL_MIN_SCREEN_PX, are invisible: skipped. */
+const CONNECTOR_MIN_SCREEN_PX = 3;
+const LABEL_MIN_SCREEN_PX = 6;
+
+export function drawConnector(c: CanvasRenderingContext2D, g: PreparedConnector, d: Design, zoom: number, dashed: boolean, label: string | undefined, arrival?: EdgeArrival | null): void {
+  if (Math.hypot(g.b.x - g.a.x, g.b.y - g.a.y) * zoom < CONNECTOR_MIN_SCREEN_PX) return;
+  c.save();
+  if (arrival) c.globalAlpha = arrival.alpha;
+  c.strokeStyle = d.tokens['edge']!;
+  c.lineWidth = d.metrics.edgeWidth;
+  c.lineCap = 'round';
+  c.lineJoin = 'round';
+  if (dashed) c.setLineDash([...CANVAS_STYLE.edge.dash]);
+  else if (arrival && arrival.draw < 1) c.setLineDash([g.len * arrival.draw, g.len * 2]); // draws from source to target
+  if (!(arrival && arrival.draw <= 0.001)) c.stroke(g.path);
+  c.setLineDash([]);
+  c.stroke(g.arrowPath);
+
+  // The design system's connector label (`.vi-edge__label`), growing up to LABEL_GROWTH.connector when zoomed out (`--vi-inv`); the readable face is smaller and bolder.
+  const labelPx = label ? d.edgeLabel.size * labelGrowth(zoom).connector : 0;
+  if (label && labelPx * zoom >= LABEL_MIN_SCREEN_PX) {
+    const px = labelPx;
+    c.font = `${d.edgeLabel.weight} ${px}px ${d.fontNote}`;
+    c.textAlign = 'center';
+    c.textBaseline = 'middle';
+    // paint-order: stroke — a halo in the canvas colour keeps the label legible over the line.
+    c.lineWidth = CANVAS_STYLE.edge.labelHaloWidth;
+    c.strokeStyle = d.tokens['canvas']!;
+    c.strokeText(label, g.mid.x, g.mid.y);
+    c.fillStyle = d.tokens['edge-label']!;
+    c.fillText(label, g.mid.x, g.mid.y);
+  }
+  c.restore();
+}
+

package/src/design/measure.ts

@@ -0,0 +1,34 @@
+// ─── Label measurement ────────────────────────────────────────────────────────
+//
+// The text measurement the design system's ideaSize (geometry/idea.ts) needs:
+// the idea label's width in its own face and weight — Kalam, or the UI face with
+// its .02em tracking in readable type — on a 2D canvas, the same engine that draws it.
+
+import { TYPE_STYLES, approximateMeasure, type IdeaMeasure } from '@visualli/core';
+import type { Design } from './design';
+import { fontsEpoch } from './runtime';
+
+let ctx: CanvasRenderingContext2D | null | undefined;
+const cache = new Map<string, number>();
+const MAX_CACHED = 8192;
+
+/** Width of a label in `d`'s idea face (cached per face, size, text and font load). */
+export function ideaMeasure(d: Pick<Design, 'fontHand' | 'comfort'>): IdeaMeasure {
+  if (ctx === undefined) ctx = typeof document !== 'undefined' ? document.createElement('canvas').getContext('2d') : null;
+  const c = ctx;
+  if (!c) return approximateMeasure;
+  const weight = TYPE_STYLES['node-label'].weight;
+  const tracking = d.comfort.readableType ? 0.02 : 0;
+  return (text, px) => {
+    const font = `${weight} ${px}px ${d.fontHand}`;
+    const key = `${fontsEpoch()}|${font}|${text}`;
+    let w = cache.get(key);
+    if (w === undefined) {
+      c.font = font;
+      w = c.measureText(text).width + text.length * px * tracking;
+      if (cache.size >= MAX_CACHED) cache.clear();
+      cache.set(key, w);
+    }
+    return w;
+  };
+}