flowfig 0.5.0 → 0.7.0

package/dist/init.js

@@ -1,7 +1,6 @@
-// `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, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 import { AGENT_TEXT, SKILL_DESCRIPTION } from './guide.js';
 import { runPicker } from './picker.js';
@@ -65,20 +64,20 @@ export const AGENTS = [
         mcp: { file: '.kiro/settings/mcp.json', key: 'mcpServers', global: '.kiro/settings/mcp.json' },
     },
 ];
-/** The ids of the agents that the repo at `dir` already uses. */
 export const detect = (dir) => AGENTS.filter((a) => a.marks.some((m) => existsSync(join(dir, m)))).map((a) => a.id);
-/** Toggle the agents named by numbers ("1 3" or "1,3"). A number out of range and other text are ignored. */
+/** Toggle the agents named by numbers ("1 3" or "1,3"). Ignore bad input. */
 export function toggle(input, selected, count) {
     const next = new Set(selected);
     for (const t of input.split(/[\s,]+/)) {
         const n = /^\d+$/.test(t) ? Number(t) : 0;
         const id = n >= 1 && n <= count ? AGENTS[n - 1].id : undefined;
-        if (id)
-            next.has(id) ? next.delete(id) : next.add(id);
+        if (id && next.has(id))
+            next.delete(id);
+        else if (id)
+            next.add(id);
     }
     return next;
 }
