@contraagent/elements 0.0.0-stage → 0.1.0

package/src/graph/layout.ts

@@ -0,0 +1,331 @@
+// The drawing of a layered graph: coordinates from the measured sizes, and each
+// edge as straight runs that bend only between layers.
+import { isPoint } from './arrange.js';
+import type { Arrangement, EdgeStyle, EdgePathStep } from './types.js';
+
+export interface Size {
+  w: number;
+  h: number;
+}
+
+/** A rectangle in the drawing. */
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** A straight stretch of an edge along the flow, from `a` to `b`, `at` across it; an edge bends between two. */
+export interface Stretch {
+  a: number;
+  b: number;
+  at: number;
+}
+
+export interface GraphLayout {
+  /** The drawing's size, its margin included. */
+  w: number;
+  h: number;
+  /** Every node, stub and cluster, by id. */
+  at: Record<string, Rect>;
+  /** Every edge path, with its runs. */
+  edges: { from: string; to: string; style: EdgeStyle; runs: Stretch[] }[];
+  /** Each cycling cluster's return to its next round. */
+  returns: LoopReturn[];
+  down: boolean;
+}
+
+/**
+ * A cluster's return to its next round, along the flow (`u`) and across it (`v`): from
+ * the far side of its last layer's outermost item (`from`, at `v0`) out to a band
+ * past its content (`band`), back along the band, and in to its first layer's
+ * outermost item (`to`, at `v1`). Left to right the band is under the nodes; top to
+ * bottom, on their right.
+ */
+export interface LoopReturn {
+  box: string;
+  from: number;
+  v0: number;
+  to: number;
+  v1: number;
+  band: number;
+}
+
+/** The spaces of a drawing; left to right unless `down`. */
+export interface LayoutSpace {
+  /** Between two layers, at the top level and in a cluster. */
+  gap: number;
+  boxGap: number;
+  /** Between two items of a layer, and next to a point an edge passes. */
+  sep: number;
+  pointSep: number;
+  /** A cluster's padding, and the space under its label. */
+  pad: number;
+  /** The space after a box's content, across the flow: the band its return to the next round runs in. */
+  padEnd: number;
+  margin: number;
+}
+
+/** The band past a cluster's content that its return to the next round runs in, and the return's corner radius. */
+export const RETURN_BAND = 24;
+export const RETURN_R = 6;
+
+export const SPACE: Record<'across' | 'down', LayoutSpace> = {
+  across: { gap: 56, boxGap: 40, sep: 16, pointSep: 12, pad: 12, padEnd: RETURN_BAND, margin: 16 },
+  down: { gap: 40, boxGap: 32, sep: 16, pointSep: 12, pad: 10, padEnd: RETURN_BAND, margin: 16 },
+};
+
+/** Tops (across the flow) nearest to `want` that keep the order and each gap: weighted isotonic regression (pool adjacent violators). */
+function placeRow(want: readonly number[], gaps: readonly number[], weight: readonly number[]): number[] {
+  const off: number[] = [0];
+  for (let i = 1; i < want.length; i++) off.push((off[i - 1] as number) + (gaps[i - 1] as number));
+  const blocks: { sum: number; w: number; n: number }[] = [];
+  want.forEach((v, i) => {
+    const w = weight[i] ?? 1;
+    blocks.push({ sum: w * (v - (off[i] as number)), w, n: 1 });
+    while (blocks.length > 1) {
+      const b = blocks[blocks.length - 1] as { sum: number; w: number; n: number };
+      const a = blocks[blocks.length - 2] as { sum: number; w: number; n: number };
+      if (a.sum / a.w <= b.sum / b.w) break;
+      blocks.splice(-2, 2, { sum: a.sum + b.sum, w: a.w + b.w, n: a.n + b.n });
+    }
+  });
+  const out: number[] = [];
+  for (const b of blocks) for (let k = 0; k < b.n; k++) out.push(b.sum / b.w + (off[out.length] as number));
+  return out;
+}
+
+/**
+ * Where everything of a layered graph is drawn, from the sizes of its nodes, its stubs
+ * and its clusters' labels (`lbl:<box id>`): left to right, or top to bottom when
+ * `down`. Each container is laid out inside out, a box being one item of its parent:
+ * its layers side by side, an item at the start of its layer; across the flow, each
+ * item as near as its order allows to the items it is joined to (sweeps of weighted
+ * isotonic regression), so chains run straight. An edge runs along its points and
+ * bends only in the gap between two layers; it enters and leaves a box where its
+ * point inside is, and never passes a node or a box's label.
+ */
+export function layoutGraph(g: Pick<Arrangement, 'clusters' | 'slots' | 'edgePaths'>, sizes: ReadonlyMap<string, Size>, down = false): GraphLayout {
+  const S = SPACE[down ? 'down' : 'across'];
+  const len = (s: Size) => (down ? s.h : s.w);
+  const brd = (s: Size) => (down ? s.w : s.h);
+  const boxIds = new Set(g.clusters.map((b) => b.id));
+  const parentOf = new Map(g.clusters.map((b) => [b.id, b.parent]));
+  const label = (box: string): Size => sizes.get(`lbl:${box}`) ?? { w: 0, h: 0 };
+  // A box's padding: along the flow, and across it. Its label is in a band at its top: across
+  // the flow left to right; along it top to bottom, where a gap under the label lets edges in.
+  const padOf = (box: string) =>
+    down
+      ? { u0: label(box).h + S.pad + S.gap / 2, u1: S.pad, v0: S.pad, v1: S.padEnd, minU: 0, minV: label(box).w + 2 * S.pad }
+      : { u0: S.pad, u1: S.pad, v0: label(box).h + S.pad, v1: S.padEnd, minU: label(box).w + 2 * S.pad, minV: 0 };
+  const extent = new Map<string, { u: number; v: number }>(); // a box's size, along and across
+  const slotSize = (id: string): { u: number; v: number } => {
+    if (boxIds.has(id)) return extent.get(id) ?? { u: 0, v: 0 };
+    if (isPoint(id)) return { u: 0, v: 0 };
+    const s = sizes.get(id) ?? { w: 0, h: 0 };
+    return { u: len(s), v: brd(s) };
+  };
+  interface Local {
+    rows: string[][];
+    start: number[];
+    width: number[];
+    top: Map<string, number>;
+    u: number;
+    v: number;
+  }
+  const local = new Map<string, Local>();
+  const layerIn = new Map<string, Map<string, number>>();
+  const depth = (c: string): number => (c === '' ? 0 : 1 + depth(parentOf.get(c) ?? ''));
+  const containers = ['', ...g.clusters.map((b) => b.id)].sort((a, b) => depth(b) - depth(a));
+  // Where an edge meets a slot, across the flow from the slot's top: a node's middle,
+  // a point, or (a box) where the edge's step inside it is.
+  const attach = (ri: number, si: number): number => {
+    const steps = g.edgePaths[ri]?.steps ?? [];
+    const s = steps[si] as EdgePathStep;
+    if (isPoint(s.id)) return 0;
+    if (!boxIds.has(s.id)) return slotSize(s.id).v / 2;
+    const inner = steps[si - 1]?.in === s.id ? si - 1 : si + 1;
+    const step = steps[inner] as EdgePathStep;
+    return padOf(s.id).v0 + (local.get(s.id)?.top.get(step.id) ?? 0) + attach(ri, inner);
+  };
+  for (const c of containers) {
+    const rows = (g.slots[c] ?? []).map((r) => [...r]);
+    layerIn.set(c, new Map(rows.flatMap((r, i) => r.map((id) => [id, i] as const))));
+    const width = rows.map((r) => Math.max(0, ...r.map((id) => slotSize(id).u)));
+    const gap = c === '' ? S.gap : S.boxGap;
+    const start: number[] = [];
+    width.forEach((_, i) => start.push(i ? (start[i - 1] as number) + (width[i - 1] as number) + gap : 0));
+    // The joins inside this container: slot a of layer l to slot b of layer l + 1.
+    const links: { a: string; b: string; oa: number; ob: number }[] = [];
+    g.edgePaths.forEach((r, ri) =>
+      r.steps.forEach((s, si) => {
+        const p = r.steps[si - 1];
+        if (si && p && p.in === c && s.in === c && layerIn.get(c)?.get(p.id) !== layerIn.get(c)?.get(s.id)) links.push({ a: p.id, b: s.id, oa: attach(ri, si - 1), ob: attach(ri, si) });
+      }),
+    );
+    // Points sit close to each other and to a node, further from a box (its next-pass mark is on its edge).
+    const sepOf = (a: string, b: string | undefined) =>
+      b === undefined ? 0 : boxIds.has(a) || boxIds.has(b) || !(isPoint(a) || isPoint(b)) ? S.sep : S.pointSep;
+    const top = new Map<string, number>();
+    for (const r of rows) {
+      let v = 0;
+      r.forEach((id, i) => {
+        top.set(id, v);
+        v += slotSize(id).v + sepOf(id, r[i + 1]);
+      });
+    }
+    const place = (r: string[], want: (id: string) => number[]) => {
+      const desired = r.map((id) => {
+        const xs = want(id);
+        return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : (top.get(id) ?? 0);
+      });
+      const gaps = r.map((id, i) => slotSize(id).v + sepOf(id, r[i + 1]));
+      // The nodes first, as if the points between them were fixed in size; then the points, around the nodes.
+      const real = r.map((id, i) => (isPoint(id) ? -1 : i)).filter((i) => i >= 0);
+      const span = (i: number, j: number) => gaps.slice(i, j).reduce((a, b) => a + b, 0);
+      const at = placeRow(
+        real.map((i) => desired[i] as number),
+        real.map((i, k) => (k + 1 < real.length ? span(i, real[k + 1] as number) : 0)),
+        real.map(() => 1),
+      );
+      real.forEach((i, k) => (desired[i] = at[k] as number));
+      placeRow(desired, gaps, r.map((id) => (isPoint(id) ? 1 : 1e6))).forEach((v, i) => top.set(r[i] as string, Math.round(v * 100) / 100));
+    };
+    // A node lines up with the nodes it is joined to, when it has any on that side, else with the points;
+    // a point lines up with whatever it is joined to, so a chain runs straight and a long edge goes round it.
+    const near = (id: string, ls: { other: string; at: number }[]) => {
+      const real = isPoint(id) ? ls : ls.filter((x) => !isPoint(x.other));
+      return (real.length ? real : ls).map((x) => x.at);
+    };
+    const fromPrev = (id: string) => near(id, links.filter((l) => l.b === id).map((l) => ({ other: l.a, at: (top.get(l.a) ?? 0) + l.oa - l.ob })));
+    const fromNext = (id: string) => near(id, links.filter((l) => l.a === id).map((l) => ({ other: l.b, at: (top.get(l.b) ?? 0) + l.ob - l.oa })));
+    for (let sweep = 0; sweep < 8; sweep++) {
+      const order = rows.map((_, i) => i);
+      if (sweep % 2) order.reverse();
+      for (const i of order) place(rows[i] as string[], sweep % 2 ? fromNext : fromPrev);
+    }
+    for (const r of rows) place(r, (id) => [...fromPrev(id), ...fromNext(id)]);
+    const lo = top.size ? Math.min(...top.values()) : 0;
+    for (const [id, v] of top) top.set(id, v - lo);
+    const u = (start[start.length - 1] ?? 0) + (width[width.length - 1] ?? 0);
+    const v = Math.max(0, ...rows.flat().map((id) => (top.get(id) ?? 0) + slotSize(id).v));
+    local.set(c, { rows, start, width, top, u, v });
+    if (c !== '') {
+      const p = padOf(c);
+      extent.set(c, { u: Math.max(p.u0 + u + p.u1, p.minU), v: Math.max(p.v0 + v + p.v1, p.minV) });
+    }
+  }
+
+  // Inside out, then outside in: each container's place in the drawing.
+  const at: Record<string, Rect> = {};
+  const origin = new Map<string, { u: number; v: number }>();
+  const rect = (u: number, v: number, s: { u: number; v: number }): Rect => (down ? { x: v, y: u, w: s.v, h: s.u } : { x: u, y: v, w: s.u, h: s.v });
+  const put = (c: string, ou: number, ov: number) => {
+    origin.set(c, { u: ou, v: ov });
+    const l = local.get(c) as Local;
+    l.rows.forEach((r, i) =>
+      r.forEach((id) => {
+        if (isPoint(id)) return;
+        const u = ou + (l.start[i] as number);
+        const v = ov + (l.top.get(id) ?? 0);
+        at[id] = rect(u, v, slotSize(id));
+        if (boxIds.has(id)) {
+          const p = padOf(id);
+          put(id, u + p.u0, v + p.v0);
+        }
+      }),
+    );
+  };
+  put('', S.margin, S.margin);
+  const whole = local.get('') as Local;
+  const U = whole.u + 2 * S.margin;
+  const V = whole.v + 2 * S.margin;
+
+  // A container's layer l: where it starts and ends along the flow, in the drawing.
+  const col = (c: string, l: number): [number, number] => {
+    const lc = local.get(c) as Local;
+    const o = origin.get(c) ?? { u: 0, v: 0 };
+    const c0 = o.u + (lc.start[l] ?? 0);
+    return [c0, c0 + (lc.width[l] ?? 0)];
+  };
+  const layer = (c: string, id: string) => layerIn.get(c)?.get(id) ?? 0;
+  const byOf = (s: EdgePathStep | undefined): string => (s && isPoint(s.id) ? (/\|by:([^|]*)\|/.exec(s.id)?.[1] ?? '') : '');
+  const edges = g.edgePaths.map((r, ri) => {
+    const vOf = (si: number): number => {
+      const s = r.steps[si] as EdgePathStep;
+      const o = origin.get(s.in) ?? { u: 0, v: 0 };
+      return o.v + (local.get(s.in)?.top.get(s.id) ?? 0) + attach(ri, si);
+    };
+    const runs: Stretch[] = r.steps.map((s, si): Stretch => {
+      const prev = r.steps[si - 1];
+      const next = r.steps[si + 1];
+      const [c0, c1] = col(s.in, layer(s.in, s.id));
+      const v = vOf(si);
+      if (si === 0) return { a: c0 + slotSize(s.id).u, b: c1, at: v };
+      if (si === r.steps.length - 1) return { a: c0, b: c0, at: v };
+      if (isPoint(s.id)) {
+        const box = byOf(s);
+        // Beside a box: from where it left the box's side, or up to where it goes in.
+        if (box && prev?.id === box) return { a: col(box, layer(box, r.steps[si - 2]?.id ?? '') + 1)[0], b: c1, at: v };
+        if (box && next?.id === box) {
+          const ln = layer(box, r.steps[si + 2]?.id ?? '');
+          const gap = ln > 0 ? col(box, ln - 1)[1] : (at[box] ? (down ? at[box].y : at[box].x) : c0) + label(box).h + S.pad;
+          return { a: c0, b: gap, at: v };
+        }
+        return { a: c0, b: c1, at: v };
+      }
+      const p = padOf(s.id);
+      const inner = local.get(s.id) as Local;
+      // Out of a box: at its far side, or through its side after the layer it leaves.
+      if (prev?.in === s.id) {
+        if (byOf(next) === s.id) {
+          const u = col(s.id, layer(s.id, prev.id) + 1)[0];
+          return { a: u, b: u, at: vOf(si + 1) };
+        }
+        return { a: c0 + p.u0 + inner.u, b: c1, at: v };
+      }
+      // Into a box: at its near side, or through its side before the layer it goes to.
+      if (byOf(prev) === s.id) {
+        const u = col(s.id, layer(s.id, next?.id ?? ''))[0];
+        return { a: u, b: u, at: vOf(si + 1) };
+      }
+      return { a: c0, b: c0 + p.u0, at: v };
+    });
+    return { from: r.from, to: r.to, style: r.style, runs };
+  });
+  // Each box's return to its next round: from its last layer's item that reaches furthest
+  // across the flow, along the band past the content, to its first layer's.
+  const returns = g.clusters.flatMap((b): LoopReturn[] => {
+    if (!b.cycle) return [];
+    const l = local.get(b.id);
+    const o = origin.get(b.id);
+    if (!l || !o) return [];
+    const outer = (row: readonly string[] | undefined) => {
+      const ids = (row ?? []).filter((id) => !isPoint(id));
+      let best: { u: number; v: number } | null = null;
+      for (const id of ids) {
+        const s = slotSize(id);
+        const v = (l.top.get(id) ?? 0) + s.v;
+        if (!best || v > best.v) best = { u: s.u, v };
+      }
+      return best;
+    };
+    const real = l.rows.map((r, i) => (r.some((id) => !isPoint(id)) ? i : -1)).filter((i) => i >= 0);
+    const fi = real[0] ?? 0;
+    const li = real[real.length - 1] ?? 0;
+    const last = outer(l.rows[li]);
+    const first = outer(l.rows[fi]);
+    if (!last || !first) return [];
+    // An item's middle along the flow, as wide as its layer; one layer: either side of its middle.
+    let from = o.u + (l.start[li] ?? 0) + (l.width[li] ?? 0) / 2;
+    let to = o.u + (l.start[fi] ?? 0) + (l.width[fi] ?? 0) / 2;
+    if (from - to < 4 * RETURN_R) {
+      const d = Math.max(2 * RETURN_R, Math.min(28, Math.min(last.u, first.u) / 4));
+      from = (from + to) / 2 + d;
+      to = from - 2 * d;
+    }
+    return [{ box: b.id, from, v0: o.v + last.v, to, v1: o.v + first.v, band: o.v + l.v + RETURN_BAND / 2 }];
+  });
+  return { w: down ? V : U, h: down ? U : V, at, edges, returns, down };
+}

