flowfig 0.3.0 → 0.5.0

package/dist/picker.js

@@ -0,0 +1,148 @@
+// 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 = [
+    '███████╗██╗      ██████╗ ██╗    ██╗███████╗██╗ ██████╗ ',
+    '██╔════╝██║     ██╔═══██╗██║    ██║██╔════╝██║██╔════╝ ',
+    '█████╗  ██║     ██║   ██║██║ █╗ ██║█████╗  ██║██║  ███╗',
+    '██╔══╝  ██║     ██║   ██║██║███╗██║██╔══╝  ██║██║   ██║',
+    '██║     ███████╗╚██████╔╝╚███╔███╔╝██║     ██║╚██████╔╝',
+    '╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ ╚═╝     ╚═╝ ╚═════╝ ',
+];
+const BANNER_WIDTH = Math.max(...BANNER.map((l) => l.length));
+const NOT = '(not detected)'.length; // the width of the detected column
+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. */
+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)));
+    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 = '';
+    for (const [text, code] of pieces) {
+        const cut = text.length > room ? `${text.slice(0, Math.max(room - 1, 0))}…` : text;
+        out += code ? ansi(color, code, cut) : cut;
+        room -= cut.length;
+        if (room <= 0)
+            break;
+    }
+    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
+    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([
+        [`${mark(i)} [${s.sel.has(r.id) ? 'x' : ' '}] `, ''],
+        [r.name.padEnd(pad), ''],
+        [` ${r.detected ? ''.padEnd(NOT) : '(not detected)'}`, '90'],
+        [`  ${r.files.join(', ')}`, '36'],
+    ], w, o.color));
+    const mcp = fit([
+        [`${mark(s.rows.length)} [${s.mcp ? 'x' : ' '}] `, ''],
+        [`${'MCP server'.padEnd(pad)} ${''.padEnd(NOT)}`, ''],
+        ['  register flowfig in the MCP file of each agent', '36'],
+    ], w, o.color);
+    return [
+        ...banner(o),
+        '',
+        fit([['Pick the coding agents that should draw diagrams in this repo.', '']], w, o.color),
+        '',
+        ...rows,
+        ansi(o.color, '90', '─'.repeat(Math.min(w, 40))),
+        mcp,
+        '',
+        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 n = last + 1;
+    if (k.name === 'escape' || k.name === 'q' || (k.ctrl && k.name === 'c'))
+        return 'cancel';
+    if (k.name === 'return')
+        return 'confirm';
+    if (k.name === 'up' || k.name === 'k')
+        return { ...s, cursor: (s.cursor + n - 1) % n };
+    if (k.name === 'down' || k.name === 'j')
+        return { ...s, cursor: (s.cursor + 1) % n };
+    if (k.name === 'space') {
+        if (s.cursor === last)
+            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);
+        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. */
+export function runPicker(rows, start, mcp) {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function')
+        return Promise.resolve('fallback');
+    try {
+        stdin.setRawMode(true);
+    }
+    catch {
+        return Promise.resolve('fallback');
+    }
+    const color = process.env.NO_COLOR === undefined;
+    let state = { rows, sel: start, mcp, cursor: 0 };
+    let drawn = 0;
+    const draw = () => {
+        const lines = screen(state, { color, width: stdout.columns || 80 });
+        stdout.write(`${drawn ? `\x1b[${drawn}A\r\x1b[J` : ''}${lines.join('\n')}\n`);
+        drawn = lines.length;
+    };
+    return new Promise((resolve, reject) => {
+        const end = (r) => {
+            stdin.off('keypress', onKey);
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdout.write(`\x1b[${drawn}A\r\x1b[J\x1b[?25h`);
+            resolve(r);
+        };
+        const onKey = (_, key = {}) => {
+            try {
+                const next = keyStep(state, key);
+                if (next === 'cancel')
+                    return end();
+                if (next === 'confirm')
+                    return end({ ids: state.sel, mcp: state.mcp });
+                state = next;
+                draw();
+            }
+            catch (e) {
+                stdin.off('keypress', onKey);
+                stdin.setRawMode(false);
+                stdin.pause();
+                stdout.write('\x1b[?25h');
+                reject(e);
+            }
+        };
+        emitKeypressEvents(stdin);
+        stdin.on('keypress', onKey);
+        stdin.resume();
+        stdout.write('\x1b[?25l');
+        draw();
+    });
+}

package/dist/png.d.ts

@@ -0,0 +1,7 @@
+/** RGBA pixels, 4 bytes per pixel, rows top to bottom. */
+export type Image = {
+    width: number;
+    height: number;
+    data: Uint8Array;
+};
+export declare function decodePng(png: Uint8Array): Image;

package/dist/png.js

@@ -0,0 +1,70 @@
+// Read the PNG screenshots of the capture browser. 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) {
+    if (png.length < 8 || SIGNATURE.some((b, i) => png[i] !== b))
+        throw new Error('not a PNG: bad signature');
+    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));
+        const body = png.subarray(at + 8, at + 8 + len);
+        if (kind === 'IHDR') {
+            width = view.getUint32(at + 8);
+            height = view.getUint32(at + 12);
+            if (body[8] !== 8)
+                throw new Error(`unsupported PNG: bit depth ${body[8]}`);
+            if (body[9] !== 2 && body[9] !== 6)
+                throw new Error(`unsupported PNG: color type ${body[9]}`);
+            if (body[12] !== 0)
+                throw new Error(`unsupported PNG: interlace ${body[12]}`);
+            bpp = body[9] === 6 ? 4 : 3;
+        }
+        else if (kind === 'IDAT')
+            idat.push(body);
+        else if (kind === 'IEND')
+            break;
+        at += 12 + len;
+    }
+    if (!bpp)
+        throw new Error('not a PNG: no IHDR chunk');
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = width * bpp;
+    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);
+    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.
+        if (filter === 1)
+            for (let x = bpp; x < stride; x++)
+                row[x] += row[x - bpp];
+        else if (filter === 2)
+            for (let x = 0; x < stride; x++)
+                row[x] += prev[x];
+        else if (filter === 3)
+            for (let x = 0; x < stride; x++)
+                row[x] += ((x >= bpp ? row[x - bpp] : 0) + prev[x]) >> 1;
+        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);
+                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;
+        }
+        prev = row;
+    }
+    return { width, height, data };
+}

