flowfig 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,15 +1,20 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
 import { 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, decisions, edgeId, groupGap, isGroup, isRows, nodes, toBeat, } from './model.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, laneColumns, LANE_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
 const MONO = 'var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular, Menlo, monospace)';
-const glow = `0 0 0 3px color-mix(in srgb, ${v('accent')} 18%, transparent)`;
+const NONE = []; // a stable default, so a memo keyed on it does not run every render
+const ACTIVE = 'flowfig-active'; // the box a packet has just reached
+// The active box reads --ff-hop (the tone of the hop that arrived), then --ff-box (the tone of the box), then the accent.
+const hue = `var(--ff-hop, var(--ff-box, ${v('accent')}))`;
+const glow = `0 0 0 3px color-mix(in srgb, ${hue} 18%, transparent)`;
 const cardBody = (c) => {
     if (c == null)
         return '—';
@@ -43,7 +48,14 @@ const cardBody = (c) => {
  * The interactive player for one figure: tabs for the steps, play and pause, speed, hover and full screen.
  * Give it a `FlowProps` spec. Use `toSvg` from `flowfig/svg` for a static animated SVG instead.
  */
-export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay = true, check = false, rail: withRail = false }) {
+export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900, autoplay = true, check = false, rail: withRail = false, lanes, timeline, today, }) {
+    const tl = timeline && isLanesLayout(layout);
+    // A timeline with no steps of its own walks its dated items in date order, with no tab row.
+    const synthetic = tl && !stepsIn.length;
+    const steps = useMemo(() => (synthetic ? timelineBeats({ layout, edges, timeline, today }) : stepsIn), [synthetic, layout, edges, timeline, today, stepsIn]);
+    // The width of the timeline area in px: the server draws TL_AXIS_W, and the browser measures the real width after mount.
+    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 });
@@ -59,6 +71,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     const chips = useRef([]);
     const bar = useRef(null); // the active tab's progress line
     const [beat, setBeat] = useState(0);
+    const [holding, setHolding] = useState(false); // the step hold: a timeline's today line rests at today
     const paths = useRef({});
     const [routed, setRouted] = useState([]);
     const [active, setActive] = useState(steps.length ? 0 : null);
@@ -72,7 +85,15 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     const clock = useRef({ beats: null, elapsed: 0 });
     const [hover, setHover] = useState(null);
     const ids = useMemo(() => edges.map(edgeId), [edges]);
-    const tips = useMemo(() => new Set(decisions(layout)), [layout]);
+    // A milestone is a diamond too, so its edges meet the tips.
+    const tips = useMemo(() => new Set([
+        ...decisions(layout),
+        ...(tl
+            ? timelineLayout({ layout, edges, timeline, today }, TL_AXIS_W)
+                .items.filter((i) => i.milestone)
+                .map((i) => i.id)
+            : []),
+    ]), [layout, tl, edges, timeline, today]);
     const step = active == null ? null : steps[active];
     const beats = useMemo(() => (step?.flow ?? []).map(toBeat), [step]);
     // Every content each box's card will ever show. The card is sized to the largest, so text never gets cut and nothing jumps.
@@ -129,6 +150,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
             const scale = Math.max(0.5, Math.min(1, box.clientWidth / el.offsetWidth));
             setFit({ scale, height: el.offsetHeight * scale });
             setMapW(el.offsetWidth);
+            if (area.current)
+                setAxisW(area.current.offsetWidth);
             const base = el.getBoundingClientRect();
             const k = base.width / el.offsetWidth; // the scale currently on screen; rects are measured unscaled
             const rects = {};
@@ -141,7 +164,18 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     h: r.height / k,
                 };
             });
-            setRouted(route(edges.map((e, i) => ({ id: ids[i], from: e.from, to: e.to, around: e.around })), rects, tips));
+            const avoid = [];
+            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 });
+            });
+            setRouted(route(edges.map((e, i) => ({
+                id: ids[i],
+                from: e.from,
+                to: e.to,
+                around: e.around,
+                ...(tl && { sides: ['r', 'l'], elbow: true }),
+            })), rects, tips, avoid));
         };
         measure();
         const ro = new ResizeObserver(measure);
