flowfig 0.11.0 → 0.12.0

package/dist/explain.js

@@ -0,0 +1,161 @@
+import { edgeId, isGroup, isLanesLayout, nodes, str, toBeat } from './model.js';
+const CAST_MAX = 6;
+const isStore = (n) => n.shape === 'store';
+const isDecision = (n) => n?.shape === 'decision';
+const dead = (t) => t === 'red' || t === 'gray';
+export const isCheck = (n) => !!n && (n.shape === 'decision' || !!n.check);
+export const question = (n) => n.check || (n.shape === 'decision' ? str(n.label) : '');
+export const failed = (byId, h) => isCheck(byId.get(h.source)) && (dead(byId.get(h.target)?.tone) || h.tone === 'red');
+const labeledTop = (g) => g.children.flatMap((c) => (!isGroup(c) ? [] : c.label != null ? [c] : labeledTop(c)));
+export const hopsOf = (fig, step) => {
+    const byId = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    return step.flow.map((b) => {
+        const beat = toBeat(b);
+        const hops = beat.hops.flatMap((h) => {
+            const edge = byId.get(h.edge);
+            return edge ? [{ ...h, edge, source: h.back ? edge.to : edge.from, target: h.back ? edge.from : edge.to }] : [];
+        });
+        return { beat, hops };
+    });
+};
+export function cast(fig) {
+    const all = nodes(fig.layout);
+    const stores = all.filter(isStore);
+    const byId = new Map(all.map((n) => [n.id, n]));
+    const groups = fig.lanes && isLanesLayout(fig.layout) ? fig.layout.children.filter(isGroup) : labeledTop(fig.layout);
+    let actors = [];
+    for (const g of groups) {
+        const boxes = nodes(g).filter((n) => !isStore(n));
+        if (boxes.length)
+            actors.push({ name: str(g.label), look: g.look, boxes: boxes.map((n) => n.id) });
+    }
+    if (actors.length) {
+        const owned = new Set(actors.flatMap((a) => a.boxes));
+        for (const step of fig.steps ?? [])
+            for (const { hops } of hopsOf(fig, step))
+                for (const id of hops.flatMap((h) => [h.source, h.target])) {
+                    const n = byId.get(id);
+                    if (!n || owned.has(id) || isStore(n) || isDecision(n))
+                        continue;
+                    owned.add(id);
+                    actors.push({ name: str(n.label), look: n.look, boxes: [id] });
+                }
+        const rank = new Map(all.map((n, i) => [n.id, i]));
+        actors.sort((a, b) => rank.get(a.boxes[0]) - rank.get(b.boxes[0]));
+    }
+    if (!actors.length) {
+        const seen = new Set();
+        for (const step of fig.steps ?? [])
+            for (const { hops } of hopsOf(fig, step))
+                for (const h of hops)
+                    for (const id of [h.source, h.target])
+                        if (byId.has(id) && !isStore(byId.get(id)) && !isDecision(byId.get(id)))
+                            seen.add(id);
+        actors = [...seen].slice(0, stores.length ? CAST_MAX - 1 : CAST_MAX).map((id) => {
+            const n = byId.get(id);
+            return { name: str(n.label), look: n.look, boxes: [id] };
+        });
+    }
+    if (stores.length)
+        actors.push({ name: 'Records', look: stores.find((s) => s.look)?.look, boxes: stores.map((s) => s.id) });
+    return actors;
+}
+export function moments(fig, step) {
+    const s = fig.steps?.find((x) => str(x.label) === step);
+    if (!s)
+        return [];
+    const actors = cast(fig);
+    const byId = new Map(nodes(fig.layout).map((n) => [n.id, n]));
+    const actorOf = new Map(actors.flatMap((a) => a.boxes.map((id) => [id, a.name])));
+    const groupLabels = new Map();
+    const walk = (g) => {
+        for (const c of g.children) {
+            if (!isGroup(c))
+                continue;
+            if (c.id)
+                groupLabels.set(c.id, c.label);
+            walk(c);
+        }
+    };
+    walk(fig.layout);
+    const labelOf = (id) => str(byId.get(id)?.label ?? groupLabels.get(id));
+    const beats = hopsOf(fig, s);
+    if (!beats.length)
+        return [];
+    const last = beats.flatMap((b) => b.hops).at(-1);
+    const outcome = last ? labelOf(last.target) : '';
+    let prev = actors[0]?.name ?? '';
+    const out = beats.map(({ beat, hops }, i) => {
+        const end = hops.at(-1);
+        const own = (id) => actorOf.get(id) ?? labelOf(id);
+        const actor = !end ? prev : actorOf.has(end.target) || !isDecision(byId.get(end.target)) ? own(end.target) : i ? prev : own(end.source);
+        prev = actor;
+        const labels = hops.map((h) => str(h.edge.label)).filter(Boolean);
+        const say = str(beat.say) || (end ? (labels.length ? `${labels.join(', ')}: ${labelOf(end.target)}` : labelOf(end.target)) : '');
+        const moment = { actor, say, note: str(beat.note), records: [] };
+        const asks = hops.filter((h) => isCheck(byId.get(h.source)));
+        const ask = asks.find((h) => failed(byId, h)) ?? asks.at(-1);
+        if (ask) {
+            moment.stamp = { mark: failed(byId, ask) ? '✗' : '✓', label: str(ask.edge.label) };
+            moment.question = question(byId.get(ask.source));
+        }
+        for (const h of hops) {
+            const store = byId.get(h.target);
+            if (store && isStore(store))
+                moment.records.push(str(h.data) || str(h.edge.label) || str(store.label));
+        }
+        return moment;
+    });
+    const mine = new Set(beats.flatMap((b) => b.hops.flatMap((h) => [h.source, h.target])));
+    const refusal = beats.flatMap((b) => b.hops).find((h) => failed(byId, h));
+    const order = [];
+    if (refusal) {
+        const live = fig.edges.filter((e) => e !== refusal.edge && byId.has(e.to) && !dead(byId.get(e.to).tone));
+        const reach = new Set([refusal.source]);
+        for (let grew = true; grew;) {
+            grew = false;
+            for (const e of live)
+                if (reach.has(e.from) && !reach.has(e.to)) {
+                    reach.add(e.to);
+                    grew = true;
+                }
+        }
+        const inner = live.filter((e) => reach.has(e.from) && reach.has(e.to) && e.to !== refusal.source);
+        const need = new Map();
+        for (const e of inner)
+            need.set(e.to, (need.get(e.to) ?? 0) + 1);
+        for (const queue = [refusal.source]; queue.length;) {
+            const id = queue.shift();
+            order.push(id);
+            for (const e of inner) {
+                if (e.from !== id)
+                    continue;
+                need.set(e.to, need.get(e.to) - 1);
+                if (!need.get(e.to))
+                    queue.push(e.to);
+            }
+        }
+        for (const id of reach)
+            if (!order.includes(id))
+                order.push(id);
+    }
+    const notReached = order
+        .slice(1)
+        .filter((id) => !mine.has(id))
+        .map(labelOf);
+    out.forEach((m, i) => {
+        const next = out.slice(i + 1).find((o) => o.actor !== m.actor);
+        if (!m.note && next)
+            m.note = `${next.actor} acts next.`;
+    });
+    out.push({
+        actor: out.at(-1).actor,
+        say: s.outcome || (/[.?!]$/.test(outcome) ? outcome : `${outcome}.`),
+        note: '',
+        records: [],
+        summary: { outcome, notReached },
+    });
+    return out;
+}
+const PLACES = ['person', 'shop', 'truck'];
+export const worldReady = (fig) => fig.edges.some((e) => !!e.carries && typeof e.carries === 'object') || cast(fig).some((a) => PLACES.includes(a.look));

