flowfig 0.8.4 → 0.10.0

package/dist/model.d.ts

@@ -26,6 +26,8 @@ export type FigNode = {
     mark?: 'start' | 'end';
     /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
+    /** A figure with more detail: an SVG path from the repo root. */
+    detail?: string;
 };
 /** A frame that lays out its children in a row or a column. */
 export type FigGroup = {
@@ -37,10 +39,12 @@ export type FigGroup = {
     direction?: 'row' | 'column';
     /** Space between children in px. Default: 28 for a column, fitted for a row. */
     gap?: number;
-    /** Where children line up across the group's direction. Default: center (columns stretch). */
+    /** Where children line up across the group's direction. Default: `center`, also for a column. */
     align?: 'start' | 'center' | 'end';
     /** The boxes and groups inside, in order. */
     children: (FigNode | FigGroup)[];
+    /** On the root layout: flowfig places the boxes. A labeled group is a frame. */
+    auto?: true;
 };
 /** An arrow from one box to another. */
 export type FigEdge = {
@@ -52,8 +56,8 @@ export type FigEdge = {
     to: string;
     /** Text on the edge, drawn as a small pill. */
     label?: ReactNode;
-    /** Routes the edge over or under the boxes in between (loops, skip-ahead edges). */
-    around?: 'above' | 'below';
+    /** Routes the edge around the boxes in between (loops, skip-ahead edges). */
+    around?: 'above' | 'below' | 'left' | 'right';
     /** Draws the edge only while a step uses it. */
     quiet?: boolean;
     /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
@@ -350,4 +354,12 @@ export declare const counts: (p: FlowProps) => {
     steps: number;
     messages: number;
 };
+export declare const idsIn: (c: FigNode | FigGroup) => string[];
 export declare function groupGap(g: FigGroup, edges: FigEdge[]): number;
+export declare const altText: (fig: FlowProps) => {
+    title: string;
+    desc: string;
+};
+export declare const specKey: (...parts: unknown[]) => string;
+export declare const fitScale: (wide: number, box: number, map: number) => number;
+export declare const nextWide: (wide: number, box: number, map: number) => number;

package/dist/model.js

@@ -451,7 +451,7 @@ export const counts = (p) => {
         messages: st.reduce((n, s) => n + s.flow.reduce((m, b) => m + toBeat(b).hops.length, 0), 0),
     };
 };
-const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
+export const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
 const LINE_CLEAR = 16;
 export function groupGap(g, edges) {
     const side = new Map();
@@ -472,3 +472,58 @@ export function groupGap(g, edges) {
         auto = Math.max(56, need);
     return Math.max(g.gap ?? 0, auto);
 }
+export const altText = (fig) => {
+    const names = new Map();
+    const walk = (g) => g.children.forEach((c) => {
+        if (c.id)
+            names.set(c.id, str(c.label) || c.id);
+        if (isGroup(c))
+            walk(c);
+    });
+    walk(fig.layout);
+    const name = (id) => names.get(id) ?? id;
+    const ends = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    const boxes = nodes(fig.layout).map((n) => name(n.id));
+    const steps = fig.steps ?? [];
+    const lines = steps.flatMap((s) => [
+        `${str(s.label)}.`,
+        ...s.flow.map(toBeat).flatMap((b) => {
+            if (str(b.say))
+                return [str(b.say)];
+            return b.hops.flatMap((h) => {
+                const e = ends.get(h.edge);
+                if (!e)
+                    return [];
+                return [h.back ? `${name(e.to)} to ${name(e.from)}` : `${name(e.from)} to ${name(e.to)}`];
+            });
+        }),
+    ]);
+    return {
+        title: `Flow figure: ${boxes.join(', ')}.${steps.length ? ` Steps: ${steps.map((s) => str(s.label)).join(', ')}.` : ''}`,
+        desc: [`The figure has these boxes: ${boxes.join(', ')}.`, ...lines].join('\n'),
+    };
+};
+const keyOf = (v, path) => {
+    if (typeof v === 'function' || typeof v === 'symbol')
+        return undefined;
+    if (typeof v === 'bigint')
+        return `${v}n`;
+    if (typeof v !== 'object' || v === null)
+        return v;
+    if (path.includes(v))
+        return '[cycle]';
+    const at = [...path, v];
+    if (Array.isArray(v))
+        return v.map((x) => keyOf(x, at));
+    const el = v;
+    const proto = Object.getPrototypeOf(v);
+    if (!el.$$typeof && proto !== Object.prototype && proto !== null)
+        return '[object]';
+    const src = el.$$typeof ? { type: typeof el.type === 'string' ? el.type : el.type?.name, key: el.key, props: el.props } : v;
+    return Object.fromEntries(Object.entries(src).flatMap(([k, x]) => (k === 'ref' || k.startsWith('_') ? [] : [[k, keyOf(x, at)]])));
+};
+export const specKey = (...parts) => JSON.stringify(keyOf(parts, []));
+export const fitScale = (wide, box, map) => Math.max(wide ? 1 : 0.5, Math.min(1, box / map));
+const PHONE = 480;
+const folds = (box, map) => box < map / 2 || (box < PHONE && box < map);
+export const nextWide = (wide, box, map) => (folds(box, wide || map) ? wide || map : 0);

package/dist/open.d.ts

@@ -7,6 +7,7 @@ export declare function openerFor(platform: NodeJS.Platform, file: string): Open
 /** The temp page name: each character other than a letter, digit, - or _ becomes -. */
 export declare function pageName(svgPath: string): string;
 export declare const openedLine: (page: string) => string;
+export declare function openFile(path: string): Promise<void>;
 /** Write the page to a new temp folder, then start the opener. Returns the written paths. */
 export declare function openSvg(svgPath: string, html?: string): Promise<string[]>;
 export declare function runOpen(argv: string[]): Promise<number>;

package/dist/open.js

@@ -20,6 +20,16 @@ export function pageName(svgPath) {
         .replace(/[^\w-]/g, '-') + '.html');
 }
 export const openedLine = (page) => `${page} — opened in the default browser`;
+export async function openFile(path) {
+    const o = process.env.FLOWFIG_OPENER
+        ? { cmd: process.env.FLOWFIG_OPENER, args: [path], verbatim: false }
+        : openerFor(process.platform, path);
+    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 ${path} in a browser.`)));
+    });
+}
 /** Write the page to a new temp folder, then start the opener. Returns the written paths. */
 export async function openSvg(svgPath, html) {
     const page = pageHtml(readFileSync(svgPath, 'utf8'), basename(svgPath));
@@ -30,14 +40,7 @@ export async function openSvg(svgPath, html) {
     writeFileSync(temp, page);
     if (html)
         writeFileSync(html, page);
-    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.`)));
-    });
+    await openFile(temp);
     return html ? [temp, html] : [temp];
 }
 export async function runOpen(argv) {

package/dist/page.d.ts

@@ -1 +1,2 @@
-export declare function pageHtml(svg: string, title: string): string;
+export declare const esc: (s: string) => string;
+export declare function pageHtml(svg: string, title: string, before?: string, after?: string, head?: string): string;

package/dist/page.js

@@ -1,14 +1,15 @@
-const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-export function pageHtml(svg, title) {
+export const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function pageHtml(svg, title, before = '', after = '', head = '') {
     // Use element selectors only: figure styles use class names.
     return `<!doctype html>
 <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${esc(title)}</title>
-<style>
+${head}<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}
+${before}${svg}${after}
 `;
 }

package/dist/svg.d.ts

@@ -1,10 +1,11 @@
 import { type CheckOptions } from './check.ts';
 import type { Finding, Scene } from './scene.ts';
+import type { DiffMarks } from './diff.ts';
 export type { CheckOptions } from './check.ts';
 export type { Finding, Scene } from './scene.ts';
 export type * from './model.ts';
 export { parseSource, links, type Link } from './source.ts';
-export { diff, formatDiff, type Change } from './diff.ts';
+export { diff, formatDiff, mergeFigures, type Change, type DiffMark, type DiffMarks } from './diff.ts';
 import { type FigTheme, type FlowProps } from './model.ts';
 export { LIGHT, DARK } from './model.ts';
 /** Options for `toSvg`, `render` and `check`. */
@@ -18,9 +19,13 @@ export type SvgOptions = {
     /** Lanes: page width and smallest text size that set the wrap. Default: 830 and 10. */
     width?: number;
     minText?: number;
+    /** Draws a still diff with a legend. `mergeFigures` makes the marks. */
+    marks?: DiffMarks;
+    /** Links a box to an href, by box id. `flowfig atlas` sets it. */
+    links?: Record<string, string>;
 };
 /** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
-export declare function render(fig: FlowProps, opts?: SvgOptions): {
+export declare function render(spec: FlowProps, opts?: SvgOptions): {
     svg: string;
     scene: Scene;
 };

package/dist/svg.js

@@ -1,14 +1,16 @@
 // Wrapping is approximate: text is measured by character class, not by a browser.
-import { arcRoom, avoidOf, route } from './geometry.js';
+import { arcRoom, avoidOf, markSide, route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth, wrap } from './text.js';
 import { checkRendered, planFor } from './check.js';
+import { autoLayout, rowBreaks } from './auto.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, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
+export { diff, formatDiff, mergeFigures } 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, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, altText, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const SUB_LINE = 15;
+const MIN_W = 320;
 const FRAME_TOP = 37, FRAME_BOTTOM = 18;
 // The card-on fills approximate the player's 8 % accent tint.
 const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
@@ -159,13 +161,39 @@ function place(item, x, y, s, out) {
         }
     }
 }
+const MARK_COLOR = { added: TONES.green, removed: TONES.red, changed: TONES.orange };
+const marked = (mark, inner) => mark === 'removed' ? `<g opacity="0.5" stroke-dasharray="5 4">${inner}</g>` : mark ? `<g stroke-width="2">${inner}</g>` : inner;
+function legendOf(m) {
+    const count = (kind) => Object.values(m.boxes).filter((k) => k === kind).length + Object.values(m.edges).filter((k) => k === kind).length;
+    const items = ['added', 'removed', 'changed'].filter(count).map((k) => ({ color: MARK_COLOR[k], text: `${k} ${count(k)}` }));
+    if (m.steps)
+        items.push({ color: 'none', text: 'steps: see the text diff' });
+    return items.length ? items : [{ color: 'none', text: 'no change in boxes and edges' }];
+}
+const legendWidths = (items) => items.map((i) => textWidth(i.text, 12) + (i.color === 'none' ? 0 : 16));
+const legendWidth = (items) => legendWidths(items).reduce((a, b) => a + b + 20, -20);
+function legendSvg(items, W, H) {
+    if (!items.length)
+        return '';
+    const widths = legendWidths(items);
+    let x = (W - legendWidth(items)) / 2;
+    return items
+        .map((i, k) => {
+        const sq = i.color === 'none' ? '' : `<rect x="${n2(x)}" y="${n2(H - 24)}" width="10" height="10" rx="2" fill="${i.color}"/>`;
+        const out = `${sq}<text x="${n2(x + (i.color === 'none' ? 0 : 16))}" y="${n2(H - 15)}" font-size="12" fill="var(--muted)">${esc(i.text)}</text>\n`;
+        x += widths[k] + 20;
+        return out;
+    })
+        .join('');
+}
 const SYSTEM_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
 /** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
-export function render(fig, opts = {}) {
+export function render(spec, opts = {}) {
+    const fig = autoLayout(spec);
     const speed = (opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
     const pad = opts.padding ?? 24;
     const tl = fig.timeline && isLanesLayout(fig.layout) ? timelineLayout(fig, TL_AXIS_W) : null;
-    const synthetic = tl != null && !fig.steps?.length;
+    const synthetic = tl != null && !fig.steps?.length && !opts.marks;
     const steps = synthetic ? timelineBeats(fig) : (fig.steps ?? []);
     const beats = steps.map((s) => s.flow.map(toBeat));
     const cards = new Map();
@@ -233,6 +261,7 @@ export function render(fig, opts = {}) {
             to: end(ids[i], e.to, false),
             around: e.around ?? (plan?.around.has(ids[i]) ? 'below' : undefined),
             ...(tl && { sides: ['r', 'l'], elbow: true }),
+            ...(rowBreaks.has(e) && { drop: true }),
             ...(stubs.has(ids[i]) && { stub: stubs.get(ids[i]).map(labelPillW), bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)] }),
             ...(!tl && e.label != null && { labelW: labelPillW(str(e.label)) }),
         })), rects, tips, avoidOf(placed.filter((p) => !isGroup(p.item)), stubs.size
@@ -451,8 +480,13 @@ export function render(fig, opts = {}) {
                 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 tip = (inner) => (item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner);
-        const bt = item.tone && TONES[item.tone];
+        const diffMark = opts.marks?.boxes[item.id];
+        const href = opts.links?.[item.id];
+        const tip = (inner) => {
+            const body = marked(diffMark, item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner);
+            return href == null ? body : `<a href="${esc(href)}" tabindex="-1">${body}</a>`;
+        };
+        const bt = diffMark ? MARK_COLOR[diffMark] : 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)';
@@ -490,11 +524,13 @@ export function render(fig, opts = {}) {
                 ? `<text x="${n2(cx)}" y="${n2(firstY + extra + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>`
                 : '';
         const dot = bt ?? 'var(--accent)';
-        const my = n2(p.y + p.h / 2);
+        const side = item.mark && markSide(item.id, item.mark, routed);
+        const mx = n2(side === 'l' ? p.x - 12 : side === 'r' ? p.x + p.w + 12 : cx);
+        const my = n2(side === 't' ? p.y - 12 : side === 'b' ? p.y + p.h + 12 : p.y + p.h / 2);
         const mark = item.mark === 'start'
-            ? `<circle cx="${n2(p.x - 12)}" cy="${my}" r="5" fill="${dot}"/>`
+            ? `<circle cx="${mx}" 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}"/>`
+                ? `<circle cx="${mx}" cy="${my}" r="6.25" fill="none" stroke="${dot}" stroke-width="1.5"/><circle cx="${mx}" cy="${my}" r="4" fill="${dot}"/>`
                 : '';
         return tip(shape + label + sub + mark + (contents ? card(p, cardTop, contents) : ''));
     });
@@ -562,18 +598,21 @@ export function render(fig, opts = {}) {
         const lit = cls(toned
             ? frames(on.map((x, i) => (x ? `stroke: ${col[i]}; stroke-width: ${EDGE_ON}` : off)), 'e', off)
             : anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, off, 'e'));
+        const em = opts.marks?.edges[r.id];
+        const line = em && (em !== 'changed' || e.label == null) ? MARK_COLOR[em] : 'var(--muted)';
         const tip = edgeTip(r.id, e.source, beats.flat());
         const path0 = r.stub
             ? r.stub.parts
-                .map((d) => `<path d="${d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
+                .map((d) => `<path d="${d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
                 .join('') + `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="none"/>`
-            : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
+            : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
         const path = tip ? `<g><title>${esc(tip)}</title>${path0}</g>` : path0;
-        const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"` +
+        const pillColor = em ? MARK_COLOR[em] : undefined;
+        const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="${pillColor ? toneTint(pillColor, 'var(--bg)', 14) : 'var(--bg)'}" stroke="${pillColor ?? 'var(--border)'}"` +
             cls(toned
                 ? frames(on.map((x, i) => x ? `fill: ${tone[i] ? toneFill(col[i]) : col[i]}; stroke: ${col[i]}` : 'fill: var(--bg); stroke: var(--border)'), 'l', 'fill: var(--bg); stroke: var(--border)')
                 : anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
-            `/><text x="${n2(x)}" y="${n2(y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(text)}</text>`;
+            `/><text x="${n2(x)}" y="${n2(y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}${pillColor ? ' style="fill: var(--fg)"' : ''}>${esc(text)}</text>`;
         let label = '';
         if (r.stub) {
             fonts.push(11);
@@ -586,7 +625,7 @@ export function render(fig, opts = {}) {
             fonts.push(11);
             label = pill(r.mid.x, r.mid.y, lw, str(e.label));
         }
-        return hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label;
+        return marked(em === 'removed' ? em : undefined, hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label);
     });
     const packets = hops.map((h, i) => {
         const t0 = h.t0 / total, t1 = h.t1 / total, tEnd = h.tEnd / total;
@@ -683,16 +722,21 @@ export function render(fig, opts = {}) {
     }
     const bounds = placed[0];
     const [arcT, arcB, arcL, arcR] = ['above', 'below', 'left', 'right'].map((w) => arcRoom(routed, w));
-    const capLines = [...new Set(captions)].flatMap((c) => wrap(c, Math.max(560, bounds.w), 13.5).length);
-    const mapW = Math.max(bounds.w + pad * 2 + arcL + arcR, 560);
+    const legend = opts.marks ? legendOf(opts.marks) : [];
+    const stepLabels = fig.rail || synthetic ? [] : steps.map((s) => textWidth(str(s.label), 13, true));
+    const floor = Math.max(MIN_W, ...[...stepLabels, legend.length ? legendWidth(legend) : 0].map((w) => w + 16));
+    const mapW = Math.max(bounds.w + pad * 2 + arcL + arcR, floor);
     const rail = fig.rail ? layoutRail(fig, fig.rail === 'only' ? 560 : mapW) : null;
     const only = fig.rail === 'only' && rail != null;
+    const wrapW = Math.max(only ? 560 : MIN_W, bounds.w);
+    const capLines = [...new Set(captions)].flatMap((c) => wrap(c, wrapW, 13.5).length);
     const capTop = rail ? 20 : 26;
     const capH = steps.length ? capTop + 4 + Math.max(0, ...capLines) * 20 : 0;
-    const W = only ? Math.max(560, rail.width) : Math.max(mapW, rail?.width ?? 0);
+    const W = only ? Math.max(560, floor, rail.width) : Math.max(mapW, rail?.width ?? 0);
     const mapH = only ? 0 : bounds.h + pad * 2 + arcT + arcB;
     const top = only ? pad : mapH + RAIL.gap;
-    const H = only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH;
+    const legendH = opts.marks ? 34 : 0;
+    const H = (only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH) + legendH;
     const shift = (W - (bounds.w + pad * 2 + arcL + arcR)) / 2 + arcL;
     const railX = rail ? (W - rail.width) / 2 : 0;
     const labels = rail || synthetic
@@ -703,7 +747,7 @@ export function render(fig, opts = {}) {
         });
     const said = [...new Set(captions)].map((text) => {
         const on = captions.map((c) => c === text);
-        const lines = wrap(text, Math.max(560, bounds.w), 13.5);
+        const lines = wrap(text, wrapW, 13.5);
         return (`<g opacity="0"${cls(anim(on, 'opacity: 1', 'opacity: 0', 'y'))}>` +
             lines.map((l, li) => `<text x="${n2(W / 2)}" y="${n2(H - capH + capTop + 16 + li * 20)}" class="caption">${esc(l)}</text>`).join('') +
             `</g>`);
@@ -782,7 +826,11 @@ export function render(fig, opts = {}) {
             return `<g transform="translate(${n2(railX)} 0)">${parts.join('')}</g>`;
         })();
     const { font, ...t0 } = { ...LIGHT, ...fig.theme, ...opts.theme };
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}">
+    const alt = altText(fig);
+    const holdAt = beats[0]?.length ? n2(segs[beats[0].length - 1].t1 - 0.1) : 0;
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}" role="img">
+<title>${esc(alt.title)}</title>
+<desc>${esc(alt.desc)}</desc>
 <style>
 svg { ${vars(t0, '#eef5fd')} }
 @media (prefers-color-scheme: dark) { svg { ${vars(DARK, '#1d2733')} } }
@@ -806,6 +854,7 @@ svg { ${vars(t0, '#eef5fd')} }
 .railphase.muted { fill: var(--muted); }
 .end { text-anchor: end; }
 ${css.join('\n')}
+@media (prefers-reduced-motion: reduce) { * { animation-play-state: paused !important; animation-delay: -${holdAt}s !important; } }
 </style>
 <defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="context-stroke"/></marker></defs>
 <rect width="100%" height="100%" fill="var(--bg)"/>
@@ -823,10 +872,12 @@ ${todaySvg}
 `}${railSvg}
 ${labels.join('\n')}
 ${said.join('\n')}
-</svg>
+${legendSvg(legend, W, H)}</svg>
 `;
     if (rail)
         fonts.push(12, 13);
+    if (legend.length)
+        fonts.push(12);
     const scene = {
         width: n2(W),
         ...(!only && { area: { x: -shift, y: -arcT, w: W, h: mapH } }),

package/dist/trace.d.ts

@@ -0,0 +1,30 @@
+import { type Read } from './code.ts';
+export type TraceEdge = {
+    from: string;
+    to: string;
+    at: string;
+};
+export type TraceNote = {
+    at: string;
+    reason: string;
+};
+export type TraceResult = {
+    start: string;
+    edges: TraceEdge[];
+    unsure: TraceNote[];
+    open: TraceNote[];
+    stops: {
+        reason: 'depth' | 'max';
+        count: number;
+    }[];
+    outside: number;
+    ms: number;
+};
+export type TraceOptions = {
+    root?: string;
+    depth?: number;
+    max?: number;
+    read?: Read;
+};
+export declare function trace(start: string, { root, depth, max, read }?: TraceOptions): TraceResult;
+export declare function traceLines(r: TraceResult, depth: number, max: number): string[];