@@ -149,7 +183,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         ro.observe(box);
         el.querySelectorAll('[data-fig]').forEach((n) => ro.observe(n));
         return () => ro.disconnect();
-    }, [edges, ids, layout, tips, noMap]);
+    }, [edges, ids, layout, tips, noMap, lanes, tl, axisW]);
     // The same rules as `flowfig check`, on what the browser actually drew: real fonts, real wrapping. Each fault prints once.
     const reported = useRef(new Set());
     useEffect(() => {
@@ -192,7 +226,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
             edges: [
                 ...routed.map((r) => {
                     const e = edges[ids.indexOf(r.id)];
-                    return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labels[r.id] };
+                    return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labels[r.id], ...(tl && { behind: true }) };
                 }),
                 // A rail pill is a label for label-overlap; its curve is a point at the pill center, so it can cross no box.
                 ...(rail?.rows ?? []).flatMap((row) => {
@@ -228,23 +262,23 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     }, [check, routed, layout, edges, steps, ids, theme, rail, noMap]);
     // Play the step's beats: each moves its packets (and their data cards) along its edges, then the next step starts.
     useEffect(() => {
-        const gs = dots.current, cs = chips.current;
+        const gs = dots.current, cs = chips.current, edgeOf = Object.fromEntries(edges.map((e, i) => [ids[i], e]));
         if (clock.current.beats !== beats) {
             // A rail click can open another step at a later beat; start the clock at that beat, not at 0.
             const j = jump.current ?? 0;
             jump.current = null;
-            clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + (b.ms ?? speed), 0) };
+            clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + beatMs(b, speed), 0) };
             setBeat(j);
         }
-        if (!beats.length || (!noMap && !routed.length))
+        if (!beats.length || (!noMap && !routed.length && !(tl && !edges.length)))
             return;
         if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
             if (bar.current)
                 bar.current.style.transform = 'none';
             return void setBeat(beats.length - 1);
         }
-        const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + (b.ms ?? speed)], []);
-        const total = ends.at(-1) + speed * 1.5; // hold on the last beat before moving on
+        const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + beatMs(b, speed)], []);
+        const total = ends.at(-1) + STEP_HOLD_MS; // The figure holds on the last beat before the next step.
         let raf = 0, last = performance.now(), shownBeat = -1;
         const tick = (now) => {
             if (playingRef.current)
@@ -262,8 +296,9 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
             const i = next === -1 ? beats.length - 1 : next;
             if (i !== shownBeat)
                 setBeat((shownBeat = i));
+            setHolding(t >= ends.at(-1));
             const start = i ? ends[i - 1] : 0;
-            const f = Math.min(1, (t - start) / ((beats[i].ms ?? speed) * 0.8)); // arrive a little early, rest at the end
+            const f = Math.min(1, (t - start) / speed); // the packet crosses in `speed`; the hold gives the rest
             const eased = f < 0.5 ? 2 * f * f : 1 - (-2 * f + 2) ** 2 / 2;
             const hops = t < ends.at(-1) ? beats[i].hops : [];
             gs.forEach((g, j) => {
@@ -277,20 +312,56 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     return;
                 }
                 const pt = p.getPointAtLength((hops[j].back ? 1 - eased : eased) * p.getTotalLength());
+                const tone = hops[j].tone && TONES[hops[j].tone];
                 if (g) {
                     g.setAttribute('transform', `translate(${pt.x} ${pt.y})`);
                     g.style.opacity = '1';
+                    g.style.color = tone ?? v('accent');
                 }
                 if (c) {
+                    c.style.background = tone ? toneFill(tone) : v('accent');
                     c.style.transform = `translate(${pt.x}px, ${pt.y}px) translate(-50%, calc(-100% - 12px))`;
                     c.style.opacity = hops[j].data == null ? '0' : '1';
                 }
             });
