flowfig 0.6.0 → 0.8.0

package/dist/mcp.js

@@ -1,13 +1,12 @@
-// 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 { verify } from './verify.js';
+import { check, render } from './svg.js';
+import { checkRendered } from './check.js';
+import { coverageLine, unsureLines, verifyReport } from './verify.js';
 import { VERSION } from './version.js';
 const specSchema = {
     description: 'The figure: the props object, { props }, or a path to a .json file or an SVG that flowfig wrote.',
@@ -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);
@@ -117,6 +115,7 @@ function run(name, args) {
         types(args, name, { root: 'string', strict: 'boolean' });
         const root = args.root == null ? process.cwd() : String(args.root);
         const lines = [];
+        const counts = [];
         let errors = 0;
         for (const p of args.paths) {
             let props;
@@ -130,13 +129,15 @@ function run(name, args) {
                 lines.push(`${'error'.padEnd(8)} ${'missing-file'.padEnd(18)} ${e.message}`);
                 continue;
             }
-            const findings = sortFindings([...check(props), ...verify(props, { root })], args.strict === true);
+            const report = verifyReport(props, { root });
+            counts.push(coverageLine(p, report.coverage), ...unsureLines(report.coverage));
+            const findings = sortFindings([...check(props), ...report.findings], args.strict === true);
             errors += findings.filter((f) => f.severity === 'error').length;
             lines.push(...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${p}: ${f.message}`));
         }
         const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
         const total = lines.length;
-        lines.push(`${n(errors, 'error')}, ${n(total - errors, 'warning')}`);
+        lines.push(`${n(errors, 'error')}, ${n(total - errors, 'warning')}`, ...counts);
         return ok(lines.join('\n'), errors > 0);
     }
     if (name === 'diff') {
@@ -147,7 +148,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 +157,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 +196,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,10 +54,12 @@ 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;
+    /** The route, queue, topic or table that carries this edge. Checked by `flowfig verify`. */
+    via?: string;
 };
 /** One packet on one edge. A string is the edge `id`. */
 export type FigHop = string | {
@@ -67,12 +69,14 @@ 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;
+    /** The route, queue, topic or table that carries this edge. Checked by `flowfig verify`. */
+    via?: string;
 };
 /** One moment of a step. No edges means a pause. */
 export type FigBeat = {
@@ -80,13 +84,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 +108,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 +118,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 +133,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 +156,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;
@@ -161,33 +165,23 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         tone?: FigTone;
         async?: boolean;
         source?: string;
+        via?: string;
     }[];
 };
 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,27 +198,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 item the playhead rests on when the loop starts: the playhead item of the first beat of the first step. */
 export declare const loopStartItem: <T extends {
     id: string;
 }>(items: T[], steps: {
     flow: FigStep['flow'];
 }[]) => T | undefined;
-/** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
 export declare const outsideLabelRect: (bar: {
     x: number;
     y: number;
@@ -236,38 +223,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: {
@@ -280,58 +251,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;
@@ -339,16 +298,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;
@@ -362,7 +314,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`). */
@@ -370,21 +322,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;
@@ -392,8 +343,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;