flowfig 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,11 +1,12 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useEffect, useId, useMemo, useRef, useState } from 'react';
-import { arcRoom, avoidOf, route } from './geometry.js';
+import { Fragment, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { arcRoom, avoidOf, markSide, 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, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, altText, 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';
+import { autoLayout, rowBreaks } from './auto.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, altText, 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, fitScale, shownFont, textFloor, specKey, nextWide, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -54,17 +55,37 @@ const HIDDEN = {
  * The interactive player for one figure. Give it a `FlowProps` spec.
  * Use `toSvg` from `flowfig/svg` for a static animated SVG.
  */
-export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900, autoplay = true, check = false, rail: withRail = false, lanes, timeline, today, }) {
+export function Flow(props) {
+    const { layout, edges, steps, lanes, timeline } = props;
+    const key = useMemo(() => specKey(layout, edges, steps), [layout, edges, steps]);
+    const [narrow, setNarrow] = useState({ wide: 0, key: '' });
+    const fold = !lanes && !timeline && props.rail !== 'only';
+    const wide = fold && narrow.key === key ? narrow.wide : 0;
+    const setWide = useCallback((w) => setNarrow({ wide: w, key }), [key]);
+    const placed = useMemo(() => autoLayout({ layout: wide > 0 ? { ...layout, auto: true, direction: 'column' } : layout, edges, steps, lanes, timeline }), [wide, layout, edges, steps, lanes, timeline]);
+    return (_jsx(FlowBody, { ...props, layout: placed.layout, edges: placed.edges, written: props, wide: wide, setWide: fold ? setWide : undefined }));
+}
+// The ASYNC tag is 9 px.
+const RAIL_TEXT = 9;
+// offsetWidth is rounded, so a rect ratio reads scale 1 as 0.999.
+const shownScale = (el) => {
+    let k = 1;
+    for (let n = el; n; n = n.parentElement)
+        k *= new DOMMatrix(getComputedStyle(n).transform).a;
+    return k;
+};
+function FlowBody({ layout, edges, steps: stepsIn = NONE, theme, speed = 900, autoplay = true, check = false, rail: withRail = false, lanes, timeline, today, written, wide, setWide, }) {
     const tl = timeline && isLanesLayout(layout);
     const alt = useMemo(() => altText({ layout, edges, steps: stepsIn }), [layout, edges, stepsIn]);
     const descId = useId();
+    const tabsId = useId();
     const synthetic = tl && !stepsIn.length;
     const steps = useMemo(() => (synthetic ? timelineBeats({ layout, edges, timeline, today }) : stepsIn), [synthetic, layout, edges, timeline, today, stepsIn]);
     const [axisW, setAxisW] = useState(TL_AXIS_W);
     const area = useRef(null);
     const root = useRef(null);
     const outer = useRef(null);
-    const [fit, setFit] = useState({ scale: 1, height: 0 });
+    const [fit, setFit] = useState({ scale: 1, height: 0, scroll: false });
     const [full, setFull] = useState(false);
     useEffect(() => {
         if (!full)
@@ -82,6 +103,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const firstLabel = useRef('');
     const paths = useRef({});
     const [routed, setRouted] = useState([]);
+    const routedOn = useRef(new WeakMap());
+    const markSides = new Set(nodes(layout).flatMap((n) => (n.mark ? [markSide(n.id, n.mark, routed)] : [])));
     const [extraTall, setExtraTall] = useState(new Set());
     const lanePlan = useMemo(() => lanes && !tl && isLanesLayout(layout)
         ? planLanes({ layout, edges, steps, lanes }, { floor: withRail ? (layoutRail({ layout, edges, steps, rail: true }, 560)?.width ?? 0) : 0 })
@@ -129,6 +152,13 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const railOnly = withRail === 'only';
     const rail = useMemo(() => (withRail ? layoutRail({ layout, edges, steps, rail: true }, railOnly ? 560 : mapW) : null), [withRail, railOnly, layout, edges, steps, mapW]);
     const noMap = railOnly && rail != null;
+    const railPane = useRef(null);
+    const [railBox, setRailBox] = useState(0);
+    const zoom = wide ? 11 / RAIL_TEXT : noMap && railBox ? textFloor(railBox) / RAIL_TEXT : 0;
+    const follow = useRef(true);
+    const user = useRef(false);
+    const left = useRef(0);
+    const busy = useRef(0);
     const jump = useRef(null);
     const [hoverEdge, setHoverEdge] = useState(null);
     const [still, setStill] = useState(false);
@@ -148,15 +178,20 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const el = root.current, box = outer.current;
         if (!el || !box)
             return;
+        let last = '';
         const measure = () => {
-            const scale = Math.max(0.5, Math.min(1, box.clientWidth / el.offsetWidth));
-            setFit({ scale, height: el.offsetHeight * scale });
+            if (!el.offsetWidth)
+                return;
+            const goal = nextWide(wide, box.clientWidth, el.offsetWidth);
+            if (setWide && goal !== wide)
+                return setWide(goal);
+            const scale = fitScale(wide, box.clientWidth, el.offsetWidth);
+            setFit({ scale, height: el.offsetHeight * scale, scroll: scale > box.clientWidth / el.offsetWidth });
             setMapW(el.offsetWidth);
             if (area.current)
                 setAxisW(area.current.offsetWidth);
             const base = el.getBoundingClientRect();
-            // Rects are measured unscaled: k is the scale on screen.
-            const k = base.width / el.offsetWidth;
+            const k = shownScale(el);
             const rects = {};
             el.querySelectorAll('[data-fig]').forEach((n) => {
                 const r = n.getBoundingClientRect();
@@ -202,6 +237,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 const li = layout.children.findIndex((l) => isGroup(l) && (l.id === id || l.children.some((b) => b.id === id)));
                 return laneBands[`${li}@${lanePlan?.ends.get(eid)?.[j]}`];
             };
+            const key = JSON.stringify([rects, extra, bands, laneBands, pillArea], (_k, v) => (typeof v === 'number' ? Math.round(v) : v));
+            if (key === last)
+                return;
+            last = key;
             const end = (eid, id, start) => lanePlan ? laneEnd(lanePlan, eid, id, start, (lane, b) => bands[`${lane}@${b}`], rects) : id;
             const next = route(edges.map((e, i) => ({
                 id: ids[i],
@@ -209,12 +248,14 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 to: end(ids[i], e.to, false),
                 around: e.around ?? (lanePlan?.around.has(ids[i]) ? 'below' : undefined),
                 ...(tl && { sides: ['r', 'l'], elbow: true }),
+                ...(rowBreaks.has(e) && { drop: true }),
                 ...(stubs.has(ids[i]) && {
                     stub: stubs.get(ids[i]).map(labelPillW),
                     bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)],
                 }),
                 ...(!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);
+            routedOn.current.set(next, rects);
             setRouted(next);
             if (lanePlan) {
                 const more = [...tightCopies(layout.children, lanePlan.ends, edges, next)].filter((k) => !lanePlan.tall.has(k) && !extraTall.has(k));
@@ -224,19 +265,44 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         };
         measure();
         const ro = new ResizeObserver(measure);
-        ro.observe(el);
+        ro.observe(el, { box: 'border-box' });
         ro.observe(box);
         el.querySelectorAll('[data-fig]').forEach((n) => ro.observe(n));
         return () => ro.disconnect();
-    }, [edges, ids, layout, tips, noMap, lanes, tl, axisW, lanePlan, extraTall]);
+    }, [edges, ids, layout, tips, noMap, lanes, tl, axisW, lanePlan, extraTall, wide, setWide]);
+    useEffect(() => {
+        const pane = railPane.current;
+        const n = rail?.rows.flatMap((r) => (r.kind === 'message' && r.step === active && r.beat === beat ? [r.n] : []))[0];
+        const now = zoom && follow.current && n != null ? pane?.querySelector(`[data-rail-row="${n}"] path`) : null;
+        if (!pane || !now)
+            return;
+        const [p, r] = [pane.getBoundingClientRect(), now.getBoundingClientRect()];
+        user.current = false;
+        // Some browsers fire no scrollend event.
+        busy.current = performance.now() + 1000;
+        pane.scrollTo({ left: pane.scrollLeft + (r.left + r.right) / 2 - p.left - pane.clientWidth / 2, behavior: still ? 'auto' : 'smooth' });
+    }, [zoom, active, beat, still, rail]);
+    useEffect(() => {
+        const pane = railPane.current;
+        if (!pane)
+            return;
+        const end = () => (busy.current = 0);
+        pane.addEventListener('scrollend', end);
+        const ro = new ResizeObserver(() => setRailBox(pane.clientWidth));
+        if (noMap)
+            ro.observe(pane);
+        return () => (pane.removeEventListener('scrollend', end), ro.disconnect());
+    }, [rail, noMap]);
     const reported = useRef(new Set());
     useEffect(() => {
         const el = root.current, box = outer.current;
         const fig = figure.current;
-        if (!check || !fig || (!noMap && (!el || !box)))
+        if (!check || !fig || (noMap ? !railBox : !el || !box || !el.offsetWidth))
+            return;
+        if (setWide && el && box && nextWide(wide, box.clientWidth, el.offsetWidth) !== wide)
             return;
         const base = (el ?? fig).getBoundingClientRect();
-        const k = el ? base.width / el.offsetWidth : 1;
+        const k = el ? shownScale(el) : 1;
         const rel = (n) => {
             const r = n.getBoundingClientRect();
             return { x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k };
@@ -253,7 +319,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     .filter((t) => !t.children.length && t.textContent?.trim() && t.clientWidth > 0 && !t.closest('[aria-hidden]'))
                     .map((t) => {
                     const fontSize = parseFloat(getComputedStyle(t).fontSize);
-                    if (!n.dataset.diamond)
+                    if (!n.dataset.diamond || t.closest('[data-fig-outside]'))
                         return { text: t.textContent, fontSize, room: t.clientWidth, need: t.scrollWidth };
                     const [r, range] = [rel(t), document.createRange()];
                     range.selectNodeContents(t);
@@ -267,17 +333,28 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 }),
             };
         });
+        const moved = (b) => {
+            const r = routedOn.current.get(routed)?.[b.id];
+            return !r || Math.abs(r.x - b.rect.x) > 1 || Math.abs(r.y - b.rect.y) > 1;
+        };
+        if (el && boxes.some(moved))
+            return;
         const fonts = [...fig.querySelectorAll('*')]
             .filter((t) => !t.children.length &&
             t.textContent?.trim() &&
             // An SVG <text> has no CSS box, so skip clientWidth.
             (t instanceof SVGElement || t.clientWidth > 0) &&
             !t.closest('[data-fig-tag],[aria-hidden]'))
-            .map((t) => parseFloat(getComputedStyle(t).fontSize));
+            .map((t) => {
+            const svg = railPane.current?.firstElementChild;
+            const place = el?.contains(t) ? 'map' : svg?.contains(t) && rail ? 'rail' : 'plain';
+            const railScale = svg && rail ? svg.getBoundingClientRect().width / rail.width : 1;
+            return shownFont(parseFloat(getComputedStyle(t).fontSize), place, { map: k, rail: railScale });
+        });
         const labels = Object.fromEntries([...fig.querySelectorAll('[data-fig-label]')].map((n) => [n.dataset.figLabel, rel(n)]));
         const lanesIn = el ? [...el.querySelectorAll('[data-fig-band]')] : [];
         const scene = {
-            width: Math.max(el?.offsetWidth ?? 0, rail?.width ?? 0),
+            width: (box ?? fig).clientWidth,
             boxes,
             ...(lanePlan?.stubs.size && {
                 lanes: lanesIn.map((n) => ({
@@ -322,8 +399,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             minFont: Math.min(...fonts),
         };
         for (const f of [
-            ...checkSpec({ layout, edges, steps }),
-            ...checkScene(scene, { width: (box ?? fig).clientWidth }),
+            ...checkSpec(written),
+            ...checkScene(scene, { width: (box ?? fig).clientWidth, minText: textFloor((box ?? fig).clientWidth), auto: written.layout.auto }),
             ...checkTheme(theme),
         ]) {
             const key = f.rule + ':' + f.ids.join() + ':' + f.message;
@@ -333,7 +410,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             // oxlint-disable-next-line no-console
             console.warn(`flowfig check: ${f.severity} ${f.rule}: ${f.message}`);
         }
-    }, [check, routed, layout, edges, steps, ids, theme, rail, noMap, lanePlan]);
+    }, [check, routed, written, layout, edges, steps, ids, theme, rail, noMap, railBox, lanePlan, wide, setWide]);
     useEffect(() => {
         const gs = dots.current, cs = chips.current, edgeOf = Object.fromEntries(edges.map((e, i) => [ids[i], e]));
         if (clock.current.beats !== beats) {
@@ -453,6 +530,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         return t && TONES[t];
     };
     const goTo = (step, b) => {
+        follow.current = true;
         setPlaying(true);
         if (step === active) {
             clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + beatMs(x, speed), 0);
@@ -648,15 +726,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             display: 'flex',
                             flexDirection: item.direction ?? 'row',
                             gap: groupGap(item, edges),
-                            alignItems: item.align
-                                ? item.align === 'center'
-                                    ? 'center'
-                                    : 'flex-' + item.align
-                                : item.direction === 'column'
-                                    ? 'stretch'
-                                    : 'center',
+                            alignItems: !item.align || item.align === 'center' ? 'center' : 'flex-' + item.align,
                             justifyContent: 'center',
-                        }, children: item.children.map((c) => renderItem(c, depth + 1)) })] }, item.id ?? depth + String(item.label)));
+                        }, children: item.children.map((c) => renderItem(c, depth + 1)) })] }, item.id ?? `group:${nodes(item)[0]?.id}`));
         }
         const lit = litNodes.has(item.id);
         const diamond = item.shape === 'decision';