package/dist/scene.d.ts

@@ -13,20 +13,29 @@ export type SceneBox = {
     texts: TextRun[];
 };
 /** `step` marks a rail row: rows of two steps never show at the same time, so their labels cannot overlap. */
+/** `behind` marks an edge drawn under the boxes (a timeline dependency): `check` skips its crossing test. */
+/** `pts` are the corners of an edge drawn as straight runs (a cross-block lanes edge): `check` tests them in place of `curve`. */
 export type SceneEdge = {
     id: string;
     from: string;
     to: string;
     curve: [Pt, Pt, Pt, Pt];
+    pts?: Pt[];
     label?: Rect;
     step?: number;
+    behind?: true;
 };
 /** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
+/** `lanes` are the lane bands of a swimlanes figure, one per lane and block, named by the lane label. A stub pill stays inside one. */
 export type Scene = {
     width: number;
     boxes: SceneBox[];
     edges: SceneEdge[];
     minFont: number;
+    lanes?: {
+        id: string;
+        rect: Rect;
+    }[];
 };
 /** One fault that `flowfig check` found. `rule` names the check, for example `unknown-id`, `text-overflow`, `edge-crosses-box`, `label-overlap`, `small-text`, `low-contrast`. `ids` are the boxes or edges it names. */
 export type Finding = {

package/dist/svg.d.ts

@@ -15,6 +15,9 @@ export type SvgOptions = {
     padding?: number;
     /** Colors, in place of `FlowProps.theme`. Default: `FlowProps.theme`. */
     theme?: FigTheme;
+    /** Lanes: the page width and the smallest text that decide when the time columns wrap into blocks. Default: 830 and 10, as in `check`. */
+    width?: number;
+    minText?: number;
 };
 /**
  * The SVG string, and the scene it drew. The scene lets `flowfig check` test the same layout the SVG uses.