@anvpx/motion-scenes 0.0.0-stage → 0.1.0

package/dist/scenes/countdown/index.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { defineScene } from "../../define-scene.js";
+import { animAttrs, esc } from "../../html.js";
+import { positionClass, positionCss, positionSchema } from "../../position.js";
+import { readText } from "../../text-file.js";
+import { text } from "../../words.js";
+const MAX_STEPS = 60;
+const count = z.number().int().min(0).max(999);
+const configSchema = z
+    .strictObject({
+    from: count,
+    to: count,
+    label: text.optional(),
+    position: positionSchema.default("center"),
+})
+    .superRefine((props, ctx) => {
+    const steps = Math.abs(props.from - props.to) + 1;
+    if (steps > MAX_STEPS) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["to"],
+            message: `${steps} steps; max ${MAX_STEPS}`,
+            params: { suggestion: `keep |from - to| < ${MAX_STEPS}` },
+        });
+    }
+});
+const render = (props) => {
+    const label = props.label ? `\n<p class="mk-label">${esc(props.label)}</p>` : "";
+    return [
+        `<div class="mk-count ${positionClass(props.position)}" ${animAttrs("fade", 0)}>`,
+        `<span class="mk-dial"><span class="mk-number" data-from="${props.from}" data-to="${props.to}">${props.from}</span></span>${label}`,
+        "</div>",
+    ].join("\n");
+};
+export const countdownScene = defineScene({
+    type: "countdown",
+    layer: "overlay",
+    configSchema,
+    meta: {
+        purpose: "Integer count between from and to, one step per equal slice of the duration.",
+        example: { from: 3, to: 1 },
+    },
+    style: readText("./style.css", import.meta.url),
+    script: readText("./scene.js", import.meta.url),
+    render: (props, _ctx, root) => ({ body: render(props), css: positionCss(root) }),
+});

package/dist/scenes/countdown/scene.d.ts

@@ -0,0 +1,2 @@
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export declare function createScene(root: HTMLElement, config: import("../../runtime/mount.js").SceneConfig, ctx: import("../../runtime/mount.js").RuntimeContext): import("../../runtime/mount.js").Runtime;

package/dist/scenes/countdown/scene.js

@@ -0,0 +1,21 @@
+// @ts-check
+import { mountOverlay } from "../../runtime/mount.js";
+import { countdownState } from "../../runtime/timeline.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    const number = /** @type {HTMLElement} */ (root.querySelector("[data-from]"));
+    const from = Number(number.dataset.from);
+    const to = Number(number.dataset.to);
+    const duration = ctx.duration ?? Number(root.dataset.duration);
+    return mountOverlay(root, config, ctx, { baseDelay: 0, staggerFrames: 3, rise: 0 }, {
+        update: (t) => {
+            const state = countdownState(t, duration, from, to);
+            number.textContent = String(state.value);
+            number.style.transform = `scale(${state.scale})`;
+        },
+        reset: () => {
+            number.textContent = String(from);
+            number.style.removeProperty("transform");
+        },
+    });
+}

package/dist/scenes/countdown/style.css

@@ -0,0 +1,32 @@
+#scene-root .mk-count {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--mk-space-md);
+}
+#scene-root .mk-dial {
+  display: grid;
+  place-items: center;
+  width: 280px;
+  height: 280px;
+  border-radius: 50%;
+  border: 4px solid var(--mk-color-accent);
+  background: linear-gradient(155deg, var(--mk-color-deep) 0%, var(--mk-color-deepEnd) 100%);
+  color: var(--mk-color-onDeep);
+}
+#scene-root .mk-number {
+  font-family: var(--mk-font-display, var(--mk-font-sans));
+  font-size: var(--mk-font-size-display);
+  font-weight: 800;
+  line-height: 1;
+  font-variant-numeric: var(--mk-numeric, tabular-nums);
+}
+#scene-root .mk-label {
+  padding: var(--mk-space-sm) var(--mk-space-lg);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-color-card);
+  border: var(--mk-stroke-card, 2px) solid var(--mk-color-divider);
+  font-size: var(--mk-font-size-md);
+  font-weight: 700;
+  color: var(--mk-color-fg);
+}

package/dist/scenes/flow/index.d.ts

@@ -0,0 +1 @@
+export declare const flowScene: import("@anvpx/motion-schema").ScenePlugin;

package/dist/scenes/flow/index.js