@@ -664,7 +736,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         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 lines = w != null && str(item.label) ? labelLines(item, w) : null;
         const bt = item.tone && TONES[item.tone];
         return (_jsxs("div", { "data-fig": item.id, title: item.source, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
                 position: 'relative',
@@ -711,14 +783,12 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                         transition: 'border-color .25s',
                     } })), item.mark && (_jsx("span", { "aria-hidden": true, style: {
                         position: 'absolute',
-                        top: '50%',
-                        transform: 'translateY(-50%)',
+                        ...markAt(markSide(item.id, item.mark, routed), item.mark === 'start' ? -18 : -20),
                         boxSizing: 'border-box',
                         borderRadius: '50%',
                         ...(item.mark === 'start'
-                            ? { left: -18, width: 10, height: 10, background: bt ?? v('accent') }
+                            ? { width: 10, height: 10, background: bt ?? v('accent') }
                             : {
-                                right: -20,
                                 width: 14,
                                 height: 14,
                                 border: `1.5px solid ${bt ?? v('accent')}`,
@@ -788,8 +858,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                         borderBottom: `1px solid ${v('border')}`,
                         backgroundImage: `radial-gradient(color-mix(in srgb, ${v('fg')} 16%, transparent) 1px, transparent 1.2px)`,
                         backgroundSize: '14px 14px',
-                    }, children: _jsx("div", { ref: outer, style: {
-                            overflow: fit.scale > 0.5 ? 'hidden' : 'auto',
+                    }, children: _jsx("div", { ref: outer, role: "tabpanel", id: `${tabsId}-panel`, "aria-labelledby": `${tabsId}-tab-${active ?? 0}`, style: {
+                            overflow: wide || fit.scroll ? 'auto' : 'hidden',
                             height: fit.scale < 1 ? fit.height : undefined,
                         }, children: _jsxs("div", { ref: root, style: {
                                 position: 'relative',
@@ -797,8 +867,8 @@ 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',
-                                paddingTop: arcRoom(routed, 'above') || 4,
-                                paddingBottom: arcRoom(routed, 'below') || 4,
+                                paddingTop: arcRoom(routed, 'above') || (markSides.has('t') ? 20 : 4),
+                                paddingBottom: arcRoom(routed, 'below') || (markSides.has('b') ? 20 : 4),
                                 paddingLeft: arcRoom(routed, 'left') || 4,
                                 paddingRight: arcRoom(routed, 'right') || 4,
                             }, children: [renderItem(layout, 0), _jsxs("svg", { style: {
@@ -879,52 +949,72 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                             fontFamily: MONO,
                                             transition: 'background .25s, color .25s, opacity .25s',
                                         }, children: p.text }, p.key)));
-                                })] }) }) }) })), rail && (_jsxs("svg", { viewBox: `0 0 ${rail.width} ${rail.height}`, style: {
-                    display: 'block',
-                    width: '100%',
-                    maxWidth: rail.width,
-                    height: 'auto',
-                    margin: `${noMap ? 0 : RAIL.gap}px auto 0`,
-                    overflow: 'visible',
-                    fontFamily: v('font'),
-                }, children: [rail.bands.map((b) => (_jsxs("g", { children: [_jsx("rect", { x: b.rect.x, y: b.rect.y, width: b.rect.w, height: b.rect.h, rx: 10, fill: v('surface'), stroke: v('border') }), _jsx("text", { x: b.rect.x + 10, y: b.rect.y + 14, fill: v('muted'), fontSize: 11, fontWeight: 600, letterSpacing: ".04em", children: b.label.toUpperCase() })] }, b.id))), rail.columns.map((c) => (_jsx("text", { x: c.x, y: rail.head - RAIL.cols / 2 + 4, fill: v('fg'), fontSize: 12, fontWeight: 500, textAnchor: "middle", children: c.label }, c.id))), (() => {
-                        const st = railState(rail, active ?? 0);
-                        const lines = rail.rows.flatMap((row, i) => row.kind === 'message' && st[i].shown ? rail.columns.map((c) => `M ${c.x} ${st[i].y} V ${st[i].y + RAIL.row}`) : []);
-                        return _jsx("path", { d: lines.join(' '), stroke: v('border'), strokeDasharray: "2 3" });
-                    })(), (() => {
-                        const st = railState(rail, active ?? 0);
-                        return rail.rows.map((row, i) => {
-                            if (!st[i].shown)
-                                return null;
-                            const y = st[i].y;
-                            if (row.kind === 'phase') {
-                                const open = !rail.folds || row.step === active;
-                                const playing = row.step === active ? rail.rows.find((r) => r.kind === 'message' && r.step === active && r.beat === beat) : undefined;
-                                return (_jsxs("g", { style: { cursor: open ? undefined : 'pointer' }, onClick: open ? undefined : () => goTo(row.step, 0), children: [_jsx("text", { x: RAIL.pad, y: y + 19, fill: open ? v('fg') : v('muted'), fontSize: 13, fontWeight: 600, fontFamily: MONO, children: open ? row.label : foldedLabel(row) }), _jsx("path", { d: `M ${open ? row.line.open : row.line.folded} ${y + 15} H ${row.line.end}`, stroke: v('border') }), playing?.kind === 'message' && (_jsxs("text", { x: rail.width - RAIL.pad, y: y + 19, fill: v('muted'), fontSize: 11, fontWeight: 600, textAnchor: "end", children: [still ? rail.total : playing.n, " of ", rail.total] }))] }, `p${i}`));
-                            }
-                            const state = still
-                                ? 'done'
-                                : active == null || row.step > active || (row.step === active && row.beat > beat)
-                                    ? 'next'
-                                    : row.step === active && row.beat === beat
-                                        ? 'now'
-                                        : 'done';
-                            const on = state === 'now' ||
-                                hoverEdge === row.edge ||
-                                (hover != null && [rail.columns[row.from].id, rail.columns[row.to].id].includes(hover));
-                            const [x1, x2] = [rail.columns[row.from].x, rail.columns[row.to].x];
-                            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;
-                            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;
-                                            return (_jsxs(_Fragment, { children: [_jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: v('bg') }), _jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: TONES.gray, fillOpacity: 0.15 }), _jsx("text", { x: tx + tagW / 2, y: ly + 3, fill: TONES.gray, fontSize: 9, fontWeight: 600, letterSpacing: ".03em", textAnchor: "middle", "data-fig-tag": true, children: "ASYNC" })] }));
-                                        })(), row.pill && (_jsxs("g", { "data-fig-label": `rail:${row.n}`, children: [_jsx("rect", { x: row.pill.x, y: ly - 9, width: row.pill.w, height: 18, rx: 9, fill: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'), stroke: on ? (tone ?? v('accent')) : v('border') }), _jsx("text", { x: row.pill.x + row.pill.w / 2, y: ly + 4, fill: on ? ON_ACCENT : v('muted'), fontSize: 11, fontFamily: MONO, textAnchor: "middle", children: row.text })] }))] }, `m${i}`));
-                        });
-                    })(), _jsx("defs", { children: _jsx("marker", { id: "flowfig-rail-arrow", viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: v('muted') }) }) })] })), steps.length > 0 && (_jsxs("figcaption", { style: { marginTop: 14, textAlign: 'center' }, children: [_jsxs("div", { style: { display: 'flex', gap: 10, justifyContent: 'center', alignItems: 'center' }, children: [_jsx("button", { type: "button", "aria-label": playing ? 'Pause' : 'Play', title: playing ? 'Pause' : 'Play', style: iconBtn, onClick: () => setPlaying((p) => !p), children: _jsx(Icon, { d: playing ? 'M5.5 4v8M10.5 4v8' : 'M5 3.5v9l7.5-4.5z', fill: !playing }) }), !synthetic && (_jsx("div", { role: "tablist", style: {
+                                })] }) }) }) })), rail && (_jsx("div", { ref: railPane, onWheel: () => (user.current = true), onPointerDown: () => (user.current = true), onTouchStart: () => (user.current = true), onScroll: (e) => {
+                    const x = e.currentTarget.scrollLeft;
+                    if (user.current && x !== left.current && performance.now() > busy.current)
+                        follow.current = false;
+                    left.current = x;
+                }, style: { overflowX: zoom ? 'auto' : undefined }, children: _jsxs("svg", { viewBox: `0 0 ${rail.width} ${rail.height}`, style: {
+                        display: 'block',
+                        width: zoom ? rail.width * zoom : '100%',
+                        maxWidth: zoom ? undefined : rail.width,
+                        height: 'auto',
+                        margin: `${noMap ? 0 : RAIL.gap}px auto 0`,
+                        overflow: 'visible',
+                        fontFamily: v('font'),
+                    }, children: [rail.bands.map((b) => (_jsxs("g", { children: [_jsx("rect", { x: b.rect.x, y: b.rect.y, width: b.rect.w, height: b.rect.h, rx: 10, fill: v('surface'), stroke: v('border') }), _jsx("text", { x: b.rect.x + 10, y: b.rect.y + 14, fill: v('muted'), fontSize: 11, fontWeight: 600, letterSpacing: ".04em", children: b.label.toUpperCase() })] }, b.id))), rail.columns.map((c) => (_jsx("text", { x: c.x, y: rail.head - RAIL.cols / 2 + 4, fill: v('fg'), fontSize: 12, fontWeight: 500, textAnchor: "middle", children: c.label }, c.id))), (() => {
+                            const st = railState(rail, active ?? 0);
+                            const lines = rail.rows.flatMap((row, i) => row.kind === 'message' && st[i].shown ? rail.columns.map((c) => `M ${c.x} ${st[i].y} V ${st[i].y + RAIL.row}`) : []);
+                            return _jsx("path", { d: lines.join(' '), stroke: v('border'), strokeDasharray: "2 3" });
+                        })(), (() => {
+                            const st = railState(rail, active ?? 0);
+                            return rail.rows.map((row, i) => {
+                                if (!st[i].shown)
+                                    return null;
+                                const y = st[i].y;
+                                if (row.kind === 'phase') {
+                                    const open = !rail.folds || row.step === active;
+                                    const playing = row.step === active ? rail.rows.find((r) => r.kind === 'message' && r.step === active && r.beat === beat) : undefined;
+                                    return (_jsxs("g", { style: { cursor: open ? undefined : 'pointer' }, onClick: open ? undefined : () => goTo(row.step, 0), children: [_jsx("text", { x: RAIL.pad, y: y + 19, fill: open ? v('fg') : v('muted'), fontSize: 13, fontWeight: 600, fontFamily: MONO, children: open ? row.label : foldedLabel(row) }), _jsx("path", { d: `M ${open ? row.line.open : row.line.folded} ${y + 15} H ${row.line.end}`, stroke: v('border') }), playing?.kind === 'message' && (_jsxs("text", { x: rail.width - RAIL.pad, y: y + 19, fill: v('muted'), fontSize: 11, fontWeight: 600, textAnchor: "end", children: [still ? rail.total : playing.n, " of ", rail.total] }))] }, `p${i}`));
+                                }
+                                const state = still
+                                    ? 'done'
+                                    : active == null || row.step > active || (row.step === active && row.beat > beat)
+                                        ? 'next'
+                                        : row.step === active && row.beat === beat
+                                            ? 'now'
+                                            : 'done';
+                                const on = state === 'now' ||
+                                    hoverEdge === row.edge ||
+                                    (hover != null && [rail.columns[row.from].id, rail.columns[row.to].id].includes(hover));
+                                const [x1, x2] = [rail.columns[row.from].x, rail.columns[row.to].x];
+                                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;
+                                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;
+                                                return (_jsxs(_Fragment, { children: [_jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: v('bg') }), _jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: TONES.gray, fillOpacity: 0.15 }), _jsx("text", { x: tx + tagW / 2, y: ly + 3, fill: TONES.gray, fontSize: 9, fontWeight: 600, letterSpacing: ".03em", textAnchor: "middle", "data-fig-tag": true, children: "ASYNC" })] }));
+                                            })(), row.pill && (_jsxs("g", { "data-fig-label": `rail:${row.n}`, children: [_jsx("rect", { x: row.pill.x, y: ly - 9, width: row.pill.w, height: 18, rx: 9, fill: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'), stroke: on ? (tone ?? v('accent')) : v('border') }), _jsx("text", { x: row.pill.x + row.pill.w / 2, y: ly + 4, fill: on ? ON_ACCENT : v('muted'), fontSize: 11, fontFamily: MONO, textAnchor: "middle", children: row.text })] }))] }, `m${i}`));
+                            });
+                        })(), _jsx("defs", { children: _jsx("marker", { id: "flowfig-rail-arrow", viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: v('muted') }) }) })] }) })), steps.length > 0 && (_jsxs("figcaption", { style: { marginTop: 14, textAlign: 'center' }, children: [_jsxs("div", { style: { display: 'flex', gap: 10, justifyContent: 'center', alignItems: 'center' }, children: [_jsx("button", { type: "button", "aria-label": playing ? 'Pause' : 'Play', title: playing ? 'Pause' : 'Play', style: iconBtn, onClick: () => {
+                                    follow.current ||= !playing;
+                                    setPlaying((p) => !p);
+                                }, children: _jsx(Icon, { d: playing ? 'M5.5 4v8M10.5 4v8' : 'M5 3.5v9l7.5-4.5z', fill: !playing }) }), !synthetic && (_jsx("div", { role: "tablist", onKeyDown: (e) => {
+                                    const to = { ArrowRight: (active ?? 0) + 1, ArrowLeft: (active ?? 0) - 1, Home: 0, End: steps.length - 1 }[e.key];
+                                    if (to === undefined)
+                                        return;
+                                    e.preventDefault();
+                                    const n = (to + steps.length) % steps.length;
+                                    clock.current.elapsed = 0;
+                                    follow.current = true;
+                                    setActive(n);
+                                    setPlaying(true);
+                                    setBeat(0);
+                                    document.getElementById(`${tabsId}-tab-${n}`)?.focus();
+                                }, style: {
                                     display: 'inline-flex',
                                     gap: 2,
                                     padding: 3,
@@ -933,8 +1023,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                     border: `1px solid ${v('border')}`,
                                 }, children: steps.map((s, i) => {
                                     const on = active === i;
-                                    return (_jsxs("button", { type: "button", role: "tab", "aria-selected": on, onClick: () => {
+                                    return (_jsxs("button", { type: "button", role: "tab", "aria-selected": on, id: `${tabsId}-tab-${i}`, "aria-controls": noMap ? undefined : `${tabsId}-panel`, tabIndex: on ? 0 : -1, onClick: () => {
                                             clock.current.elapsed = 0;
+                                            follow.current = true;
                                             setActive(i);
                                             setPlaying(true);
                                             setBeat(0);
@@ -983,6 +1074,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             animation: 'flowfig-in .35s ease-out',
                         }, children: said }, `${active}-${saidAt}`))] }))] }));
 }
+const markAt = (side, off) => side === 'l' || side === 'r'
+    ? { [side === 'l' ? 'left' : 'right']: off, top: '50%', transform: 'translateY(-50%)' }
+    : { [side === 't' ? 'top' : 'bottom']: off, left: '50%', transform: 'translateX(-50%)' };
 function Icon({ d, fill = false }) {
     return (_jsx("svg", { width: 14, height: 14, viewBox: "0 0 16 16", fill: fill ? 'currentColor' : 'none', stroke: "currentColor", strokeWidth: 1.6, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: _jsx("path", { d: d }) }));
 }

package/dist/load.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { altText, counts, toBeat } from './model.js';
-import { coverageLine, owners, unsureLines, verifyReport } from './verify.js';
+import { coverageLine, detailFindings, owners, unsureLines, verifyReport } from './verify.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
@@ -68,8 +68,9 @@ export function summaryLines(props) {
     return [...edges, ...steps, `alt: ${altText(props).title}`];
 }
 export function verifyLines(props, figure, root = process.cwd()) {
-    if (!owners(props).some(([, source, via]) => source != null || via != null))
-        return [];
+    if (!owners(props).some(([, source, via]) => source != null || via != null)) {
+        return detailFindings(props, root).map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${figure}: ${f.message}`);
+    }
     const { findings, coverage } = verifyReport(props, { root });
     return [
         ...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${figure}: ${f.message}`),

package/dist/mermaid.d.ts

@@ -0,0 +1,19 @@
+import { type FlowProps } from './model.ts';
+export type MermaidFault = {
+    line: number;
+    reason: string;
+};
+type Result = {
+    spec: FlowProps;
+    faults: [];
+} | {
+    spec?: undefined;
+    faults: MermaidFault[];
+};
+export declare function fromMermaid(text: string, first?: number): Result;
+export declare function markdownBlocks(text: string): {
+    text: string;
+    line: number;
+}[];
+export declare function runFromMermaid(argv: string[]): number;
+export {};