+            // A box is active from the packet arrival to the end of the step hold. The tick toggles the class and skips React.
+            const arrived = new Map();
+            if (f >= 1)
+                for (const h of beats[i].hops) {
+                    const to = h.back ? edgeOf[h.edge]?.from : edgeOf[h.edge]?.to;
+                    arrived.set(to, arrived.get(to) ?? (h.tone && TONES[h.tone]));
+                }
+            // A focused box turns active at the beat start; in a timeline, when the today line arrives.
+            if (t - start >= (tl ? 400 * BASE_RATE : 0))
+                for (const id of beats[i].focus ?? [])
+                    if (!arrived.has(id))
+                        arrived.set(id, undefined);
+            root.current?.querySelectorAll('[data-fig]').forEach((n) => {
+                const on = arrived.has(n.dataset.fig ?? '');
+                if (on) {
+                    const tone = arrived.get(n.dataset.fig);
+                    if (tone)
+                        n.style.setProperty('--ff-hop', tone);
+                    else
+                        n.style.removeProperty('--ff-hop');
+                }
+                if (on === n.classList.contains(ACTIVE))
+                    return;
+                if (!on)
+                    return void n.classList.remove(ACTIVE); // the transition fades the box
+                // The box turns active at once: no transition while the class arrives.
+                const keep = n.style.transition;
+                n.style.transition = 'none';
+                n.classList.add(ACTIVE);
+                void n.offsetWidth;
+                n.style.transition = keep;
+            });
             raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
         return () => {
             cancelAnimationFrame(raf);
+            root.current?.querySelectorAll(`.${ACTIVE}`).forEach((n) => n.classList.remove(ACTIVE));
             gs.forEach((g) => g && (g.style.opacity = '0'));
             cs.forEach((c) => c && (c.style.opacity = '0'));
         };
@@ -304,15 +375,20 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         ? [edges[hoverEdgeIdx].from, edges[hoverEdgeIdx].to]
         : hover
             ? [hover]
-            : [...(step?.nodes ?? []), ...Object.keys(shown), ...(cur?.light ?? [])]);
+            : [...(step?.nodes ?? []), ...Object.keys(shown), ...(cur?.light ?? []), ...(cur?.focus ?? [])]);
     edges.forEach((e, i) => {
         if (litEdges.has(ids[i]))
             litNodes.add(e.from).add(e.to);
     });
+    // A toned hop colors its edge for its own beat only; the trail after it is the accent.
+    const hopTone = (edge) => {
+        const t = cur?.hops.find((h) => h.edge === edge && h.tone)?.tone;
+        return t && TONES[t];
+    };
     const goTo = (step, b) => {
         setPlaying(true);
         if (step === active) {
-            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + (x.ms ?? speed), 0);
+            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + beatMs(x, speed), 0);
             setBeat(b);
         }
         else {
@@ -322,7 +398,149 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     };
     const focus = hover != null || hoverEdge != null || step != null;
     const vars = Object.fromEntries(Object.entries(theme ?? {}).map(([k, val]) => [`--fig-${k}`, val]));
