flowfig 0.3.0 → 0.5.0

package/dist/model.js

@@ -1,4 +1,4 @@
-import { textWidth } from './text.js';
+import { textWidth, wrap } from './text.js';
 export const toBeat = (b) => {
     const isBeat = typeof b === 'object' && !Array.isArray(b) && !('edge' in b);
     const { edges, ...rest } = isBeat ? b : { edges: b };
@@ -53,18 +53,430 @@ export const readMs = (say) => {
 };
 /** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
 export const beatMs = (b, speed) => b.ms ?? speed + readMs(b.say);
+/** The item the playhead rests on at beat `i`: the first dated id in the latest focus up to `i`, or undefined for home. */
+export const playheadItem = (items, beats, i) => {
+    for (let k = Math.min(i, beats.length - 1); k >= 0; k--) {
+        const id = (beats[k].focus ?? []).find((f) => items.some((x) => x.id === f));
+        if (id != null)
+            return items.find((x) => x.id === id);
+    }
+    return undefined;
+};
+/** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
+export const outsideLabelRect = (bar, label) => ({
+    x: bar.x + bar.w + 6,
+    y: bar.y,
+    w: textWidth(label, 13),
+    h: bar.h,
+});
+/**
+ * The time span in which the playhead label shows its date. The label waits for the line to arrive: it stays hidden for
+ * the ramp (the move), so it never shows a date at a place that is not that date, and it never meets "today" on the way.
+ */
+export const labelSpan = (t0, end, ramp) => [Math.min(t0 + ramp, end), end];
+/** True if a playhead date label at x would overlap the "today" label, so it moves to the top row. Widths are in px. */
+export const dateLabelRaised = (x, today, w, todayW) => today != null && x + 3 < today - 3 && x + 3 + w > today - 3 - todayW;
 /** The hold at the end of each step, before the next step starts. */
 export const STEP_HOLD_MS = 2000;
 export const nodes = (g) => g.children.flatMap((c) => (isGroup(c) ? nodes(c) : [c]));
+/** Lane layout constants, shared by both renderers: the gap between time columns, the padding inside a lane, and the gap between lanes. */
+export const LANE_GAP = 56, LANE_PAD = 24, LANE_ROW_GAP = 20;
+/** True if the layout can draw as lanes: a `column` group whose every child is a labeled group with boxes only. */
+export const isLanesLayout = (g) => g.direction === 'column' && g.children.every((c) => isGroup(c) && c.label != null && c.children.every((k) => !isGroup(k)));
+/** True if `at` is a usable time column: an integer of 0 or more. */
+export const validAt = (at) => typeof at === 'number' && Number.isInteger(at) && at >= 0;
+/** The time column of each box in a lanes figure: its first appearance in the steps (from, then to; a back hop to, then from),
+ * then the boxes no step touches in layout order. `at` overrides. Two boxes may share a column. */
+export function laneColumns(fig) {
+    const byId = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    const cols = new Map();
+    const seen = (id) => {
+        if (!cols.has(id))
+            cols.set(id, cols.size);
+    };
+    for (const s of fig.steps ?? [])
+        for (const b of s.flow.map(toBeat))
+            for (const h of b.hops) {
+                const e = byId.get(h.edge);
+                if (!e)
+                    continue;
+                for (const id of h.back ? [e.to, e.from] : [e.from, e.to])
+                    seen(id);
+            }
+    for (const n of nodes(fig.layout))
+        seen(n.id);
+    for (const n of nodes(fig.layout))
+        if (validAt(n.at))
+            cols.set(n.id, n.at);
+    return cols;
+}
+/** The side of an SVG frame, and the width limits of a box with no card. The lane split measures with them. */
+export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
+/** The gap between two blocks of wrapped lanes. */
+export const LANE_BLOCK_GAP = 40;
+/** The length of a stub line between a box and its pill, the clear space past a pill, and the room a lane grows by for a pill. */
+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) {
+    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));
+}
+/** The room a diamond of size w by h gives a text line whose far edge sits `far` px from the center: the width of the outline there, less 8 px. */
+export const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
+/** The lines of a diamond with no card. The sub wraps to the room the outline gives its last line; the diamond grows taller by 15 px
+ * for each line until the lines fit. `dy` is the baseline of each line below the center, as the SVG draws it: the label sits 2 px
+ * above the center over a one-line sub, and 5 px below it with no sub. `far` is the distance from the center to the far edge of the text. */
+export function diamondLines(item, w) {
+    const sub = item.sub ? str(item.sub) : '';
+    for (let n = sub ? 1 : 0;; n++) {
+        const h = 62 + 15 * n;
+        const dy0 = n ? -2 - 7.5 * (n - 1) : 5;
+        const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
+        const last = n ? at(dy0 + 15 * n, 12) : 0;
+        const lines = n ? wrap(sub, diamondRoom(w, h, last), 12) : [];
+        if (lines.length <= n || n >= 6)
+            return {
+                h,
+                label: { dy: dy0, far: at(dy0, 14) },
+                subs: lines.map((text, k) => ({ text, dy: dy0 + 15 * (k + 1), far: at(dy0 + 15 * (k + 1), 12) })),
+            };
+    }
+}
+/** The lane copies (`laneIndex@block`) that hold a stub end with no place clear of every edge path. A renderer grows each by
+ * STUB_ROOM and routes again: the pill then fits under or over its box, inside the band. Both renderers call it with their routes. */
+export function tightCopies(lanes, ends, edges, routed) {
+    const laneOf = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
+    const out = new Set();
+    for (const r of routed) {
+        const e = edges.find((x) => edgeId(x) === r.id);
+        const [fb, tb] = ends.get(r.id) ?? [];
+        if (!e || !r.stub)
+            continue;
+        if (r.stub.tight[0] && fb != null)
+            out.add(`${laneOf(e.from)}@${fb}`);
+        if (r.stub.tight[1] && tb != null)
+            out.add(`${laneOf(e.to)}@${tb}`);
+    }
+    return out;
+}
+/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
+export const laneGutter = (lanes) => Math.max(0, ...lanes.map((l) => textWidth(str(l.label).toUpperCase(), 12))) + FRAME_SIDE * 2;
+/** The block of a time column, from the block starts of a plan. */
+export const laneBlock = (starts, c) => {
+    let k = 0;
+    while (k < starts.length - 2 && c >= starts[k + 1])
+        k++;
+    return k;
+};
+/** The pill texts of a cross-block edge: "label → Target" at the source, "from Source" at the target, and "→ Target", a
+ * shorter source text for a pill that has no place for the long one. */
+export const stubTexts = (label, from, to) => [
+    `${str(label) ? str(label) + ' ' : ''}→ ${str(to)}`,
+    `from ${str(from)}`,
+    ...(str(label) ? [`→ ${str(to)}`] : []),
+];
+/**
+ * The wrap of a lanes figure. If all the time columns do not fit `width` with text at `minText` or more, the lanes wrap like a
+ * line of text: block 1 holds columns 0..n-1, block 2 holds n..2n-1. n is the largest count that fits; it is 1 at least.
+ * The text test is the one `check` runs: the smallest text (11 px, or 10.5 px with a mono card row) times width / figure width.
+ * If the wrap cannot make the text readable, the lanes do not wrap: the smallest font is under `minText`, or `floor` (the least
+ * width of the rest of the figure, such as the rail) is already too wide.
+ * The blocks share the columns as evenly as they can, and a block holds 2 columns at least: if 2 do not fit, the lanes keep
+ * one block. An edge between two blocks becomes two stubs with pills. A pill takes no room of its own, so n depends on the boxes.
+ */
+export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor = 0 } = {}) {
+    const cols = laneColumns(fig);
+    const n = Math.max(-1, ...cols.values()) + 1;
+    const shown = (fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => Object.entries(toBeat(b).show ?? {})));
+    const carded = new Set(shown.map(([id]) => id));
+    const mono = shown.some(([, c]) => isRows(c) && c.some((r) => r.mono));
+    const colW = Array.from({ length: n }, () => 0);
+    const byId = new Map(nodes(fig.layout).map((b) => [b.id, b]));
+    for (const b of byId.values()) {
+        const c = cols.get(b.id);
+        colW[c] = Math.max(colW[c], nodeWidth(b, carded.has(b.id)) + (b.shape === 'decision' ? 70 : 0));
+    }
+    const font = mono ? 10.5 : 11;
+    const limit = (width * font) / minText;
+    const room = limit - padding * 2;
+    const lanes = fig.layout.children;
+    const laneOf = new Map(lanes.filter((l) => l.id != null).map((l) => [l.id, l]));
+    const gutter = laneGutter(lanes);
+    const plan = (count) => {
+        // count blocks share the n columns evenly; the first n % count blocks take one column more.
+        const starts = [0];
+        for (let k = 0; k < count; k++)
+            starts.push(starts[k] + Math.floor(n / count) + (k < n % count ? 1 : 0));
+        const colBlock = (c) => laneBlock(starts, c);
+        const blockOf = (id) => colBlock(cols.get(id));
+        const held = [...new Set([...byId.keys()].map(blockOf))].sort((a, b) => a - b);
+        const blocks = held.length ? held : [0];
+        const wrapped = blocks.length > 1;
+        // The blocks that show a lane: a wrapped block shows only the lanes with a box in it.
+        const showing = (l) => wrapped ? [...new Set(l.children.map((b) => blockOf(b.id)))].sort((a, b) => a - b) : blocks;
+        const stubs = new Map();
+        const ends = new Map();
+        const lost = [];
+        fig.edges.forEach((e) => {
+            const id = edgeId(e);
+            const [fl, tl] = [laneOf.get(e.from), laneOf.get(e.to)];
+            if (!(byId.has(e.from) || fl) || !(byId.has(e.to) || tl))
+                return;
+            // A lane source takes the last block at or before the target that shows it; a lane target the first at or after the source.
+            let miss = false;
+            const near = (l, k, after) => {
+                const ks = showing(l);
+                const hit = after ? ks.find((b) => b >= k) : ks.findLast((b) => b <= k);
+                if (hit != null)
+                    return hit;
+                miss = true;
+                return after ? ks.at(-1) : ks[0];
+            };
+            let fb, tb;
+            if (!fl)
+                fb = blockOf(e.from);
+            if (!tl)
+                tb = blockOf(e.to);
+            if (fl && tl)
+                fb = showing(fl)[0];
+            if (fl && !tl)
+                fb = near(fl, tb, false);
+            if (tl)
+                tb = near(tl, fb, true);
+            if (fb == null || tb == null)
+                return void (wrapped && lost.push(id));
+            if (miss)
+                lost.push(id);
+            ends.set(id, [fb, tb]);
+            if (fb === tb)
+                return;
+            const texts = stubTexts(e.label, (byId.get(e.from) ?? fl).label, (byId.get(e.to) ?? tl).label);
+            stubs.set(id, texts);
+        });
+        // A pill takes no room of its own: the route puts it in free space (route() in geometry.ts), so n depends on the boxes only.
+        // A label on an edge between two next columns of one block sits in the gap between them. A label too wide for the gap would
+        // cover a box, so that gap grows to the label plus 8 px. A label that fits keeps the gap of 0.4.0.
+        const label = Array.from({ length: n }, () => 0);
+        for (const e of fig.edges) {
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            if (e.label == null || a == null || b == null || Math.abs(a - b) !== 1 || colBlock(a) !== colBlock(b))
+                continue;
+            const w = labelPillW(str(e.label));
+            if (w - 2 > LANE_GAP)
+                label[Math.min(a, b)] = Math.max(label[Math.min(a, b)], w + 8);
+        }
+        const gaps = colW.map((_, c) => (c === starts[colBlock(c) + 1] - 1 ? FRAME_SIDE : Math.max(LANE_GAP, label[c])));
+        const per = Math.max(...starts.slice(1).map((e, k) => e - starts[k]));
+        const lead = Array.from({ length: count }, () => 0);
+        // A pill takes free room only: a gap next to a stub end grows for its pill while the block still fits the width. So the
+        // block count never depends on a pill. A pill with no room finds a free place in route() (geometry.ts).
+        const want = (text) => STUB + labelPillW(text) + STUB_CLEAR;
+        const fit = blocks.every((k) => widthOf(starts[k], starts[k + 1], gaps, 0) <= room);
+        const out = new Map(), inn = new Map();
+        const roomOut = new Set(), roomIn = new Set();
+        for (const [id, texts] of stubs) {
+            const e = fig.edges.find((x) => edgeId(x) === id);
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            if (a != null)
+                out.set(a, Math.max(out.get(a) ?? 0, want(texts[0])));
+            if (b != null)
+                inn.set(b, Math.max(inn.get(b) ?? 0, want(texts[1])));
+        }
+        for (const k of blocks) {
+            const [c0, end] = [starts[k], starts[k + 1]];
+            let free = room - widthOf(c0, end, gaps, 0);
+            const grow = (extra, apply) => {
+                if (extra > 0 && extra <= free) {
+                    free -= extra;
+                    apply();
+                }
+            };
+            grow(inn.get(c0) ?? 0, () => (lead[k] = inn.get(c0)));
+            if (!inn.has(c0) || lead[k])
+                roomIn.add(c0);
+            for (let c = c0; c < end; c++) {
+                const need = (out.get(c) ?? 0) + (c < end - 1 ? (inn.get(c + 1) ?? 0) : 0);
+                grow(need - gaps[c], () => (gaps[c] = need));
+                if (gaps[c] >= need)
+                    roomOut.add(c).add(-1 - (c + 1)); // -1 - c marks room before column c
+            }
+        }
+        // A stub end with no room beside its box makes its lane taller in that block: the pill then fits under the box, inside the band.
+        const laneIndex = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
+        const tall = new Set();
+        for (const [id] of stubs) {
+            const e = fig.edges.find((x) => edgeId(x) === id);
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            const [fb, tb] = ends.get(id);
+            if (a == null || !roomOut.has(a))
+                tall.add(`${laneIndex(e.from)}@${fb}`);
+            if (b == null || !(b === starts[tb] ? roomIn.has(b) : roomOut.has(-1 - b)))
+                tall.add(`${laneIndex(e.to)}@${tb}`);
+        }
+        const laneOfBox = new Map(lanes.flatMap((l) => l.children.map((b) => [b.id, l])));
+        const around = new Set(fig.edges
+            .filter((e) => {
+            const [a, b, l] = [cols.get(e.from), cols.get(e.to), laneOfBox.get(e.from)];
+            if (e.around || a == null || b == null || !l || l !== laneOfBox.get(e.to) || colBlock(a) !== colBlock(b))
+                return false;
+            return l.children.some((x) => cols.get(x.id) > Math.min(a, b) && cols.get(x.id) < Math.max(a, b));
+        })
+            .map(edgeId));
+        return [{ cols, starts, per, blocks, gutter, gaps, lead, ends, stubs, around, tall, lost }, fit];
+    };
+    const widthOf = (c, end, gaps, lead) => gutter + lead + colW.slice(c, end).reduce((a, w) => a + w, 0) + gaps.slice(c, end).reduce((a, g) => a + g, 0);
+    // The wrap only narrows the lanes. If the text stays too small at any width, keep one block, and check reports small-text.
+    if (font < minText || floor > limit)
+        return plan(1)[0];
+    // A block has 2 columns at least: one column per block reads as a list, not as lanes. If 2 do not fit, keep one block.
+    // The fit uses the boxes and the label gaps only, before a pill takes free room.
+    for (let count = 1; count <= Math.max(1, Math.floor(n / 2)); count++) {
+        const [p, fit] = plan(count);
+        if (fit)
+            return p;
+    }
+    return plan(1)[0];
+}
+/**
+ * The rect id that an edge end routes to in wrapped lanes. A box keeps its id. A lane has one band per block, so a lane end names
+ * the band in the block from the plan (`band` finds it). A stub end at a lane is a point inside that band: the source at the band
+ * end, past the room for its pill, and the target at the first column of the block. The function adds the rect it names to `rects`.
+ */
+export function laneEnd(plan, edge, id, start, band, rects) {
+    const k = plan.ends.get(edge)?.[start ? 0 : 1];
+    const b = k == null ? undefined : band(id, k);
+    if (plan.blocks.length < 2 || plan.cols.has(id) || !b)
+        return id;
+    const texts = plan.stubs.get(edge);
+    const key = texts ? `${edge}@${start ? 's' : 't'}` : `${id}@${k}`;
+    const x = start ? b.x + b.w - (STUB + labelPillW(texts?.[0] ?? '') + STUB_CLEAR) : b.x + plan.gutter + plan.lead[k];
+    rects[key] = texts ? { x, y: b.y, w: 0, h: b.h } : b;
+    return key;
+}
+/** Timeline constants, shared by both renderers: the bar height, the gap between rows, the least bar width, the milestone width,
+ * the axis strip height and the axis width of the SVG. */
+export const TL_BAR_H = 28, TL_ROW_GAP = 8, TL_MIN_BAR = 24, TL_DIAMOND = 14, TL_AXIS_H = 28, TL_AXIS_W = 640;
+/** The days since 1970-01-01 (UTC) of a YYYY-MM-DD date. It is null for any other text and for a date that does not exist. */
+export const dayOf = (iso) => {
+    const m = typeof iso === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso) : null;
+    if (!m)
+        return null;
+    const t = Date.UTC(+m[1], +m[2] - 1, +m[3]);
+    return new Date(t).toISOString().slice(0, 10) === iso ? t / 86400000 : null;
+};
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const dateOf = (day) => new Date(day * 86400000);
+// Day 0 is a Thursday, so this is 0 for Monday and 6 for Sunday.
+const weekday = (day) => (((day + 3) % 7) + 7) % 7;
+/** The ISO 8601 week number of a day: the week of the year's first Thursday is week 1. */
+const isoWeek = (day) => {
+    const thu = day - weekday(day) + 3;
+    const jan1 = Date.UTC(dateOf(thu).getUTCFullYear(), 0, 1) / 86400000;
+    return Math.floor((thu - jan1) / 7) + 1;
+};
+/** The boxes with a real `from`, in layout order, with their track (the index of the top-level child) and their days.
+ * A `to` that is not a date, or is before `from`, makes the box a milestone; `checkSpec` reports it. */
+const datedItems = (fig) => {
+    const out = [];
+    fig.layout.children.forEach((c, track) => nodes(isGroup(c) ? c : { children: [c] }).forEach((n) => {
+        const from = n.from == null ? null : dayOf(n.from);
+        if (from == null)
+            return;
+        const to = n.to == null ? null : dayOf(n.to);
+        out.push({ id: n.id, track, from, to: to != null && to >= from ? to : null, label: n });
+    }));
+    return out;
+};
+/** Where each dated item, tick and the today line sit on the axis, `axisWidth` px wide. Both renderers call it. */
+export function timelineLayout(fig, axisWidth) {
+    const items = datedItems(fig);
+    const today = fig.today == null ? null : dayOf(fig.today);
+    const days = [...items.flatMap((i) => [i.from, i.to ?? i.from]), ...(today == null ? [] : [today])];
+    const first = days.length ? Math.min(...days) : 0;
+    const last = days.length ? Math.max(...days) : 0;
+    const start = first - weekday(first);
+    let end = last + (6 - weekday(last));
+    const px = (day) => ((day - start) / (end - start + 1)) * axisWidth;
+    // A label right of the last items may pass the axis end. Add whole weeks and lay out again; after 4 passes the label stays and `check` reports it.
+    for (let pass = 0; pass < 4; pass++) {
+        const over = Math.max(0, ...items.map((i) => {
+            const x = i.to != null ? px(i.from) : px(i.from) - TL_DIAMOND / 2;
+            const w = i.to != null ? Math.max(TL_MIN_BAR, px(i.to + 1) - px(i.from)) : TL_DIAMOND;
+            const need = textWidth(str(i.label.label), 13);
+            return i.to != null && need + 16 <= w ? 0 : x + w + 6 + need - axisWidth;
+        }));
+        if (over <= 0)
+            break;
+        end += Math.ceil(over / (axisWidth / (end - start + 1)) / 7) * 7;
+    }
+    const ticks = [];
+    if ((end - start + 1) / 7 <= 16)
+        for (let d = start; d <= end; d += 7)
+            ticks.push({ x: px(d), label: `W${isoWeek(d)}` });
+    else
+        for (let d = start; d <= end; d++)
+            if (dateOf(d).getUTCDate() === 1)
+                ticks.push({ x: px(d), label: MONTHS[dateOf(d).getUTCMonth()] });
+    const rows = fig.layout.children.map(() => 1);
+    const placed = [];
+    const busy = fig.layout.children.map(() => []); // per track: the px end of the latest item in each row, with its label
+    const GAP = 8; // the least px between two items in a row
+    for (const i of [...items].sort((a, b) => a.from - b.from)) {
+        const bar = i.to != null;
+        const x = bar ? px(i.from) : px(i.from) - TL_DIAMOND / 2;
+        const w = bar ? Math.max(TL_MIN_BAR, px(i.to + 1) - px(i.from)) : TL_DIAMOND;
+        const need = textWidth(str(i.label.label), 13);
+        const labelInside = bar && need + 16 <= w;
+        let row = busy[i.track].findIndex((until) => until + GAP <= x);
+        if (row < 0)
+            row = busy[i.track].length;
+        busy[i.track][row] = labelInside ? x + w : x + w + 6 + need;
+        rows[i.track] = Math.max(rows[i.track], row + 1);
+        placed.push({ id: i.id, track: i.track, row, x, w, milestone: !bar, labelInside, date: fmt(i.from) });
+    }
+    // Keep the layout order in the result.
+    const order = new Map(items.map((i, k) => [i.id, k]));
+    placed.sort((a, b) => order.get(a.id) - order.get(b.id));
+    return {
+        start,
+        end,
+        ticks,
+        items: placed,
+        rows,
+        today: items.length && today != null ? px(today) : null,
+        last: items.length ? px(last) : null,
+        lastDate: fmt(last),
+    };
+}
+const fmt = (d) => `${dateOf(d).getUTCDate()} ${MONTHS[dateOf(d).getUTCMonth()]}`;
+/** One step, "timeline", with one beat for each dated item in date order. The beat lights the item and says "label, d MMM to d MMM" (a milestone: "label, d MMM"), then " · sub". */
+export function timelineBeats(fig) {
+    const items = datedItems(fig).sort((a, b) => a.from - b.from);
+    const flow = items.map((i, k) => ({
+        focus: [i.id],
+        light: items.slice(0, k + 1).map((p) => p.id),
+        say: `${str(i.label.label)}, ${fmt(i.from)}${i.to != null ? ` to ${fmt(i.to)}` : ''}${i.label.sub != null ? ` · ${str(i.label.sub)}` : ''}`,
+    }));
+    return [{ label: 'timeline', flow }];
+}
 const labeledGroups = (g) => (g.label ? 1 : 0) + g.children.reduce((n, c) => n + (isGroup(c) ? labeledGroups(c) : 0), 0);
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
-export const counts = (p) => ({
-    boxes: nodes(p.layout).length,
-    groups: labeledGroups(p.layout),
-    edges: p.edges.length,
-    steps: (p.steps ?? []).length,
-    messages: (p.steps ?? []).reduce((n, s) => n + s.flow.reduce((m, b) => m + toBeat(b).hops.length, 0), 0),
-});
+export const counts = (p) => {
+    // A timeline with no steps plays one synthetic step.
+    const st = p.timeline && isLanesLayout(p.layout) && !p.steps?.length ? timelineBeats(p) : (p.steps ?? []);
+    return {
+        boxes: nodes(p.layout).length,
+        groups: labeledGroups(p.layout),
+        edges: p.edges.length,
+        steps: st.length,
+        messages: st.reduce((n, s) => n + s.flow.reduce((m, b) => m + toBeat(b).hops.length, 0), 0),
+    };
+};
 /** Every id inside a child: its own id, and the ids of all boxes and groups below it. */
 const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
 /**

package/dist/open.d.ts

@@ -0,0 +1,15 @@
+export type Opener = {
+    cmd: string;
+    args: string[];
+    verbatim: boolean;
+};
+/** The command that opens a file in the default program of the system. Pure. */
+export declare function openerFor(platform: NodeJS.Platform, file: string): Opener;
+/** The name of the temp page: the SVG base name, each character other than a letter, a digit, - or _ as -. */
+export declare function pageName(svgPath: string): string;
+/** The line that `open`, a render with `--open` and `draw --open` print. */
+export declare const openedLine: (page: string) => string;
+/** Write the page to a new temp folder (and to `html`, if given), then start the opener. Returns the written paths. */
+export declare function openSvg(svgPath: string, html?: string): Promise<string[]>;
+/** `flowfig open`: parse argv, call openSvg, print. Returns the exit code. */
+export declare function runOpen(argv: string[]): Promise<number>;

