@shortlink-org/portolan 0.1.0

package/src/likec4/FlowView.tsx

@@ -0,0 +1,235 @@
+import { useCallback, useMemo } from "react";
+import type { RefObject } from "react";
+import type { DiagramApi } from "likec4/react";
+import type { Flow } from "../catalog";
+import { walkSteps } from "../catalog";
+import { InteractiveView } from "./InteractiveView";
+import { CanvasBridge } from "./CanvasBridge";
+import type { CanvasHandle } from "./CanvasBridge";
+import { flowCrossViewId, flowViewId, fqn, participantFqn } from "./ids";
+import { catalogIdOf } from "./mapping";
+import {
+  flowPairing,
+  viewBounds,
+  viewEdgeIds,
+  viewHasNode,
+  viewNodeIds,
+} from "./view-index";
+import { offPathFrameIds } from "./flow-edges";
+import {
+  buildFrameCss,
+  buildFocusedPathCss,
+  buildWalkthroughCss,
+} from "./frame-theme";
+import { centredViewport, readableViewport } from "./canvas-viewport";
+import type { Size } from "./canvas-viewport";
+import { flowStepId } from "../selection/model";
+import { useSelectionStore } from "../selection/store";
+
+/** A stable empty list, so `useMemo` below is not defeated by a fresh `[]`. */
+const NOTHING: readonly string[] = [];
+
+/**
+ * The flow picture. LikeC4 owns it end to end: the sequence is declared in
+ * likec4/views.c4, generated from the same catalog.json the rest of the page
+ * reads. Portolan draws nothing here itself — it says which steps are lit,
+ * where to look, and what colour the frames should be, and hears which step
+ * was clicked and which one playback is on.
+ */
+export function FlowView({
+  flow,
+  crossOnly,
+  variant,
+  litSteps = [],
+  pathSteps = null,
+  focusStep = null,
+  canvas,
+  onWalkthroughStep,
+}: {
+  flow: Flow;
+  crossOnly: boolean;
+  variant: "diagram" | "sequence";
+  /** Catalog step ids to mark; the rest of the sequence is dimmed. */
+  litSteps?: readonly string[];
+  /**
+   * Steps of the path being read, when one is chosen. Everything outside that
+   * executable path leaves the picture, matching the focused rail beside it.
+   */
+  pathSteps?: readonly string[] | null;
+  /** The step the canvas should bring into view, when the rail asks for one. */
+  focusStep?: string | null;
+  canvas: RefObject<CanvasHandle | null>;
+  /** The step playback is on, in catalog terms, or null when it is stopped. */
+  onWalkthroughStep: (stepId: string | null) => void;
+}) {
+  const viewId = crossOnly ? flowCrossViewId(flow) : flowViewId(flow);
+  const pairing = flowPairing(flow, crossOnly);
+
+  const selection = useSelectionStore((s) => s.selection);
+  const source = useSelectionStore((s) => s.source);
+  const select = useSelectionStore((s) => s.select);
+  const clear = useSelectionStore((s) => s.clear);
+
+  const onNode = useCallback(
+    (likec4Id: string) => select(catalogIdOf(likec4Id), "diagram"),
+    [select],
+  );
+
+  // A clicked arrow is a step, not a relation: the sequence is what this view
+  // is about, so the click resolves through the edge-to-step pairing.
+  const onEdge = useCallback(
+    (edgeId: string) => {
+      const stepId = pairing.stepOf.get(edgeId);
+      if (stepId) select(flowStepId(flow.slug, stepId), "diagram");
+    },
+    [pairing, flow.slug, select],
+  );
+
+  const onCanvasClick = useCallback(() => clear("diagram"), [clear]);
+
+  const onWalkthroughEdge = useCallback(
+    (edgeId: string | null) => {
+      onWalkthroughStep(edgeId ? (pairing.stepOf.get(edgeId) ?? null) : null);
+    },
+    [pairing, onWalkthroughStep],
+  );
+
+  // A selection is narrower than a path, so it wins: choosing a path lifts the
+  // branch you are reading, and clicking a step then narrows to that one step.
+  const marked = litSteps.length > 0 ? litSteps : (pathSteps ?? NOTHING);
+
+  const highlightEdges = useMemo(
+    () =>
+      marked
+        .map((stepId) => pairing.edgeOf.get(stepId))
+        .filter((id): id is string => id !== undefined),
+    [marked, pairing],
+  );
+
+  const focusedPathEdges = useMemo(
+    () =>
+      pathSteps
+        ? pathSteps
+            .map((stepId) => pairing.edgeOf.get(stepId))
+            .filter((id): id is string => id !== undefined)
+        : null,
+    [pathSteps, pairing],
+  );
+
+  // Frames go with their steps. A chosen path is a structural focus, so its
+  // unused arrows and empty frames disappear; selecting one step remains a
+  // paint-only highlight and never changes the surrounding graph.
+  const extraCss = useMemo(() => {
+    const theme = [buildFrameCss(), buildWalkthroughCss()].join("\n");
+    if (!pathSteps) return theme;
+    const allEdges = viewEdgeIds(viewId);
+    const onPath = new Set(focusedPathEdges ?? []);
+    const edges = allEdges.filter((id) => !onPath.has(id));
+    const edgeLabelPositions = allEdges
+      .map((id, index) => (onPath.has(id) ? null : index + 1))
+      .filter((position): position is number => position !== null);
+    const pathStepIds = new Set(
+      pathSteps.filter((stepId) => pairing.edgeOf.has(stepId)),
+    );
+    const participantsById = new Map(
+      flow.participants.map((participant) => [
+        participant.id,
+        participantFqn(participant),
+      ]),
+    );
+    const onPathNodes = new Set(
+      walkSteps(flow.steps)
+        .filter((step) => pathStepIds.has(step.id))
+        .flatMap((step) => [step.from, step.to])
+        .map((id) => participantsById.get(id) ?? fqn(id)),
+    );
+    const nodes = viewNodeIds(viewId).filter((id) => !onPathNodes.has(id));
+    const frames = offPathFrameIds(allEdges, onPath);
+    return [
+      theme,
+      buildFocusedPathCss(edges, edgeLabelPositions, nodes, frames),
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }, [flow, pathSteps, focusedPathEdges, pairing, viewId]);
+
+  // Lanes are marked only for a selection made somewhere else, and only when
+  // this variant of the view actually has that lane.
+  const highlightNodes =
+    selection &&
+    source !== "diagram" &&
+    (selection.kind === "service" || selection.kind === "unknown") &&
+    viewHasNode(viewId, fqn(selection.id))
+      ? [fqn(selection.id)]
+      : [];
+
+  /**
+   * The opening viewport, applied once the canvas is live.
+   *
+   * Both variants open at the size their labels were drawn for — fitting a
+   * flow of this length puts every label at four pixels, which shows that it
+   * is long and nothing else. What differs is where they open. A sequence has
+   * a beginning: its top-left corner is step one. A diagram does not — it
+   * folds forty-five steps onto nine boxes and has no reading order — so it
+   * opens centred on the arrow that draws step one instead.
+   *
+   * The second `send` is the point of the first one. LikeC4 refits on resize
+   * unless the viewport was moved by hand, and the page resizes the canvas
+   * itself whenever the rail is dragged — so a viewport set programmatically
+   * and left unclaimed would be thrown away the first time the reader touched
+   * the divider. Claiming it says: this is where the reader is looking.
+   */
+  const onReady = useCallback(
+    ({ diagram, canvas: box }: { diagram: DiagramApi; canvas: Size }) => {
+      if (box.width === 0) return;
+
+      let viewport;
+      if (variant === "sequence") {
+        const bounds = viewBounds(viewId, variant);
+        if (!bounds) return;
+        viewport = readableViewport(bounds, box);
+      } else {
+        const firstEdge = viewEdgeIds(viewId)[0];
+        const start = firstEdge
+          ? diagram.findDiagramEdge(firstEdge)?.points[0]
+          : undefined;
+        // No geometry to aim at is not worth a guess: LikeC4's own fit is
+        // already on screen, and leaving it beats jumping somewhere arbitrary.
+        if (!start) return;
+        viewport = centredViewport({ x: start[0], y: start[1] }, box);
+      }
+
+      diagram.send({ type: "xyflow.setViewport", viewport, duration: 0 });
+      diagram.send({ type: "xyflow.viewportMoved", viewport, manually: true });
+    },
+    [viewId, variant],
+  );
+
+  return (
+    <InteractiveView
+      viewId={viewId}
+      variant={variant}
+      // LikeC4's own controls panel carries a toolbar and a wordmark. The page
+      // already has one toolbar, and two is one too many, so the panel is off
+      // and every control it held has a place in ours.
+      controls={false}
+      walkthrough
+      highlightNodes={highlightNodes}
+      highlightEdges={highlightEdges}
+      extraCss={extraCss}
+      onNode={onNode}
+      onEdge={onEdge}
+      onCanvas={onCanvasClick}
+      onReady={onReady}
+    >
+      <CanvasBridge
+        handle={canvas}
+        activeEdgeId={
+          focusStep ? (pairing.edgeOf.get(focusStep) ?? null) : null
+        }
+        focusEdgeIds={focusedPathEdges}
+        onWalkthroughEdge={onWalkthroughEdge}
+      />
+    </InteractiveView>
+  );
+}

package/src/likec4/InteractiveView.tsx

@@ -0,0 +1,144 @@
+import { useCallback, useMemo, useRef } from "react";
+import type { ReactNode } from "react";
+import type { DiagramApi } from "likec4/react";
+import { ReactLikeC4, isLikeC4ViewId } from "./generated";
+import { useTheme } from "../app/theme";
+import { Ident } from "../components/Ident";
+import { buildHighlightCss } from "./highlight-css";
+import type { Size } from "./canvas-viewport";
+
+export interface InteractiveViewProps {
+  viewId: string;
+  /** Sequence for flows, diagram for element views. */
+  variant?: "diagram" | "sequence";
+  controls?: boolean;
+  walkthrough?: boolean;
+  /** LikeC4 element ids to mark; everything else on the canvas is dimmed. */
+  highlightNodes?: readonly string[];
+  /** LikeC4 edge ids to mark; the other edges are dimmed. */
+  highlightEdges?: readonly string[];
+  /**
+   * More rules for the same stylesheet — retuned theme tokens, dimmed frames.
+   * Anything that paints rather than lays out belongs here rather than in a
+   * prop the layout would have to be recomputed for.
+   */
+  extraCss?: string;
+  onNode?: (likec4Id: string) => void;
+  onEdge?: (edgeId: string) => void;
+  onCanvas?: () => void;
+  /**
+   * Once the canvas is live, with the diagram's API and the size of the box it
+   * was given. The size is measured here because this is the component that
+   * owns the box; nothing inside LikeC4 will say how big it was made.
+   */
+  onReady?: (params: { diagram: DiagramApi; canvas: Size }) => void;
+  /**
+   * Rendered inside the canvas, where LikeC4's own hooks work. For bridges,
+   * not for decoration: anything drawn over the picture belongs beside it.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * A view id that resolves to nothing. This is not an error the reader caused
+ * and not one they can fix from here, so it is stated rather than alarmed
+ * about: the id in monospace, because that is the thing to go and look for,
+ * and one muted line saying why the box is empty.
+ *
+ * The box keeps its size. A diagram that fails to exist must not also make the
+ * page around it change shape.
+ */
+function Missing({ viewId }: { viewId: string }) {
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <div className="max-w-prose rounded-card border border-dashed px-4 py-3 text-center border-line-strong">
+        <Ident value={viewId} className="text-ink" />
+        <p className="meta mt-1.5">
+          no such view in the generated bundle — it was renamed, or the bundle
+          is older than the model
+        </p>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The one place portolan embeds a LikeC4 canvas. The packaged LikeC4View gives
+ * no way to hear a click, so the lower-level component is used instead and the
+ * clicks are forwarded straight to the selection store by the caller.
+ */
+export function InteractiveView({
+  viewId,
+  variant = "diagram",
+  controls = false,
+  walkthrough = false,
+  highlightNodes = [],
+  highlightEdges = [],
+  extraCss = "",
+  onNode,
+  onEdge,
+  onCanvas,
+  onReady,
+  children,
+}: InteractiveViewProps) {
+  const { theme } = useTheme();
+  const boxRef = useRef<HTMLDivElement | null>(null);
+
+  // Keyed on contents rather than array identity: callers build these lists
+  // inline, so comparing by reference would rebuild the sheet every render.
+  const nodeKey = highlightNodes.join(" ");
+  const edgeKey = highlightEdges.join(" ");
+  const css = useMemo(() => {
+    const rules = buildHighlightCss(
+      nodeKey ? nodeKey.split(" ") : [],
+      edgeKey ? edgeKey.split(" ") : [],
+    );
+    return [extraCss, rules].filter(Boolean).join("\n");
+  }, [nodeKey, edgeKey, extraCss]);
+
+  const onInitialized = useCallback(
+    ({ diagram }: { diagram: DiagramApi }) => {
+      const box = boxRef.current?.getBoundingClientRect();
+      if (!box) return;
+      onReady?.({ diagram, canvas: { width: box.width, height: box.height } });
+    },
+    [onReady],
+  );
+
+  if (!isLikeC4ViewId(viewId)) return <Missing viewId={viewId} />;
+
+  return (
+    <div ref={boxRef} className="h-full w-full bg-canvas">
+      <ReactLikeC4
+        // Remounting on viewId keeps LikeC4's own walkthrough state from
+        // leaking across a filter or variant switch. The variant is in the key
+        // for a second reason: it is an initial value inside LikeC4, so the
+        // only honest way to change it is to start the canvas again. The
+        // selection is deliberately absent: re-keying would re-layout.
+        key={`${viewId}:${variant}:${theme}`}
+        viewId={viewId}
+        dynamicViewVariant={variant}
+        colorScheme={theme}
+        background="dots"
+        controls={controls}
+        fitView
+        pannable
+        zoomable
+        enableDynamicViewWalkthrough={walkthrough}
+        enableNotes
+        enableElementDetails={false}
+        enableRelationshipDetails={false}
+        enableSearch={false}
+        injectFontCss={false}
+        onNodeClick={(node) => onNode?.(String(node.id))}
+        onEdgeClick={(edge) => onEdge?.(String(edge.id))}
+        onCanvasClick={() => onCanvas?.()}
+        onInitialized={onInitialized}
+        style={{ width: "100%", height: "100%" }}
+      >
+        {css ? <style>{css}</style> : null}
+        {children}
+      </ReactLikeC4>
+    </div>
+  );
+}

package/src/likec4/canvas-viewport.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import {
+  CANVAS_PAD,
+  MIN_FOCUS_ZOOM,
+  READABLE_ZOOM,
+  boundsOf,
+  centredViewport,
+  focusViewport,
+  readableViewport,
+} from "./canvas-viewport";
+
+/** Where a point of the diagram lands on screen under a viewport. */
+const project = (
+  value: number,
+  offset: number,
+  zoom: number,
+): number => value * zoom + offset;
+
+describe("readableViewport", () => {
+  const canvas = { width: 1000, height: 700 };
+
+  it("opens at the authored size rather than at whatever fits", () => {
+    const huge = { x: 0, y: 0, width: 4000, height: 9000 };
+    expect(readableViewport(huge, canvas).zoom).toBe(READABLE_ZOOM);
+  });
+
+  it("puts the top of the diagram at the top of the canvas", () => {
+    const bounds = { x: 120, y: 60, width: 400, height: 3000 };
+    const viewport = readableViewport(bounds, canvas);
+    expect(project(bounds.y, viewport.y, viewport.zoom)).toBe(CANVAS_PAD);
+  });
+
+  it("centres a diagram narrower than the canvas", () => {
+    const bounds = { x: 40, y: 0, width: 400, height: 300 };
+    const viewport = readableViewport(bounds, canvas);
+    const left = project(bounds.x, viewport.x, viewport.zoom);
+    const right = project(bounds.x + bounds.width, viewport.x, viewport.zoom);
+    expect(left).toBeCloseTo(canvas.width - right, 0);
+  });
+
+  it("left-aligns a diagram wider than the canvas, so step one is on screen", () => {
+    const bounds = { x: 40, y: 0, width: 3000, height: 300 };
+    const viewport = readableViewport(bounds, canvas);
+    expect(project(bounds.x, viewport.x, viewport.zoom)).toBe(CANVAS_PAD);
+  });
+
+  it("does not centre a diagram that only just overflows", () => {
+    // Exactly canvas-wide still needs its padding, so it counts as overflow
+    // rather than as a fit with no room to breathe.
+    const bounds = { x: 0, y: 0, width: canvas.width, height: 300 };
+    expect(readableViewport(bounds, canvas).x).toBe(CANVAS_PAD);
+  });
+
+  it("honours a zoom the caller asks for", () => {
+    const bounds = { x: 0, y: 0, width: 400, height: 300 };
+    const viewport = readableViewport(bounds, canvas, 2);
+    expect(viewport.zoom).toBe(2);
+    expect(project(bounds.y, viewport.y, viewport.zoom)).toBe(CANVAS_PAD);
+  });
+
+  it("returns whole pixels, so nothing lands on a half-device-pixel", () => {
+    const bounds = { x: 3, y: 7, width: 333, height: 111 };
+    const viewport = readableViewport(bounds, canvas);
+    expect(Number.isInteger(viewport.x)).toBe(true);
+    expect(Number.isInteger(viewport.y)).toBe(true);
+  });
+});
+
+describe("boundsOf", () => {
+  it("has nothing to say about a line with no points", () => {
+    expect(boundsOf([])).toBeNull();
+  });
+
+  it("boxes a polyline, wherever its ends happen to be", () => {
+    // Deliberately not monotonic: an edge routed round a lane doubles back,
+    // and the box has to hold the detour rather than just the endpoints.
+    expect(
+      boundsOf([
+        [830, 1769],
+        [1245, 1510],
+        [1917, 1647],
+      ]),
+    ).toEqual({ x: 830, y: 1510, width: 1087, height: 259 });
+  });
+});
+
+describe("centredViewport", () => {
+  it("puts the point in the middle of the canvas", () => {
+    const vp = centredViewport({ x: 300, y: 200 }, { width: 800, height: 600 });
+    expect(300 * vp.zoom + vp.x).toBe(400);
+    expect(200 * vp.zoom + vp.y).toBe(300);
+  });
+});
+
+describe("focusViewport", () => {
+  const canvas = { width: 703, height: 665 };
+
+  /** Where the box lands on screen under a viewport. */
+  const project = (b: ReturnType<typeof boundsOf>, vp: { x: number; y: number; zoom: number }) => {
+    if (!b) throw new Error("no bounds");
+    return {
+      left: b.x * vp.zoom + vp.x,
+      right: (b.x + b.width) * vp.zoom + vp.x,
+      top: b.y * vp.zoom + vp.y,
+      bottom: (b.y + b.height) * vp.zoom + vp.y,
+    };
+  };
+
+  it("gets an arrow wider than the canvas wholly on screen", () => {
+    // checkout's step 12 in the diagram variant: 1087pt of arrow in a 703px
+    // pane. LikeC4's own centring caps the zoom at 1 and leaves it hanging off
+    // the right-hand edge; this is the case the helper exists for.
+    const bounds = { x: 830, y: 1509, width: 1087, height: 260 };
+    const vp = focusViewport(bounds, canvas);
+    const at = project(bounds, vp);
+    // Within a pixel: the viewport is rounded to whole pixels on purpose, so
+    // nothing lands on a half-device-pixel and blurs.
+    expect(at.left).toBeCloseTo(CANVAS_PAD, 0);
+    expect(canvas.width - at.right).toBeCloseTo(CANVAS_PAD, 0);
+    expect(at.top).toBeGreaterThanOrEqual(0);
+    expect(at.bottom).toBeLessThanOrEqual(canvas.height);
+  });
+
+  it("does not magnify a short arrow past the readable size", () => {
+    const bounds = { x: 0, y: 0, width: 40, height: 10 };
+    expect(focusViewport(bounds, canvas).zoom).toBe(READABLE_ZOOM);
+  });
+
+  it("centres whatever it is shown", () => {
+    const bounds = { x: 100, y: 4000, width: 200, height: 80 };
+    const vp = focusViewport(bounds, canvas);
+    const at = project(bounds, vp);
+    // Equal margins either side, to within the whole-pixel rounding.
+    expect(Math.abs(at.left - (canvas.width - at.right))).toBeLessThanOrEqual(1);
+    expect(Math.abs(at.top - (canvas.height - at.bottom))).toBeLessThanOrEqual(1);
+  });
+
+  it("stops zooming out at the floor rather than vanishing", () => {
+    const monstrous = { x: 0, y: 0, width: 100000, height: 100000 };
+    expect(focusViewport(monstrous, canvas).zoom).toBe(MIN_FOCUS_ZOOM);
+  });
+
+  it("survives a zero-height arrow, which is what a straight one is", () => {
+    const flat = { x: 0, y: 500, width: 300, height: 0 };
+    const vp = focusViewport(flat, canvas);
+    expect(vp.zoom).toBe(READABLE_ZOOM);
+    expect(Number.isFinite(vp.x) && Number.isFinite(vp.y)).toBe(true);
+  });
+});

package/src/likec4/canvas-viewport.ts

@@ -0,0 +1,135 @@
+// Where the canvas starts looking, and at what size.
+//
+// Fit-to-view is the wrong opening move for a flow. Fitting a forty-five step
+// sequence into a pane puts every label at three or four pixels, which is a
+// picture of a flow rather than a flow: the reader can see that it is long and
+// nothing else. So the canvas opens at the size the labels were drawn for and
+// shows the beginning, which is where reading starts anyway. Fit-to-view stays
+// one button away, for the reader who wants the shape rather than the words.
+//
+// Pure arithmetic, kept out of the component so the one decision worth arguing
+// about — what "the beginning" means when the diagram is narrower than the
+// pane — is stated once and tested.
+
+export interface BBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface Viewport {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+/** The authored size. Below roughly 0.7 the 16px labels stop being words. */
+export const READABLE_ZOOM = 1;
+
+/** Breathing room between the diagram and the edge of the pane. */
+export const CANVAS_PAD = 24;
+
+/**
+ * The opening viewport: the top of the diagram, at readable zoom.
+ *
+ * Horizontally it centres when the diagram fits and left-aligns when it does
+ * not. Centring a diagram that overflows would open the reader in the middle
+ * of the first row with the start scrolled off to the left, and left-aligning
+ * one that fits leaves a dead half-canvas on the right — so it is neither rule
+ * everywhere, it is each rule where it is the true one.
+ *
+ * Vertically it always aligns to the top: the first step is the first step
+ * whether or not the sequence fits, and centring a short flow would push it
+ * down away from the participants header it belongs under.
+ */
+export function readableViewport(
+  bounds: BBox,
+  canvas: Size,
+  zoom: number = READABLE_ZOOM,
+): Viewport {
+  const width = bounds.width * zoom;
+  const fits = width + CANVAS_PAD * 2 <= canvas.width;
+  const x = fits
+    ? (canvas.width - width) / 2 - bounds.x * zoom
+    : CANVAS_PAD - bounds.x * zoom;
+  return {
+    x: Math.round(x),
+    y: Math.round(CANVAS_PAD - bounds.y * zoom),
+    zoom,
+  };
+}
+
+/** How far the canvas may zoom out to get one step wholly on screen. */
+export const MIN_FOCUS_ZOOM = 0.2;
+
+/** The box a polyline occupies, or null for a line with no points. */
+export function boundsOf(
+  points: readonly (readonly [number, number])[],
+): BBox | null {
+  if (points.length === 0) return null;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of points) {
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/**
+ * A viewport that shows one thing whole, as large as it will go.
+ *
+ * This exists because "bring step 12 into view" has to mean it. LikeC4's own
+ * centring caps the zoom at what the viewport already had, which for a step
+ * whose arrow is wider than the pane leaves the arrow half off the screen —
+ * technically centred, not actually visible. So the zoom comes down as far as
+ * it must and no further, and stops at MIN_FOCUS_ZOOM rather than diving to
+ * whatever a pathological arrow would need.
+ */
+export function focusViewport(
+  bounds: BBox,
+  canvas: Size,
+  max: number = READABLE_ZOOM,
+): Viewport {
+  const room = (span: number, size: number): number =>
+    span > 0 ? (size - CANVAS_PAD * 2) / span : max;
+  const zoom = Math.max(
+    MIN_FOCUS_ZOOM,
+    Math.min(max, room(bounds.width, canvas.width), room(bounds.height, canvas.height)),
+  );
+  return centredViewport(
+    { x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 },
+    canvas,
+    zoom,
+  );
+}
+
+/**
+ * Readable zoom, centred on one point of the diagram.
+ *
+ * For the variant that has no beginning. A diagram folds a flow's steps onto
+ * the handful of boxes that repeat, so there is no top-left corner that means
+ * "start here" — but there is still a first step, and its arrow is a place the
+ * reader can be put down at a size where the labels are words.
+ */
+export function centredViewport(
+  point: { x: number; y: number },
+  canvas: Size,
+  zoom: number = READABLE_ZOOM,
+): Viewport {
+  return {
+    x: Math.round(canvas.width / 2 - point.x * zoom),
+    y: Math.round(canvas.height / 2 - point.y * zoom),
+    zoom,
+  };
+}