package/dist/frames.d.ts

@@ -0,0 +1,34 @@
+import { type FlowProps } from './model.ts';
+export type Tile = {
+    frame: number;
+    kinds: string[];
+    step: number;
+    beat: number;
+    text: string;
+    say: string;
+};
+type Grid = {
+    cols: number;
+    rows: number;
+    tile: number;
+    tileH: number;
+    width: number;
+    height: number;
+    warning?: string;
+};
+export declare function keyFrames(fig: FlowProps, o: {
+    fps: number;
+    every?: number;
+    step?: number;
+}): {
+    tiles: Tile[];
+    frames: number;
+};
+export declare function sheetGrid(count: number, width: number, height: number, scale?: number): Grid;
+export declare function sheetSvg(tiles: Tile[], pngs: Buffer[], grid: Grid, o: {
+    header: string;
+    fps: number;
+    dark: boolean;
+    scale: number;
+}): string;
+export {};

package/dist/frames.js

@@ -0,0 +1,117 @@
+import { beatTimes, DARK, edgeId, LIGHT, n2, nodes, scenes, str, toBeat, tourPlan } from './model.js';
+import { esc } from './page.js';
+import { textWidth } from './text.js';
+export function keyFrames(fig, o) {
+    const steps = fig.steps ?? [];
+    const beats = steps.map((s) => s.flow.map(toBeat));
+    const tour = scenes(fig).length > 1 ? tourPlan(fig) : undefined;
+    const model = tour?.times ?? beatTimes(beats, fig.speed ?? 900);
+    const loop = tour ? tour.ms / 1000 : (model.ends.at(-1) ?? 0);
+    const dur = n2(loop || 1);
+    const scale = loop ? dur / loop : 1;
+    const times = {
+        beats: model.beats.map((step) => step.map((b) => ({ t0: b.t0 * scale, t1: b.t1 * scale, tEnd: b.tEnd * scale }))),
+        ends: model.ends.map((e) => e * scale),
+    };
+    const frames = Math.max(1, Math.round(dur * o.fps));
+    const first = o.step ?? 1;
+    const name = new Map(nodes(fig.layout).map((n) => [n.id, str(n.label) || n.id]));
+    const edges = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    const hopText = (si, bi) => beats[si][bi].hops
+        .map((h) => {
+        const e = edges.get(h.edge);
+        if (!e)
+            return h.edge;
+        const [a, b] = h.back ? [e.to, e.from] : [e.from, e.to];
+        const label = str(e.label);
+        return `${name.get(a) ?? a} → ${name.get(b) ?? b}${label ? ` (${label})` : ''}`;
+    })
+        .join('; ') || 'no hop';
+    const said = (si, bi) => {
+        const at = beats[si].slice(0, bi + 1).findLastIndex((b) => b.say != null);
+        return str(at === -1 ? steps[si].caption : beats[si][at].say);
+    };
+    const tiles = [];
+    const add = (at, kind, si, bi, text, say) => {
+        const last = tiles.at(-1);
+        const frame = Math.min(frames - 1, Math.max(at, last?.frame ?? 0));
+        if (last && frame === last.frame) {
+            if (!last.kinds.includes(kind))
+                last.kinds.push(kind);
+            return;
+        }
+        tiles.push({ frame, kinds: [kind], step: si + first, beat: bi + 1, text, say });
+    };
+    const f = o.fps;
+    if (o.every) {
+        const flat = beats.flatMap((step, si) => step.map((b, bi) => ({ si, bi, hop: b.hops.length > 0, ...times.beats[si][bi] })));
+        for (let k = 0; k * o.every < dur * 1000; k++) {
+            if (Math.round((k * o.every * f) / 1000) >= frames)
+                break;
+            const t = (k * o.every) / 1000;
+            const at = flat.findLast((x) => x.t0 <= t) ?? flat[0];
+            const kind = at.hop && t < Math.min(at.t1, at.tEnd) ? 'move' : t < at.tEnd ? 'read' : 'hold';
+            add(Math.round((k * o.every * f) / 1000), kind, at.si, at.bi, hopText(at.si, at.bi), said(at.si, at.bi));
+        }
+        return { tiles, frames };
+    }
+    beats.forEach((step, si) => {
+        step.forEach((b, bi) => {
+            const { t0, t1, tEnd } = times.beats[si][bi];
+            const text = hopText(si, bi), say = said(si, bi);
+            if (b.hops.length) {
+                add(Math.round(((t0 + Math.min(t1, tEnd)) / 2) * f), 'move', si, bi, text, say);
+                if (t1 <= tEnd)
+                    add(Math.ceil(t1 * f + 0.5), 'arrive', si, bi, text, say);
+            }
+            add(Math.floor(tEnd * f - 0.5), 'read', si, bi, text, say);
+        });
+        add(Math.floor(times.ends[si] * f - 0.5), 'end', si, -1, `end of step ${si + first}: ${str(steps[si].label)}`, '');
+    });
+    return { tiles, frames };
+}
+export function sheetGrid(count, width, height, scale = 1) {
+    const [limit, gap, head, band] = [1568, 8, 24, 34].map((n) => Math.round(n * scale));
+    const size = (cols, tile) => {
+        const rows = Math.ceil(count / cols), tileH = Math.round((tile * height) / width);
+        return { cols, rows, tile, tileH, width: cols * tile + (cols + 1) * gap, height: head + rows * (tileH + band) + (rows + 1) * gap };
+    };
+    let best = size(1, 0);
+    for (let c = 1; c <= count; c++) {
+        const rows = Math.ceil(count / c);
+        let tile = Math.floor(Math.min((limit - (c + 1) * gap) / c, (((limit - head - (rows + 1) * gap) / rows - band) * width) / height));
+        while (tile > 1 && Math.max(size(c, tile).width, size(c, tile).height) > limit)
+            tile--;
+        if (tile > best.tile)
+            best = size(c, tile);
+    }
+    const small = 160 * scale;
+    return best.tile < small
+        ? { ...best, warning: `warning: the tiles are ${best.tile} px wide, under ${small} px. Use --step <n> to show fewer tiles.` }
+        : best;
+}
+export function sheetSvg(tiles, pngs, grid, o) {
+    const c = o.dark ? DARK : LIGHT;
+    const [gap, head, band, font, pad] = [8, 24, 34, 12, 4].map((n) => Math.round(n * o.scale));
+    const fit = (line) => {
+        let cut = line;
+        while (cut && textWidth(cut === line ? cut : cut + '…', font, true) > grid.tile - 2 * pad)
+            cut = cut.slice(0, -1);
+        return cut === line ? line : cut + '…';
+    };
+    const text = (x, y, s) => `<text x="${x}" y="${y}">${esc(s)}</text>`;
+    const cells = tiles.map((t, i) => {
+        const x = gap + (i % grid.cols) * (grid.tile + gap), y = head + gap + Math.floor(i / grid.cols) * (grid.tileH + band + gap);
+        const line1 = `#${t.frame} · ${Math.round((t.frame * 1000) / o.fps)} ms · step ${t.step}${t.beat ? ` beat ${t.beat}` : ''} · ${t.kinds.join('+')}`;
+        return (`<image x="${x}" y="${y}" width="${grid.tile}" height="${grid.tileH}" href="data:image/png;base64,${pngs[i].toString('base64')}"/>` +
+            `<rect x="${x - 0.5}" y="${y - 0.5}" width="${grid.tile + 1}" height="${grid.tileH + 1}" fill="none" stroke="${c.border}"/>` +
+            text(x + pad, y + grid.tileH + Math.round(14 * o.scale), fit(line1)) +
+            text(x + pad, y + grid.tileH + Math.round(29 * o.scale), fit(t.text)));
+    });
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${grid.width}" height="${grid.height}" viewBox="0 0 ${grid.width} ${grid.height}" ` +
+        `font-family="ui-monospace, Menlo, Consolas, monospace" font-size="${font}" fill="${c.fg}">` +
+        `<rect width="${grid.width}" height="${grid.height}" fill="${c.surface}"/>` +
+        text(gap, head - Math.round(7 * o.scale), o.header) +
+        cells.join('') +
+        `</svg>`);
+}