package/dist/open.js

@@ -0,0 +1,82 @@
+// `flowfig open`: show a figure in the default browser. An .svg file often opens in an editor; an .html page opens in a browser.
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { pageHtml } from './page.js';
+const USAGE = 'usage: flowfig open <figure.svg> [--html <path>]';
+/** The command that opens a file in the default program of the system. Pure. */
+export function openerFor(platform, file) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [file], verbatim: false };
+    // `start` reads its first quoted argument as a window title, so an empty title goes first.
+    if (platform === 'win32')
+        return { cmd: 'cmd', args: ['/c', 'start', '""', `"${file}"`], verbatim: true };
+    return { cmd: 'xdg-open', args: [file], verbatim: false };
+}
+/** The name of the temp page: the SVG base name, each character other than a letter, a digit, - or _ as -. */
+export function pageName(svgPath) {
+    // The safe name also keeps cmd metacharacters such as & out of the Windows command line.
+    return (basename(svgPath)
+        .replace(/\.svg$/, '')
+        .replace(/[^\w-]/g, '-') + '.html');
+}
+/** The line that `open`, a render with `--open` and `draw --open` print. */
+export const openedLine = (page) => `${page} — opened in the default browser`;
+/** Write the page to a new temp folder (and to `html`, if given), then start the opener. Returns the written paths. */
+export async function openSvg(svgPath, html) {
+    const page = pageHtml(readFileSync(svgPath, 'utf8'), basename(svgPath));
+    // A fresh private folder (mode 0700): a fixed shared path lets another user plant a symlink there.
+    const dir = mkdtempSync(join(tmpdir(), 'flowfig-open-'));
+    // The page stays after the exit: the browser reads it after the CLI stops.
+    const temp = join(dir, pageName(svgPath));
+    writeFileSync(temp, page);
+    if (html)
+        writeFileSync(html, page);
+    // FLOWFIG_OPENER replaces the system opener, so the tests start no browser.
+    const o = process.env.FLOWFIG_OPENER
+        ? { cmd: process.env.FLOWFIG_OPENER, args: [temp], verbatim: false }
+        : openerFor(process.platform, temp);
+    await new Promise((resolve, reject) => {
+        const child = spawn(o.cmd, o.args, { detached: true, windowsHide: true, stdio: 'ignore', windowsVerbatimArguments: o.verbatim });
+        child.once('spawn', () => (child.unref(), resolve()));
+        child.once('error', (e) => reject(new Error(`${e.message}. Open ${temp} in a browser.`)));
+    });
+    return html ? [temp, html] : [temp];
+}
+/** `flowfig open`: parse argv, call openSvg, print. Returns the exit code. */
+export async function runOpen(argv) {
+    const fail = (message, code) => (console.error(message), code);
+    const args = [...argv];
+    let html;
+    const at = args.indexOf('--html');
+    if (at !== -1) {
+        html = args.splice(at, 2)[1];
+        if (!html || html.startsWith('-'))
+            return fail('--html needs a path', 2);
+    }
+    const bad = args.find((a) => a.startsWith('-'));
+    if (bad)
+        return fail(`unknown flag ${bad}`, 2);
+    const [path] = args;
+    if (!path)
+        return fail(USAGE, 2);
+    if (!path.endsWith('.svg'))
+        return fail(`${path}: expected a .svg path`, 2);
+    try {
+        readFileSync(path);
+    }
+    catch (e) {
+        return fail(`${path}: ${e.message}`, 2);
+    }
+    try {
+        const [page, copy] = await openSvg(path, html);
+        console.log(openedLine(page));
+        if (copy)
+            console.log(copy);
+        return 0;
+    }
+    catch (e) {
+        return fail(`open: ${e.message}`, 1);
+    }
+}

