flowfig 0.10.0 → 0.12.0

package/dist/load.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
-import { altText, counts, toBeat } from './model.js';
-import { coverageLine, detailFindings, owners, unsureLines, verifyReport } from './verify.js';
+import { altText, counts, scenes, toBeat, tourPlan } from './model.js';
+import { coverageLine, detailFindings, levelLines, owners, unsureLines, verifyReport } from './verify.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
@@ -47,12 +47,16 @@ export function sortFindings(findings, strict) {
 const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
 /** One line per finding, the counts line (unless `withCounts` is false), and the `figure:` line. No color: the CLI adds it. */
 export function reportLines(props, findings, withCounts = true) {
-    const out = findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.message}`);
+    const out = findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.scene ? `[${f.scene}] ` : ''}${f.message}`);
     const errors = findings.filter((f) => f.severity === 'error').length;
     if (withCounts)
         out.push(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
     const c = counts(props);
-    out.push(`figure: ${n(c.boxes, 'box').replace('boxs', 'boxes')}, ${n(c.groups, 'group')}, ${n(c.edges, 'edge')}, ${n(c.steps, 'step')}, ${n(c.messages, 'message')}`);
+    const all = scenes(props);
+    const levels = all.length > 1
+        ? `; ${1 + Math.max(...all.map((s) => s.path.length))} levels, ${all.length} scenes, ${all.reduce((k, s) => k + s.parts, 0)} parts; tour ${Math.round(tourPlan(props).ms / 1000)} s`
+        : '';
+    out.push(`figure: ${n(c.boxes, 'box').replace('boxs', 'boxes')}, ${n(c.groups, 'group')}, ${n(c.edges, 'edge')}, ${n(c.steps, 'step')}, ${n(c.messages, 'message')}${levels}`);
     return out;
 }
 const text = (x) => (typeof x === 'string' ? x : '');