package/src/graph/marks.ts

@@ -0,0 +1,42 @@
+// How a node draws its marks: a grid, or a bar of counts when it has many; and
+// what a node without `counts` or `progress` shows.
+import type { StateStyles } from '../primitives/states.js';
+import type { GraphNode, GraphNodeInput } from './types.js';
+
+/**
+ * A node with its defaults: no marks, its marks by state as its counts, and as its
+ * progress its marks whose state has the tone `done`, of all its marks, in the words
+ * of `words`.
+ */
+export function fillNode(n: GraphNodeInput, states: StateStyles, words: (done: number, total: number) => string): GraphNode {
+  const { marks = [], loose = [] } = n;
+  const counts: Record<string, number> = {};
+  let done = 0;
+  let total = 0;
+  for (const m of [...marks, ...loose]) {
+    if (!m) continue;
+    counts[m.state] = (counts[m.state] ?? 0) + 1;
+    total++;
+    if (states[m.state]?.tone === 'done') done++;
+  }
+  return { ...n, marks, loose, counts: n.counts ?? counts, progress: n.progress ?? { done, total, label: words(done, total) } };
+}
+
+/** How a node lays out its series marks: as many columns as series up to 12, then 10, then 20; smaller marks as they grow. */
+export function markGrid(series: number): { cols: number; size: number } {
+  if (series <= 12) return { cols: Math.max(1, series), size: 12 };
+  if (series <= 100) return { cols: 10, size: 10 };
+  return { cols: 20, size: 6 };
+}
+
+/** Above this many marks, a node shows a bar of its counts and lists its failed marks. */
+export const BAR_MARKS = 200;
+
+/** A node shows its marks as a bar of counts: it has more than `at` marks. */
+export const asBar = (n: Pick<GraphNode, 'marks' | 'loose'>, at = BAR_MARKS): boolean => n.marks.filter((m) => m !== null).length + n.loose.length > at;
+
+/** A node's bar: each state's share of its items, in `order`, the states it has only. */
+export function barParts(counts: Readonly<Record<string, number>>, order: readonly string[]): { state: string; n: number; pct: number }[] {
+  const total = order.reduce((a, s) => a + (counts[s] ?? 0), 0);
+  return order.filter((s) => (counts[s] ?? 0) > 0).map((s) => ({ state: s, n: counts[s] ?? 0, pct: (100 * (counts[s] ?? 0)) / Math.max(1, total) }));
+}

