flowfig 0.8.0 → 0.8.2

package/dist/index.js

@@ -1,11 +1,11 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
-import { route } from './geometry.js';
+import { arcRoom, avoidOf, route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, labelLines, fitCap, LABEL_LINE, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -95,7 +95,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             : []),
     ]), [layout, tl, edges, timeline, today]);
     const step = active == null ? null : steps[active];
+    const allBeats = useMemo(() => steps.flatMap((s) => s.flow.map(toBeat)), [steps]);
     const beats = useMemo(() => (step?.flow ?? []).map(toBeat), [step]);
+    const cap = useMemo(() => fitCap({ layout, edges, steps, lanes, timeline }, 830), [layout, edges, steps, lanes, timeline]);
     const carded = useMemo(() => {
         const all = new Map();
         for (const b of steps.flatMap((s) => s.flow.map(toBeat)))
@@ -155,25 +157,18 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     h: r.height / k,
                 };
             });
-            const avoid = [];
+            const extra = [];
             el.querySelectorAll('[data-fig-outside]').forEach((n) => {
                 const r = n.getBoundingClientRect();
-                avoid.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
+                extra.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
             });
-            if (tl)
-                for (const n of nodes(layout))
-                    if (rects[n.id])
-                        avoid.push({ ...rects[n.id], box: true });
             const stubs = lanePlan?.stubs ?? new Map();
-            if (stubs.size) {
-                for (const n of nodes(layout))
-                    if (rects[n.id])
-                        avoid.push(rects[n.id]);
+            if (stubs.size)
                 el.querySelectorAll('[data-fig-gutter]').forEach((n) => {
                     const r = n.getBoundingClientRect();
-                    avoid.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
+                    extra.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
                 });
-            }
+            const avoid = avoidOf(nodes(layout).flatMap((n) => (rects[n.id] ? [rects[n.id]] : [])), extra, stubs.size > 0);
             const bands = {};
             el.querySelectorAll('[data-fig-copy]').forEach((n) => {
                 const r = n.getBoundingClientRect();
@@ -208,7 +203,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     stub: stubs.get(ids[i]).map(labelPillW),
                     bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)],
                 }),
