flowfig 0.3.0 → 0.5.0

package/dist/init.js

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

package/dist/mcp.js

@@ -100,7 +100,7 @@ function run(name, args) {
         if (name === 'check' || errors)
             return ok(lines.join('\n'), errors);
         const out = String(args.out);
-        const svg = svgWithSpec(props);
+        const svg = svgWithSpec(props, opts);
         try {
             mkdirSync(dirname(out), { recursive: true });
             writeFileSync(out, svg);

package/dist/model.d.ts

@@ -1,4 +1,5 @@
 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. */
 export type FigNode = {
     /** Name that edges, steps and beats use to point at this box. Must be unique in the figure. */
@@ -13,8 +14,16 @@ export type FigNode = {
     lines?: number;
     /** Width in px. Overrides the width the layout picks. */
     width?: number;
+    /** In a `lanes` figure: the time column of the box, 0-based. Default: the box's first appearance in the steps. */
+    at?: number;
+    /** In a `timeline` figure: the start of the item, or the date of a milestone, as YYYY-MM-DD. */
+    from?: string;
+    /** In a `timeline` figure: the last day of the item, as YYYY-MM-DD. The day counts. Without it the box is a milestone. */
+    to?: string;
     /** A permanent state color for the box, such as a failing part. It gives a 1 px border and a light tint. An arrival with no hop tone uses it too. */
     tone?: FigTone;
+    /** A lifecycle mark: `start` draws a filled dot before the box, `end` a ringed dot after it. No layout change. */
+    mark?: 'start' | 'end';
     /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
     source?: string;
 };
@@ -75,6 +84,8 @@ export type FigBeat = {
     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. */
+    focus?: string[];
     /** How long the beat lasts in ms. The packet crosses in `speed`; the rest is a hold. An explicit `ms` wins as written. Default: `speed` plus the time to read `say`. */
     ms?: number;
 };
@@ -128,6 +139,12 @@ export type FlowProps = {
     check?: boolean;
     /** Draw the steps as a lifeline rail under the map: one row for each message, with its payload. `'only'` draws the rail without the map. Default: `false`. */
     rail?: boolean | 'only';
+    /** Draw the layout as swimlanes: a `column` group of labeled groups, one per role, with the boxes in time order left to right. Default: off. */
+    lanes?: true;
+    /** Draw the layout as a timeline: one labeled group per track, with the boxes placed by their `from` and `to` dates. Default: off. */
+    timeline?: true;
+    /** In a `timeline` figure: the date of the fixed today marker, as YYYY-MM-DD. With no `today`, the figure has no marker. */
+    today?: string;
 };
 /** A figure file's default export: a title, a source note and the props. */
 export type Figure = {
@@ -195,9 +212,172 @@ export declare const str: (n: unknown) => string;
 export declare const readMs: (say: unknown) => number;
 /** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
 export declare const beatMs: (b: Beat, speed: number) => number;
+/** The item the playhead rests on at beat `i`: the first dated id in the latest focus up to `i`, or undefined for home. */
+export declare const playheadItem: <T extends {
+    id: string;
+}>(items: T[], beats: {
+    focus?: string[];
+}[], i: number) => T | undefined;
+/** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
+export declare const outsideLabelRect: (bar: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, label: string) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * The time span in which the playhead label shows its date. The label waits for the line to arrive: it stays hidden for
+ * the ramp (the move), so it never shows a date at a place that is not that date, and it never meets "today" on the way.
+ */
+export declare const labelSpan: (t0: number, end: number, ramp: number) => [number, number];
+/** True if a playhead date label at x would overlap the "today" label, so it moves to the top row. Widths are in px. */
+export declare const dateLabelRaised: (x: number, today: number | null | undefined, w: number, todayW: number) => boolean;
 /** The hold at the end of each step, before the next step starts. */
 export declare const STEP_HOLD_MS = 2000;
 export declare const nodes: (g: FigGroup) => FigNode[];
+/** Lane layout constants, shared by both renderers: the gap between time columns, the padding inside a lane, and the gap between lanes. */
+export declare const LANE_GAP = 56, LANE_PAD = 24, LANE_ROW_GAP = 20;
+/** True if the layout can draw as lanes: a `column` group whose every child is a labeled group with boxes only. */
+export declare const isLanesLayout: (g: FigGroup) => boolean;
+/** True if `at` is a usable time column: an integer of 0 or more. */
+export declare const validAt: (at: unknown) => at is number;
+/** The time column of each box in a lanes figure: its first appearance in the steps (from, then to; a back hop to, then from),
+ * then the boxes no step touches in layout order. `at` overrides. Two boxes may share a column. */
+export declare function laneColumns(fig: FlowProps): Map<string, number>;
+/** 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. */
+export declare function diamondLines(item: FigNode, w: number): {
+    h: number;
+    label: {
+        dy: number;
+        far: number;
+    };
+    subs: {
+        text: string;
+        dy: 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. */
+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. */
+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. */
+    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. */
+    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. */
+    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. */
+    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. */
+    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. */
+    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. */
+    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. */
+    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.
+ */
+export declare function lanePlan(fig: FlowProps, { width, minText, padding, floor }?: {
+    floor?: number | undefined;
+    minText?: number | undefined;
+    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`.
+ */
+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;
+    track: number;
+    row: number;
+    x: number;
+    w: number;
+    milestone: boolean;
+    labelInside: boolean;
+    /** The `from` date in the d MMM form, for the playhead label. */
+    date: string;
+};
+export type TimelineLayout = {
+    /** The range in days, rounded out to whole weeks: the Monday of the first week and the Sunday of the last week. */
+    start: number;
+    end: number;
+    /** The week ticks (`W41`) or the month ticks (`Oct`). */
+    ticks: {
+        x: number;
+        label: string;
+    }[];
+    /** Bars and milestones. `x` and `w` are px inside the axis; `row` is the stack row inside the track. */
+    items: TimelineItem[];
+    /** The row count of each track. */
+    rows: number[];
+    /** The x of the today marker. It is null when the figure has no valid `today`. */
+    today: number | null;
+    /** The x and the d MMM date of the last day: the playhead rests there in the step hold. The x is null when the figure has no dated item. */
+    last: number | null;
+    lastDate: string;
+};
+/** Where each dated item, tick and the today line sit on the axis, `axisWidth` px wide. Both renderers call it. */
+export declare function timelineLayout(fig: FlowProps, axisWidth: number): TimelineLayout;
+/** One step, "timeline", with one beat for each dated item in date order. The beat lights the item and says "label, d MMM to d MMM" (a milestone: "label, d MMM"), then " · sub". */
+export declare function timelineBeats(fig: FlowProps): FigStep[];
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
 export declare const counts: (p: FlowProps) => {
     boxes: number;