package/src/graph/nav.ts

@@ -0,0 +1,19 @@
+// Keyboard moves along a drawn edge.
+
+/**
+ * The node joined to `from` along a drawn edge: a later one (`later`, that waits for
+ * it or was created after it) or an earlier one; of several, the one nearest across
+ * the flow (`across`), then the first in drawing order. Null when there is none.
+ */
+export function alongEdge(
+  g: { drawn: readonly string[]; edges: readonly { from: string; to: string }[]; back: readonly boolean[] },
+  from: string,
+  dir: 'later' | 'earlier',
+  across: (id: string) => number,
+): string | null {
+  const rank = new Map(g.drawn.map((id, i) => [id, i]));
+  const ids = [...new Set(g.edges.filter((e, i) => !g.back[i] && (dir === 'later' ? e.from === from : e.to === from)).map((e) => (dir === 'later' ? e.to : e.from)))];
+  const at = across(from);
+  ids.sort((a, b) => Math.abs(across(a) - at) - Math.abs(across(b) - at) || (rank.get(a) ?? 0) - (rank.get(b) ?? 0));
+  return ids[0] ?? null;
+}

package/src/graph/pan-zoom.ts

@@ -0,0 +1,219 @@
+// The graph's frame: fit the drawing in it, zoom, and pan. The view is written on
+// the stage directly, so panning and zooming do not render the element again.
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { FRAME_MIN, FRAME_SHARE } from '../core/frame.js';
+import { fitView, zoomView, type View } from './view.js';
+
+/** How far the view zooms: from half of the whole-drawing view (or of 1) up to this. */
+export const ZOOM_MAX = 2.5;
+/** A pointer moved this far is a pan, not a click. */
+export const DRAG = 4;
+
+/** The transform that shows `v`. */
+export const transformOf = (v: View): string => `translate(${v.x}px,${v.y}px) scale(${v.k})`;
+
+/** What there is to fit: the drawing's size, whether it runs top to bottom, and the least frame height (the selection's card). */
+export interface Drawing {
+  w: number;
+  h: number;
+  down: boolean;
+  room: number;
+}
+
+export interface PanZoomOptions {
+  /** The frame, and the stage in it that the view moves. */
+  frame: () => HTMLElement | null;
+  stage: () => HTMLElement | null;
+  /** What to fit, or null while there is nothing to fit (a view without the drawing). */
+  drawing: () => Drawing | null;
+  /** Ctrl (or ⌘) and the wheel zoom: the drawing is shown. */
+  wheel: () => boolean;
+  /** The drawing runs top to bottom: a touch scrolls the page, a mouse still pans. */
+  down: () => boolean;
+  /** After the view moved. */
+  onMove: () => void;
+  /** After the host's size changed. */
+  onResize: () => void;
+}
+
+/**
+ * The zoom and pan of a drawing in its frame, and the frame's height. Until the
+ * reader zooms or pans (`moved`), the view shows the whole drawing. The host
+ * renders again only when what it draws changes: the frame's height, and whether
+ * "Show all" does anything (`moved`, `fitK`).
+ */
+export class PanZoomController implements ReactiveController {
+  /** The zoom and pan, written on the stage. */
+  view: View = { k: 1, x: 0, y: 0 };
+  /** The frame's height as the drawing needs it; a height set on the host makes the frame taller or shorter. */
+  frameH = 0;
+  /** The scale that shows the whole drawing. */
+  fitK = 1;
+  /** The reader has zoomed or panned away from the whole drawing. */
+  moved = false;
+  /** A pointer is down on the frame. */
+  pressed = false;
+  /** A pan in progress, and whether it went far enough to swallow the click that ends it. */
+  private pan: { id: number; px: number; py: number; x: number; y: number; far: boolean } | null = null;
+  private swallowClick = false;
+  private resize?: ResizeObserver;
+
+  constructor(
+    private readonly host: ReactiveControllerHost & HTMLElement,
+    private readonly o: PanZoomOptions,
+  ) {
+    host.addController(this);
+  }
+
+  hostConnected(): void {
+    // Ctrl (or ⌘) and the wheel zoom; the wheel alone still scrolls the page.
+    this.host.addEventListener('wheel', this.onWheel, { passive: false });
+    this.host.addEventListener('click', this.onClickCapture, { capture: true });
+  }
+
+  hostDisconnected(): void {
+    this.host.removeEventListener('wheel', this.onWheel);
+    this.host.removeEventListener('click', this.onClickCapture, { capture: true });
+    this.resize?.disconnect();
+    this.resize = undefined;
+  }
+
+  hostUpdated(): void {
+    if (this.resize) return;
+    this.resize = new ResizeObserver(() => this.o.onResize());
+    this.resize.observe(this.host);
+  }
+
+  /** The stage's style: the view, as the host renders it. */
+  get transform(): string {
+    return transformOf(this.view);
+  }
+
+  /** Back to the whole drawing, on a new layer. */
+  reset(): void {
+    this.moved = false;
+  }
+
+  /** The frame's height and, until the reader zooms or pans, the view of the whole drawing. */
+  fit(): void {
+    const d = this.o.drawing();
+    if (!d) return;
+    const frame = this.o.frame();
+    // The frame is beside the inspector, or above it on a narrow screen.
+    const width = frame?.clientWidth || this.host.clientWidth;
+    // Top to bottom, the drawing is as tall as it needs at the frame's width.
+    const own = fitView(d.w, d.h, width, d.down ? Infinity : Math.max(FRAME_MIN, FRAME_SHARE * globalThis.innerHeight));
+    // A height set on the host: the frame is not as tall as it was drawn, and the drawing fits the frame as it is.
+    const fh = frame?.clientHeight ?? 0;
+    const whole = `${fh}px` !== (frame?.style.height ?? '0px') ? fitView(d.w, d.h, width, fh, fh) : own;
+    if (whole.k !== this.fitK) {
+      this.fitK = whole.k;
+      this.host.requestUpdate();
+    }
+    // A short drawing's frame grows down to hold the selection's card; the drawing stays where it is.
+    const h = d.down ? own.h : Math.max(own.h, d.room);
+    if (!this.moved) {
+      this.setHeight(h);
+      if (whole.k !== this.view.k || whole.x !== this.view.x || whole.y !== this.view.y) this.setView({ k: whole.k, x: whole.x, y: whole.y });
+    } else if (h > this.frameH) this.setHeight(h);
+  }
+
+  /** Back to the whole drawing. */
+  showAll(): void {
+    this.moved = false;
+    this.fit();
+    this.host.requestUpdate();
+  }
+
+  zoomBy(factor: number, cx = (this.o.frame()?.clientWidth ?? this.host.clientWidth) / 2, cy = (this.o.frame()?.clientHeight ?? this.frameH) / 2): void {
+    this.setMoved();
+    this.setView(zoomView(this.view, factor, cx, cy, Math.min(1, this.fitK) / 2, ZOOM_MAX));
+  }
+
+  /** Bring `el` into the frame when zoom or pan left it outside. */
+  reveal(el: HTMLElement): void {
+    const frame = this.o.frame();
+    if (!frame) return;
+    const f = frame.getBoundingClientRect();
+    const r = el.getBoundingClientRect();
+    const pad = 24;
+    let dx = 0;
+    let dy = 0;
+    if (r.left < f.left + pad) dx = f.left + pad - r.left;
+    else if (r.right > f.right - pad) dx = f.right - pad - r.right;
+    if (r.top < f.top + pad) dy = f.top + pad - r.top;
+    else if (r.bottom > f.bottom - pad) dy = f.bottom - pad - r.bottom;
+    if (dx || dy) {
+      this.setMoved();
+      this.setView({ ...this.view, x: this.view.x + dx, y: this.view.y + dy });
+    }
+  }
+
+  readonly onPointerDown = (e: PointerEvent): void => {
+    this.pressed = true;
+    globalThis.addEventListener('pointerup', () => (this.pressed = false), { once: true });
+    // On a narrow screen a touch scrolls the page; a mouse still pans.
+    if (e.button !== 0 || (e.target as HTMLElement).closest('.tools') || (this.o.down() && e.pointerType !== 'mouse')) return;
+    this.pan = { id: e.pointerId, px: e.clientX, py: e.clientY, x: this.view.x, y: this.view.y, far: false };
+  };
+
+  readonly onPointerMove = (e: PointerEvent): void => {
+    const p = this.pan;
+    if (!p || p.id !== e.pointerId) return;
+    const dx = e.clientX - p.px;
+    const dy = e.clientY - p.py;
+    if (!p.far && Math.hypot(dx, dy) < DRAG) return;
+    if (!p.far) {
+      p.far = true;
+      (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+      (e.currentTarget as HTMLElement).classList.add('drag');
+    }
+    this.setMoved();
+    this.setView({ ...this.view, x: p.x + dx, y: p.y + dy });
+  };
+
+  readonly onPointerUp = (e: PointerEvent): void => {
+    const p = this.pan;
+    if (!p || p.id !== e.pointerId) return;
+    this.pan = null;
+    (e.currentTarget as HTMLElement).classList.remove('drag');
+    if (p.far) this.swallowClick = true;
+  };
+
+  private readonly onWheel = (e: WheelEvent): void => {
+    if (!this.o.wheel() || !(e.ctrlKey || e.metaKey)) return;
+    const frame = this.o.frame();
+    if (!frame) return;
+    e.preventDefault();
+    const r = frame.getBoundingClientRect();
+    this.zoomBy(Math.exp(-e.deltaY * 0.0015), e.clientX - r.left, e.clientY - r.top);
+  };
+
+  /** The click that ends a pan opens nothing. */
+  private readonly onClickCapture = (e: Event): void => {
+    if (!this.swallowClick) return;
+    this.swallowClick = false;
+    e.stopPropagation();
+    e.preventDefault();
+  };
+
+  private setMoved(): void {
+    if (this.moved) return;
+    this.moved = true;
+    this.host.requestUpdate();
+  }
+
+  private setHeight(h: number): void {
+    if (h === this.frameH) return;
+    this.frameH = h;
+    this.host.requestUpdate();
+  }
+
+  /** Write the view on the stage; the host's next render writes the same. */
+  private setView(v: View): void {
+    this.view = v;
+    const stage = this.o.stage();
+    if (stage) stage.style.transform = this.transform;
+    this.o.onMove();
+  }
+}

package/src/graph/paths.ts

@@ -0,0 +1,41 @@
+// Edges and loop returns as SVG paths.
+import { RETURN_R, type LoopReturn, type Stretch } from './layout.js';
+
+/**
+ * A loop box's return as an SVG path: out from its last layer to the band, back along
+ * it with rounded corners, and in to its first layer, stopping `gap` short of each item.
+ */
+export function returnPath(r: LoopReturn, down = false, gap = 3): string {
+  const r2 = (n: number) => Math.round(n * 2) / 2;
+  const pt = (u: number, v: number) => (down ? `${r2(v)},${r2(u)}` : `${r2(u)},${r2(v)}`);
+  const k = Math.max(0, Math.min(RETURN_R, (r.from - r.to) / 2, r.band - r.v0 - gap, r.band - r.v1 - gap));
+  return [
+    `M${pt(r.from, r.v0 + gap)}`,
+    `L${pt(r.from, r.band - k)}`,
+    `Q${pt(r.from, r.band)} ${pt(r.from - k, r.band)}`,
+    `L${pt(r.to + k, r.band)}`,
+    `Q${pt(r.to, r.band)} ${pt(r.to, r.band - k)}`,
+    `L${pt(r.to, r.v1 + gap)}`,
+  ].join(' ');
+}
+
+/** An edge's line as an SVG path: its runs, joined by a curve in each gap where it bends. */
+export function edgePath(runs: readonly Stretch[], down = false): string {
+  const r2 = (n: number) => Math.round(n * 2) / 2;
+  const pt = (u: number, v: number) => (down ? `${r2(v)},${r2(u)}` : `${r2(u)},${r2(v)}`);
+  const first = runs[0];
+  if (!first) return '';
+  let d = `M${pt(first.a, first.at)}`;
+  runs.forEach((r, i) => {
+    if (r.b !== r.a) d += ` L${pt(r.b, r.at)}`;
+    const next = runs[i + 1];
+    if (!next) return;
+    if (Math.abs(next.at - r.at) < 0.5) {
+      if (next.a !== r.b) d += ` L${pt(next.a, next.at)}`;
+      return;
+    }
+    const m = (r.b + next.a) / 2;
+    d += ` C${pt(m, r.at)} ${pt(m, next.at)} ${pt(next.a, next.at)}`;
+  });
+  return d;
+}