@@ -0,0 +1,66 @@
+import { defineScene } from "../../define-scene.js";
+import { animAttrs, esc } from "../../html.js";
+import { readText } from "../../text-file.js";
+import { arrowPoints, DEFAULT_FONTS } from "./layout.js";
+import { planFlow } from "./plan.js";
+import { configSchema } from "./schema.js";
+/** Steps between an edge starting to draw and its head and label appearing. */
+const HEAD_DELAY_STEPS = 3;
+const fontsOf = (ctx) => ({
+    sm: ctx.theme.fontSizes.sm ?? DEFAULT_FONTS.sm,
+    md: ctx.theme.fontSizes.md ?? DEFAULT_FONTS.md,
+    lg: ctx.theme.fontSizes.lg ?? DEFAULT_FONTS.lg,
+});
+const nodeHtml = (node, index) => {
+    const attrs = animAttrs("rise", index, node.id);
+    const source = node.layer === 0 ? " mk-src" : "";
+    const lines = node.lines.map((line) => `<span class="mk-line">${esc(line)}</span>`).join("");
+    return `<div class="mk-node mk-n${index}${source}" ${attrs}>${lines}</div>`;
+};
+const nodeCss = (root, node, index) => `${root} .mk-n${index} { left: ${node.x}px; top: ${node.y}px; width: ${node.w}px; height: ${node.h}px; font-size: var(--mk-font-size-${node.step}); }\n`;
+const edgeHtml = (row, placed) => {
+    const { edge, geometry, label } = row;
+    const from = placed.get(edge.from);
+    if (!from)
+        return "";
+    const keys = `${edge.from} ${edge.to}`;
+    const drawStep = from.step + 1;
+    const headAttrs = animAttrs("fade", drawStep + HEAD_DELAY_STEPS, keys);
+    const text = label
+        ? `<text class="mk-edge-label" x="${label.x}" y="${label.y}" ${headAttrs}>${esc(label.text)}</text>`
+        : "";
+    return [
+        `<path class="mk-edge-line" d="${geometry.path}" pathLength="1" ${animAttrs("draw", drawStep, keys)}/>`,
+        `<polygon class="mk-edge-head" points="${arrowPoints(geometry.tip, geometry.direction)}" ${headAttrs}/>`,
+        text,
+    ]
+        .filter(Boolean)
+        .join("\n");
+};
+const render = (props, ctx, root) => {
+    const plan = planFlow(props, ctx, fontsOf(ctx));
+    const placed = new Map(plan.nodes.map((node, step) => [node.id, { node, step }]));
+    const edges = plan.edges.map((row) => edgeHtml(row, placed));
+    const svg = `<svg class="mk-edges" width="${ctx.width}" height="${ctx.height}" viewBox="0 0 ${ctx.width} ${ctx.height}" aria-hidden="true">\n${edges.join("\n")}\n</svg>`;
+    return {
+        body: [svg, ...plan.nodes.map(nodeHtml)].join("\n"),
+        css: plan.nodes.map((node, index) => nodeCss(root, node, index)).join(""),
+    };
+};
+export const flowScene = defineScene({
+    type: "flow",
+    configSchema,
+    meta: {
+        purpose: "Node-and-arrow diagram (2-8 nodes) laid out left-right or top-bottom.",
+        example: {
+            nodes: [
+                { id: "a", label: "A" },
+                { id: "b", label: "B" },
+            ],
+            edges: [{ from: "a", to: "b" }],
+        },
+    },
+    style: readText("./style.css", import.meta.url),
+    script: readText("./scene.js", import.meta.url),
+    render,
+});

package/dist/scenes/flow/inspect.d.ts

@@ -0,0 +1,26 @@
+import { type FlowFonts } from "./layout.ts";
+/** What lint needs to know about a flow scene's layout; indexes are positions in props. */
+export interface FlowReport {
+    /** Node label size (px). */
+    readonly font: number;
+    /** Labels do not fit the cards even at the smallest theme text step (too many or too long nodes). */
+    readonly crowded: boolean;
+    /** Nodes with a word wider than the card's text area (it would break mid-word). */
+    readonly wordBreaks: readonly {
+        readonly node: number;
+        readonly id: string;
+        readonly word: string;
+    }[];
+    /** Edge labels still touching a card, another label or another edge. */
+    readonly labelOverlaps: readonly {
+        readonly edge: number;
+        readonly with: readonly string[];
+        /** Touches a card or another label (not just a crossing edge). */
+        readonly hard: boolean;
+    }[];
+}
+/** Lays the props out as the scene would; `undefined` when they are not a valid flow graph. */
+export declare const inspectFlow: (props: unknown, size: {
+    readonly width: number;
+    readonly height: number;
+}, fonts?: FlowFonts) => FlowReport | undefined;

