flowfig 0.5.0 → 0.7.0

package/dist/model.js

@@ -8,18 +8,14 @@ export const toBeat = (b) => {
         hops: hops.map((h) => (typeof h === 'string' ? { edge: h, back: false } : { back: false, ...h })),
     };
 };
-/** A React node can be an object too, so a row is told apart by its `text` key. */
+// A React node can be an object, so test for the `text` key.
 export const isRows = (c) => Array.isArray(c) && c.every((r) => r != null && typeof r === 'object' && 'text' in r);
 export const edgeId = (e) => e.id ?? `${e.from}->${e.to}`;
 export const isGroup = (x) => 'children' in x;
 export const decisions = (g) => g.children.flatMap((c) => (isGroup(c) ? decisions(c) : c.shape === 'decision' ? [c.id] : []));
-/** The width of a content card in px. Both renderers use it, so a figure lays out the same way in each. */
 export 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 const BASE_RATE = 1.25;
-/** The height of one text line in a content card, and the padding above and below the lines. */
 export const CARD_LINE = 15, CARD_PAD = 6;
-/** The fixed color of each row tone. */
 export const TONES = {
     blue: '#3b82f6',
     purple: '#8b5cf6',
@@ -28,32 +24,22 @@ export const TONES = {
     red: '#ef4444',
     gray: '#8b949e',
 };
-/** A tone as a fill under white text: darker, so the text keeps its contrast. */
 export const toneFill = (c) => `color-mix(in srgb, ${c} 64%, #000)`;
-/** The light tint of a tone over a background: the fill of a toned box. */
 export const toneTint = (c, bg, pct = 8) => `color-mix(in srgb, ${c} ${pct}%, ${bg})`;
-/** 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 const labelPillW = (label) => textWidth(label, 11, true) + 14;
-/** The width of the `async` tag in px. */
 export const ASYNC_TAG_W = textWidth('ASYNC', 9) + 8;
-/** The stroke width in px of an edge that a packet crosses now, and of an idle edge. */
 export 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 const LIGHT = { accent: '#0074d9', fg: '#1c1e21', muted: '#606770', bg: '#ffffff', surface: '#f5f7fa', border: '#d0d7de' };
-// The dark accent is darker than a typical dark-mode blue: white text sits on it and needs 4.5:1.
+// White text on the dark accent needs 4.5:1 contrast.
 export const DARK = { accent: '#1f78c8', fg: '#e3e3e3', muted: '#9aa0a6', bg: '#1b1b1d', surface: '#242526', border: '#3a3b3c' };
-/** Text on an accent fill: the data chips and a lit edge label. */
 export const ON_ACCENT = '#ffffff';
-/** Only text survives outside React: a React element has no string form. */
+// A React element has no string form, so only text survives.
 export const str = (n) => (typeof n === 'string' || typeof n === 'number' ? String(n) : '');
-/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
 export const readMs = (say) => {
     const w = str(say).split(/\s+/).filter(Boolean).length;
     return w ? 400 + 240 * w : 0;
 };
-/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
 export const beatMs = (b, speed) => b.ms ?? speed + readMs(b.say);
-/** 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 const playheadItem = (items, beats, i) => {
     for (let k = Math.min(i, beats.length - 1); k >= 0; k--) {
         const id = (beats[k].focus ?? []).find((f) => items.some((x) => x.id === f));
@@ -62,31 +48,21 @@ export const playheadItem = (items, beats, i) => {
     }
     return undefined;
 };
-/** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
+export const loopStartItem = (items, steps) => playheadItem(items, (steps[0]?.flow ?? []).slice(0, 1).map(toBeat), 0);
 export const outsideLabelRect = (bar, label) => ({
     x: bar.x + bar.w + 6,
     y: bar.y,
     w: textWidth(label, 13),
     h: bar.h,
 });
-/**
- * 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 const labelSpan = (t0, end, ramp) => [Math.min(t0 + ramp, end), end];
-/** 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 const dateLabelRaised = (x, today, w, todayW) => today != null && x + 3 < today - 3 && x + 3 + w > today - 3 - todayW;
-/** The hold at the end of each step, before the next step starts. */
 export const STEP_HOLD_MS = 2000;
 export const nodes = (g) => g.children.flatMap((c) => (isGroup(c) ? nodes(c) : [c]));
-/** Lane layout constants, shared by both renderers: the gap between time columns, the padding inside a lane, and the gap between lanes. */
 export 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 const isLanesLayout = (g) => g.direction === 'column' && g.children.every((c) => isGroup(c) && c.label != null && c.children.every((k) => !isGroup(k)));
-/** True if `at` is a usable time column: an integer of 0 or more. */
 export const validAt = (at) => typeof at === 'number' && Number.isInteger(at) && at >= 0;
-/** 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 function laneColumns(fig) {
     const byId = new Map(fig.edges.map((e) => [edgeId(e), e]));
     const cols = new Map();
@@ -110,11 +86,8 @@ export function laneColumns(fig) {
             cols.set(n.id, n.at);
     return cols;
 }
-/** The side of an SVG frame, and the width limits of a box with no card. The lane split measures with them. */
 export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
-/** The gap between two blocks of wrapped lanes. */
 export 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 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 function nodeWidth(item, carded) {
@@ -126,11 +99,8 @@ export function nodeWidth(item, carded) {
     const sub = textWidth(str(item.sub), 12) + 32;
     return Math.min(NODE_MAX_W, Math.max(NODE_MIN_W, label, sub));
 }
-/** 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 const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
-/** 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 function diamondLines(item, w) {
     const sub = item.sub ? str(item.sub) : '';
     for (let n = sub ? 1 : 0;; n++) {
@@ -147,8 +117,7 @@ export function diamondLines(item, w) {
             };
     }
 }
-/** 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 function tightCopies(lanes, ends, edges, routed) {
     const laneOf = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
     const out = new Set();
@@ -164,30 +133,21 @@ export function tightCopies(lanes, ends, edges, routed) {
     }
     return out;
 }
-/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
 export const laneGutter = (lanes) => Math.max(0, ...lanes.map((l) => textWidth(str(l.label).toUpperCase(), 12))) + FRAME_SIDE * 2;
-/** The block of a time column, from the block starts of a plan. */
 export const laneBlock = (starts, c) => {
     let k = 0;
     while (k < starts.length - 2 && c >= starts[k + 1])
         k++;
     return k;
 };
-/** 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 const stubTexts = (label, from, to) => [
     `${str(label) ? str(label) + ' ' : ''}→ ${str(to)}`,
     `from ${str(from)}`,
     ...(str(label) ? [`→ ${str(to)}`] : []),
 ];
 /**
- * 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 function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor = 0 } = {}) {
     const cols = laneColumns(fig);
@@ -208,7 +168,6 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
     const laneOf = new Map(lanes.filter((l) => l.id != null).map((l) => [l.id, l]));
     const gutter = laneGutter(lanes);
     const plan = (count) => {
-        // count blocks share the n columns evenly; the first n % count blocks take one column more.
         const starts = [0];
         for (let k = 0; k < count; k++)
             starts.push(starts[k] + Math.floor(n / count) + (k < n % count ? 1 : 0));
@@ -217,7 +176,6 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
         const held = [...new Set([...byId.keys()].map(blockOf))].sort((a, b) => a - b);
         const blocks = held.length ? held : [0];
         const wrapped = blocks.length > 1;
-        // The blocks that show a lane: a wrapped block shows only the lanes with a box in it.
         const showing = (l) => wrapped ? [...new Set(l.children.map((b) => blockOf(b.id)))].sort((a, b) => a - b) : blocks;
         const stubs = new Map();
         const ends = new Map();
@@ -227,7 +185,6 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
             const [fl, tl] = [laneOf.get(e.from), laneOf.get(e.to)];
             if (!(byId.has(e.from) || fl) || !(byId.has(e.to) || tl))
                 return;
-            // A lane source takes the last block at or before the target that shows it; a lane target the first at or after the source.
             let miss = false;
             const near = (l, k, after) => {
                 const ks = showing(l);
@@ -258,9 +215,7 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
             const texts = stubTexts(e.label, (byId.get(e.from) ?? fl).label, (byId.get(e.to) ?? tl).label);
             stubs.set(id, texts);
         });
-        // A pill takes no room of its own: the route puts it in free space (route() in geometry.ts), so n depends on the boxes only.
-        // A label on an edge between two next columns of one block sits in the gap between them. A label too wide for the gap would
-        // cover a box, so that gap grows to the label plus 8 px. A label that fits keeps the gap of 0.4.0.
+        // A label wider than the gap would cover a box, so the gap grows.
         const label = Array.from({ length: n }, () => 0);
         for (const e of fig.edges) {
             const [a, b] = [cols.get(e.from), cols.get(e.to)];
@@ -273,8 +228,6 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
         const gaps = colW.map((_, c) => (c === starts[colBlock(c) + 1] - 1 ? FRAME_SIDE : Math.max(LANE_GAP, label[c])));
         const per = Math.max(...starts.slice(1).map((e, k) => e - starts[k]));
         const lead = Array.from({ length: count }, () => 0);
-        // A pill takes free room only: a gap next to a stub end grows for its pill while the block still fits the width. So the
-        // block count never depends on a pill. A pill with no room finds a free place in route() (geometry.ts).
         const want = (text) => STUB + labelPillW(text) + STUB_CLEAR;
         const fit = blocks.every((k) => widthOf(starts[k], starts[k + 1], gaps, 0) <= room);
         const out = new Map(), inn = new Map();
@@ -303,10 +256,9 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
                 const need = (out.get(c) ?? 0) + (c < end - 1 ? (inn.get(c + 1) ?? 0) : 0);
                 grow(need - gaps[c], () => (gaps[c] = need));
                 if (gaps[c] >= need)
-                    roomOut.add(c).add(-1 - (c + 1)); // -1 - c marks room before column c
+                    roomOut.add(c).add(-1 - (c + 1));
             }
         }
-        // A stub end with no room beside its box makes its lane taller in that block: the pill then fits under the box, inside the band.
         const laneIndex = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
         const tall = new Set();
         for (const [id] of stubs) {
@@ -330,11 +282,8 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
         return [{ cols, starts, per, blocks, gutter, gaps, lead, ends, stubs, around, tall, lost }, fit];
     };
     const widthOf = (c, end, gaps, lead) => gutter + lead + colW.slice(c, end).reduce((a, w) => a + w, 0) + gaps.slice(c, end).reduce((a, g) => a + g, 0);
-    // The wrap only narrows the lanes. If the text stays too small at any width, keep one block, and check reports small-text.
     if (font < minText || floor > limit)
         return plan(1)[0];
-    // A block has 2 columns at least: one column per block reads as a list, not as lanes. If 2 do not fit, keep one block.
-    // The fit uses the boxes and the label gaps only, before a pill takes free room.
     for (let count = 1; count <= Math.max(1, Math.floor(n / 2)); count++) {
         const [p, fit] = plan(count);
         if (fit)
@@ -342,11 +291,7 @@ export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor =
     }
     return plan(1)[0];
 }
-/**
- * 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 function laneEnd(plan, edge, id, start, band, rects) {
     const k = plan.ends.get(edge)?.[start ? 0 : 1];
     const b = k == null ? undefined : band(id, k);
@@ -358,10 +303,7 @@ export function laneEnd(plan, edge, id, start, band, rects) {
     rects[key] = texts ? { x, y: b.y, w: 0, h: b.h } : b;
     return key;
 }
-/** 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 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 const dayOf = (iso) => {
     const m = typeof iso === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso) : null;
     if (!m)
@@ -373,14 +315,12 @@ const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', '
 const dateOf = (day) => new Date(day * 86400000);
 // Day 0 is a Thursday, so this is 0 for Monday and 6 for Sunday.
 const weekday = (day) => (((day + 3) % 7) + 7) % 7;
-/** The ISO 8601 week number of a day: the week of the year's first Thursday is week 1. */
+// ISO 8601: the week with the first Thursday of the year is week 1.
 const isoWeek = (day) => {
     const thu = day - weekday(day) + 3;
     const jan1 = Date.UTC(dateOf(thu).getUTCFullYear(), 0, 1) / 86400000;
     return Math.floor((thu - jan1) / 7) + 1;
 };
-/** The boxes with a real `from`, in layout order, with their track (the index of the top-level child) and their days.
- * A `to` that is not a date, or is before `from`, makes the box a milestone; `checkSpec` reports it. */
 const datedItems = (fig) => {
     const out = [];
     fig.layout.children.forEach((c, track) => nodes(isGroup(c) ? c : { children: [c] }).forEach((n) => {
@@ -402,7 +342,7 @@ export function timelineLayout(fig, axisWidth) {
     const start = first - weekday(first);
     let end = last + (6 - weekday(last));
     const px = (day) => ((day - start) / (end - start + 1)) * axisWidth;
-    // A label right of the last items may pass the axis end. Add whole weeks and lay out again; after 4 passes the label stays and `check` reports it.
+    // After 4 passes the label stays, and `check` reports it.
     for (let pass = 0; pass < 4; pass++) {
         const over = Math.max(0, ...items.map((i) => {
             const x = i.to != null ? px(i.from) : px(i.from) - TL_DIAMOND / 2;
@@ -424,22 +364,21 @@ export function timelineLayout(fig, axisWidth) {
                 ticks.push({ x: px(d), label: MONTHS[dateOf(d).getUTCMonth()] });
     const rows = fig.layout.children.map(() => 1);
     const placed = [];
-    const busy = fig.layout.children.map(() => []); // per track: the px end of the latest item in each row, with its label
-    const GAP = 8; // the least px between two items in a row
+    const rowEnd = fig.layout.children.map(() => []);
+    const MIN_ITEM_GAP = 8;
     for (const i of [...items].sort((a, b) => a.from - b.from)) {
         const bar = i.to != null;
         const x = bar ? px(i.from) : px(i.from) - TL_DIAMOND / 2;
         const w = bar ? Math.max(TL_MIN_BAR, px(i.to + 1) - px(i.from)) : TL_DIAMOND;
         const need = textWidth(str(i.label.label), 13);
         const labelInside = bar && need + 16 <= w;
-        let row = busy[i.track].findIndex((until) => until + GAP <= x);
+        let row = rowEnd[i.track].findIndex((until) => until + MIN_ITEM_GAP <= x);
         if (row < 0)
-            row = busy[i.track].length;
-        busy[i.track][row] = labelInside ? x + w : x + w + 6 + need;
+            row = rowEnd[i.track].length;
+        rowEnd[i.track][row] = labelInside ? x + w : x + w + 6 + need;
         rows[i.track] = Math.max(rows[i.track], row + 1);
         placed.push({ id: i.id, track: i.track, row, x, w, milestone: !bar, labelInside, date: fmt(i.from) });
     }
-    // Keep the layout order in the result.
     const order = new Map(items.map((i, k) => [i.id, k]));
     placed.sort((a, b) => order.get(a.id) - order.get(b.id));
     return {
@@ -454,7 +393,7 @@ export function timelineLayout(fig, axisWidth) {
     };
 }
 const fmt = (d) => `${dateOf(d).getUTCDate()} ${MONTHS[dateOf(d).getUTCMonth()]}`;
-/** 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 function timelineBeats(fig) {
     const items = datedItems(fig).sort((a, b) => a.from - b.from);
     const flow = items.map((i, k) => ({
@@ -465,9 +404,7 @@ export function timelineBeats(fig) {
     return [{ label: 'timeline', flow }];
 }
 const labeledGroups = (g) => (g.label ? 1 : 0) + g.children.reduce((n, c) => n + (isGroup(c) ? labeledGroups(c) : 0), 0);
-/** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
 export const counts = (p) => {
-    // A timeline with no steps plays one synthetic step.
     const st = p.timeline && isLanesLayout(p.layout) && !p.steps?.length ? timelineBeats(p) : (p.steps ?? []);
     return {
         boxes: nodes(p.layout).length,
@@ -477,12 +414,8 @@ export const counts = (p) => {
         messages: st.reduce((n, s) => n + s.flow.reduce((m, b) => m + toBeat(b).hops.length, 0), 0),
     };
 };
-/** Every id inside a child: its own id, and the ids of all boxes and groups below it. */
 const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
-/**
- * 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 function groupGap(g, edges) {
     if (g.gap != null)
         return g.gap;

package/dist/open.d.ts

@@ -3,13 +3,10 @@ export type Opener = {
     args: string[];
     verbatim: boolean;
 };
-/** The command that opens a file in the default program of the system. Pure. */
 export declare function openerFor(platform: NodeJS.Platform, file: string): Opener;
-/** The name of the temp page: the SVG base name, each character other than a letter, a digit, - or _ as -. */
+/** The temp page name: each character other than a letter, digit, - or _ becomes -. */
 export declare function pageName(svgPath: string): string;
-/** The line that `open`, a render with `--open` and `draw --open` print. */
 export declare const openedLine: (page: string) => string;
-/** Write the page to a new temp folder (and to `html`, if given), then start the opener. Returns the written paths. */
+/** 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[]>;
-/** `flowfig open`: parse argv, call openSvg, print. Returns the exit code. */
 export declare function runOpen(argv: string[]): Promise<number>;

package/dist/open.js

@@ -1,39 +1,35 @@
-// `flowfig open`: show a figure in the default browser. An .svg file often opens in an editor; an .html page opens in a browser.
 import { spawn } from 'node:child_process';
 import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { pageHtml } from './page.js';
 const USAGE = 'usage: flowfig open <figure.svg> [--html <path>]';
-/** The command that opens a file in the default program of the system. Pure. */
 export function openerFor(platform, file) {
     if (platform === 'darwin')
         return { cmd: 'open', args: [file], verbatim: false };
-    // `start` reads its first quoted argument as a window title, so an empty title goes first.
+    // `start` reads its first quoted argument as a window title.
     if (platform === 'win32')
         return { cmd: 'cmd', args: ['/c', 'start', '""', `"${file}"`], verbatim: true };
     return { cmd: 'xdg-open', args: [file], verbatim: false };
 }
-/** The name of the temp page: the SVG base name, each character other than a letter, a digit, - or _ as -. */
+/** The temp page name: each character other than a letter, digit, - or _ becomes -. */
 export function pageName(svgPath) {
-    // The safe name also keeps cmd metacharacters such as & out of the Windows command line.
+    // The safe name keeps cmd metacharacters such as & out of the command line.
     return (basename(svgPath)
         .replace(/\.svg$/, '')
         .replace(/[^\w-]/g, '-') + '.html');
 }
-/** The line that `open`, a render with `--open` and `draw --open` print. */
 export const openedLine = (page) => `${page} — opened in the default browser`;
-/** Write the page to a new temp folder (and to `html`, if given), then start the opener. Returns the written paths. */
+/** 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));
-    // A fresh private folder (mode 0700): a fixed shared path lets another user plant a symlink there.
+    // A fixed shared path lets another user plant a symlink.
     const dir = mkdtempSync(join(tmpdir(), 'flowfig-open-'));
-    // The page stays after the exit: the browser reads it after the CLI stops.
+    // The browser reads the page after the CLI stops, so keep it.
     const temp = join(dir, pageName(svgPath));
     writeFileSync(temp, page);
     if (html)
         writeFileSync(html, page);
-    // FLOWFIG_OPENER replaces the system opener, so the tests start no browser.
     const o = process.env.FLOWFIG_OPENER
         ? { cmd: process.env.FLOWFIG_OPENER, args: [temp], verbatim: false }
         : openerFor(process.platform, temp);
@@ -44,7 +40,6 @@ export async function openSvg(svgPath, html) {
     });
     return html ? [temp, html] : [temp];
 }
-/** `flowfig open`: parse argv, call openSvg, print. Returns the exit code. */
 export async function runOpen(argv) {
     const fail = (message, code) => (console.error(message), code);
     const args = [...argv];

package/dist/page.d.ts

@@ -1,2 +1 @@
-/** The page: the figure SVG inline, centered, scaled down to the window width. The title is escaped. */
 export declare function pageHtml(svg: string, title: string): string;

package/dist/page.js

@@ -1,8 +1,6 @@
-// The page that holds a figure SVG: `flowfig open` shows it in the default browser, and `flowfig gif` captures it. Pure.
 const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-/** The page: the figure SVG inline, centered, scaled down to the window width. The title is escaped. */
 export function pageHtml(svg, title) {
-    // Element selectors only: the figure styles use class names, so the two sets of rules do not meet.
+    // Use element selectors only: figure styles use class names.
     return `<!doctype html>
 <meta charset="utf-8">
 <title>${esc(title)}</title>

package/dist/picker.d.ts

@@ -23,11 +23,9 @@ export type Picked = {
     ids: Set<string>;
     mcp: boolean;
 };
-/** The banner lines. A terminal narrower than the banner gets the plain version line. */
+/** A terminal narrower than the banner gets the plain version line. */
 export declare function banner({ color, width }: Screen): string[];
-/** The picker screen, one string per line. */
 export declare function screen(s: PickState, o: Screen): string[];
-/** One key press. Returns the next state, or `confirm` or `cancel`. */
 export declare function keyStep(s: PickState, k: Key): PickState | 'confirm' | 'cancel';
-/** Run the picker on the terminal. Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
+/** Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
 export declare function runPicker(rows: PickRow[], start: Set<string>, mcp: boolean): Promise<Picked | undefined | 'fallback'>;

package/dist/picker.js

@@ -1,4 +1,3 @@
-// The arrow-key picker for `flowfig init`. The screen and the keys are pure, so the tests need no TTY.
 import { emitKeypressEvents } from 'node:readline';
 import { VERSION } from './version.js';
 const BANNER = [
@@ -10,26 +9,22 @@ const BANNER = [
     '╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ ╚═╝     ╚═╝ ╚═════╝ ',
 ];
 const BANNER_WIDTH = Math.max(...BANNER.map((l) => l.length));
-const NOT = '(not detected)'.length; // the width of the detected column
+const NOT = '(not detected)'.length;
 const HELP = '↑↓ move · space toggle · a all · enter confirm · esc cancel';
 const SHADOW = '38;2;43;93;143';
 const ansi = (on, code, text) => (on ? `\x1b[${code}m${text}\x1b[0m` : text);
-/** Row `i` of `n`: the blue gradient from #4da3ff to #0074d9. */
 const blue = (i, n) => {
     const mix = (a, b) => Math.round(a + ((b - a) * i) / (n - 1));
     return `38;2;${mix(0x4d, 0x00)};${mix(0xa3, 0x74)};${mix(0xff, 0xd9)}`;
 };
-/** The banner lines. A terminal narrower than the banner gets the plain version line. */
+/** A terminal narrower than the banner gets the plain version line. */
 export function banner({ color, width }) {
     const ver = `flowfig ${VERSION}`;
     if (width < BANNER_WIDTH)
         return [ansi(color, '1;38;2;77;163;255', ver)];
-    const art = BANNER.map((l, i) => 
-    // each run of one character type gets its own colour: the block letters take the gradient, the shadow takes dim blue
-    l.replace(/█+|[╗║╚═╔╝]+/g, (run) => ansi(color, run[0] === '█' ? blue(i, BANNER.length - 1) : SHADOW, run)));
+    const art = BANNER.map((l, i) => l.replace(/█+|[╗║╚═╔╝]+/g, (run) => ansi(color, run[0] === '█' ? blue(i, BANNER.length - 1) : SHADOW, run)));
     return [...art, ansi(color, '90', ver)];
 }
-/** Cut the pieces `[text, colour code]` to `width` visible characters, then colour them. */
 function fit(pieces, width, color) {
     let room = width;
     let out = '';
@@ -42,9 +37,9 @@ function fit(pieces, width, color) {
     }
     return out;
 }
-/** The picker screen, one string per line. */
 export function screen(s, o) {
-    const w = Math.max(o.width - 1, 1); // the last column stays free, so no row wraps
+    // Leave the last column free, so no row wraps.
+    const w = Math.max(o.width - 1, 1);
     const pad = Math.max(...s.rows.map((r) => r.name.length), 10);
     const mark = (i) => (i === s.cursor ? '›' : ' ');
     const rows = s.rows.map((r, i) => fit([
@@ -70,9 +65,8 @@ export function screen(s, o) {
         fit([[HELP, '90']], w, o.color),
     ];
 }
-/** One key press. Returns the next state, or `confirm` or `cancel`. */
 export function keyStep(s, k) {
-    const last = s.rows.length; // the MCP row
+    const last = s.rows.length;
     const n = last + 1;
     if (k.name === 'escape' || k.name === 'q' || (k.ctrl && k.name === 'c'))
         return 'cancel';
@@ -87,14 +81,17 @@ export function keyStep(s, k) {
             return { ...s, mcp: !s.mcp };
         const id = s.rows[s.cursor].id;
         const sel = new Set(s.sel);
-        sel.has(id) ? sel.delete(id) : sel.add(id);
+        if (sel.has(id))
+            sel.delete(id);
+        else
+            sel.add(id);
         return { ...s, sel };
     }
     if (k.name === 'a')
         return { ...s, sel: s.sel.size === last ? new Set() : new Set(s.rows.map((r) => r.id)) };
     return s;
 }
-/** Run the picker on the terminal. Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
+/** Returns `undefined` on cancel, or `'fallback'` if the terminal has no raw mode. */
 export function runPicker(rows, start, mcp) {
     const { stdin, stdout } = process;
     if (!stdin.isTTY || typeof stdin.setRawMode !== 'function')

package/dist/png.js

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

package/dist/rail.d.ts

@@ -29,7 +29,6 @@ export type RailRow = {
     step: number;
     label: string;
     messages: number;
-    /** The divider: it starts after the open label or after the folded label, and ends before the counter. */
     line: {
         open: number;
         folded: number;
@@ -58,7 +57,7 @@ export type RailState = {
 };
 export type Rail = {
     width: number;
-    /** The y where the first row starts: below the band-label line (if a band exists) and the column labels. */
+    /** The y where the first row starts. */
     head: number;
     height: number;
     columns: RailColumn[];
@@ -72,7 +71,6 @@ export type Rail = {
     folds: boolean;
     states: RailState[][];
 };
-/** The folded phase text. Both renderers and the layout use it, so the measured width matches the drawn width. */
 export declare const foldedLabel: (row: {
     label: string;
     messages: number;