flowfig 0.11.0 → 0.12.0

package/dist/looks.js

@@ -0,0 +1,32 @@
+const base = {
+    font: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+};
+export const TOKENS = {
+    light: {
+        ...base,
+        bg: '#fafbfd',
+        surface: '#ffffff',
+        border: '#dfe7f0',
+        ink: '#1d2433',
+        muted: '#5d687a',
+        accent: '#0074d9',
+        'on-accent': '#ffffff',
+        bad: '#c8352f',
+        good: '#23704e',
+        play: '#1d2433',
+    },
+    dark: {
+        ...base,
+        bg: '#131820',
+        surface: '#1c2330',
+        border: '#2a3343',
+        ink: '#e9eef6',
+        muted: '#9aa6b8',
+        accent: '#4da3f0',
+        'on-accent': '#0b1220',
+        bad: '#ee5d57',
+        good: '#5cc48f',
+        play: '#6b778c',
+    },
+};
+export const HUD = { wide: 880, roomy: 1200, panel: 376, slim: 300, pad: 16, chips: 52, sheet: 160, short: 560, tall: 760 };

package/dist/mcp.d.ts

@@ -81,6 +81,10 @@ export declare const TOOLS: ({
                 type: string;
                 description: string;
             };
+            scene: {
+                type: string;
+                description: string;
+            };
             paths?: undefined;
             root?: undefined;
             old?: undefined;

package/dist/mcp.js

@@ -6,7 +6,7 @@ import { GUIDE, TOPICS } from './guide.js';
 import { loadSpec, reportLines, sortFindings, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render } from './svg.js';
 import { checkRendered } from './check.js';
-import { coverageLine, unsureLines, verifyReport } from './verify.js';
+import { coverageLine, levelLines, 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.',
@@ -34,7 +34,11 @@ export const TOOLS = [
         description: 'Check a figure, then write it as one animated SVG file. Returns the check lines and the path. On an error, writes nothing.',
         inputSchema: {
             type: 'object',
-            properties: { ...checkProps, out: { type: 'string', description: 'The SVG path to write.' } },
+            properties: {
+                ...checkProps,
+                out: { type: 'string', description: 'The SVG path to write.' },
+                scene: { type: 'string', description: 'The id of a box with inside: render that level as a plain figure.' },
+            },
             required: ['spec', 'out'],
         },
     },
@@ -98,11 +102,15 @@ function run(name, args) {
     }
     if (name === 'check' || name === 'render') {
         need(args, name, name === 'render' ? ['spec', 'out'] : ['spec']);
-        types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
+        types(args, name, { width: 'number', minText: 'number', out: 'string', scene: 'string', strict: 'boolean' });
         const props = spec(args.spec, name);
-        const opts = { width: args.width, minText: args.minText };
+        const opts = {
+            width: args.width,
+            minText: args.minText,
+            ...(name === 'render' && { scene: args.scene }),
+        };
         const rendered = render(props, opts);
-        const findings = sortFindings(checkRendered(props, opts, rendered.scene), args.strict === true);
+        const findings = sortFindings(checkRendered(props, opts, rendered.scene, rendered.levels), args.strict === true);
         const errors = findings.some((f) => f.severity === 'error');
         const lines = reportLines(props, findings);
         if (name === 'check' || errors)
@@ -140,7 +148,7 @@ function run(name, args) {
                 continue;
             }
             const report = verifyReport(props, { root });
-            counts.push(coverageLine(p, report.coverage), ...unsureLines(report.coverage));
+            counts.push(coverageLine(p, report.coverage), ...levelLines(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}`));

package/dist/model.d.ts

@@ -1,5 +1,7 @@
 import type { ReactNode } from 'react';
 import type { Rect } from './geometry.ts';
+export declare const LOOKS: readonly ['person', 'shop', 'desk', 'truck', 'phone', 'server', 'cabinet', 'team', 'tower', 'queue', 'gear', 'cloud'];
+export type FigLook = (typeof LOOKS)[number];
 /** A box. A box with `show` in a step becomes a content card. */
 export type FigNode = {
     /** Name that edges, steps and beats use for this box. Unique in the figure. */
@@ -28,6 +30,14 @@ export type FigNode = {
     source?: string;
     /** A figure with more detail: an SVG path from the repo root. */
     detail?: string;
+    /** The parts inside the box, down to 3 levels. */
+    inside?: FigInside;
+    /** The picture of this box or group in <flowfig-explain>. The diagram ignores it. */
+    look?: FigLook;
+    /** The question on the gate in <flowfig-explain>. Default: the label of a `decision` box. */
+    check?: string;
+    /** The state after this box, such as "Oil in stock". The <flowfig-explain> ending shows it. */
+    done?: string;
 };
 /** A frame that lays out its children in a row or a column. */
 export type FigGroup = {
@@ -45,6 +55,28 @@ export type FigGroup = {
     children: (FigNode | FigGroup)[];
     /** On the root layout: flowfig places the boxes. A labeled group is a frame. */
     auto?: true;
+    /** The picture of this box or group in <flowfig-explain>. The diagram ignores it. */
+    look?: FigLook;
+};
+/** A physical thing that moves on an edge in <flowfig-explain>. */
+export type FigCarry = {
+    /** The name of the thing, in plain words. */
+    thing: string;
+    /** The picture of one unit. Default: `box`. */
+    form?: 'box' | 'barrel' | 'notes';
+    /** How many units move, 1 to 4. Default: 1. */
+    count?: number;
+    /** The id of the box or group where the thing starts. Default: the edge `from`. */
+    from?: string;
+};
+/** The parts inside a box. A reader opens the box to see them. */
+export type FigInside = {
+    /** The parts and how they line up. The rules of `FlowProps.layout` apply, `auto` too. */
+    layout: FigGroup;
+    /** The arrows between the parts. One end can name an outer neighbor. */
+    edges?: FigEdge[];
+    /** The stories inside the box. Each step is a tab when the box is open. */
+    steps?: FigStep[];
 };
 /** An arrow from one box to another. */
 export type FigEdge = {
@@ -64,6 +96,8 @@ export type FigEdge = {
     source?: string;
     /** The route, queue, topic or table that carries this edge. Checked by `flowfig verify`. */
     via?: string;
+    /** What moves on this edge in <flowfig-explain>: `data`, or a thing. Default: `data`. */
+    carries?: 'data' | FigCarry;
 };
 /** One packet on one edge. A string is the edge `id`. */
 export type FigHop = string | {
@@ -88,6 +122,8 @@ export type FigBeat = {
     edges?: FigHop | FigHop[];
     /** The line of narration for this beat. */
     say?: ReactNode;
+    /** One line under the say in <flowfig-explain>, 15 words or fewer. */
+    note?: ReactNode;
     /** 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. */
@@ -126,6 +162,8 @@ export type FigStep = {
     flow: (FigHop | FigHop[] | FigBeat)[];
     /** Ids of boxes to highlight for the whole step. */
     nodes?: string[];
+    /** One sentence, 15 words or fewer, on how the story ends in <flowfig-explain>. */
+    outcome?: string;
 };
 /** 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>>;
@@ -231,7 +269,66 @@ export declare const outsideLabelRect: (bar: {
 export declare const labelSpan: (t0: number, end: number, ramp: number) => [number, number];
 export declare const dateLabelRaised: (x: number, today: number | null | undefined, w: number, todayW: number) => boolean;
 export declare const STEP_HOLD_MS = 2000;
+export declare const n2: (v: number) => number;
+export declare const beatTimes: (beats: Beat[][], speedMs: number) => {
+    beats: {
+        t0: number;
+        t1: number;
+        tEnd: number;
+    }[][];
+    ends: number[];
+};
 export declare const nodes: (g: FigGroup) => FigNode[];
+export type FigPort = {
+    id: string;
+    way: 'in' | 'out' | 'in and out';
+    name: string;
+};
+export type FigScene = {
+    path: string[];
+    name: string;
+    line: string;
+    props: FlowProps;
+    ports: FigPort[];
+    parts: number;
+};
+export declare const PORT_GAP = 28;
+export declare const MAX_LEVEL = 3;
+export declare const portLabel: (p: FigPort) => string;
+export declare function scenes(fig: FlowProps): FigScene[];
+export declare const OPEN_MS: {
+    fade: number;
+    grow: number;
+    stagger: number;
+    hide: number;
+    shrink: number;
+};
+export type Times = {
+    beats: {
+        t0: number;
+        t1: number;
+        tEnd: number;
+    }[][];
+    ends: number[];
+};
+export type TourOpen = {
+    path: string[];
+    step: number;
+    open: [number, number];
+    grown: number;
+    loop: [number, number][];
+    back: [number, number];
+    times: Times;
+};
+export type Tour = {
+    ms: number;
+    loop: [number, number][];
+    times: Times;
+    opens: TourOpen[];
+};
+export declare function insideStep(s: FigScene, port?: string): number;
+export declare function flowOrder(s: FigScene): string[];
+export declare function tourPlan(fig: FlowProps, speed?: number): Tour;
 export declare const LANE_GAP = 56, LANE_PAD = 24, LANE_ROW_GAP = 20;
 export declare const isLanesLayout: (g: FigGroup) => boolean;
 export declare const validAt: (at: unknown) => at is number;

package/dist/model.js

@@ -1,4 +1,5 @@
 import { textWidth, wrap } from './text.js';
+export const LOOKS = ['person', 'shop', 'desk', 'truck', 'phone', 'server', 'cabinet', 'team', 'tower', 'queue', 'gear', 'cloud'];
 export const toBeat = (b) => {
     const isBeat = typeof b === 'object' && !Array.isArray(b) && !('edge' in b);
     const { edges, ...rest } = isBeat ? b : { edges: b };
@@ -66,7 +67,180 @@ export const outsideLabelRect = (bar, label) => ({
 export const labelSpan = (t0, end, ramp) => [Math.min(t0 + ramp, end), end];
 export const dateLabelRaised = (x, today, w, todayW) => today != null && x + 3 < today - 3 && x + 3 + w > today - 3 - todayW;
 export const STEP_HOLD_MS = 2000;
+export const n2 = (v) => Math.round(v * 10) / 10;
+export const beatTimes = (beats, speedMs) => {
+    const travel = speedMs / 1000 / BASE_RATE, hold = STEP_HOLD_MS / 1000 / BASE_RATE;
+    const ends = [];
+    let t = 0;
+    const times = beats.map((step) => {
+        const out = step.map((b, bi) => {
+            const t0 = t, dur = beatMs(b, speedMs) / 1000 / BASE_RATE;
+            t += dur + (bi === step.length - 1 ? hold : 0);
+            return { t0, t1: t0 + travel, tEnd: t0 + dur };
+        });
+        ends.push(t);
+        return out;
+    });
+    return { beats: times, ends };
+};
 export const nodes = (g) => g.children.flatMap((c) => (isGroup(c) ? nodes(c) : [c]));
+// Measured: a 56 px gap makes the Orders level of figures/inside-shop.ts fail small-text.
+export const PORT_GAP = 28;
+export const MAX_LEVEL = 3;
+export const portLabel = (p) => p.way === 'in' ? `in: from ${p.name}` : p.way === 'out' ? `out: to ${p.name}` : `in and out: ${p.name}`;
+export function scenes(fig) {
+    const root = { path: [], name: '', line: '', props: fig, ports: [], parts: 0 };
+    if (fig.lanes || fig.timeline || fig.rail === 'only')
+        return [root];
+    const real = new Map();
+    const index = (g, level) => nodes(g).forEach((n) => {
+        real.set(n.id, n);
+        if (n.inside && level < MAX_LEVEL)
+            index(n.inside.layout, level + 1);
+    });
+    index(fig.layout, 1);
+    const name = (id) => str(real.get(id)?.label) || id;
+    const { theme, speed, rail } = fig;
+    const out = [root];
+    const open = (parent) => {
+        for (const b of nodes(parent.props.layout)) {
+            const parts = b.inside ? nodes(b.inside.layout) : [];
+            if (!b.inside || !parts.length)
+                continue;
+            const ids = new Set(parts.map((n) => n.id));
+            const edges = b.inside.edges ?? [];
+            const ins = [], outs = [];
+            for (const e of edges) {
+                if (ids.has(e.from) === ids.has(e.to))
+                    continue;
+                if (!ids.has(e.from) && !ins.includes(e.from))
+                    ins.push(e.from);
+                if (!ids.has(e.to) && !outs.includes(e.to))
+                    outs.push(e.to);
+            }
+            const ports = [...ins, ...outs.filter((id) => !ins.includes(id))].map((id) => ({
+                id,
+                way: !ins.includes(id) ? 'out' : outs.includes(id) ? 'in and out' : 'in',
+                name: name(id),
+            }));
+            const box = (p) => {
+                const source = real.get(p.id)?.source;
+                return { id: p.id, label: portLabel(p), ...(source != null && { source }) };
+            };
+            const before = ports.filter((p) => p.way !== 'out').map(box), after = ports.filter((p) => p.way === 'out').map(box);
+            const l = b.inside.layout;
+            const layout = l.auto
+                ? { ...l, children: [...before, ...l.children, ...after] }
+                : { direction: l.direction === 'column' ? 'column' : 'row', gap: PORT_GAP, children: [...before, l, ...after] };
+            const path = [...parent.path, b.id];
+            const s = {
+                path,
+                name: name(b.id),
+                line: path.map(name).join(' > '),
+                props: { layout, edges, steps: b.inside.steps, theme, speed, rail },
+                ports,
+                parts: ids.size,
+            };
+            out.push(s);
+            if (path.length + 1 < MAX_LEVEL)
+                open(s);
+        }
+    };
+    open(root);
+    return out;
+}
+export const OPEN_MS = { fade: 120, grow: 360, stagger: 50, hide: 120, shrink: 300 };
+const hopEnds = (e, back) => (back ? [e.to, e.from] : [e.from, e.to]);
+export function insideStep(s, port) {
+    const byId = new Map(s.props.edges.map((e) => [edgeId(e), e]));
+    const at = (s.props.steps ?? []).findIndex((st) => {
+        const h = st.flow.length ? toBeat(st.flow[0]).hops[0] : undefined;
+        const e = h && byId.get(h.edge);
+        return e != null && hopEnds(e, h.back)[0] === port;
+    });
+    return Math.max(at, 0);
+}
+export function flowOrder(s) {
+    const cols = laneColumns(s.props);
+    const ids = nodes(s.props.layout)
+        .map((n) => n.id)
+        .sort((a, b) => cols.get(a) - cols.get(b));
+    const port = new Set(s.ports.map((p) => p.id));
+    return [...ids.filter((id) => port.has(id)), ...ids.filter((id) => !port.has(id))];
+}
+export function tourPlan(fig, speed = fig.speed ?? 900) {
+    const all = scenes(fig);
+    const byKey = new Map(all.map((s) => [s.path.join('>'), s]));
+    const opens = [];
+    const done = new Set();
+    const cut = (from, to, spans) => {
+        const out = [];
+        let at = from;
+        for (const [a, b] of spans) {
+            if (a > at)
+                out.push([at, a]);
+            at = b;
+        }
+        if (to > at)
+            out.push([at, to]);
+        return out;
+    };
+    const play = (s, steps, at) => {
+        const beats = steps.map((st) => st.flow.map(toBeat));
+        const base = beatTimes(beats, speed);
+        const byId = new Map(s.props.edges.map((e) => [edgeId(e), e]));
+        const spans = [];
+        let shift = 0;
+        const openAt = (id, port, p) => {
+            const key = [...s.path, id].join('>');
+            const inner = byKey.get(key);
+            if (!inner || done.has(key))
+                return;
+            const L = openBox(inner, port, p);
+            spans.push([p, p + L]);
+            shift += L;
+        };
+        const times = { beats: [], ends: [] };
+        beats.forEach((row, si) => {
+            times.beats.push(row.map((b, bi) => {
+                const t = base.beats[si][bi];
+                const t0 = at + t.t0 * 1000 + shift, t1 = at + t.t1 * 1000 + shift;
+                for (const h of b.hops) {
+                    const e = byId.get(h.edge);
+                    if (e)
+                        openAt(hopEnds(e, h.back)[1], hopEnds(e, h.back)[0], at + t.tEnd * 1000 + shift);
+                }
+                return { t0: t0 / 1000, t1: t1 / 1000, tEnd: (at + t.tEnd * 1000 + shift) / 1000 };
+            }));
+            times.ends.push((at + base.ends[si] * 1000 + shift) / 1000);
+        });
+        const last = at + (base.ends.at(-1) ?? 0) * 1000;
+        for (const n of nodes(s.props.layout))
+            openAt(n.id, undefined, last + shift);
+        if (times.ends.length)
+            times.ends[times.ends.length - 1] = (last + shift) / 1000;
+        return { times, end: last + shift, spans };
+    };
+    const openBox = (sc, port, p) => {
+        done.add(sc.path.join('>'));
+        const grown = p + readMs(sc.name) + OPEN_MS.fade + OPEN_MS.grow;
+        const count = nodes(sc.props.layout).length;
+        const loopAt = grown + OPEN_MS.stagger * (count - 1) + readMs([sc.line, ...sc.ports.map(portLabel)].join(' '));
+        const steps = sc.props.steps ?? [];
+        const step = steps.length ? insideStep(sc, port) : -1;
+        const entry = { path: sc.path, step, open: [p, loopAt], grown, loop: [], back: [0, 0], times: { beats: [], ends: [] } };
+        opens.push(entry);
+        const r = play(sc, step === -1 ? [] : [steps[step]], loopAt);
+        const up = sc.path.length > 1 ? `back to ${byKey.get(sc.path.slice(0, -1).join('>')).name}` : 'Back';
+        const end = r.end + readMs(up) + OPEN_MS.hide + OPEN_MS.shrink + OPEN_MS.fade;
+        entry.loop = cut(loopAt, r.end, r.spans);
+        entry.back = [r.end, end];
+        entry.times = r.times;
+        return end - p;
+    };
+    const root = play(all[0], fig.steps ?? [], 0);
+    return { ms: root.end, loop: cut(0, root.end, root.spans), times: root.times, opens };
+}
 export const LANE_GAP = 56, LANE_PAD = 24, LANE_ROW_GAP = 20;
 export const isLanesLayout = (g) => g.direction === 'column' && g.children.every((c) => isGroup(c) && c.label != null && c.children.every((k) => !isGroup(k)));
 export const validAt = (at) => typeof at === 'number' && Number.isInteger(at) && at >= 0;
@@ -507,9 +681,16 @@ export const altText = (fig) => {
             });
         }),
     ]);
+    const levels = scenes(fig)
+        .slice(1)
+        .map((s) => {
+        const port = new Set(s.ports.map((p) => p.id));
+        const parts = nodes(s.props.layout).filter((n) => !port.has(n.id));
+        return `${s.line}: ${parts.map((n) => str(n.label) || n.id).join(', ')}.${s.ports.length ? ` Ports: ${s.ports.map(portLabel).join(', ')}.` : ''}`;
+    });
     return {
         title: `Flow figure: ${boxes.join(', ')}.${steps.length ? ` Steps: ${steps.map((s) => str(s.label)).join(', ')}.` : ''}`,
-        desc: [`The figure has these boxes: ${boxes.join(', ')}.`, ...lines].join('\n'),
+        desc: [`The figure has these boxes: ${boxes.join(', ')}.`, ...lines, ...levels].join('\n'),
     };
 };
 const keyOf = (v, path) => {

package/dist/scene.d.ts

@@ -47,4 +47,6 @@ export type Finding = {
     severity: 'error' | 'warning';
     ids: string[];
     message: string;
+    /** The path line of the level, for a finding inside a box. */
+    scene?: string;
 };

package/dist/source.d.ts

@@ -10,8 +10,10 @@ export type Link = {
     source: string;
     path: string;
     symbol?: string;
+    level?: string;
 };
-/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
-export declare function owners(fig: FlowProps): [string, string | undefined, string | undefined][];
+type Owner = [string, string | undefined, string | undefined, string];
+export declare function owners(fig: FlowProps): Owner[];
 /** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
 export declare function links(fig: FlowProps): Link[];
+export {};

package/dist/source.js

@@ -1,5 +1,5 @@
 // No Node import: the React and SVG entries must stay browser-safe.
-import { edgeId, nodes, toBeat } from './model.js';
+import { edgeId, nodes, scenes, toBeat } from './model.js';
 /** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
 export function parseSource(s) {
     const m = /^([^\s#]+)(?:#([^\s#]+))?$/.exec(s);
@@ -12,18 +12,24 @@ export const headingSlug = (text) => text
     .toLowerCase()
     .replace(/[^\p{L}\p{N} -]/gu, '')
     .replace(/ /g, '-');
-/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
 export function owners(fig) {
-    return [
-        ...nodes(fig.layout).map((n) => [`box "${n.id}"`, n.source, undefined]),
-        ...fig.edges.map((e) => [`edge "${edgeId(e)}"`, e.source, e.via]),
-        ...(fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"`, h.source, h.via]))),
-    ];
+    return scenes(fig).flatMap((s) => {
+        const ports = new Set(s.ports.map((p) => p.id));
+        const at = s.line ? ` [${s.line}]` : '';
+        const kind = s.line ? 'part' : 'box';
+        return [
+            ...nodes(s.props.layout)
+                .filter((n) => !ports.has(n.id))
+                .map((n) => [`${kind} "${n.id}"${at}`, n.source, undefined, s.path.join('>')]),
+            ...s.props.edges.map((e) => [`edge "${edgeId(e)}"${at}`, e.source, e.via, s.path.join('>')]),
+            ...(s.props.steps ?? []).flatMap((st) => st.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"${at}`, h.source, h.via, s.path.join('>')]))),
+        ];
+    });
 }
 /** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
 export function links(fig) {
-    return owners(fig).flatMap(([owner, source]) => {
+    return owners(fig).flatMap(([owner, source, , level]) => {
         const p = source == null ? null : parseSource(source);
-        return p ? [{ owner, source: source, ...p }] : [];
+        return p ? [{ owner, source: source, ...p, ...(level && { level }) }] : [];
     });
 }

package/dist/svg.d.ts

@@ -23,11 +23,23 @@ export type SvgOptions = {
     marks?: DiffMarks;
     /** Links a box to an href, by box id. `flowfig atlas` sets it. */
     links?: Record<string, string>;
+    /** Draws the level of this box as a plain figure: no tour, no script. */
+    scene?: string;
+    /** Adds the script that opens a box on a click, for a figure with parts. */
+    script?: boolean;
+    /** A prefix for animation names and path ids. Each page SVG needs its own. */
+    scope?: string;
+};
+export type Level = {
+    line: string;
+    props: FlowProps;
+    scene: Scene;
 };
 /** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
 export declare function render(spec: FlowProps, opts?: SvgOptions): {
     svg: string;
     scene: Scene;
+    levels?: Level[];
 };
 /** One self-contained animated SVG string for the figure. Needs no React and no browser. */
 export declare function toSvg(fig: FlowProps, opts?: SvgOptions): string;