package/dist/scenes/flow/inspect.js

@@ -0,0 +1,25 @@
+import { DEFAULT_FONTS } from "./layout.js";
+import { planFlow } from "./plan.js";
+import { flowGraphSchema } from "./schema.js";
+/** Lays the props out as the scene would; `undefined` when they are not a valid flow graph. */
+export const inspectFlow = (props, size, fonts = DEFAULT_FONTS) => {
+    const parsed = flowGraphSchema.safeParse(props);
+    if (!parsed.success)
+        return undefined;
+    const plan = planFlow(parsed.data, size, fonts);
+    const index = new Map(parsed.data.nodes.map((node, i) => [node.id, i]));
+    return {
+        font: plan.font,
+        crowded: plan.nodes.some((node) => node.crowded),
+        wordBreaks: plan.nodes.flatMap((node) => node.overlong.map((word) => ({ node: index.get(node.id) ?? 0, id: node.id, word }))),
+        labelOverlaps: plan.edges.flatMap((row, i) => row.label !== undefined && row.label.overlaps.length > 0
+            ? [
+                {
+                    edge: i,
+                    with: row.label.overlaps,
+                    hard: row.label.overlaps.some((o) => !o.startsWith("edge ")),
+                },
+            ]
+            : []),
+    };
+};

package/dist/scenes/flow/layout.d.ts

@@ -0,0 +1,83 @@
+export type Direction = "lr" | "tb";
+export interface FlowNode {
+    readonly id: string;
+    readonly label: string;
+}
+/** Theme font sizes (px) the scene uses; the defaults match the built-in themes. */
+export interface FlowFonts {
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+}
+export declare const DEFAULT_FONTS: FlowFonts;
+export type FontStep = keyof FlowFonts;
+export interface FlowEdge {
+    readonly from: string;
+    readonly to: string;
+}
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A node with its layer rank and top-left box in canvas px. */
+export interface PlacedNode extends FlowNode {
+    readonly layer: number;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    /** Label font size (px), shared by every node of a diagram. */
+    readonly font: number;
+    /** Theme font-size step the label uses (the CSS var `--mk-font-size-<step>`). */
+    readonly step: FontStep;
+    /** The label text does not fit the card even at the smallest step: too many or too long nodes. */
+    readonly crowded: boolean;
+    /** Label lines, split at spaces only. */
+    readonly lines: readonly string[];
+    /** Words wider than the text area of the card (they would have to break). */
+    readonly overlong: readonly string[];
+}
+export interface EdgeGeometry {
+    readonly path: string;
+    /** Where the arrow head points. */
+    readonly tip: Point;
+    /** Unit vector the arrow head points along. */
+    readonly direction: Point;
+    readonly mid: Point;
+    /** Evenly spaced points along the edge, tail to tip (`EDGE_SAMPLES + 1` of them). */
+    readonly samples: readonly Point[];
+}
+export declare const EDGE_SAMPLES = 40;
+/**
+ * Longest-path layering: a node sits one layer after its deepest predecessor.
+ * Self edges are ignored; cycles terminate because layers are capped at n-1.
+ */
+export declare const assignLayers: (ids: readonly string[], edges: readonly FlowEdge[]) => Map<string, number>;
+/** Cards roomy enough for the larger label size. */
+export declare const isLargeNode: (node: {
+    readonly w: number;
+    readonly h: number;
+}) => boolean;
+/**
+ * Gap (px) a layer boundary needs so an edge label sits between the cards, not on them and can
+ * slide along its edge: 2.2x the longest label's width (lr) or height (tb) plus padding; 0 when no edge has a label.
+ */
+export declare const edgeLabelRoom: (edges: readonly {
+    readonly label?: string | undefined;
+}[], direction: Direction, fontSize: number, slide?: number) => number;
+/** Padding (px) between a card's edge and its text, each side. */
+export declare const NODE_PADDING = 24;
+/**
+ * Hand-coded layered layout inside the 5% safe area; deterministic and integer-valued.
+ * `labelRoom` (see `edgeLabelRoom`) is the gap between layers the cards leave when they can; cards
+ * widen for their text down to `minLabelRoom` (default: `labelRoom`).
+ * Card width follows the label text (estimated, see `measure.ts`); labels wrap at spaces only.
+ */
+export declare const layoutFlow: (nodes: readonly FlowNode[], edges: readonly FlowEdge[], direction: Direction, size: {
+    readonly width: number;
+    readonly height: number;
+}, labelRoom?: number, fonts?: FlowFonts, minLabelRoom?: number) => PlacedNode[];
+/** Forward edges are S-curves between facing sides; other edges are straight and clipped to the boxes. */
+export declare const edgeGeometry: (from: PlacedNode, to: PlacedNode, direction: Direction, forward: boolean) => EdgeGeometry;
+/** SVG polygon points of an arrow head ending at `tip`. */
+export declare const arrowPoints: (tip: Point, direction: Point) => string;

