flowfig 0.2.0 → 0.4.0

package/dist/init.js

@@ -1,9 +1,10 @@
 // `flowfig init`: write flowfig instructions for the coding agents of a repo. Pure functions where possible, so the tests need no TTY.
 import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { AGENT_TEXT, SKILL_DESCRIPTION } from './guide.js';
+import { runPicker } from './picker.js';
 const START = '<!-- flowfig:start -->';
 const END = '<!-- flowfig:end -->';
 export const MCP_ENTRY = { command: 'npx', args: ['flowfig', 'mcp'] };
@@ -15,6 +16,10 @@ export const AGENTS = [
         file: '.claude/skills/figure/SKILL.md',
         kind: 'whole',
         mcp: { file: '.mcp.json', key: 'mcpServers', type: true, global: '.claude.json' },
+        also: {
+            file: 'CLAUDE.md',
+            text: '## Diagrams\nDraw every diagram with the `figure` skill (flowfig). The user can run `/figure <question>`. Do not answer a diagram request with a Mermaid block or ASCII art, unless the user asks for that tool.',
+        },
         head: `---\nname: figure\ndescription: ${JSON.stringify(SKILL_DESCRIPTION)}\nuser_invocable: true\n---\n\n`,
     },
     { id: 'agents', name: 'AGENTS.md', marks: ['AGENTS.md'], file: 'AGENTS.md', kind: 'section', note: 'Codex, Amp, Jules, ...' },
@@ -87,12 +92,16 @@ export function renderList(selected, detected, dir) {
         'Type numbers to toggle (for example "1 3"), Enter to write, q to quit.',
     ].join('\n');
 }