+    const timelineFig = useMemo(() => (tl ? timelineLayout({ layout, edges, timeline, today }, axisW) : null), [tl, layout, edges, timeline, today, axisW]);
+    // A bar or a milestone of a timeline: placed by the shared layout, with the look of a box.
+    const renderBar = (n, it) => {
+        const lit = litNodes.has(n.id);
+        const bt = n.tone && TONES[n.tone];
+        const label = String(n.label);
+        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: {
+                position: 'absolute',
+                left: it.x,
+                top: it.milestone ? top + (TL_BAR_H - it.w) / 2 : top,
+                width: it.w,
+                height: it.milestone ? it.w : TL_BAR_H,
+                boxSizing: 'border-box',
+                display: 'flex',
+                alignItems: 'center',
+                padding: it.milestone ? 0 : '0 calc(8px - var(--ff-b, 0px))',
+                color: v('fg'),
+                background: it.milestone ? undefined : bt ? toneTint(bt, v('bg')) : v('bg'),
+                border: it.milestone ? undefined : `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
+                ...(bt && { '--ff-box': bt }),
+                borderRadius: 6,
+                fontSize: 13,
+                fontWeight: 500,
+                whiteSpace: 'nowrap',
+                opacity: focus && !lit ? 0.7 : 1,
+                transition: 'border-color .4s, background .4s, box-shadow .4s, border-width .4s, padding .4s, opacity .25s',
+                cursor: 'default',
+            }, children: [it.milestone && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", style: { position: 'absolute', inset: 0, width: '100%', height: '100%', overflow: 'visible' }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: bt ? toneTint(bt, v('bg')) : v('bg'), stroke: bt ?? (lit ? v('accent') : v('border')), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .4s, fill .4s, stroke-width .4s' } }) })), inside ? _jsx("span", { style: { position: 'relative' }, children: label }) : outside] }, n.id));
+    };
     const renderItem = (item, depth) => {
+        if (timelineFig && item === layout) {
+            const lanesList = layout.children;
+            // The playhead follows the latest dated focus in the step, and rests at the last date before one and in the hold.
+            const focused = holding || still ? undefined : playheadItem(timelineFig.items, beats, beat);
+            const home = timelineFig.last ?? 0;
+            const at = focused ? focused.x + (focused.milestone ? focused.w / 2 : 0) : home;
+            const dateText = focused ? focused.date : timelineFig.lastDate;
+            const rowsPx = timelineFig.rows.map((r) => r * TL_BAR_H + (r - 1) * TL_ROW_GAP + LANE_PAD * 2);
+            return (_jsxs("div", { style: {
+                    display: 'grid',
+                    gridTemplateColumns: `max-content minmax(${TL_AXIS_W}px, 1fr) 18px`,
+                    // The axis strip sits over the gap above the first band, as in the SVG.
+                    gridTemplateRows: `${TL_AXIS_H - LANE_ROW_GAP}px ${rowsPx.map((h) => h + 'px').join(' ')}`,
+                    rowGap: LANE_ROW_GAP,
+                    position: 'relative',
+                }, children: [_jsxs("div", { "data-fig-axis": "", style: { gridColumn: '2 / 4', gridRow: 1, position: 'relative', height: TL_AXIS_H, alignSelf: 'start' }, children: [_jsx("div", { style: { position: 'absolute', left: 0, right: 0, top: TL_AXIS_H - 1, height: 1, background: v('border') } }), timelineFig.ticks.map((k) => (_jsxs(Fragment, { children: [_jsx("div", { style: { position: 'absolute', left: k.x, top: TL_AXIS_H - 5, width: 1, height: 4, background: v('border') } }), _jsx("div", { style: { position: 'absolute', left: k.x + 3, top: 0, fontSize: 11, lineHeight: '13px', color: v('muted') }, children: k.label })] }, k.x)))] }), lanesList.map((lane, li) => {
+                        const lit = lane.id != null && litNodes.has(lane.id);
+                        return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-lane": "", style: {
+                                        gridColumn: '1 / -1',
+                                        gridRow: li + 2,
+                                        background: v('surface'),
+                                        border: `1px solid ${lit ? v('accent') : v('border')}`,
+                                        boxShadow: lit ? glow : undefined,
+                                        transition: 'border-color .25s, box-shadow .25s',
+                                        borderRadius: 14,
+                                        zIndex: 0,
+                                    } }), _jsx("div", { style: {
+                                        gridColumn: 1,
+                                        gridRow: li + 2,
+                                        alignSelf: 'center',
+                                        zIndex: 1,
+                                        padding: '0 18px',
+                                        fontSize: 12,
+                                        fontWeight: 600,
+                                        letterSpacing: '.04em',
+                                        textTransform: 'uppercase',
+                                        color: v('muted'),
+                                    }, children: lane.label }), _jsx("div", { ref: li === 0 ? area : undefined, style: { gridColumn: 2, gridRow: li + 2, position: 'relative', zIndex: 1 }, children: timelineFig.items
+                                        .filter((it) => it.track === li)
+                                        .map((it) => renderBar(lane.children.find((k) => k.id === it.id), it)) })] }, lane.id ?? String(lane.label)));
+                    }), timelineFig.last != null && (_jsxs("div", { style: { gridColumn: '2 / 4', gridRow: '1 / -1', position: 'relative', zIndex: 2, pointerEvents: 'none' }, children: [timelineFig.today != null && (_jsxs("div", { "data-fig-today": "", style: { position: 'absolute', left: timelineFig.today, top: 12, bottom: 0, width: 0 }, children: [_jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, borderLeft: `1px dashed ${v('accent')}`, opacity: 0.6 } }), _jsx("span", { style: {
+                                            position: 'absolute',
+                                            right: 3,
+                                            top: -1,
+                                            fontSize: 11,
+                                            lineHeight: '11px',
+                                            fontWeight: 600,
+                                            color: v('accent'),
+                                        }, children: "today" })] })), _jsx("div", { "data-fig-playhead": "", style: {
+                                    position: 'absolute',
+                                    left: 0,
+                                    top: 12,
+                                    bottom: 0,
+                                    width: 1.5,
+                                    background: v('accent'),
+                                    transform: `translateX(${at}px)`,
+                                    transition: still ? 'none' : 'transform .4s linear',
+                                }, children: _jsx("span", { style: {
+                                        position: 'absolute',
+                                        left: 3,
+                                        top: dateLabelRaised(at, timelineFig.today, textWidth(dateText, 11), textWidth('today', 11)) ? -13 : -1,
+                                        fontSize: 11,
+                                        lineHeight: '11px',
+                                        fontWeight: 600,
+                                        whiteSpace: 'nowrap',
+                                        color: v('accent'),
+                                        animation: still ? undefined : 'flowfig-label .4s step-end',
+                                    }, children: dateText }, dateText) })] }))] }));
+        }
+        if (lanes && item === layout && isLanesLayout(layout)) {
+            const cols = laneColumns({ layout, edges, steps, lanes });
+            const n = Math.max(0, ...cols.values()) + 1;
+            return (_jsx("div", { style: {
+                    display: 'grid',
+                    gridTemplateColumns: `max-content repeat(${n}, max-content)`,
+                    columnGap: 0,
+                    rowGap: LANE_ROW_GAP,
+                    position: 'relative',
+                }, children: layout.children.map((lane, li) => {
+                    const lit = lane.id != null && litNodes.has(lane.id);
+                    return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-lane": "", style: {
+                                    gridColumn: '1 / -1',
+                                    gridRow: li + 1,
+                                    background: v('surface'),
+                                    border: `1px solid ${lit ? v('accent') : v('border')}`,
+                                    boxShadow: lit ? glow : undefined,
+                                    transition: 'border-color .25s, box-shadow .25s',
+                                    borderRadius: 14,
+                                    zIndex: 0,
+                                } }), _jsx("div", { style: {
+                                    gridColumn: 1,
+                                    gridRow: li + 1,
+                                    alignSelf: 'center',
+                                    zIndex: 1,
+                                    padding: '0 18px',
+                                    fontSize: 12,
+                                    fontWeight: 600,
+                                    letterSpacing: '.04em',
+                                    textTransform: 'uppercase',
+                                    color: v('muted'),
+                                }, children: lane.label }), lane.children.map((b) => (_jsx("div", { style: {
+                                    gridColumn: cols.get(b.id) + 2,
+                                    gridRow: li + 1,
+                                    alignSelf: 'center',
+                                    zIndex: 1,
+                                    // The last time column keeps the frame side, as in the SVG.
+                                    padding: `${LANE_PAD}px ${cols.get(b.id) === n - 1 ? 18 : LANE_GAP}px ${LANE_PAD}px 0`,
+                                }, children: renderItem(b, 1) }, b.id)))] }, lane.id ?? String(lane.label)));
+                }) }));
+        }
         if (isGroup(item)) {
             const lit = item.id != null && litNodes.has(item.id);
             const framed = item.label != null;
@@ -360,7 +578,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         const diamond = item.shape === 'decision';
         const store = item.shape === 'store';
         const card = carded.has(item.id);
-        return (_jsxs("div", { "data-fig": item.id, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
+        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: {
                 position: 'relative',
                 isolation: 'isolate',
                 minWidth: 100,
@@ -371,17 +590,20 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                 display: 'flex',
                 flexDirection: 'column',
                 justifyContent: 'center',
-                padding: diamond ? '22px 34px' : `${store ? 24 : 10}px ${card ? 10 : 16}px 10px`,
+                padding: diamond
+                    ? '22px 34px'
+                    : `calc(${store ? 24 : 10}px - var(--ff-b, 0px)) calc(${card ? 10 : 16}px - var(--ff-b, 0px)) calc(10px - var(--ff-b, 0px))`,
                 textAlign: 'center',
-                background: diamond ? undefined : v('bg'),
+                background: diamond ? undefined : bt ? toneTint(bt, v('bg')) : v('bg'),
                 color: v('fg'),
-                border: diamond ? undefined : `1px solid ${lit ? v('accent') : v('border')}`,
-                boxShadow: diamond ? undefined : lit ? glow : '0 1px 2px rgba(0,0,0,.06)',
+                border: diamond ? undefined : `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
+                ...(bt && { '--ff-box': bt }),
+                boxShadow: diamond ? undefined : '0 1px 2px rgba(0,0,0,.06)',
                 opacity: focus && !lit ? 0.7 : 1,
                 borderRadius: store ? '50% / 12px' : 10,
                 fontSize: 14,
                 fontWeight: 500,
-                transition: 'border-color .25s, box-shadow .25s, opacity .25s',
+                transition: 'border-color .4s, background .4s, box-shadow .4s, border-width .4s, padding .4s, opacity .25s',
                 cursor: 'default',
             }, children: [diamond && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", style: {
                         position: 'absolute',
@@ -390,7 +612,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: '100%',
                         overflow: 'visible',
                         zIndex: -1,
-                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: v('bg'), stroke: lit ? v('accent') : v('border'), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .25s' } }) })), store && (_jsx("div", { style: {
+                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: bt ? toneTint(bt, v('bg')) : v('bg'), stroke: bt ?? (lit ? v('accent') : v('border')), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .4s, fill .4s, stroke-width .4s' } }) })), store && (_jsx("div", { style: {
                         position: 'absolute',
                         top: -1,
                         left: -1,
@@ -398,8 +620,23 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: 24,
                         boxSizing: 'border-box',
                         borderRadius: '50%',
-                        border: `1px solid ${lit ? v('accent') : v('border')}`,
+                        border: `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
                         transition: 'border-color .25s',
+                    } })), item.mark && (_jsx("span", { "aria-hidden": true, style: {
+                        position: 'absolute',
+                        top: '50%',
+                        transform: 'translateY(-50%)',
+                        boxSizing: 'border-box',
+                        borderRadius: '50%',
+                        ...(item.mark === 'start'
+                            ? { left: -18, width: 10, height: 10, background: bt ?? v('accent') }
+                            : {
+                                right: -20,
+                                width: 14,
+                                height: 14,
+                                border: `1.5px solid ${bt ?? v('accent')}`,
+                                background: `radial-gradient(circle, ${bt ?? v('accent')} 0 4px, transparent 4.5px)`,
+                            }),
                     } })), _jsx("div", { children: item.label }), item.sub != null && _jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), marginTop: 2 }, children: item.sub }), card && (_jsxs("div", { style: {
                         marginTop: 8,
                         padding: '6px 8px',
@@ -452,7 +689,10 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     zIndex: 3,
                     width: 28,
                     height: 28,
-                }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@keyframes flowfig-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
+                }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@keyframes flowfig-label{from{opacity:0}to{opacity:0}}@keyframes flowfig-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' +
+                    // The active box has a 2 px border, a tint and a glow. The padding shrinks by 1 px. The box size stays the same, so the edges keep their route.
+                    `.${ACTIVE}:not([data-diamond]){--ff-b:1px;border-width:2px!important;background:color-mix(in srgb, ${hue} 10%, ${v('surface')})!important;box-shadow:${glow}!important;border-color:${hue}!important}` +
+                    `.${ACTIVE} polygon{fill:color-mix(in srgb, ${hue} 10%, ${v('surface')});stroke:${hue};stroke-width:2px}` }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
                         margin: full ? '-48px -24px 0' : '-20px -16px 0',
                         padding: full ? '48px 24px 24px' : '24px 16px',
                         borderRadius: full ? 0 : '16px 16px 0 0',
@@ -479,15 +719,18 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                         height: '100%',
                                         overflow: 'visible',
                                         pointerEvents: 'none',
-                                    }, children: [_jsx("defs", { children: ['off', 'on'].map((k) => (_jsx("marker", { id: `fig-arrow-${k}`, 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: k === 'on' ? v('accent') : v('muted') }) }, k))) }), routed.map((r) => {
+                                        // A timeline dependency runs under the bars (z-index 1) and over the bands (0).
+                                        zIndex: tl ? 0 : undefined,
+                                    }, children: [_jsx("defs", { children: ['off', 'on'].map((k) => (_jsx("marker", { id: `fig-arrow-${k}`, 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: "context-stroke" }) }, k))) }), routed.map((r) => {
                                             const on = litEdges.has(r.id);
+                                            const tone = hopTone(r.id);
                                             const hidden = !on && edges[ids.indexOf(r.id)].quiet;
                                             return (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
-                                                }, d: r.d, fill: "none", stroke: on ? 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' } }, r.id));
+                                                }, d: r.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' } }, r.id));
                                         }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsxs("g", { ref: (g) => {
                                                 dots.current[j] = g;
-                                            }, style: { opacity: 0 }, children: [_jsx("circle", { r: 10, fill: v('accent'), opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: v('accent') })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
+                                            }, style: { opacity: 0, color: v('accent') }, children: [_jsx("circle", { r: 10, fill: "currentColor", opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: "currentColor" })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
                                         chips.current[j] = c;
                                     }, style: {
                                         position: 'absolute',
@@ -508,9 +751,10 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                         transition: 'opacity .2s',
                                     }, children: cur?.hops[j]?.data }, j))), routed.map((r) => {
                                     const e = edges[ids.indexOf(r.id)];
-                                    if (e.label == null)
+                                    if (e.label == null || tl)
                                         return null;
                                     const on = litEdges.has(r.id);
+                                    const tone = hopTone(r.id);
                                     return (_jsx("div", { "data-fig-label": r.id, style: {
                                             position: 'absolute',
                                             left: r.mid.x,
@@ -522,9 +766,9 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                             borderRadius: 999,
                                             whiteSpace: 'nowrap',
                                             pointerEvents: 'none',
-                                            background: on ? v('accent') : v('bg'),
+                                            background: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'),
                                             color: on ? ON_ACCENT : v('muted'),
-                                            border: `1px solid ${on ? v('accent') : v('border')}`,
+                                            border: `1px solid ${on ? (tone ?? v('accent')) : v('border')}`,
                                             opacity: !on && e.quiet ? 0 : focus && !on ? 0.6 : 1,
                                             fontFamily: MONO,
                                             transition: 'background .25s, color .25s, opacity .25s',
@@ -565,16 +809,17 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                 (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;
-                            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 ? v('accent') : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
+                            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 tagW = ASYNC_TAG_W;
                                             // The tag sits on the tail side of the pill, so it never hides the arrowhead.
                                             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 ? v('accent') : v('bg'), stroke: on ? 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}`));
+                                        })(), 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 }) }), _jsx("div", { role: "tablist", style: {
+                    })(), _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: {
                                     display: 'inline-flex',
                                     gap: 2,
                                     padding: 3,
@@ -613,7 +858,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                                     transform: 'scaleX(0)',
                                                     opacity: playing ? 1 : 0.35,
                                                 } }))] }, i));
-                                }) }), _jsxs("button", { type: "button", "aria-label": `Speed ${rate}×, switch to ${rate === 1 ? 2 : 1}×`, title: "Playback speed", style: {
+                                }) })), _jsxs("button", { type: "button", "aria-label": `Speed ${rate}×, switch to ${rate === 1 ? 2 : 1}×`, title: "Playback speed", style: {
                                     ...iconBtn,
                                     width: 'auto',
                                     padding: '0 10px',

package/dist/init.d.ts

@@ -19,6 +19,11 @@ type Agent = {
     };
     /** Shown in place of the MCP file when init cannot write the config. */
     mcpNote?: string;
+    /** A second file, a marked section in a file the user owns. Written only in a repo run, never with `--global`. */
+    also?: {
+        file: string;
+        text: string;
+    };
 };
 export declare const MCP_ENTRY: {
     command: string;