flowfig 0.3.0 → 0.4.0

package/dist/picker.js

@@ -0,0 +1,148 @@
+// The arrow-key picker for `flowfig init`. The screen and the keys are pure, so the tests need no TTY.
+import { emitKeypressEvents } from 'node:readline';
+import { VERSION } from './version.js';
+const BANNER = [
+    '███████╗██╗      ██████╗ ██╗    ██╗███████╗██╗ ██████╗ ',
+    '██╔════╝██║     ██╔═══██╗██║    ██║██╔════╝██║██╔════╝ ',
+    '█████╗  ██║     ██║   ██║██║ █╗ ██║█████╗  ██║██║  ███╗',
+    '██╔══╝  ██║     ██║   ██║██║███╗██║██╔══╝  ██║██║   ██║',
+    '██║     ███████╗╚██████╔╝╚███╔███╔╝██║     ██║╚██████╔╝',
+    '╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ ╚═╝     ╚═╝ ╚═════╝ ',
+];
+const BANNER_WIDTH = Math.max(...BANNER.map((l) => l.length));
+const NOT = '(not detected)'.length; // the width of the detected column
+const HELP = '↑↓ move · space toggle · a all · enter confirm · esc cancel';
+const SHADOW = '38;2;43;93;143';
+const ansi = (on, code, text) => (on ? `\x1b[${code}m${text}\x1b[0m` : text);
+/** Row `i` of `n`: the blue gradient from #4da3ff to #0074d9. */
+const blue = (i, n) => {
+    const mix = (a, b) => Math.round(a + ((b - a) * i) / (n - 1));
+    return `38;2;${mix(0x4d, 0x00)};${mix(0xa3, 0x74)};${mix(0xff, 0xd9)}`;
+};
+/** The banner lines. A terminal narrower than the banner gets the plain version line. */
+export function banner({ color, width }) {
+    const ver = `flowfig ${VERSION}`;
+    if (width < BANNER_WIDTH)
+        return [ansi(color, '1;38;2;77;163;255', ver)];
+    const art = BANNER.map((l, i) => 
+    // each run of one character type gets its own colour: the block letters take the gradient, the shadow takes dim blue
+    l.replace(/█+|[╗║╚═╔╝]+/g, (run) => ansi(color, run[0] === '█' ? blue(i, BANNER.length - 1) : SHADOW, run)));
+    return [...art, ansi(color, '90', ver)];
+}
+/** Cut the pieces `[text, colour code]` to `width` visible characters, then colour them. */
+function fit(pieces, width, color) {
+    let room = width;
+    let out = '';
+    for (const [text, code] of pieces) {
+        const cut = text.length > room ? `${text.slice(0, Math.max(room - 1, 0))}…` : text;
+        out += code ? ansi(color, code, cut) : cut;
+        room -= cut.length;
+        if (room <= 0)
+            break;
+    }
+    return out;
+}
+/** The picker screen, one string per line. */
+export function screen(s, o) {
+    const w = Math.max(o.width - 1, 1); // the last column stays free, so no row wraps
+    const pad = Math.max(...s.rows.map((r) => r.name.length), 10);
+    const mark = (i) => (i === s.cursor ? '›' : ' ');
+    const rows = s.rows.map((r, i) => fit([
+        [`${mark(i)} [${s.sel.has(r.id) ? 'x' : ' '}] `, ''],
+        [r.name.padEnd(pad), ''],
+        [` ${r.detected ? ''.padEnd(NOT) : '(not detected)'}`, '90'],
+        [`  ${r.files.join(', ')}`, '36'],
+    ], w, o.color));
+    const mcp = fit([
+        [`${mark(s.rows.length)} [${s.mcp ? 'x' : ' '}] `, ''],
+        [`${'MCP server'.padEnd(pad)} ${''.padEnd(NOT)}`, ''],
+        ['  register flowfig in the MCP file of each agent', '36'],
+    ], w, o.color);
+    return [
+        ...banner(o),
+        '',
+        fit([['Pick the coding agents that should draw diagrams in this repo.', '']], w, o.color),
+        '',
+        ...rows,
+        ansi(o.color, '90', '─'.repeat(Math.min(w, 40))),
+        mcp,
+        '',
+        fit([[HELP, '90']], w, o.color),
+    ];
+}
+/** One key press. Returns the next state, or `confirm` or `cancel`. */
+export function keyStep(s, k) {
+    const last = s.rows.length; // the MCP row
+    const n = last + 1;
+    if (k.name === 'escape' || k.name === 'q' || (k.ctrl && k.name === 'c'))
+        return 'cancel';
+    if (k.name === 'return')
+        return 'confirm';
+    if (k.name === 'up' || k.name === 'k')
+        return { ...s, cursor: (s.cursor + n - 1) % n };
+    if (k.name === 'down' || k.name === 'j')
+        return { ...s, cursor: (s.cursor + 1) % n };
+    if (k.name === 'space') {
+        if (s.cursor === last)
+            return { ...s, mcp: !s.mcp };
+        const id = s.rows[s.cursor].id;
+        const sel = new Set(s.sel);
+        sel.has(id) ? sel.delete(id) : sel.add(id);
+        return { ...s, sel };
+    }
+    if (k.name === 'a')
+        return { ...s, sel: s.sel.size === last ? new Set() : new Set(s.rows.map((r) => r.id)) };
+    return s;
+}
+/** Run the picker on the terminal. Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
+export function runPicker(rows, start, mcp) {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function')
+        return Promise.resolve('fallback');
+    try {
+        stdin.setRawMode(true);
+    }
+    catch {
+        return Promise.resolve('fallback');
+    }
+    const color = process.env.NO_COLOR === undefined;
+    let state = { rows, sel: start, mcp, cursor: 0 };
+    let drawn = 0;
+    const draw = () => {
+        const lines = screen(state, { color, width: stdout.columns || 80 });
+        stdout.write(`${drawn ? `\x1b[${drawn}A\r\x1b[J` : ''}${lines.join('\n')}\n`);
+        drawn = lines.length;
+    };
+    return new Promise((resolve, reject) => {
+        const end = (r) => {
+            stdin.off('keypress', onKey);
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdout.write(`\x1b[${drawn}A\r\x1b[J\x1b[?25h`);
+            resolve(r);
+        };
+        const onKey = (_, key = {}) => {
+            try {
+                const next = keyStep(state, key);
+                if (next === 'cancel')
+                    return end();
+                if (next === 'confirm')
+                    return end({ ids: state.sel, mcp: state.mcp });
+                state = next;
+                draw();
+            }
+            catch (e) {
+                stdin.off('keypress', onKey);
+                stdin.setRawMode(false);
+                stdin.pause();
+                stdout.write('\x1b[?25h');
+                reject(e);
+            }
+        };
+        emitKeypressEvents(stdin);
+        stdin.on('keypress', onKey);
+        stdin.resume();
+        stdout.write('\x1b[?25l');
+        draw();
+    });
+}

package/dist/png.d.ts

@@ -0,0 +1,7 @@
+/** RGBA pixels, 4 bytes per pixel, rows top to bottom. */
+export type Image = {
+    width: number;
+    height: number;
+    data: Uint8Array;
+};
+export declare function decodePng(png: Uint8Array): Image;