-const block = () => `${START}\n${AGENT_TEXT.trimEnd()}\n${END}\n`;
+const block = (text = AGENT_TEXT) => `${START}\n${text.trimEnd()}\n${END}\n`;
 /** The new file text, or `undefined` if the file belongs to the user and init must leave it. `old` is `undefined` for a missing file. */
 export function place(a, old) {
     const mine = block();
     if (a.kind === 'whole')
         return old === undefined || old.includes(START) ? `${a.head ?? ''}${mine}` : undefined;
+    return section(old, mine);
+}
+/** `old` with the marked block `mine` added or replaced. `undefined` if the block is open. */
+function section(old, mine) {
     if (old === undefined)
         return mine;
     const s = old.indexOf(START), e = old.indexOf(END, s);
@@ -124,12 +133,17 @@ export function registerMcp(a, old) {
     json[a.mcp.key] = { ...servers, flowfig: entry };
     return JSON.stringify(json, null, 2) + '\n';
 }
+/** `✓ ` before a finished write. */
+const mark = (status) => (/^(created|updated|unchanged)$/.test(status) ? '✓ ' : '');
+/** The path to show: relative to the repo folder, or `~` for the home folder. */
+const shown = (path, base, global) => (global ? `~/${relative(base, path)}` : relative(base, path));
 const HINT = 'run with -y or --agents <ids>';
 /** Run `flowfig init`. Returns the exit code. */
 export async function runInit(argv) {
     const args = [...argv];
     const flag = (n, ...alias) => [n, ...alias].some((x) => args.includes(x) && args.splice(args.indexOf(x), 1).length > 0);
-    const listAgents = flag('--list-agents'), all = flag('--all-agents'), yes = flag('-y', '--yes'), global = flag('--global'), dry = flag('--dry-run'), noMcp = flag('--no-mcp');
+    const listAgents = flag('--list-agents'), all = flag('--all-agents'), yes = flag('-y', '--yes'), global = flag('--global'), dry = flag('--dry-run');
+    let noMcp = flag('--no-mcp');
     let ids;
     const at = args.indexOf('--agents');
     if (at !== -1)
@@ -165,30 +179,50 @@ export async function runInit(argv) {
         return fail(HINT);
     }
     else {
-        const picked = await pick(auto, detected, dir);
-        if (!picked)
+        const rows = AGENTS.map((a) => ({
+            id: a.id,
+            name: a.name,
+            detected: detected.includes(a.id),
+            files: [...new Set([a.file, a.also?.file, a.mcp?.file].filter((f) => !!f))],
+        }));
+        const got = await runPicker(rows, auto, !noMcp);
+        if (got === 'fallback') {
+            const picked = await pick(auto, detected, dir);
+            if (!picked)
+                return 0;
+            chosen = picked;
+        }
+        else if (!got)
             return 0;
-        chosen = picked;
+        else {
+            chosen = got.ids;
+            noMcp = !got.mcp;
+        }
     }
     for (const a of AGENTS.filter((x) => chosen.has(x.id))) {
-        const path = global ? join(homedir(), a.file) : join(dir, a.file);
-        const old = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
-        const next = place(a, old);
-        let status;
-        if (next === undefined)
-            status = old?.includes(START) ? 'skipped (flowfig:start without flowfig:end)' : 'skipped (the file exists and is not from flowfig)';
-        else if (next === old)
-            status = 'unchanged';
-        else {
-            status = old === undefined ? 'created' : 'updated';
-            if (dry)
-                status = `would ${status === 'created' ? 'create' : 'update'}`;
+        const files = [{ file: a.file, place: (o) => place(a, o) }];
+        if (a.also && !global)
+            files.push({ file: a.also.file, place: (o) => section(o, block(a.also.text)) });
+        for (const f of files) {
+            const path = global ? join(homedir(), f.file) : join(dir, f.file);
+            const old = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+            const next = f.place(old);
+            let status;
+            if (next === undefined)
+                status = old?.includes(START) ? 'skipped (flowfig:start without flowfig:end)' : 'skipped (the file exists and is not from flowfig)';
+            else if (next === old)
+                status = 'unchanged';
             else {
-                mkdirSync(dirname(path), { recursive: true });
-                writeFileSync(path, next);
+                status = old === undefined ? 'created' : 'updated';
+                if (dry)
+                    status = `would ${status === 'created' ? 'create' : 'update'}`;
+                else {
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, next);
+                }
             }
+            console.log(`${mark(status)}${status.padEnd(9)} ${shown(path, global ? homedir() : dir, global)}`);
         }
-        console.log(`${status.padEnd(9)} ${path}`);
         if (noMcp)
             continue;
         if (a.mcpNote) {
@@ -227,8 +261,10 @@ export async function runInit(argv) {
                 }
             }
         }
-        console.log(`${mcpStatus.padEnd(9)} ${mcpPath}`);
+        console.log(`${mark(mcpStatus)}${mcpStatus.padEnd(9)} ${shown(mcpPath, global ? homedir() : dir, global)}`);
     }
+    if (!dry)
+        console.log(`Next: start a new agent session.${chosen.has('claude') ? ' In Claude Code, run /figure how does login work.' : ''}`);
     return 0;
 }
 function fail(message) {

package/dist/model.d.ts

@@ -13,6 +13,16 @@ export type FigNode = {
     lines?: number;
     /** Width in px. Overrides the width the layout picks. */
     width?: number;
+    /** In a `lanes` figure: the time column of the box, 0-based. Default: the box's first appearance in the steps. */
+    at?: number;
+    /** In a `timeline` figure: the start of the item, or the date of a milestone, as YYYY-MM-DD. */
+    from?: string;
+    /** In a `timeline` figure: the last day of the item, as YYYY-MM-DD. The day counts. Without it the box is a milestone. */
+    to?: string;
+    /** A permanent state color for the box, such as a failing part. It gives a 1 px border and a light tint. An arrival with no hop tone uses it too. */
+    tone?: FigTone;
+    /** A lifecycle mark: `start` draws a filled dot before the box, `end` a ringed dot after it. No layout change. */
+    mark?: 'start' | 'end';
     /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
     source?: string;
 };
@@ -56,6 +66,8 @@ export type FigHop = string | {
     back?: boolean;
     /** A small card that rides along with the packet. */
     data?: ReactNode;
+    /** Colors the packet, its data card, the edge and the box it arrives at, for this beat. The trail after the beat stays the accent. Default: the accent. */
+    tone?: FigTone;
     /** Marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag. Default: `false`. */
     async?: boolean;
     /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
@@ -71,7 +83,9 @@ export type FigBeat = {
     show?: Record<string, FigContent>;
     /** Ids of boxes to highlight for this beat, without a packet or a content card. */
     light?: string[];
-    /** How long the beat lasts in ms. Default: the time one packet needs to cross an edge (`speed`). */
+    /** Ids of boxes that take the active look for this beat: a 2 px border, a tint and a glow. The boxes in `light` keep the trail look. */
+    focus?: string[];
+    /** How long the beat lasts in ms. The packet crosses in `speed`; the rest is a hold. An explicit `ms` wins as written. Default: `speed` plus the time to read `say`. */
     ms?: number;
 };
 /** One line of a content card. */
@@ -89,8 +103,8 @@ export type FigRow = {
     /** Draws the text in a monospace font. Default: `false`. */
     mono?: boolean;
 };
-/** The color of a row tag. Each tone is a fixed color. */
-export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'gray';
+/** The color of a row tag, a hop or a box. Each tone is a fixed color. */
+export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'red' | 'gray';
 /** What a content card shows: rows, or anything React can render. */
 export type FigContent = FigRow[] | ReactNode;
 /** One story the figure can tell. The player shows one tab for each step. */
@@ -124,6 +138,12 @@ export type FlowProps = {
     check?: boolean;
     /** Draw the steps as a lifeline rail under the map: one row for each message, with its payload. `'only'` draws the rail without the map. Default: `false`. */
     rail?: boolean | 'only';
+    /** Draw the layout as swimlanes: a `column` group of labeled groups, one per role, with the boxes in time order left to right. Default: off. */
+    lanes?: true;
+    /** Draw the layout as a timeline: one labeled group per track, with the boxes placed by their `from` and `to` dates. Default: off. */
+    timeline?: true;
+    /** In a `timeline` figure: the date of the fixed today marker, as YYYY-MM-DD. With no `today`, the figure has no marker. */
+    today?: string;
 };
 /** A figure file's default export: a title, a source note and the props. */
 export type Figure = {
@@ -137,6 +157,7 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         edge: string;
         back: boolean;
         data?: ReactNode;
+        tone?: FigTone;
         async?: boolean;
         source?: string;
     }[];
@@ -155,6 +176,10 @@ export declare const BASE_RATE = 1.25;
 export declare const CARD_LINE = 15, CARD_PAD = 6;
 /** The fixed color of each row tone. */
 export declare const TONES: Record<FigTone, string>;
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export declare const toneFill: (c: string) => string;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export declare const toneTint: (c: string, bg: string, pct?: number) => string;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export declare const labelPillW: (label: string) => number;
 /** The width of the `async` tag in px. */
@@ -182,7 +207,86 @@ export declare const DARK: {
 export declare const ON_ACCENT = "#ffffff";
 /** Only text survives outside React: a React element has no string form. */
 export declare const str: (n: unknown) => string;
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export declare const readMs: (say: unknown) => number;
+/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
+export declare const beatMs: (b: Beat, speed: number) => number;
+/** 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 declare const playheadItem: <T extends {
+    id: string;
+}>(items: T[], beats: {
+    focus?: string[];
+}[], i: number) => T | undefined;
+/** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
+export declare const outsideLabelRect: (bar: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, label: string) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * 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 declare const labelSpan: (t0: number, end: number, ramp: number) => [number, number];
+/** 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 declare const dateLabelRaised: (x: number, today: number | null | undefined, w: number, todayW: number) => boolean;
+/** The hold at the end of each step, before the next step starts. */
+export declare const STEP_HOLD_MS = 2000;
 export declare const nodes: (g: FigGroup) => FigNode[];
+/** Lane layout constants, shared by both renderers: the gap between time columns, the padding inside a lane, and the gap between lanes. */
+export declare 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 declare const isLanesLayout: (g: FigGroup) => boolean;
+/** True if `at` is a usable time column: an integer of 0 or more. */
+export declare const validAt: (at: unknown) => at is number;
+/** 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 declare function laneColumns(fig: FlowProps): Map<string, number>;
+/** 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 declare 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 declare const dayOf: (iso: string) => number | null;
+export type TimelineItem = {
+    id: string;
+    track: number;
+    row: number;
+    x: number;
+    w: number;
+    milestone: boolean;
+    labelInside: boolean;
+    /** The `from` date in the d MMM form, for the playhead label. */
+    date: string;
+};
+export type TimelineLayout = {
+    /** The range in days, rounded out to whole weeks: the Monday of the first week and the Sunday of the last week. */
+    start: number;
+    end: number;
+    /** The week ticks (`W41`) or the month ticks (`Oct`). */
+    ticks: {
+        x: number;
+        label: string;
+    }[];
+    /** Bars and milestones. `x` and `w` are px inside the axis; `row` is the stack row inside the track. */
+    items: TimelineItem[];
+    /** The row count of each track. */
+    rows: number[];
+    /** The x of the today marker. It is null when the figure has no valid `today`. */
+    today: number | null;
+    /** The x and the d MMM date of the last day: the playhead rests there in the step hold. The x is null when the figure has no dated item. */
+    last: number | null;
+    lastDate: string;
+};
+/** Where each dated item, tick and the today line sit on the axis, `axisWidth` px wide. Both renderers call it. */
+export declare function timelineLayout(fig: FlowProps, axisWidth: number): TimelineLayout;
+/** 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 declare function timelineBeats(fig: FlowProps): FigStep[];
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
 export declare const counts: (p: FlowProps) => {
     boxes: number;

package/dist/model.js

@@ -25,8 +25,13 @@ export const TONES = {
     purple: '#8b5cf6',
     green: '#10b981',
     orange: '#f59e0b',
+    red: '#ef4444',
     gray: '#8b949e',
 };
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export const toneFill = (c) => `color-mix(in srgb, ${c} 64%, #000)`;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export const toneTint = (c, bg, pct = 8) => `color-mix(in srgb, ${c} ${pct}%, ${bg})`;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export const labelPillW = (label) => textWidth(label, 11, true) + 14;
 /** The width of the `async` tag in px. */
@@ -41,16 +46,189 @@ export const DARK = { accent: '#1f78c8', fg: '#e3e3e3', muted: '#9aa0a6', bg: '#
 export const ON_ACCENT = '#ffffff';
 /** Only text survives outside React: a React element has no string form. */
 export const str = (n) => (typeof n === 'string' || typeof n === 'number' ? String(n) : '');
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export const readMs = (say) => {
+    const w = str(say).split(/\s+/).filter(Boolean).length;
+    return w ? 400 + 240 * w : 0;
+};
+/** 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;
+}
+/** 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}
+`;
+}