-                ...((stubs.size || lanePlan) && e.label != null && { labelW: labelPillW(str(e.label)) }),
+                ...(!tl && e.label != null && { labelW: labelPillW(str(e.label)) }),
             })), rects, tips, avoid, pillArea, lanePlan ? { bands: Object.values(laneBands), boxes: nodes(layout).flatMap((n) => (rects[n.id] ? [rects[n.id]] : [])) } : undefined);
             setRouted(next);
             if (lanePlan) {
@@ -285,7 +280,17 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     const e = edges[ids.indexOf(r.id)];
                     if (r.stub)
                         return r.stub.pts.map((pts, j) => ({ id: r.id, from: e.from, to: e.to, curve: r.curve, pts, label: labels[`${r.id}:${j}`] }));
-                    return [{ id: r.id, from: e.from, to: e.to, curve: r.curve, label: labels[r.id], ...(tl && { behind: true }) }];
+                    return [
+                        {
+                            id: r.id,
+                            from: e.from,
+                            to: e.to,
+                            curve: r.curve,
+                            label: labels[r.id],
+                            ...(tl && { behind: true }),
+                            ...(r.elbow && { elbow: r.elbow }),
+                        },
+                    ];
                 }),
                 ...(rail?.rows ?? []).flatMap((row) => {
                     const r = row.kind === 'message' ? labels[`rail:${row.n}`] : undefined;
@@ -458,7 +463,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const inside = it.labelInside;
         const outside = (_jsx("span", { "data-fig-outside": "", style: { position: 'absolute', left: '100%', marginLeft: 6, whiteSpace: 'nowrap', fontSize: 13, fontWeight: 500, color: v('fg') }, children: label }));
         const top = LANE_PAD + it.row * (TL_BAR_H + TL_ROW_GAP);
-        return (_jsxs("div", { "data-fig": n.id, "data-diamond": it.milestone || undefined, onMouseEnter: () => setHover(n.id), onMouseLeave: () => setHover(null), style: {
+        return (_jsxs("div", { "data-fig": n.id, title: n.source, "data-diamond": it.milestone || undefined, onMouseEnter: () => setHover(n.id), onMouseLeave: () => setHover(null), style: {
                 position: 'absolute',
                 left: it.x,
                 top: it.milestone ? top + (TL_BAR_H - it.w) / 2 : top,
@@ -648,13 +653,15 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const store = item.shape === 'store';
         const card = carded.has(item.id);
         const dl = diamond && !card ? diamondLines(item, nodeWidth(item, false) + 70) : null;
+        const w = diamond || card || item.width != null || str(item.label) ? nodeWidth(item, card, cap) + (diamond ? 70 : 0) : undefined;
+        const lines = w != null && !diamond && str(item.label) ? labelLines(item, w) : null;
         const bt = item.tone && TONES[item.tone];
-        return (_jsxs("div", { "data-fig": item.id, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
+        return (_jsxs("div", { "data-fig": item.id, title: item.source, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
                 position: 'relative',
                 isolation: 'isolate',
                 minWidth: 100,
-                maxWidth: card || diamond ? undefined : 190,
-                width: diamond ? nodeWidth(item, card) + 70 : (item.width ?? (card ? CARD_WIDTH : undefined)),
+                maxWidth: w == null ? cap : undefined,
+                width: w,
                 minHeight: dl ? Math.max(dl.h, (minHeight(item.id) ?? 0) + 24) : minHeight(item.id),
                 boxSizing: 'border-box',
                 display: 'flex',
@@ -707,7 +714,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 border: `1.5px solid ${bt ?? v('accent')}`,
                                 background: `radial-gradient(circle, ${bt ?? v('accent')} 0 4px, transparent 4.5px)`,
                             }),
-                    } })), _jsx("div", { children: item.label }), dl
+                    } })), lines ? (lines.map((l, i) => (_jsx("div", { style: { whiteSpace: 'nowrap', lineHeight: `${LABEL_LINE}px` }, children: l }, i)))) : (_jsx("div", { style: { lineHeight: `${LABEL_LINE}px` }, children: item.label })), dl
                     ? dl.subs.map((l, i) => (_jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), lineHeight: '15px', whiteSpace: 'nowrap' }, children: l.text }, i)))
                     : item.sub != null && _jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), marginTop: 2 }, children: item.sub }), card && (_jsxs("div", { style: {
                         marginTop: 8,
@@ -780,11 +787,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 margin: '0 auto',
                                 transform: fit.scale < 1 ? `scale(${fit.scale})` : undefined,
                                 transformOrigin: 'top left',
-                                padding: 4,
-                                paddingTop: edges.some((e, i) => e.around === 'above' && !lanePlan?.stubs.has(ids[i])) ? 44 : 4,
-                                paddingBottom: edges.some((e, i) => (e.around === 'below' || (!e.around && lanePlan?.around.has(ids[i]))) && !lanePlan?.stubs.has(ids[i]))
-                                    ? 44
-                                    : 4,
+                                paddingTop: arcRoom(routed, 'above') || 4,
+                                paddingBottom: arcRoom(routed, 'below') || 4,
+                                paddingLeft: arcRoom(routed, 'left') || 4,
+                                paddingRight: arcRoom(routed, 'right') || 4,
                             }, children: [renderItem(layout, 0), _jsxs("svg", { style: {
                                         position: 'absolute',
                                         inset: 0,
@@ -797,11 +803,12 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                             const on = litEdges.has(r.id);
                                             const tone = hopTone(r.id);
                                             const hidden = !on && edges[ids.indexOf(r.id)].quiet;
+                                            const tip = edgeTip(r.id, edges[ids.indexOf(r.id)].source, allBeats);
                                             const look = (d, key, guides = false) => (_jsx("path", { ref: guides
                                                     ? (p) => {
                                                         paths.current[r.id] = p;
                                                     }
-                                                    : undefined, d: d, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s' } }, key));
+                                                    : undefined, d: d, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s', pointerEvents: tip ? 'stroke' : undefined }, children: tip && _jsx("title", { children: tip }) }, key));
                                             const guide = (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
                                                 }, d: r.d, fill: "none", stroke: "none" }, r.id));
@@ -899,7 +906,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             const ly = y + RAIL.row / 2;
                             const tone = state === 'now' && row.tone ? TONES[row.tone] : undefined;
                             const g = row.group != null ? rail.groups[row.group] : null;
-                            return (_jsxs("g", { "data-rail-row": row.n, "data-state": state, opacity: state === 'next' && !on ? 0.45 : 1, style: { cursor: 'pointer' }, onClick: () => goTo(row.step, row.beat), onMouseEnter: () => setHoverEdge(row.edge), onMouseLeave: () => setHoverEdge(null), children: [g && g.rows[0] === i && (_jsx("rect", { x: groupBox(rail, g).x, y: y + groupBox(rail, g).y, width: groupBox(rail, g).w, height: groupBox(rail, g).h, rx: 6, fill: `color-mix(in srgb, ${v('accent')} 8%, ${v('bg')})`, stroke: v('accent'), strokeDasharray: "3 3" })), _jsx("path", { d: `M ${x1} ${ly} H ${x2}`, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
+                            const tip = edgeTip(row.edge, edges[ids.indexOf(row.edge)].source, allBeats);
+                            return (_jsxs("g", { "data-rail-row": row.n, "data-state": state, opacity: state === 'next' && !on ? 0.45 : 1, style: { cursor: 'pointer' }, onClick: () => goTo(row.step, row.beat), onMouseEnter: () => setHoverEdge(row.edge), onMouseLeave: () => setHoverEdge(null), children: [tip && _jsx("title", { children: tip }), g && g.rows[0] === i && (_jsx("rect", { x: groupBox(rail, g).x, y: y + groupBox(rail, g).y, width: groupBox(rail, g).w, height: groupBox(rail, g).h, rx: 6, fill: `color-mix(in srgb, ${v('accent')} 8%, ${v('bg')})`, stroke: v('accent'), strokeDasharray: "3 3" })), _jsx("path", { d: `M ${x1} ${ly} H ${x2}`, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
                                         (() => {
                                             const tagW = ASYNC_TAG_W;
                                             const tx = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;

package/dist/load.d.ts

@@ -8,3 +8,5 @@ export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions, svg?: s
 export declare function sortFindings(findings: Finding[], strict: boolean): Finding[];
 /** One line per finding, the counts line (unless `withCounts` is false), and the `figure:` line. No color: the CLI adds it. */
 export declare function reportLines(props: FlowProps, findings: Finding[], withCounts?: boolean): string[];
+export declare function summaryLines(props: FlowProps): string[];
+export declare function verifyLines(props: FlowProps, figure: string, root?: string): string[];

package/dist/load.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
-import { counts } from './model.js';
+import { counts, toBeat } from './model.js';
+import { coverageLine, owners, unsureLines, verifyReport } from './verify.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
@@ -54,3 +55,25 @@ export function reportLines(props, findings, withCounts = true) {
     out.push(`figure: ${n(c.boxes, 'box').replace('boxs', 'boxes')}, ${n(c.groups, 'group')}, ${n(c.edges, 'edge')}, ${n(c.steps, 'step')}, ${n(c.messages, 'message')}`);
     return out;
 }
+const text = (x) => (typeof x === 'string' ? x : '');
+export function summaryLines(props) {
+    const edges = props.edges.map((e) => {
+        const label = text(e.label);
+        return `${e.from} -> ${e.to}${label ? `: ${label}` : ''}`;
+    });
+    const steps = (props.steps ?? []).map((s) => {
+        const hops = s.flow.reduce((k, b) => k + toBeat(b).hops.length, 0);
+        return `step "${text(s.label)}": ${hops} ${hops === 1 ? 'hop' : 'hops'}`;
+    });
+    return [...edges, ...steps];
+}
+export function verifyLines(props, figure, root = process.cwd()) {
+    if (!owners(props).some(([, source, via]) => source != null || via != null))
+        return [];
+    const { findings, coverage } = verifyReport(props, { root });
+    return [
+        ...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${figure}: ${f.message}`),
+        coverageLine(figure, coverage),
+        ...unsureLines(coverage),
+    ];
+}

package/dist/mcp.d.ts

@@ -13,6 +13,10 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic: {
+                type: string;
+                enum: string[];
+            };
             paths?: undefined;
             root?: undefined;
             strict?: undefined;
@@ -72,6 +76,7 @@ export declare const TOOLS: ({
                 type: string;
                 description: string;
             };
+            topic?: undefined;
             out: {
                 type: string;
                 description: string;
@@ -89,6 +94,7 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic?: undefined;
             paths: {
                 type: string;
                 items: {
@@ -114,6 +120,7 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic?: undefined;
             paths?: undefined;
             root?: undefined;
             strict?: undefined;

package/dist/mcp.js

@@ -2,8 +2,8 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { diff, formatDiff } from './diff.js';
-import { GUIDE } from './guide.js';
-import { loadSpec, reportLines, sortFindings, svgWithSpec } from './load.js';
+import { GUIDE, TOPICS } from './guide.js';
+import { loadSpec, reportLines, sortFindings, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render } from './svg.js';
 import { checkRendered } from './check.js';
 import { coverageLine, unsureLines, verifyReport } from './verify.js';
@@ -19,7 +19,11 @@ const checkProps = {
     minText: { type: 'number', description: 'The smallest text in px at that width. Default 10.' },
 };
 export const TOOLS = [
-    { name: 'docs', description: 'The flowfig guide. Read it before the first render.', inputSchema: { type: 'object', properties: {} } },
+    {
+        name: 'docs',
+        description: 'The flowfig guide. Read it before the first render. A topic gives the detail for one kind of figure.',
+        inputSchema: { type: 'object', properties: { topic: { type: 'string', enum: Object.keys(TOPICS) } } },
+    },
     {
         name: 'check',
         description: 'List the faults of a figure: unknown ids, text overflow, crossings, label overlap, small text, low contrast. Fix every error before render.',
@@ -84,8 +88,14 @@ const types = (args, tool, want) => {
     }
 };
 function run(name, args) {
-    if (name === 'docs')
-        return ok(GUIDE);
+    if (name === 'docs') {
+        const topic = args.topic;
+        if (topic == null)
+            return ok(GUIDE);
+        if (typeof topic !== 'string' || !Object.hasOwn(TOPICS, topic))
+            throw new Bad(`docs: topic must be one of ${Object.keys(TOPICS).join(', ')}`);
+        return ok(TOPICS[topic]);
+    }
     if (name === 'check' || name === 'render') {
         need(args, name, name === 'render' ? ['spec', 'out'] : ['spec']);
         types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
@@ -106,7 +116,7 @@ function run(name, args) {
         catch (e) {
             throw new Fault(`${out}: ${e.message}`);
         }
-        return ok([...lines, `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
+        return ok([...lines, ...summaryLines(props), ...verifyLines(props, out), `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
     }
     if (name === 'verify') {
         need(args, name, ['paths']);

package/dist/model.d.ts

@@ -169,6 +169,7 @@ export type Beat = Omit<FigBeat, 'edges'> & {
     }[];
 };
 export declare const toBeat: (b: FigHop | FigHop[] | FigBeat) => Beat;
+export declare const edgeTip: (id: string, source: string | undefined, beats: Beat[]) => string | undefined;
 export declare const isRows: (c: FigContent) => c is FigRow[];
 export declare const edgeId: (e: FigEdge) => string;
 export declare const isGroup: (x: FigNode | FigGroup) => x is FigGroup;
@@ -232,11 +233,17 @@ export declare const isLanesLayout: (g: FigGroup) => boolean;
 export declare const validAt: (at: unknown) => at is number;
 /** The time column of each box: first use in the steps, then layout order. `at` wins. */
 export declare function laneColumns(fig: FlowProps): Map<string, number>;
+export declare const LABEL_LINE = 18;
 export declare const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
 export declare const LANE_BLOCK_GAP = 40;
 export declare const STUB = 12, STUB_CLEAR = 8, STUB_ROOM = 30;
 /** The width of a box as the SVG draws it, before a diamond adds its 70 px. */
-export declare function nodeWidth(item: FigNode, carded: boolean): number;
+export declare function nodeWidth(item: FigNode, carded: boolean, cap?: number): number;
+export declare function labelLines(item: FigNode, w: number): string[];
+export declare function itemWidth(item: FigNode | FigGroup, carded: {
+    has(id: string): boolean;
+}, edges: FigEdge[], cap?: number): number;
+export declare function fitCap(fig: FlowProps, width: number, padding?: number): number;
 export declare const diamondRoom: (w: number, h: number, far: number) => number;
 /** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
 export declare function diamondLines(item: FigNode, w: number): {
@@ -343,5 +350,4 @@ export declare const counts: (p: FlowProps) => {
     steps: number;
     messages: number;
 };
-/** A row's default gap grows to hold its widest edge label, plus 8 px each side. */
 export declare function groupGap(g: FigGroup, edges: FigEdge[]): number;

package/dist/model.js

@@ -8,6 +8,14 @@ export const toBeat = (b) => {
         hops: hops.map((h) => (typeof h === 'string' ? { edge: h, back: false } : { back: false, ...h })),
     };
 };
+export const edgeTip = (id, source, beats) => {
+    const all = new Set(source ? [source] : []);
+    for (const b of beats)
+        for (const h of b.hops)
+            if (h.edge === id && h.source)
+                all.add(h.source);
+    return all.size ? [...all].join('\n') : undefined;
+};
 // A React node can be an object, so test for the `text` key.
 export const isRows = (c) => Array.isArray(c) && c.every((r) => r != null && typeof r === 'object' && 'text' in r);
 export const edgeId = (e) => e.id ?? `${e.from}->${e.to}`;
@@ -86,18 +94,47 @@ export function laneColumns(fig) {
             cols.set(n.id, n.at);
     return cols;
 }
+export const LABEL_LINE = 18;
 export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
 export const LANE_BLOCK_GAP = 40;
 export const STUB = 12, STUB_CLEAR = 8, STUB_ROOM = 30;
 /** The width of a box as the SVG draws it, before a diamond adds its 70 px. */
-export function nodeWidth(item, carded) {
+export function nodeWidth(item, carded, cap = NODE_MAX_W) {
     if (item.width != null)
         return item.width;
     if (carded)
         return CARD_WIDTH;
     const label = textWidth(str(item.label), 14) + 32;
     const sub = textWidth(str(item.sub), 12) + 32;
-    return Math.min(NODE_MAX_W, Math.max(NODE_MIN_W, label, sub));
+    return Math.min(item.shape === 'decision' ? NODE_MAX_W : cap, Math.max(NODE_MIN_W, label, sub));
+}
+export function labelLines(item, w) {
+    const label = str(item.label);
+    if (item.shape === 'decision' || textWidth(label, 14) <= w - 32 + 0.5)
+        return [label];
+    const lines = wrap(label, w - 32, 14);
+    return lines.length === 2 && lines.every((l) => textWidth(l, 14) <= w - 32) ? lines : [label];
+}
+export function itemWidth(item, carded, edges, cap = NODE_MAX_W) {
+    if (!isGroup(item))
+        return nodeWidth(item, carded.has(item.id), cap) + (item.shape === 'decision' ? 70 : 0);
+    const ws = item.children.map((c) => itemWidth(c, carded, edges, cap));
+    const inner = item.direction === 'column' ? Math.max(...ws) : ws.reduce((a, b) => a + b, 0) + groupGap(item, edges) * (ws.length - 1);
+    return inner + (item.label != null ? FRAME_SIDE * 2 : 0);
+}
+export function fitCap(fig, width, padding = 24) {
+    if ((fig.lanes || fig.timeline) && isLanesLayout(fig.layout))
+        return NODE_MAX_W;
+    const carded = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => Object.keys(toBeat(b).show ?? {}))));
+    const fits = (n, cap) => {
+        const w = nodeWidth(n, carded.has(n.id), cap);
+        return Math.max(textWidth(str(n.sub), 12), ...labelLines(n, w).map((l) => textWidth(l, 14))) + 32 <= w + 0.5;
+    };
+    const keep = nodes(fig.layout).filter((n) => fits(n, NODE_MAX_W));
+    let cap = NODE_MAX_W;
+    while (cap > 110 && itemWidth(fig.layout, carded, fig.edges, cap) + padding * 2 > width && keep.every((n) => fits(n, cap - 20)))
+        cap -= 20;
+    return cap;
 }
 export const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
 /** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
@@ -415,16 +452,22 @@ export const counts = (p) => {
     };
 };
 const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
-/** A row's default gap grows to hold its widest edge label, plus 8 px each side. */
 export function groupGap(g, edges) {
-    if (g.gap != null)
-        return g.gap;
-    if (g.direction === 'column')
-        return 28;
     const side = new Map();
     g.children.forEach((c, i) => idsIn(c).forEach((id) => side.set(id, i)));
-    const pills = edges
-        .filter((e) => e.label != null && side.has(e.from) && side.has(e.to) && side.get(e.from) !== side.get(e.to))
-        .map((e) => labelPillW(str(e.label)) + 16);
-    return Math.max(56, ...pills);
+    const spans = edges.filter((e) => e.label != null && side.has(e.from) && side.has(e.to) && side.get(e.from) !== side.get(e.to) && !(g.gap != null && e.around));
+    if (g.gap != null && !spans.length)
+        return g.gap;
+    const need = Math.max(0, ...spans.map((e) => labelPillW(str(e.label)) + 16));
+    if (g.gap != null && g.direction !== 'column')
+        return Math.max(g.gap, need - 16);
+    let auto;
+    if (g.direction === 'column') {
+        const ends = spans.map((e) => [side.get(e.from), side.get(e.to)].sort((p, q) => p - q));
+        const most = Math.max(0, ...g.children.map((_, k) => ends.filter(([lo, hi]) => lo <= k && k < hi).length));
+        auto = most > 1 ? Math.min(most, 3) * 22 + 16 : 28;
+    }
+    else
+        auto = Math.max(56, need);
+    return Math.max(g.gap ?? 0, auto);
 }

package/dist/scene.d.ts

@@ -33,6 +33,8 @@ export type Scene = {
     edges: SceneEdge[];
     /** The smallest reading text in px, before any scale. */
     minFont: number;
+    /** The drawn map area. An edge label stays inside it. */
+    area?: Rect;
     /** The lane bands of a swimlanes figure. A stub pill stays inside one. */
     lanes?: {
         id: string;