package/dist/png.js

@@ -0,0 +1,70 @@
+// Read the PNG screenshots of the capture browser. Only what Chrome writes: 8-bit RGB or RGBA, no interlace.
+import { inflateSync } from 'node:zlib';
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+export function decodePng(png) {
+    if (png.length < 8 || SIGNATURE.some((b, i) => png[i] !== b))
+        throw new Error('not a PNG: bad signature');
+    const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+    let width = 0, height = 0, bpp = 0;
+    const idat = [];
+    // The CRC of each chunk is not checked: the PNG comes from the browser over a local pipe.
+    for (let at = 8; at + 8 <= png.length;) {
+        const len = view.getUint32(at);
+        const kind = String.fromCharCode(...png.subarray(at + 4, at + 8));
+        const body = png.subarray(at + 8, at + 8 + len);
+        if (kind === 'IHDR') {
+            width = view.getUint32(at + 8);
+            height = view.getUint32(at + 12);
+            if (body[8] !== 8)
+                throw new Error(`unsupported PNG: bit depth ${body[8]}`);
+            if (body[9] !== 2 && body[9] !== 6)
+                throw new Error(`unsupported PNG: color type ${body[9]}`);
+            if (body[12] !== 0)
+                throw new Error(`unsupported PNG: interlace ${body[12]}`);
+            bpp = body[9] === 6 ? 4 : 3;
+        }
+        else if (kind === 'IDAT')
+            idat.push(body);
+        else if (kind === 'IEND')
+            break;
+        at += 12 + len;
+    }
+    if (!bpp)
+        throw new Error('not a PNG: no IHDR chunk');
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = width * bpp;
+    if (raw.length < height * (stride + 1))
+        throw new Error('not a PNG: the image data is too short');
+    const data = new Uint8Array(width * height * 4);
+    let prev = new Uint8Array(stride);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * (stride + 1)];
+        const row = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+        // Undo the row filter in place. A Uint8Array write keeps the low 8 bits, as the PNG standard needs.
+        if (filter === 1)
+            for (let x = bpp; x < stride; x++)
+                row[x] += row[x - bpp];
+        else if (filter === 2)
+            for (let x = 0; x < stride; x++)
+                row[x] += prev[x];
+        else if (filter === 3)
+            for (let x = 0; x < stride; x++)
+                row[x] += ((x >= bpp ? row[x - bpp] : 0) + prev[x]) >> 1;
+        else if (filter === 4)
+            for (let x = 0; x < stride; x++) {
+                const a = x >= bpp ? row[x - bpp] : 0, b = prev[x], c = x >= bpp ? prev[x - bpp] : 0;
+                const pa = Math.abs(b - c), pb = Math.abs(a - c), pc = Math.abs(a + b - 2 * c);
+                row[x] += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+            }
+        else if (filter !== 0)
+            throw new Error(`unsupported PNG: filter ${filter}`);
+        for (let x = 0, o = y * width * 4; x < stride; x += bpp, o += 4) {
+            data[o] = row[x];
+            data[o + 1] = row[x + 1];
+            data[o + 2] = row[x + 2];
+            data[o + 3] = bpp === 4 ? row[x + 3] : 255;
+        }
+        prev = row;
+    }
+    return { width, height, data };
+}