package/dist/scenes/flow/layout.js

@@ -0,0 +1,222 @@
+import { minLabelWidth, textWidth, wrapLabel } from "./measure.js";
+export const DEFAULT_FONTS = { sm: 28, md: 32, lg: 48 };
+export const EDGE_SAMPLES = 40;
+const SAFE_MARGIN = 0.05;
+const MAX_NODE_WIDTH = 520;
+/** Widest a card may grow to fit its label. */
+const MAX_FIT_WIDTH = 760;
+const MAX_NODE_HEIGHT = 260;
+const NODE_ASPECT = 0.75;
+const LARGE_NODE_WIDTH = 380;
+const LARGE_NODE_HEIGHT = 200;
+const MAIN_FILL = 0.74;
+const CROSS_FILL = 0.62;
+const TB_WIDTH_FILL = 0.8;
+const TB_HEIGHT_FILL = 0.55;
+const ARROW_LENGTH = 24;
+const ARROW_HALF_WIDTH = 12;
+const round = (value) => Math.round(value);
+const snap = (value) => Math.round(value * 10) / 10;
+const fmt = (value) => String(snap(value));
+/**
+ * Longest-path layering: a node sits one layer after its deepest predecessor.
+ * Self edges are ignored; cycles terminate because layers are capped at n-1.
+ */
+export const assignLayers = (ids, edges) => {
+    const layer = new Map(ids.map((id) => [id, 0]));
+    const cap = ids.length - 1;
+    for (let pass = 0; pass < ids.length; pass++) {
+        for (const { from, to } of edges) {
+            const next = Math.min((layer.get(from) ?? 0) + 1, cap);
+            if (from !== to && next > (layer.get(to) ?? 0))
+                layer.set(to, next);
+        }
+    }
+    return layer;
+};
+/** Dense ranks (0..k-1) in ascending layer order. */
+const rankOf = (layers) => {
+    const distinct = [...new Set(layers.values())].sort((a, b) => a - b);
+    return new Map([...layers].map(([id, layer]) => [id, distinct.indexOf(layer)]));
+};
+const groupByRank = (nodes, ranks) => {
+    const count = Math.max(...ranks.values()) + 1;
+    return Array.from({ length: count }, (_, rank) => nodes.filter((node) => ranks.get(node.id) === rank));
+};
+/** Cards roomy enough for the larger label size. */
+export const isLargeNode = (node) => node.w >= LARGE_NODE_WIDTH && node.h >= LARGE_NODE_HEIGHT;
+/** Smallest card width the label room may squeeze a node to. */
+const MIN_NODE_WIDTH = 160;
+/** Average glyph width of a label, in em, and the padding that keeps its halo off the cards. */
+const LABEL_LINE_EM = 1.2;
+/** A label gets this many times its own width, so it can slide along its edge past crossing edges. */
+const LABEL_SLIDE = 2.2;
+const LABEL_PADDING = 32;
+/**
+ * Gap (px) a layer boundary needs so an edge label sits between the cards, not on them and can
+ * slide along its edge: 2.2x the longest label's width (lr) or height (tb) plus padding; 0 when no edge has a label.
+ */
+export const edgeLabelRoom = (edges, direction, fontSize, slide = LABEL_SLIDE) => {
+    const widest = Math.max(0, ...edges.map((edge) => textWidth(edge.label ?? "", fontSize)));
+    if (widest === 0)
+        return 0;
+    const extent = direction === "lr" ? widest : fontSize * LABEL_LINE_EM;
+    return Math.ceil(extent * slide) + LABEL_PADDING;
+};
+const nodeSize = (horizontal, mainPitch, crossPitch, gap) => {
+    const mainFill = (fill) => Math.min(mainPitch * fill, mainPitch - gap);
+    const w = Math.min(MAX_NODE_WIDTH, Math.max(MIN_NODE_WIDTH, horizontal ? mainFill(MAIN_FILL) : crossPitch * TB_WIDTH_FILL));
+    const h = Math.min(MAX_NODE_HEIGHT, w * NODE_ASPECT, horizontal ? crossPitch * CROSS_FILL : mainFill(TB_HEIGHT_FILL));
+    return { w, h };
+};
+/** Padding (px) between a card's edge and its text, each side. */
+export const NODE_PADDING = 24;
+const LINE_HEIGHT = 1.2;
+const VERTICAL_PADDING = 16;
+/** Gap kept between neighbouring cards on the main axis, and between stacked cards. */
+const MIN_GAP = 48;
+const CROSS_GAP = 32;
+const wrapAll = (nodes, w, step, font, crowded) => {
+    const inner = w - 2 * NODE_PADDING;
+    const wrapped = nodes.map((node) => [node.id, wrapLabel(node.label, inner, font)]);
+    return {
+        step,
+        font,
+        w,
+        crowded,
+        lines: new Map(wrapped.map(([id, row]) => [id, row.lines])),
+        overlong: new Map(wrapped.map(([id, row]) => [id, row.overlong])),
+    };
+};
+const neededWidth = (nodes, font) => Math.max(...nodes.map((node) => minLabelWidth(node.label, font))) + 2 * NODE_PADDING;
+/**
+ * Largest theme font step (from `large` or `md` down to `sm`) whose text fits the cards: a card
+ * widens up to `maxW` when a label needs it, and its height must hold the wrapped lines. A word
+ * is never broken; when even `sm` does not fit, the result is flagged `crowded`.
+ */
+const fitLabels = (nodes, box, maxW, fonts, large) => {
+    const steps = large ? ["lg", "md", "sm"] : ["md", "sm"];
+    for (const step of steps) {
+        const font = fonts[step];
+        const w = Math.max(box.w, neededWidth(nodes, font));
+        if (w > maxW)
+            continue;
+        const fitted = wrapAll(nodes, w, step, font, false);
+        const rows = Math.max(...[...fitted.lines.values()].map((lines) => lines.length));
+        if (rows * font * LINE_HEIGHT + 2 * VERTICAL_PADDING <= box.h)
+            return fitted;
+    }
+    const w = Math.min(maxW, Math.max(box.w, neededWidth(nodes, fonts.sm)));
+    return wrapAll(nodes, w, "sm", fonts.sm, true);
+};
+/**
+ * Hand-coded layered layout inside the 5% safe area; deterministic and integer-valued.
+ * `labelRoom` (see `edgeLabelRoom`) is the gap between layers the cards leave when they can; cards
+ * widen for their text down to `minLabelRoom` (default: `labelRoom`).
+ * Card width follows the label text (estimated, see `measure.ts`); labels wrap at spaces only.
+ */
+export const layoutFlow = (nodes, edges, direction, size, labelRoom = 0, fonts = DEFAULT_FONTS, minLabelRoom = labelRoom) => {
+    const layers = assignLayers(nodes.map((node) => node.id), edges);
+    const columns = groupByRank(nodes, rankOf(layers));
+    const left = round(size.width * SAFE_MARGIN);
+    const top = round(size.height * SAFE_MARGIN);
+    const width = size.width - 2 * left;
+    const height = size.height - 2 * top;
+    const horizontal = direction === "lr";
+    const mainPitch = (horizontal ? width : height) / columns.length;
+    const crossLength = horizontal ? height : width;
+    const crossPitch = crossLength / Math.max(...columns.map((column) => column.length));
+    const box = nodeSize(horizontal, mainPitch, crossPitch, labelRoom);
+    const maxW = Math.max(box.w, Math.min(MAX_FIT_WIDTH, horizontal ? mainPitch - Math.max(minLabelRoom, MIN_GAP) : crossPitch - CROSS_GAP));
+    const fitted = fitLabels(nodes, box, maxW, fonts, isLargeNode(box));
+    return columns.flatMap((column, rank) => column.map((node, index) => {
+        const main = (rank + 0.5) * mainPitch;
+        const cross = crossLength / 2 + (index - (column.length - 1) / 2) * crossPitch;
+        const cx = left + (horizontal ? main : cross);
+        const cy = top + (horizontal ? cross : main);
+        return {
+            ...node,
+            layer: rank,
+            x: round(cx - fitted.w / 2),
+            y: round(cy - box.h / 2),
+            w: round(fitted.w),
+            h: round(box.h),
+            font: fitted.font,
+            step: fitted.step,
+            crowded: fitted.crowded,
+            lines: fitted.lines.get(node.id) ?? [node.label],
+            overlong: fitted.overlong.get(node.id) ?? [],
+        };
+    }));
+};
+const mid = (a, b) => ({ x: snap((a.x + b.x) / 2), y: snap((a.y + b.y) / 2) });
+const bezier = (p1, c1, c2, p2, t) => {
+    const u = 1 - t;
+    const a = u * u * u;
+    const b = 3 * u * u * t;
+    const c = 3 * u * t * t;
+    const d = t * t * t;
+    return {
+        x: snap(a * p1.x + b * c1.x + c * c2.x + d * p2.x),
+        y: snap(a * p1.y + b * c1.y + c * c2.y + d * p2.y),
+    };
+};
+const sampled = (at) => Array.from({ length: EDGE_SAMPLES + 1 }, (_, i) => at(i / EDGE_SAMPLES));
+const curve = (p1, p2, direction) => {
+    const horizontal = direction.x !== 0;
+    const c = mid(p1, p2);
+    const c1 = horizontal ? { x: c.x, y: p1.y } : { x: p1.x, y: c.y };
+    const c2 = horizontal ? { x: c.x, y: p2.y } : { x: p2.x, y: c.y };
+    const path = `M ${fmt(p1.x)} ${fmt(p1.y)} C ${fmt(c1.x)} ${fmt(c1.y)} ${fmt(c2.x)} ${fmt(c2.y)} ${fmt(p2.x)} ${fmt(p2.y)}`;
+    return {
+        path,
+        tip: p2,
+        direction,
+        mid: c,
+        samples: sampled((t) => bezier(p1, c1, c2, p2, t)),
+    };
+};
+const center = (node) => ({ x: node.x + node.w / 2, y: node.y + node.h / 2 });
+/** Point where the ray from the node centre along `unit` leaves the node box. */
+const boundary = (node, unit) => {
+    const c = center(node);
+    const reach = Math.min(node.w / 2 / Math.abs(unit.x), node.h / 2 / Math.abs(unit.y));
+    return { x: c.x + unit.x * reach, y: c.y + unit.y * reach };
+};
+const straight = (from, to) => {
+    const a = center(from);
+    const b = center(to);
+    const length = Math.hypot(b.x - a.x, b.y - a.y);
+    const unit = length === 0 ? { x: 1, y: 0 } : { x: (b.x - a.x) / length, y: (b.y - a.y) / length };
+    const p1 = boundary(from, unit);
+    const p2 = boundary(to, { x: -unit.x, y: -unit.y });
+    return {
+        path: `M ${fmt(p1.x)} ${fmt(p1.y)} L ${fmt(p2.x)} ${fmt(p2.y)}`,
+        tip: p2,
+        direction: unit,
+        mid: mid(p1, p2),
+        samples: sampled((t) => ({
+            x: snap(p1.x + (p2.x - p1.x) * t),
+            y: snap(p1.y + (p2.y - p1.y) * t),
+        })),
+    };
+};
+/** Forward edges are S-curves between facing sides; other edges are straight and clipped to the boxes. */
+export const edgeGeometry = (from, to, direction, forward) => {
+    if (!forward)
+        return straight(from, to);
+    return direction === "lr"
+        ? curve({ x: from.x + from.w, y: from.y + from.h / 2 }, { x: to.x, y: to.y + to.h / 2 }, { x: 1, y: 0 })
+        : curve({ x: from.x + from.w / 2, y: from.y + from.h }, { x: to.x + to.w / 2, y: to.y }, { x: 0, y: 1 });
+};
+/** SVG polygon points of an arrow head ending at `tip`. */
+export const arrowPoints = (tip, direction) => {
+    const base = { x: tip.x - direction.x * ARROW_LENGTH, y: tip.y - direction.y * ARROW_LENGTH };
+    const side = { x: -direction.y * ARROW_HALF_WIDTH, y: direction.x * ARROW_HALF_WIDTH };
+    const corners = [
+        tip,
+        { x: base.x + side.x, y: base.y + side.y },
+        { x: base.x - side.x, y: base.y - side.y },
+    ];
+    return corners.map((p) => `${fmt(p.x)},${fmt(p.y)}`).join(" ");
+};