@@ -75,6 +79,7 @@ export function verifyLines(props, figure, root = process.cwd()) {
     return [
         ...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${figure}: ${f.message}`),
         coverageLine(figure, coverage),
+        ...levelLines(coverage),
         ...unsureLines(coverage),
     ];
 }

package/dist/looks.d.ts

@@ -0,0 +1,15 @@
+export declare const TOKENS: {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+};
+export declare const HUD: {
+    wide: number;
+    roomy: number;
+    panel: number;
+    slim: number;
+    pad: number;
+    chips: number;
+    sheet: number;
+    short: number;
+    tall: number;
+};

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,14 +269,73 @@ 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;
 /** The time column of each box: first use in the steps, then layout order. `at` wins. */
 export declare function laneColumns(fig: FlowProps): Map<string, number>;
 export declare const LABEL_LINE = 18;
-export declare const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
+export declare const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190, DIAMOND_MAX_W = 170;
 export declare const LANE_BLOCK_GAP = 40;
 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. */
@@ -249,13 +346,13 @@ export declare function itemWidth(item: FigNode | FigGroup, carded: {
 }, edges: FigEdge[], cap?: number): number;
 export declare function fitCap(fig: FlowProps, width: number, padding?: number): number;
 export declare const diamondRoom: (w: number, h: number, far: number) => number;
-/** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
 export declare function diamondLines(item: FigNode, w: number): {
     h: number;
     label: {
+        text: string;
         dy: number;
         far: number;
-    };
+    }[];
     subs: {
         text: string;
         dy: number;
@@ -361,5 +458,10 @@ export declare const altText: (fig: FlowProps) => {
     desc: string;
 };
 export declare const specKey: (...parts: unknown[]) => string;
+export declare const textFloor: (box: number) => 9 | 11;
 export declare const fitScale: (wide: number, box: number, map: number) => number;
+export declare const shownFont: (size: number, place: 'map' | 'rail' | 'plain', scale: {
+    map: number;
+    rail: number;
+}) => number;
 export declare const nextWide: (wide: number, box: number, map: number) => 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;
@@ -95,7 +269,7 @@ export function laneColumns(fig) {
     return cols;
 }
 export const LABEL_LINE = 18;
-export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
+export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190, DIAMOND_MAX_W = 170;
 export const LANE_BLOCK_GAP = 40;
 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. */
@@ -106,14 +280,16 @@ export function nodeWidth(item, carded, cap = NODE_MAX_W) {
         return CARD_WIDTH;
     const label = textWidth(str(item.label), 14) + 32;
     const sub = textWidth(str(item.sub), 12) + 32;
-    return Math.min(item.shape === 'decision' ? NODE_MAX_W : cap, Math.max(NODE_MIN_W, label, sub));
+    return Math.min(item.shape === 'decision' ? DIAMOND_MAX_W : cap, Math.max(NODE_MIN_W, label, sub));
 }
 export function labelLines(item, w) {
     const label = str(item.label);
-    if (item.shape === 'decision' || textWidth(label, 14) <= w - 32 + 0.5)
+    if (item.shape === 'decision')
+        return wrap(label, w - 102 + 0.5, 14);
+    if (textWidth(label, 14) <= w - 32 + 0.5)
         return [label];
     const lines = wrap(label, w - 32, 14);
-    return lines.length === 2 && lines.every((l) => textWidth(l, 14) <= w - 32) ? lines : [label];
+    return lines.every((l) => textWidth(l, 14) <= w - 32) ? lines : [label];
 }
 export function itemWidth(item, carded, edges, cap = NODE_MAX_W) {
     if (!isGroup(item))
@@ -137,21 +313,28 @@ export function fitCap(fig, width, padding = 24) {
     return cap;
 }
 export const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
-/** 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++) {
-        const h = 62 + 15 * n;
-        const dy0 = n ? -2 - 7.5 * (n - 1) : 5;
-        const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
-        const last = n ? at(dy0 + 15 * n, 12) : 0;
+    const label = labelLines(item, w);
+    const k = label.length - 1;
+    const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
+    for (let n = sub ? 1 : 0, h = 0;;) {
+        h = Math.max(h, 62 + 15 * n + LABEL_LINE * k);
+        const dy0 = (n ? 5.5 : 5) - 7.5 * n - (LABEL_LINE / 2) * k;
+        const last = n ? at(dy0 + LABEL_LINE * k + 15 * n, 12) : 0;
         const lines = n ? wrap(sub, diamondRoom(w, h, last), 12) : [];
-        if (lines.length <= n || n >= 6)
-            return {
-                h,
-                label: { dy: dy0, far: at(dy0, 14) },
-                subs: lines.map((text, k) => ({ text, dy: dy0 + 15 * (k + 1), far: at(dy0 + 15 * (k + 1), 12) })),
-            };
+        const labels = label.map((text, i) => ({ text, dy: dy0 + LABEL_LINE * i, far: at(dy0 + LABEL_LINE * i, 14) }));
+        const subs = lines.map((text, j) => ({
+            text,
+            dy: dy0 + LABEL_LINE * k + 15 * (j + 1),
+            far: at(dy0 + LABEL_LINE * k + 15 * (j + 1), 12),
+        }));
+        if (lines.length > n && n < 6)
+            n++;
+        else if (h < w && labels.some((l) => textWidth(l.text, 14) > diamondRoom(w, h, l.far)))
+            h += 4;
+        else
+            return { h, label: labels, subs };
     }
 }
 /** The lane copies whose stub end has no clear place. The renderer grows each by STUB_ROOM. */
@@ -498,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) => {
@@ -523,7 +713,17 @@ const keyOf = (v, path) => {
     return Object.fromEntries(Object.entries(src).flatMap(([k, x]) => (k === 'ref' || k.startsWith('_') ? [] : [[k, keyOf(x, at)]])));
 };
 export const specKey = (...parts) => JSON.stringify(keyOf(parts, []));
-export const fitScale = (wide, box, map) => Math.max(wide ? 1 : 0.5, Math.min(1, box / map));
-const PHONE = 480;
-const folds = (box, map) => box < map / 2 || (box < PHONE && box < map);
-export const nextWide = (wide, box, map) => (folds(box, wide || map) ? wide || map : 0);
+// Edge labels are 11 px, the smallest reader text at scale 1.
+const READER_PX = 11;
+const DESKTOP_PX = 9;
+const DESKTOP_BOX = 600;
+export const textFloor = (box) => (box < DESKTOP_BOX ? READER_PX : DESKTOP_PX);
+export const fitScale = (wide, box, map) => Math.max(wide ? 1 : textFloor(box) / READER_PX, Math.min(1, box / map));
+export const shownFont = (size, place, scale) => size * (place === 'map' ? scale.map : place === 'rail' ? scale.rail : 1);
+const folds = (box, row) => box * READER_PX < row * textFloor(box);
+export const nextWide = (wide, box, map) => {
+    const row = Math.abs(wide) || map;
+    if (!folds(box, row))
+        return 0;
+    return wide > 0 && map >= wide ? -wide : wide || map;
+};

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 {};