package/dist/scene.d.ts

@@ -13,6 +13,7 @@ export type SceneBox = {
     texts: TextRun[];
 };
 /** `step` marks a rail row: rows of two steps never show at the same time, so their labels cannot overlap. */
+/** `behind` marks an edge drawn under the boxes (a timeline dependency): `check` skips its crossing test. */
 export type SceneEdge = {
     id: string;
     from: string;
@@ -20,6 +21,7 @@ export type SceneEdge = {
     curve: [Pt, Pt, Pt, Pt];
     label?: Rect;
     step?: number;
+    behind?: true;
 };
 /** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
 export type Scene = {

package/dist/svg.js

@@ -12,7 +12,7 @@ import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
 export { parseSource, links } from './source.js';
 export { diff, formatDiff } from './diff.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, toBeat, beatMs, STEP_HOLD_MS, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, laneColumns, LANE_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, labelSpan, outsideLabelRect, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const LABEL_LINE = 18, SUB_LINE = 15, NODE_MIN_W = 100, NODE_MAX_W = 190;
@@ -94,7 +94,70 @@ function size(item, s) {
     const inner = item.direction === 'column' ? { w: across, h: along } : { w: along, h: across };
     return item.label != null ? { w: inner.w + FRAME_SIDE * 2, h: inner.h + FRAME_TOP + FRAME_BOTTOM } : inner;
 }
+/** Swimlanes: the bands span the width, the label sits in a left gutter, and a box sits at its time column. */
+function placeLanes(fig, x, y, s, out) {
+    const lanes = fig.layout.children;
+    const cols = laneColumns(fig);
+    const colW = Array.from({ length: Math.max(-1, ...cols.values()) + 1 }, () => 0);
+    for (const lane of lanes)
+        for (const b of lane.children)
+            colW[cols.get(b.id)] = Math.max(colW[cols.get(b.id)], size(b, s).w);
+    const gutter = gutterOf(lanes);
+    const colX = colW.map((_, c) => gutter + colW.slice(0, c).reduce((a, w) => a + w + LANE_GAP, 0));
+    const width = gutter + colW.reduce((a, w) => a + w, 0) + LANE_GAP * Math.max(0, colW.length - 1) + FRAME_SIDE;
+    const topAt = out.length;
+    out.push({ x, y, w: width, h: 0, item: fig.layout });
+    let ly = y;
+    for (const lane of lanes) {
+        const kids = lane.children.map((b) => ({ b, ...size(b, s) }));
+        const inner = Math.max(LABEL_LINE + 20, ...kids.map((k) => k.h));
+        const h = inner + LANE_PAD * 2;
+        out.push({ x, y: ly, w: width, h, item: lane, lane: true });
+        for (const k of kids)
+            out.push({ x: x + colX[cols.get(k.b.id)], y: ly + LANE_PAD + (inner - k.h) / 2, w: k.w, h: k.h, item: k.b });
+        ly += h + LANE_ROW_GAP;
+    }
+    out[topAt].h = ly - LANE_ROW_GAP - y;
+}
+/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
+const gutterOf = (lanes) => Math.max(0, ...lanes.map((l) => textWidth(str(l.label).toUpperCase(), 12))) + FRAME_SIDE * 2;
+/** A timeline: the axis strip on top, one band per track, and the bars and milestones at the shared layout x. */
+function placeTimeline(fig, x, y, out) {
+    const lanes = fig.layout.children;
+    const gutter = gutterOf(lanes);
+    const lay = timelineLayout(fig, TL_AXIS_W);
+    const width = gutter + TL_AXIS_W + FRAME_SIDE;
+    const topAt = out.length;
+    out.push({ x, y, w: width, h: 0, item: fig.layout });
+    let ly = y + TL_AXIS_H;
+    lanes.forEach((lane, track) => {
+        const rows = lay.rows[track];
+        const h = rows * TL_BAR_H + (rows - 1) * TL_ROW_GAP + LANE_PAD * 2;
+        out.push({ x, y: ly, w: width, h, item: lane, lane: true });
+        for (const it of lay.items) {
+            if (it.track !== track)
+                continue;
+            const node = lane.children.find((k) => !isGroup(k) && k.id === it.id);
+            const top = ly + LANE_PAD + it.row * (TL_BAR_H + TL_ROW_GAP);
+            const bh = it.milestone ? it.w : TL_BAR_H;
+            out.push({
+                x: x + gutter + it.x,
+                y: top + (TL_BAR_H - bh) / 2,
+                w: it.w,
+                h: bh,
+                item: node,
+                tl: { milestone: it.milestone, labelInside: it.labelInside },
+            });
+        }
+        ly += h + LANE_ROW_GAP;
+    });
+    out[topAt].h = ly - LANE_ROW_GAP - y;
+}
 function place(item, x, y, s, out) {
+    if (item === s.fig.layout && s.fig.timeline && isLanesLayout(s.fig.layout))
+        return placeTimeline(s.fig, x, y, out);
+    if (item === s.fig.layout && s.fig.lanes && isLanesLayout(s.fig.layout))
+        return placeLanes(s.fig, x, y, s, out);
     const { w, h } = size(item, s);
     out.push({ x, y, w, h, item });
     if (!isGroup(item))
@@ -126,7 +189,10 @@ const SYSTEM_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helv
 export function render(fig, opts = {}) {
     const speed = (opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
     const pad = opts.padding ?? 24;
-    const steps = fig.steps ?? [];
+    const tl = fig.timeline && isLanesLayout(fig.layout) ? timelineLayout(fig, TL_AXIS_W) : null;
+    // A timeline with no steps of its own walks its dated items in date order.
+    const synthetic = tl != null && !fig.steps?.length;
+    const steps = synthetic ? timelineBeats(fig) : (fig.steps ?? []);
     const beats = steps.map((s) => s.flow.map(toBeat));
     // Every content a box will ever show, so its card can be sized to the biggest one up front.
     const cards = new Map();
@@ -144,7 +210,7 @@ export function render(fig, opts = {}) {
         return n > 2 ? n * 30 : 0;
     };
     const cardH = new Map();
-    const sizes = { cards, cardH, minH, gap: (g) => groupGap(g, fig.edges) };
+    const sizes = { cards, cardH, minH, gap: (g) => groupGap(g, fig.edges), fig };
     for (const [id, contents] of cards) {
         const width = CARD_WIDTH; // refined below once the node's own width is known
         const widths = [width];
@@ -166,13 +232,29 @@ export function render(fig, opts = {}) {
     for (const p of placed)
         if (p.item.id)
             rects[p.item.id] = p;
-    const tips = new Set(placed.filter((p) => !isGroup(p.item) && p.item.shape === 'decision').map((p) => p.item.id));
+    const tips = new Set(placed.filter((p) => !isGroup(p.item) && (p.item.shape === 'decision' || p.tl?.milestone)).map((p) => p.item.id));
     const ids = fig.edges.map(edgeId);
-    const routed = route(fig.edges.map((e, i) => ({ id: ids[i], from: e.from, to: e.to, around: e.around })), rects, tips);
+    const routed = route(fig.edges.map((e, i) => ({
+        id: ids[i],
+        from: e.from,
+        to: e.to,
+        around: e.around,
+        ...(tl && { sides: ['r', 'l'], elbow: true }),
+    })), rects, tips, placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))));
     const byId = Object.fromEntries(routed.map((r) => [r.id, r]));
     // What this layout drew, in scene form. Tags are left out of minFont: short bold capitals, not reading text.
     const fonts = [14, ...(steps.length ? [13.5] : [])];
     const sceneBoxes = nodes.map((p) => {
+        if (p.tl) {
+            // A label inside the bar has the bar as room; a label beside the bar has the space to the next item of its row, or to the band edge.
+            const label = str(p.item.label);
+            const mine = tl.items.find((i) => i.id === p.item.id);
+            const next = tl.items.filter((i) => i.track === mine.track && i.row === mine.row && i.x > mine.x).map((i) => p.x - mine.x + i.x - 8);
+            const limit = Math.min(placed[0].x + placed[0].w - FRAME_SIDE, ...next);
+            const room = p.tl.labelInside ? p.w - 16 : limit - (p.x + p.w) - 6;
+            fonts.push(13);
+            return { id: p.item.id, rect: { x: p.x, y: p.y, w: p.w, h: p.h }, texts: [{ text: label, fontSize: 13, room }] };
+        }
         const room = (p.item.shape === 'decision' ? p.w - 70 : p.w) - 16;
         const texts = [{ text: str(p.item.label), fontSize: 14, room }];
         if (p.item.sub) {
@@ -225,7 +307,12 @@ export function render(fig, opts = {}) {
     const shownAt = segs.map(({ si, bi }) => Object.assign({}, ...beats[si].slice(0, bi + 1).map((b) => b.show)));
     const litEdges = segs.map(({ si, bi }) => new Set(beats[si].slice(0, bi + 1).flatMap((b) => b.hops.map((h) => h.edge))));
     const litNodes = segs.map((seg, i) => {
-        const on = new Set([...(steps[seg.si].nodes ?? []), ...Object.keys(shownAt[i]), ...(beats[seg.si][seg.bi].light ?? [])]);
+        const on = new Set([
+            ...(steps[seg.si].nodes ?? []),
+            ...Object.keys(shownAt[i]),
+            ...(beats[seg.si][seg.bi].light ?? []),
+            ...(beats[seg.si][seg.bi].focus ?? []),
+        ]);
         fig.edges.forEach((e, ei) => {
             if (litEdges[i].has(ids[ei]))
                 on.add(e.from).add(e.to);
@@ -277,6 +364,7 @@ export function render(fig, opts = {}) {
      * FADE is in timeline seconds, which are wall seconds.
      */
     const FADE = 0.4;
+    const RAMP = 0.4; // the today line moves in 400 ms, in wall seconds like FADE
     // A box tone is a permanent state: a 1 px border and a light tint in the off and trail looks. The active look uses the hop tone, else the box tone.
     const looks = (look, boxTone, hopTone) => {
         const tint = boxTone ? toneTint(boxTone, 'var(--bg)') : 'var(--bg)';
@@ -295,7 +383,9 @@ export function render(fig, opts = {}) {
             if (!litNodes[i].has(id))
                 return void pieces.push({ a: s.t0, b: s.t1, look: 'off' });
             const here = hops.filter((h) => h.dest === id && h.si === s.si && h.bi === s.bi);
-            const arrive = Math.min(...here.map((h) => h.t1), s.t1);
+            // A focused box turns active at the beat start; in a timeline, when the today line arrives.
+            const focused = beats[s.si][s.bi].focus?.includes(id);
+            const arrive = Math.min(...here.map((h) => h.t1), focused ? Math.min(s.t0 + (tl ? RAMP : 0), s.t1) : s.t1, s.t1);
             if (arrive > s.t0)
                 pieces.push({ a: s.t0, b: arrive, look: 'trail' });
             if (arrive < s.t1)
@@ -330,11 +420,23 @@ export function render(fig, opts = {}) {
                 return '';
             const on = item.id ? segs.map((_, i) => litNodes[i].has(item.id)) : [];
             return (`<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="14" fill="var(--surface)" stroke="var(--border)"` +
-                cls(anim(on, 'stroke: var(--accent)', 'stroke: var(--border)', 'n')) +
-                `/><text x="${n2(p.x + FRAME_SIDE)}" y="${n2(p.y + 20)}" class="frame">${esc(str(item.label).toUpperCase())}</text>`);
+                cls(p.lane && 'lane', anim(on, 'stroke: var(--accent)', 'stroke: var(--border)', 'n')) +
+                `/><text x="${n2(p.x + FRAME_SIDE)}" y="${n2(p.lane ? p.y + p.h / 2 + 4 : p.y + 20)}" class="frame">${esc(str(item.label).toUpperCase())}</text>`);
         }
         const bt = item.tone && TONES[item.tone];
         const stroke = cls(boxAnim(item.id, true, bt));
+        if (p.tl) {
+            const fill0 = bt ? toneTint(bt, 'var(--bg)') : 'var(--bg)';
+            const stroke0 = bt ?? 'var(--border)';
+            const label = str(item.label);
+            const inside = p.tl.labelInside;
+            const cx = p.x + p.w / 2, cy = p.y + p.h / 2;
+            const shape = p.tl.milestone
+                ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(cy)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(cy)}" fill="${fill0}" stroke="${stroke0}"${stroke}/>`
+                : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="6" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
+            const tx = inside ? p.x + 8 : p.x + p.w + 6;
+            return shape + `<text x="${n2(tx)}" y="${n2(cy + 4.5)}" class="bar">${esc(label)}</text>`;
+        }
         const rim = item.shape === 'store' ? cls(boxAnim(item.id, false, bt)) : '';
         const fill0 = bt ? toneTint(bt, 'var(--bg)') : 'var(--bg)';
         const stroke0 = bt ?? 'var(--border)';
@@ -350,7 +452,15 @@ export function render(fig, opts = {}) {
                 : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
         const label = `<text x="${n2(cx)}" y="${n2(labelY)}" class="label">${esc(str(item.label))}</text>`;
         const sub = item.sub ? `<text x="${n2(cx)}" y="${n2(labelY + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>` : '';
-        return shape + label + sub + (contents ? card(p, cardTop, contents) : '');
+        // The mark sits in the gap beside the box, so it changes no size and adds nothing to the scene.
+        const dot = bt ?? 'var(--accent)';
+        const my = n2(p.y + p.h / 2);
+        const mark = item.mark === 'start'
+            ? `<circle cx="${n2(p.x - 12)}" cy="${my}" r="5" fill="${dot}"/>`
+            : item.mark === 'end'
+                ? `<circle cx="${n2(p.x + p.w + 12)}" cy="${my}" r="6.25" fill="none" stroke="${dot}" stroke-width="1.5"/><circle cx="${n2(p.x + p.w + 12)}" cy="${my}" r="4" fill="${dot}"/>`
+                : '';
+        return shape + label + sub + mark + (contents ? card(p, cardTop, contents) : '');
     });
     /** The dashed content card: one group per content it will ever hold, each visible on its own beats. */
     function card(p, top, contents) {
@@ -423,7 +533,7 @@ export function render(fig, opts = {}) {
             : anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, off, 'e'));
         const path = `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
         // A quiet edge is only drawn while a step uses it, so wrap the whole thing rather than the stroke.
-        const label = e.label == null
+        const label = e.label == null || tl
             ? ''
             : (() => {
                 const lw = labelPillW(str(e.label));
@@ -459,6 +569,79 @@ export function render(fig, opts = {}) {
             `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n4(t0)};${n4(t1)};1" keyPoints="${h.back ? '1;1;0;0' : '0;0;1;1'}" calcMode="linear">` +
             `<mpath href="#p-${esc(h.edge)}" xlink:href="#p-${esc(h.edge)}"/></animateMotion></g>`);
     });
+    // The timeline axis under the boxes, the fixed today marker and the moving playhead over them.
+    let axisSvg = '', todaySvg = '';
+    if (tl) {
+        const top = placed[0];
+        const x0 = top.x + gutterOf(fig.layout.children);
+        const ay = top.y + TL_AXIS_H;
+        fonts.push(11);
+        axisSvg =
+            `<path d="M ${n2(x0)} ${n2(ay - 1)} H ${n2(x0 + TL_AXIS_W)}" stroke="var(--border)"/>` +
+                tl.ticks
+                    .map((k) => `<path d="M ${n2(x0 + k.x)} ${n2(ay - 5)} V ${n2(ay - 1)}" stroke="var(--border)"/>` +
+                    `<text x="${n2(x0 + k.x + 3)}" y="${n2(top.y + 10)}" class="tick">${esc(k.label)}</text>`)
+                    .join('');
+        const bottom = n2(top.y + top.h);
+        // The today marker is fixed at the figure's `today`.
+        if (tl.today != null) {
+            const tx = x0 + tl.today;
+            todaySvg =
+                `<path d="M ${n2(tx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-opacity="0.6" stroke-width="1" stroke-dasharray="3 3"/>` +
+                    `<text x="${n2(tx - 3)}" y="${n2(top.y + 22)}" text-anchor="end" class="today">today</text>`;
+        }
+        // The playhead moves to the start of each beat's item, then to the last date in the step hold.
+        if (tl.last != null && segs.length) {
+            const home = tl.last;
+            const startOf = new Map(tl.items.map((i) => [i.id, i.x + (i.milestone ? i.w / 2 : 0)]));
+            const dateOf = new Map(tl.items.map((i) => [i.id, i.date]));
+            const hold = STEP_HOLD_MS / 1000 / BASE_RATE;
+            const pts = [[0, home]];
+            const dates = []; // the label date in each time span
+            let at = home;
+            segs.forEach((s, i) => {
+                const item = playheadItem(tl.items, beats[s.si], s.bi);
+                const to = item ? startOf.get(item.id) : home;
+                const date = item ? dateOf.get(item.id) : tl.lastDate;
+                const last = i === segs.length - 1 || segs[i + 1].si !== s.si;
+                const end = last ? s.t1 - hold : s.t1; // the step hold starts here
+                pts.push([s.t0, at], [Math.min(s.t0 + RAMP, end), to], [end, to]);
+                const [la, lb] = labelSpan(s.t0, end, RAMP);
+                if (la < lb)
+                    dates.push({ a: la, b: lb, d: date, x: to });
+                at = to;
+                if (last) {
+                    pts.push([Math.min(end + RAMP, s.t1), home], [s.t1, home]);
+                    const [ha, hb] = labelSpan(end, s.t1, RAMP);
+                    if (ha < hb)
+                        dates.push({ a: ha, b: hb, d: tl.lastDate, x: home });
+                    at = home;
+                }
+            });
+            const name = `a${seen.size}`;
+            seen.set('playhead', name);
+            const kf = pts.map(([t, x]) => `${pct(t / total)} { transform: translateX(${n2(x - home)}px) }`).join(' ');
+            css.push(`@keyframes ${name} { ${kf} }\n.${name} { animation: ${name} ${n2(total)}s infinite linear; }`);
+            const lx = x0 + home;
+            const labels = [...new Set(dates.map((x) => x.d))].map((d) => {
+                const on = dates.map((x) => x.d === d);
+                const key = `d${d}${on.map((x) => (x ? 1 : 0)).join('')}`;
+                if (!seen.has(key)) {
+                    const nm = `a${seen.size}`;
+                    seen.set(key, nm);
+                    // Each span ends with a hidden frame: the label stays off while the line moves.
+                    const fr = dates
+                        .map((x) => `${pct(x.a / total)},${pct(x.b / total - 0.0001)} { opacity: ${x.d === d ? 1 : 0} } ${pct(x.b / total)} { opacity: 0 }`)
+                        .join(' ');
+                    css.push(`@keyframes ${nm} { ${fr} }\n.${nm} { animation: ${nm} ${n2(total)}s infinite step-end; }`);
+                }
+                // A label that would meet "today" moves to the tick row.
+                const raised = dateLabelRaised(dates.find((x) => x.d === d).x, tl.today, textWidth(d, 11), textWidth('today', 11));
+                return `<text x="${n2(lx + 3)}" y="${n2(top.y + (raised ? 10 : 22))}" opacity="0"${cls('today', seen.get(key))}>${esc(d)}</text>`;
+            });
+            todaySvg += `<g${cls(name)}><path d="M ${n2(lx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-width="1.5"/>${labels.join('')}</g>`;
+        }
+    }
     const bounds = placed[0];
     const arcs = fig.edges.some((e) => e.around);
     const capLines = [...new Set(captions)].flatMap((c) => wrap(c, Math.max(560, bounds.w), 13.5).length);
@@ -476,7 +659,7 @@ export function render(fig, opts = {}) {
     const shift = (W - (bounds.w + pad * 2)) / 2;
     const railX = rail ? (W - rail.width) / 2 : 0;
     // The step label and its narration, both switching with the beats.
-    const labels = rail
+    const labels = rail || synthetic
         ? []
         : steps.map((_, si) => {
             const on = segs.map((s) => s.si === si);
@@ -579,6 +762,9 @@ svg { ${vars(t0, '#eef5fd')} }
 .row { fill: var(--fg); font-size: 11px; }
 .row.mono { font-size: 10.5px; font-family: ui-monospace, Menlo, monospace; }
 .muted { fill: var(--muted); }
+.bar { fill: var(--fg); font-size: 13px; font-weight: 500; }
+.tick { fill: var(--muted); font-size: 11px; }
+.today { fill: var(--accent); font-size: 11px; font-weight: 600; }
 .tag { font-size: 9px; font-weight: 600; letter-spacing: .03em; text-anchor: middle; }
 .mark { fill: var(--accent); font-size: 11px; font-weight: 600; text-anchor: end; }
 .chip { fill: ${ON_ACCENT}; font-size: 11.5px; text-anchor: middle; }
@@ -595,9 +781,13 @@ ${css.join('\n')}
 ${only
         ? ''
         : `<g transform="translate(${n2(shift)} ${arcs ? 44 : 0})">
-${boxes.filter(Boolean).join('\n')}
-${edgeSvg.join('\n')}
+${axisSvg}
+${tl ? boxes.filter((b, i) => b && isGroup(placed[i].item)).join('\n') : ''}
+${tl ? edgeSvg.join('\n') : ''}
+${boxes.filter((b, i) => b && !(tl && isGroup(placed[i].item))).join('\n')}
+${tl ? '' : edgeSvg.join('\n')}
 ${packets.join('\n')}
+${todaySvg}
 </g>
 `}${railSvg}
 ${labels.join('\n')}
@@ -612,7 +802,7 @@ ${said.join('\n')}
         edges: [
             ...(only ? [] : routed).map((r) => {
                 const e = fig.edges[ids.indexOf(r.id)];
-                return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labelRects[r.id] };
+                return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labelRects[r.id], ...(tl && { behind: true }) };
             }),
             // Each rail payload is a label too, in its own open-phase position, so label-overlap covers the rail.
             ...(rail?.rows ?? []).flatMap((row, i) => {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks them. One animated SVG for a GitHub README, PR or issue, and a React player. Set up Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro with npx flowfig init.",
   "license": "MIT",
   "repository": {