-/** The picker screen. */
 export function renderList(selected, detected, dir) {
     const rows = AGENTS.map((a, i) => {
         const found = detected.includes(a.id) ? `(${a.marks.find((m) => existsSync(join(dir, m)))} found)` : '';
@@ -93,25 +92,25 @@ export function renderList(selected, detected, dir) {
     ].join('\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. */
+/** The new file text, or `undefined` if the user owns the 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);
+    // An open block: the next run would eat the text after START.
     if (s !== -1 && e === -1)
-        return undefined; // an open block: the next run would eat the text after START
+        return undefined;
     if (s !== -1)
         return old.slice(0, s) + mine.trimEnd() + old.slice(e + END.length);
     return old + (old.endsWith('\n\n') ? '' : old.endsWith('\n') ? '\n' : '\n\n') + mine;
 }
-/** The MCP file with the flowfig entry merged in, or `undefined` when the file is not a JSON object that can hold it. */
+/** The MCP file with the flowfig entry, or `undefined` if the file cannot hold it. */
 export function registerMcp(a, old) {
     if (!a.mcp)
         return undefined;
@@ -127,18 +126,19 @@ export function registerMcp(a, old) {
     const servers = json[a.mcp.key] ?? {};
     if (typeof servers !== 'object' || servers === null || Array.isArray(servers))
         return undefined;
+    // Keep the entry: the user may have pinned a version.
     if ('flowfig' in servers)
-        return old; // the user may have pinned a version or set env: keep the entry
+        return old;
     const entry = a.mcp.type ? { ...MCP_ENTRY, type: 'stdio' } : MCP_ENTRY;
     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 shown = (path, base, global) => {
+    const rel = relative(base, path).split(sep).join('/');
+    return global ? `~/${rel}` : rel;
+};
 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);
@@ -245,8 +245,7 @@ export async function runInit(argv) {
                 mcpStatus = `would ${mcpStatus === 'created' ? 'create' : 'update'}`;
             else {
                 mkdirSync(dirname(mcpPath), { recursive: true });
-                // Same-folder temp file, then rename: a crash or a parallel write cannot leave half a file (~/.claude.json holds user settings).
-                // Resolve a symlink first, so the rename replaces the target and not the link. Copy the old mode to the new file.
+                // Rename a temp file over the symlink target, so a crash leaves no half file.
                 const real = existsSync(mcpPath) ? realpathSync(mcpPath) : mcpPath;
                 const tmp = `${real}.${process.pid}.tmp`;
                 try {
@@ -271,7 +270,6 @@ function fail(message) {
     console.error(message);
     return 2;
 }
-/** Ask on the terminal. Returns the chosen ids, or `undefined` if the user quits. */
 async function pick(start, detected, dir) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((res) => (rl.once('close', () => res(undefined)), rl.question(q, res)));

package/dist/load.d.ts

@@ -1,12 +1,10 @@
 import { type FlowProps } from './model.ts';
 import { type Finding, type SvgOptions } from './svg.ts';
-/** The spec JSON inside an SVG this package wrote. */
 export declare function specOf(svg: string, name: string): string;
 /** A spec from a `.json` or SVG path, or an object (`{ props }` or the props). Every error message starts with the name. */
 export declare function loadSpec(input: string | object, name?: string): FlowProps;
 /** The SVG with its spec in `<metadata>`: an SVG is then its own source. `]]>` would close the CDATA early, so it is escaped. */
-export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions): string;
-/** Errors first, then by rule name. `strict` makes every warning an error. */
+export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions, svg?: string): string;
 export declare function sortFindings(findings: Finding[], strict: boolean): Finding[];
 /** One line per finding, the counts line (unless `withCounts` is false), and the `figure:` line. No color: the CLI adds it. */
 export declare function reportLines(props: FlowProps, findings: Finding[], withCounts?: boolean): string[];

package/dist/load.js

@@ -1,10 +1,8 @@
-// What the CLI and the MCP server share: read a spec, write an SVG that carries its spec, and print the check lines.
 import { readFileSync } from 'node:fs';
 import { counts } from './model.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
-/** The spec JSON inside an SVG this package wrote. */
 export function specOf(svg, name) {
     const at = svg.indexOf(SPEC_OPEN);
     if (at === -1)
@@ -36,11 +34,10 @@ export function loadSpec(input, name = typeof input === 'string' ? input : 'spec
     return props;
 }
 /** The SVG with its spec in `<metadata>`: an SVG is then its own source. `]]>` would close the CDATA early, so it is escaped. */
-export function svgWithSpec(props, opts = {}) {
+export function svgWithSpec(props, opts = {}, svg = toSvg(props, opts)) {
     const spec = JSON.stringify({ props }).replaceAll(']]>', ']]\\u003e');
-    return toSvg(props, opts).replace(/(<svg[^>]*>\n?)/, (tag) => `${tag}${SPEC_OPEN}${spec}${SPEC_CLOSE}\n`);
+    return svg.replace(/(<svg[^>]*>\n?)/, (tag) => `${tag}${SPEC_OPEN}${spec}${SPEC_CLOSE}\n`);
 }
-/** Errors first, then by rule name. `strict` makes every warning an error. */
 export function sortFindings(findings, strict) {
     return findings
         .map((f) => (strict ? { ...f, severity: 'error' } : f))

package/dist/mcp.d.ts

@@ -133,7 +133,6 @@ export declare const TOOLS: ({
         required: string[];
     };
 })[];
-/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+/** Returns `undefined` for a notification. */
 export declare function handle(message: unknown): Response | undefined;
-/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
 export declare function serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;

package/dist/mcp.js

@@ -1,12 +1,11 @@
-// The MCP server: the check, render, verify, diff and docs tools over stdio JSON-RPC, for an agent with no shell.
-// No SDK: the subset the clients need is small, and the package keeps its zero dependencies.
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { diff, formatDiff } from './diff.js';
 import { GUIDE } from './guide.js';
 import { loadSpec, reportLines, sortFindings, svgWithSpec } from './load.js';
-import { check } from './svg.js';
+import { check, render } from './svg.js';
+import { checkRendered } from './check.js';
 import { verify } from './verify.js';
 import { VERSION } from './version.js';
 const specSchema = {
@@ -55,9 +54,9 @@ export const TOOLS = [
     },
 ];
 class Bad extends Error {
-} // bad params: a JSON-RPC error, not a tool result
+}
 class Fault extends Error {
-} // a path that cannot be read or written: a tool result with isError
+}
 const ok = (text, isError = false) => isError ? { content: [{ type: 'text', text }], isError: true } : { content: [{ type: 'text', text }] };
 const spec = (v, name) => {
     if (typeof v !== 'string' && (typeof v !== 'object' || v === null))
@@ -66,7 +65,6 @@ const spec = (v, name) => {
         return loadSpec(v);
     }
     catch (e) {
-        // The message of a path failure already starts with the path.
         throw typeof v === 'string' ? new Fault(e.message) : new Bad(`${name}: ${e.message}`);
     }
 };
@@ -75,7 +73,6 @@ const need = (args, tool, keys) => {
         if (args[k] == null)
             throw new Bad(`${tool}: ${k} is required`);
 };
-/** A present argument must have its type; a number must be positive. */
 const types = (args, tool, want) => {
     for (const [k, t] of Object.entries(want)) {
         const v = args[k];
@@ -94,13 +91,14 @@ function run(name, args) {
         types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
         const props = spec(args.spec, name);
         const opts = { width: args.width, minText: args.minText };
-        const findings = sortFindings(check(props, opts), args.strict === true);
+        const rendered = render(props, opts);
+        const findings = sortFindings(checkRendered(props, opts, rendered.scene), args.strict === true);
         const errors = findings.some((f) => f.severity === 'error');
         const lines = reportLines(props, findings);
         if (name === 'check' || errors)
             return ok(lines.join('\n'), errors);
         const out = String(args.out);
-        const svg = svgWithSpec(props, opts);
+        const svg = svgWithSpec(props, opts, rendered.svg);
         try {
             mkdirSync(dirname(out), { recursive: true });
             writeFileSync(out, svg);
@@ -147,7 +145,7 @@ function run(name, args) {
 }
 const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
 const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
-/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+/** Returns `undefined` for a notification. */
 export function handle(message) {
     if (typeof message !== 'object' || message === null)
         return fail(null, -32600, 'invalid request');
@@ -156,7 +154,7 @@ export function handle(message) {
     if (typeof method !== 'string')
         return notification ? undefined : fail(id, -32600, 'invalid request');
     if (notification)
-        return undefined; // a notification gets no reply, and a call sent as one does not run
+        return undefined;
     const info = { name: 'flowfig', version: VERSION };
     try {
         switch (method) {
@@ -195,7 +193,6 @@ export function handle(message) {
         return fail(id, -32603, e.message);
     }
 }
-/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
 export async function serve(input, output) {
     const rl = createInterface({ input, crlfDelay: Infinity });
     for await (const line of rl) {

package/dist/model.d.ts

@@ -1,41 +1,41 @@
 import type { ReactNode } from 'react';
 import type { Rect } from './geometry.ts';
-/** A box in the figure. A box with a `show` in some step becomes a content card: it grows to fit the most any step puts in it. */
+/** A box. A box with `show` in a step becomes a content card. */
 export type FigNode = {
-    /** Name that edges, steps and beats use to point at this box. Must be unique in the figure. */
+    /** Name that edges, steps and beats use for this box. Unique in the figure. */
     id: string;
     /** The title in the box. */
     label: ReactNode;
     /** A smaller line under the label. */
     sub?: ReactNode;
-    /** `box` is a rounded box, `decision` a diamond, `store` a database cylinder for data at rest. Default: `box`. */
+    /** `decision` is a diamond, `store` a cylinder for data at rest. Default: `box`. */
     shape?: 'box' | 'decision' | 'store';
-    /** The least number of text lines a content card keeps. The card still grows to fit its content. */
+    /** The least text lines a content card keeps. It still grows to fit. */
     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. */
+    /** In `lanes`: the 0-based time column. Default: the 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. */
+    /** In `timeline`: the start date, or the milestone date, 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. */
+    /** In `timeline`: the last day, as YYYY-MM-DD. No `to` makes 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. */
+    /** A permanent state color. An arriving hop with no 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. */
+    /** `start` draws a filled dot before the box, `end` a ringed dot after it. */
     mark?: 'start' | 'end';
-    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
 };
-/** A frame that lays out its children in a row or a column. Groups can hold groups. */
+/** A frame that lays out its children in a row or a column. */
 export type FigGroup = {
     /** Name that edges can point at, to reach the group as a whole. */
     id?: string;
-    /** The title on the frame. A group with a label is drawn as a frame around its children. */
+    /** The title on the frame. A labeled group is drawn as a frame. */
     label?: ReactNode;
     /** `row` puts the children side by side, `column` stacks them. Default: `row`. */
     direction?: 'row' | 'column';
-    /** Space between children in px. Default: 28 for a column. For a row, wide enough for the widest edge label between two children (at least 56). */
+    /** 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). */
     align?: 'start' | 'center' | 'end';
@@ -54,9 +54,9 @@ export type FigEdge = {
     label?: ReactNode;
     /** Routes the edge over or under the boxes in between (loops, skip-ahead edges). */
     around?: 'above' | 'below';
-    /** Draws the edge only while a step uses it. Use it for long edges that would cut across everything. */
+    /** Draws the edge only while a step uses it. */
     quiet?: boolean;
-    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
 };
 /** One packet on one edge. A string is the edge `id`. */
@@ -67,11 +67,11 @@ 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. */
+    /** Colors the packet, data card, edge and arrival box for this beat. 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`. */
+    /** Marks a message that needs no reply. The rail draws it dashed. Default: `false`. */
     async?: boolean;
-    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
 };
 /** One moment of a step. No edges means a pause. */
@@ -80,13 +80,13 @@ export type FigBeat = {
     edges?: FigHop | FigHop[];
     /** The line of narration for this beat. */
     say?: ReactNode;
-    /** Fills the content card of each named box. The card keeps it until the step ends. */
+    /** Fills the content card of each named box until the step ends. */
     show?: Record<string, FigContent>;
     /** Ids of boxes to highlight for this beat, without a packet or a content card. */
     light?: string[];
-    /** 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. */
+    /** Ids of boxes that take the active look in this beat. */
     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`. */
+    /** Beat length in ms. Default: `speed` plus the time to read `say`. */
     ms?: number;
 };
 /** One line of a content card. */
@@ -104,7 +104,7 @@ export type FigRow = {
     /** Draws the text in a monospace font. Default: `false`. */
     mono?: boolean;
 };
-/** The color of a row tag, a hop or a box. Each tone is a fixed color. */
+/** The color of a row tag, a hop or a box. */
 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;
@@ -114,12 +114,12 @@ export type FigStep = {
     label: ReactNode;
     /** The line shown under the figure while no beat of the step has a `say`. */
     caption?: ReactNode;
-    /** The beats in play order. A plain hop or hop array is a beat with just edges. */
+    /** The beats in play order. A bare hop or hop array is one beat. */
     flow: (FigHop | FigHop[] | FigBeat)[];
     /** Ids of boxes to highlight for the whole step. */
     nodes?: string[];
 };
-/** Colors for the figure. Each key sets one color, and a color you leave out keeps the built-in value. */
+/** Colors for the figure. A key you leave out keeps the built-in color. */
 export type FigTheme = Partial<Record<'accent' | 'fg' | 'muted' | 'bg' | 'surface' | 'border' | 'font', string>>;
 /** The spec of one figure. Give it to `Flow` (React) or to `toSvg` (SVG string). */
 export type FlowProps = {
@@ -129,21 +129,21 @@ export type FlowProps = {
     edges: FigEdge[];
     /** The stories the figure tells. With no steps, the figure is a still map. */
     steps?: FigStep[];
-    /** Colors. Can also be set from CSS with --fig-accent, --fig-bg, ... on `.flowfig`. `font` defaults to `inherit`. */
+    /** Colors. CSS `--fig-accent`, `--fig-bg` on `.flowfig` also set them. `font` defaults to `inherit`. */
     theme?: FigTheme;
     /** Milliseconds a packet takes to cross one edge. Default: 900. */
     speed?: number;
     /** Starts playing when the figure mounts. Default: `true`. Only the React player reads it. */
     autoplay?: boolean;
-    /** Development aid: run the `flowfig check` rules on what the browser drew, and print the faults with console.warn. Default: `false`. */
+    /** Dev aid: run the `flowfig check` rules on the drawn figure, then console.warn faults. */
     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`. */
+    /** Draws the steps as a lifeline rail under the map. `'only'` draws no map. */
     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. */
+    /** Draws the layout as swimlanes: a `column` group of labeled groups, one per role. */
     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. */
+    /** Draws a timeline: one labeled group per track, boxes placed by `from` and `to`. */
     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. */
+    /** In `timeline`: the date of the today marker, as YYYY-MM-DD. */
     today?: string;
 };
 /** A figure file's default export: a title, a source note and the props. */
@@ -152,7 +152,7 @@ export type Figure = {
     source?: string;
     props: FlowProps;
 };
-/** A beat with its hops spelled out: every hop has an edge id and a direction. */
+/** A beat with every hop spelled out: an edge id and a direction. */
 export type Beat = Omit<FigBeat, 'edges'> & {
     hops: {
         edge: string;
@@ -164,30 +164,19 @@ export type Beat = Omit<FigBeat, 'edges'> & {
     }[];
 };
 export declare const toBeat: (b: FigHop | FigHop[] | FigBeat) => Beat;
-/** A React node can be an object too, so a row is told apart by its `text` key. */
 export declare const isRows: (c: FigContent) => c is FigRow[];
 export declare const edgeId: (e: FigEdge) => string;
 export declare const isGroup: (x: FigNode | FigGroup) => x is FigGroup;
 export declare const decisions: (g: FigGroup) => string[];
-/** The width of a content card in px. Both renderers use it, so a figure lays out the same way in each. */
 export declare const CARD_WIDTH = 166;
-/** The player runs 1.25 times faster than the timings in a figure: figure timings are written to be read slowly. The SVG matches it. */
 export declare const BASE_RATE = 1.25;
-/** The height of one text line in a content card, and the padding above and below the lines. */
 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. */
 export declare const ASYNC_TAG_W: number;
-/** The stroke width in px of an edge that a packet crosses now, and of an idle edge. */
 export declare const EDGE_ON = 2, EDGE_OFF = 1.25;
-/** The built-in colors. Both renderers and `flowfig check` read these, so they cannot drift apart. */
 export declare const LIGHT: {
     accent: string;
     fg: string;
@@ -204,21 +193,20 @@ export declare const DARK: {
     surface: string;
     border: string;
 };
-/** Text on an accent fill: the data chips and a lit edge label. */
 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 loopStartItem: <T extends {
+    id: string;
+}>(items: T[], steps: {
+    flow: FigStep['flow'];
+}[]) => T | undefined;
 export declare const outsideLabelRect: (bar: {
     x: number;
     y: number;
@@ -230,38 +218,22 @@ export declare const outsideLabelRect: (bar: {
     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. */
+/** The time column of each box: first use in the steps, then layout order. `at` wins. */
 export declare function laneColumns(fig: FlowProps): Map<string, number>;
-/** The side of an SVG frame, and the width limits of a box with no card. The lane split measures with them. */
 export declare const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
-/** The gap between two blocks of wrapped lanes. */
 export declare const LANE_BLOCK_GAP = 40;
-/** The length of a stub line between a box and its pill, the clear space past a pill, and the room a lane grows by for a pill. */
 export declare const STUB = 12, STUB_CLEAR = 8, STUB_ROOM = 30;
 /** The width of a box as the SVG draws it, before a diamond adds its 70 px. */
 export declare function nodeWidth(item: FigNode, carded: boolean): number;
-/** The room a diamond of size w by h gives a text line whose far edge sits `far` px from the center: the width of the outline there, less 8 px. */
 export declare const diamondRoom: (w: number, h: number, far: number) => number;
-/** The lines of a diamond with no card. The sub wraps to the room the outline gives its last line; the diamond grows taller by 15 px
- * for each line until the lines fit. `dy` is the baseline of each line below the center, as the SVG draws it: the label sits 2 px
- * above the center over a one-line sub, and 5 px below it with no sub. `far` is the distance from the center to the far edge of the text. */
+/** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
 export declare function diamondLines(item: FigNode, w: number): {
     h: number;
     label: {
@@ -274,58 +246,46 @@ export declare function diamondLines(item: FigNode, w: number): {
         far: number;
     }[];
 };
-/** The lane copies (`laneIndex@block`) that hold a stub end with no place clear of every edge path. A renderer grows each by
- * STUB_ROOM and routes again: the pill then fits under or over its box, inside the band. Both renderers call it with their routes. */
+/** The lane copies whose stub end has no clear place. The renderer grows each by STUB_ROOM. */
 export declare function tightCopies(lanes: FigGroup[], ends: Map<string, [number, number]>, edges: FlowProps['edges'], routed: {
     id: string;
     stub?: {
         tight: [boolean, boolean];
     };
 }[]): Set<string>;
-/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
 export declare const laneGutter: (lanes: FigGroup[]) => number;
-/** How a lanes figure wraps. Both renderers lay out with it, so the player shows the blocks and stubs of the SVG. */
+/** How a lanes figure wraps. Both renderers lay out with it. */
 export type LanePlan = {
     /** The time column of each box. */
     cols: Map<string, number>;
-    /** The first column of each block, then the column count: block k holds columns starts[k] to starts[k + 1] - 1. */
+    /** The first column of each block, then the column count. */
     starts: number[];
     /** The most columns in one block. */
     per: number;
-    /** The blocks that hold a box, in order. A block with no box is not drawn. A figure with no box keeps block 0. */
+    /** The blocks that hold a box, in order. An empty figure keeps block 0. */
     blocks: number[];
     /** The width of the label gutter, the same in every block. */
     gutter: number;
-    /** The space after each column: the gap to the next column of its block, or the right margin of the band for the last one. */
+    /** The space after each column: the gap to the next, or the band margin. */
     gaps: number[];
     /** The room before the first column of each block, after the gutter. */
     lead: number[];
-    /** The block of the source and of the target of each edge, by edge id. A lane end names the copy of the lane in that block. */
+    /** The block of each edge source and target, by edge id. */
     ends: Map<string, [number, number]>;
-    /** The edges whose ends sit in two blocks, by edge id: the pill texts at the source and at the target, then a shorter source
-     * text without the edge label, if the edge has one. */
+    /** The pill texts of an edge across two blocks: source, target, then a short source. */
     stubs: Map<string, string[]>;
-    /** Edges between two boxes of one lane and one block, with a box of that lane between them and no `around` of their own.
-     * A straight route would cross that box, so the renderers route them around below. */
+    /** Same-lane, same-block edges with a box between them and no `around`. They route below. */
     around: Set<string>;
-    /** The lane copies (`laneIndex@block`) that grow by STUB_ROOM at the bottom: a stub pill there has no room beside its box. */
+    /** The lane copies (`laneIndex@block`) that grow by STUB_ROOM: a stub pill has no room. */
     tall: Set<string>;
-    /** Edges with a lane end that has no block on the side of the other end. They use the nearest block; `check` reports them. */
+    /** Edges with a lane end in no block on the other side. `check` reports them. */
     lost: string[];
 };
-/** The block of a time column, from the block starts of a plan. */
 export declare const laneBlock: (starts: number[], c: number) => number;
-/** The pill texts of a cross-block edge: "label → Target" at the source, "from Source" at the target, and "→ Target", a
- * shorter source text for a pill that has no place for the long one. */
 export declare const stubTexts: (label: unknown, from: unknown, to: unknown) => string[];
 /**
- * The wrap of a lanes figure. If all the time columns do not fit `width` with text at `minText` or more, the lanes wrap like a
- * line of text: block 1 holds columns 0..n-1, block 2 holds n..2n-1. n is the largest count that fits; it is 1 at least.
- * The text test is the one `check` runs: the smallest text (11 px, or 10.5 px with a mono card row) times width / figure width.
- * If the wrap cannot make the text readable, the lanes do not wrap: the smallest font is under `minText`, or `floor` (the least
- * width of the rest of the figure, such as the rail) is already too wide.
- * The blocks share the columns as evenly as they can, and a block holds 2 columns at least: if 2 do not fit, the lanes keep
- * one block. An edge between two blocks becomes two stubs with pills. A pill takes no room of its own, so n depends on the boxes.
+ * The wrap of a lanes figure: it wraps like text when the time columns do not fit `width`.
+ * The block count depends on the boxes only, not on pills.
  */
 export declare function lanePlan(fig: FlowProps, { width, minText, padding, floor }?: {
     floor?: number | undefined;
@@ -333,16 +293,9 @@ export declare function lanePlan(fig: FlowProps, { width, minText, padding, floo
     padding?: number | undefined;
     width?: number | undefined;
 }): LanePlan;
-/**
- * The rect id that an edge end routes to in wrapped lanes. A box keeps its id. A lane has one band per block, so a lane end names
- * the band in the block from the plan (`band` finds it). A stub end at a lane is a point inside that band: the source at the band
- * end, past the room for its pill, and the target at the first column of the block. The function adds the rect it names to `rects`.
- */
+/** The rect id that an edge end routes to in wrapped lanes. A stub end is a point in the band. */
 export declare function laneEnd(plan: LanePlan, edge: string, id: string, start: boolean, band: (lane: string, block: number) => Rect | undefined, rects: Record<string, Rect>): string;
-/** 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;
@@ -356,7 +309,7 @@ export type TimelineItem = {
     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. */
+    /** The range in days, rounded out to whole Monday-to-Sunday weeks. */
     start: number;
     end: number;
     /** The week ticks (`W41`) or the month ticks (`Oct`). */
@@ -364,21 +317,20 @@ export type TimelineLayout = {
         x: number;
         label: string;
     }[];
-    /** Bars and milestones. `x` and `w` are px inside the axis; `row` is the stack row inside the track. */
+    /** Bars and milestones. `x` and `w` are px in the axis. */
     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`. */
+    /** The x of the today marker, or null with 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. */
+    /** The x and date of the last day. Null x: 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". */
+/** One step with one beat for each dated item, in date order. */
 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;
     groups: number;
@@ -386,8 +338,5 @@ export declare const counts: (p: FlowProps) => {
     steps: number;
     messages: number;
 };
-/**
- * A group's gap. A row's default gap grows to hold the widest label of an edge between two of its children, with 8px each side:
- * the label sits at the middle of that gap. A gap the author sets stays as set; `flowfig check` reports it if it is too narrow.
- */
+/** A row's default gap grows to hold its widest edge label, plus 8 px each side. */
 export declare function groupGap(g: FigGroup, edges: FigEdge[]): number;