package/dist/page.d.ts

@@ -0,0 +1,2 @@
+/** The page: the figure SVG inline, centered, scaled down to the window width. The title is escaped. */
+export declare function pageHtml(svg: string, title: string): string;

package/dist/page.js

@@ -0,0 +1,16 @@
+// The page that holds a figure SVG: `flowfig open` shows it in the default browser, and `flowfig gif` captures it. Pure.
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** The page: the figure SVG inline, centered, scaled down to the window width. The title is escaped. */
+export function pageHtml(svg, title) {
+    // Element selectors only: the figure styles use class names, so the two sets of rules do not meet.
+    return `<!doctype html>
+<meta charset="utf-8">
+<title>${esc(title)}</title>
+<style>
+:root { color-scheme: light dark }
+body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: Canvas }
+svg { display: block; max-width: 100%; height: auto }
+</style>
+${svg}
+`;
+}

package/dist/picker.d.ts

@@ -0,0 +1,33 @@
+export type PickRow = {
+    id: string;
+    name: string;
+    detected: boolean;
+    files: string[];
+};
+export type PickState = {
+    rows: PickRow[];
+    sel: Set<string>;
+    mcp: boolean;
+    cursor: number;
+};
+export type Key = {
+    name?: string;
+    ctrl?: boolean;
+    sequence?: string;
+};
+export type Screen = {
+    color: boolean;
+    width: number;
+};
+export type Picked = {
+    ids: Set<string>;
+    mcp: boolean;
+};
+/** The banner lines. A terminal narrower than the banner gets the plain version line. */
+export declare function banner({ color, width }: Screen): string[];
+/** The picker screen, one string per line. */
+export declare function screen(s: PickState, o: Screen): string[];
+/** One key press. Returns the next state, or `confirm` or `cancel`. */
+export declare function keyStep(s: PickState, k: Key): PickState | 'confirm' | 'cancel';
+/** Run the picker on the terminal. Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
+export declare function runPicker(rows: PickRow[], start: Set<string>, mcp: boolean): Promise<Picked | undefined | 'fallback'>;