package/dist/scenes/flow/measure.d.ts

@@ -0,0 +1,15 @@
+import { textWidth } from "../../shared/measure.ts";
+export { textWidth };
+export declare const MAX_LABEL_LINES = 2;
+export interface Wrapped {
+    /** Lines, split only at spaces (a single word is never broken). */
+    readonly lines: readonly string[];
+    /** Every line is at most `inner` px wide. */
+    readonly fits: boolean;
+    /** Words wider than `inner` on their own. */
+    readonly overlong: readonly string[];
+}
+/** Narrowest width (px) a label can be set in: its widest word, or the best two-line split. */
+export declare const minLabelWidth: (label: string, fontPx: number) => number;
+/** Wraps a label into one line when it fits `inner` px, else the best two-line split. */
+export declare const wrapLabel: (label: string, inner: number, fontPx: number) => Wrapped;

package/dist/scenes/flow/measure.js

@@ -0,0 +1,33 @@
+import { textWidth } from "../../shared/measure.js";
+export { textWidth };
+const wordsOf = (label) => label.split(/\s+/).filter(Boolean);
+export const MAX_LABEL_LINES = 2;
+/** The two-line split with the narrowest widest line (ties: earliest split). */
+const bestSplit = (words, fontPx) => {
+    let best = [words.join(" ")];
+    let bestWidth = Number.POSITIVE_INFINITY;
+    for (let cut = 1; cut < words.length; cut++) {
+        const lines = [words.slice(0, cut).join(" "), words.slice(cut).join(" ")];
+        const widest = Math.max(...lines.map((line) => textWidth(line, fontPx)));
+        if (widest < bestWidth) {
+            best = lines;
+            bestWidth = widest;
+        }
+    }
+    return best;
+};
+/** Narrowest width (px) a label can be set in: its widest word, or the best two-line split. */
+export const minLabelWidth = (label, fontPx) => {
+    const words = wordsOf(label);
+    const lines = words.length <= 1 ? words : bestSplit(words, fontPx);
+    return Math.max(0, ...lines.map((line) => textWidth(line, fontPx)));
+};
+/** Wraps a label into one line when it fits `inner` px, else the best two-line split. */
+export const wrapLabel = (label, inner, fontPx) => {
+    const words = wordsOf(label);
+    const whole = words.join(" ");
+    const lines = textWidth(whole, fontPx) <= inner ? [whole] : bestSplit(words, fontPx);
+    const overlong = words.filter((word) => textWidth(word, fontPx) > inner);
+    const fits = lines.every((line) => textWidth(line, fontPx) <= inner);
+    return { lines, fits: fits && overlong.length === 0, overlong };
+};

package/dist/scenes/flow/plan.d.ts

@@ -0,0 +1,42 @@
+import { type Direction, type EdgeGeometry, type FlowEdge, type FlowFonts, type FlowNode, type PlacedNode } from "./layout.ts";
+export interface FlowGraph {
+    readonly nodes: readonly FlowNode[];
+    readonly edges: readonly (FlowEdge & {
+        readonly label?: string | undefined;
+    })[];
+    readonly direction: Direction;
+}
+export interface Box {
+    /** Centre. */
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface PlacedLabel extends Box {
+    readonly text: string;
+    /** What the label still overlaps after the best placement was chosen (empty = clean). */
+    readonly overlaps: readonly string[];
+}
+export interface PlannedEdge {
+    readonly edge: FlowGraph["edges"][number];
+    readonly geometry: EdgeGeometry;
+    readonly label?: PlacedLabel;
+}
+export interface FlowPlan {
+    readonly nodes: readonly PlacedNode[];
+    readonly edges: readonly PlannedEdge[];
+    /** Node label font size (px). */
+    readonly font: number;
+    /** Edge label font size (px). */
+    readonly edgeFont: number;
+}
+/**
+ * The whole diagram layout: cards sized from their labels, edge geometry, and edge labels
+ * placed along their edges so they avoid cards, other edges and each other. Pure and
+ * deterministic; the scene renders it and `mk validate` lints it.
+ */
+export declare const planFlow: (graph: FlowGraph, size: {
+    readonly width: number;
+    readonly height: number;
+}, fonts?: FlowFonts) => FlowPlan;