flowfig 0.10.0 → 0.12.0

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;

package/dist/svg.js

@@ -6,17 +6,20 @@ import { checkRendered, planFor } from './check.js';
 import { autoLayout, rowBreaks } from './auto.js';
 export { parseSource, links } from './source.js';
 export { diff, formatDiff, mergeFigures } from './diff.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, altText, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, altText, beatTimes, n2, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, scenes, tourPlan, flowOrder, OPEN_MS, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const SUB_LINE = 15;
 const MIN_W = 320;
 const FRAME_TOP = 37, FRAME_BOTTOM = 18;
-// The card-on fills approximate the player's 8 % accent tint.
-const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
+const color = (t, k) => {
+    const v = String(t[k]);
+    const depth = [...v].reduce((d, c) => (d < 0 ? d : d + (c === '(' ? 1 : c === ')' ? -1 : 0)), 0);
+    return /^[#a-zA-Z0-9 ,.%()/+-]+$/.test(v) && !/url\(/i.test(v) && depth === 0 ? v : LIGHT[k];
+};
+const vars = (t, cardOn) => `--accent:${color(t, 'accent')}; --fg:${color(t, 'fg')}; --muted:${color(t, 'muted')}; --bg:${color(t, 'bg')}; --surface:${color(t, 'surface')}; --border:${color(t, 'border')}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
 const content = (c) => (isRows(c) ? c : str(c));
 const esc = (s) => s.replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c]);
-const n2 = (v) => Math.round(v * 10) / 10;
 // Four decimals: one decimal rounds a 0.7 s hop away and the packet jumps.
 const n4 = (v) => Math.round(v * 10000) / 10000;
 const pct = (v) => Math.round(v * 10000) / 100 + '%';
@@ -162,6 +165,7 @@ function place(item, x, y, s, out) {
     }
 }
 const MARK_COLOR = { added: TONES.green, removed: TONES.red, changed: TONES.orange };
+const tagged = (op, id, inner) => op ? `<g data-diff="${op}" data-id="${esc(id)}">${inner}</g>` : inner;
 const marked = (mark, inner) => mark === 'removed' ? `<g opacity="0.5" stroke-dasharray="5 4">${inner}</g>` : mark ? `<g stroke-width="2">${inner}</g>` : inner;
 function legendOf(m) {
     const count = (kind) => Object.values(m.boxes).filter((k) => k === kind).length + Object.values(m.edges).filter((k) => k === kind).length;
@@ -179,7 +183,9 @@ function legendSvg(items, W, H) {
     let x = (W - legendWidth(items)) / 2;
     return items
         .map((i, k) => {
-        const sq = i.color === 'none' ? '' : `<rect x="${n2(x)}" y="${n2(H - 24)}" width="10" height="10" rx="2" fill="${i.color}"/>`;
+        const sq = i.color === 'none'
+            ? ''
+            : `<rect x="${n2(x)}" y="${n2(H - 24)}" width="10" height="10" rx="2" fill="${i.color}" data-diff="${i.text.split(' ')[0]}"/>`;
         const out = `${sq}<text x="${n2(x + (i.color === 'none' ? 0 : 16))}" y="${n2(H - 15)}" font-size="12" fill="var(--muted)">${esc(i.text)}</text>\n`;
         x += widths[k] + 20;
         return out;
@@ -187,10 +193,10 @@ function legendSvg(items, W, H) {
         .join('');
 }
 const SYSTEM_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
-/** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
-export function render(spec, opts = {}) {
+function draw(spec, opts, at) {
     const fig = autoLayout(spec);
-    const speed = (opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
+    const sc = opts.scope ?? '';
+    const pre = at?.prefix ?? sc;
     const pad = opts.padding ?? 24;
     const tl = fig.timeline && isLanesLayout(fig.layout) ? timelineLayout(fig, TL_AXIS_W) : null;
     const synthetic = tl != null && !fig.steps?.length && !opts.marks;
@@ -293,10 +299,10 @@ export function render(spec, opts = {}) {
         const dl = dia ? diamondLines(p.item, p.w) : null;
         const room = (far) => diamondRoom(p.w, p.h, far);
         const flat = (p.item.shape === 'decision' ? p.w - 70 : p.w) - 16;
-        const texts = labelLines(p.item, p.w).map((text) => ({
+        const texts = labelLines(p.item, p.w).map((text, i) => ({
             text,
             fontSize: 14,
-            room: dl ? room(dl.label.far) : flat,
+            room: dl ? room(dl.label[i].far) : flat,
         }));
         if (dl)
             for (const l of dl.subs)
@@ -319,12 +325,10 @@ export function render(spec, opts = {}) {
     const segs = [];
     const hops = [];
     const edgeOf = Object.fromEntries(fig.edges.map((e, i) => [ids[i], e]));
-    let t = 0;
+    const times = at?.times ?? beatTimes(beats, opts.speed ?? fig.speed ?? 900);
     beats.forEach((stepBeats, si) => {
         stepBeats.forEach((b, bi) => {
-            const last = bi === stepBeats.length - 1;
-            const dur = beatMs(b, opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
-            const hold = last ? STEP_HOLD_MS / 1000 / BASE_RATE : 0;
+            const { t0, t1, tEnd } = times.beats[si][bi];
             b.hops.forEach((h, lane) => {
                 if (byId[h.edge])
                     hops.push({
@@ -336,16 +340,15 @@ export function render(spec, opts = {}) {
                         back: h.back,
                         data: h.data,
                         tone: h.tone && TONES[h.tone],
-                        t0: t,
-                        t1: t + speed,
-                        tEnd: t + dur,
+                        t0,
+                        t1,
+                        tEnd,
                     });
             });
-            segs.push({ t0: t, t1: t + dur + hold, si, bi });
-            t += dur + hold;
+            segs.push({ t0, t1: bi === stepBeats.length - 1 ? times.ends[si] : tEnd, si, bi });
         });
     });
-    const total = t || 1;
+    const total = at?.total ?? (times.ends.at(-1) || 1);
     const shownAt = segs.map(({ si, bi }) => Object.assign({}, ...beats[si].slice(0, bi + 1).map((b) => b.show)));
     const litEdges = segs.map(({ si, bi }) => new Set(beats[si].slice(0, bi + 1).flatMap((b) => b.hops.map((h) => h.edge))));
     const litNodes = segs.map((seg, i) => {
@@ -383,7 +386,7 @@ export function render(spec, opts = {}) {
             return '';
         const key = prefix + on.map((x) => (x ? 1 : 0)).join('');
         if (!seen.has(key)) {
-            const name = `a${seen.size}`;
+            const name = `${pre}a${seen.size}`;
             seen.set(key, name);
             const frames = runs(on.map((x) => (x ? onCss : offCss)));
             css.push(`@keyframes ${name} { ${frames} }\n.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
@@ -400,7 +403,7 @@ export function render(spec, opts = {}) {
             return '';
         const key = prefix + values.join('|');
         if (!seen.has(key)) {
-            const name = `a${seen.size}`;
+            const name = `${pre}a${seen.size}`;
             seen.set(key, name);
             const kf = runs(values);
             css.push(`@keyframes ${name} { ${kf} }\n.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
@@ -464,7 +467,7 @@ export function render(spec, opts = {}) {
         const kf = merged.map((f) => `${pct(f.a / total)},${pct(f.b / total - 0.0001)} { ${f.css} }`);
         const key = (shape ? 'B' : 'R') + kf.join(' ');
         if (!seen.has(key)) {
-            const name = `a${seen.size}`;
+            const name = `${pre}a${seen.size}`;
             seen.set(key, name);
             css.push(`@keyframes ${name} { ${kf.join(' ')} }\n.${name} { animation: ${name} ${n2(total)}s infinite linear; }`);
         }
@@ -482,9 +485,11 @@ export function render(spec, opts = {}) {
         }
         const diffMark = opts.marks?.boxes[item.id];
         const href = opts.links?.[item.id];
+        const fade = at?.fades?.get(item.id);
         const tip = (inner) => {
-            const body = marked(diffMark, item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner);
-            return href == null ? body : `<a href="${esc(href)}" tabindex="-1">${body}</a>`;
+            const body = tagged(diffMark, item.id, marked(diffMark, item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner));
+            const linked = href == null ? body : `<a href="${esc(href)}" tabindex="-1">${body}</a>`;
+            return fade ? `<g class="${fade}">${linked}</g>` : linked;
         };
         const bt = diffMark ? MARK_COLOR[diffMark] : item.tone && TONES[item.tone];
         const stroke = cls(boxAnim(item.id, true, bt));
@@ -501,23 +506,29 @@ export function render(spec, opts = {}) {
             return tip(shape + `<text x="${n2(tx)}" y="${n2(cy + 4.5)}" class="bar">${esc(label)}</text>`);
         }
         const rim = item.shape === 'store' ? cls(boxAnim(item.id, false, bt)) : '';
+        const port = at?.ports.has(item.id);
         const fill0 = bt ? toneTint(bt, 'var(--bg)') : 'var(--bg)';
         const stroke0 = bt ?? 'var(--border)';
         const cx = p.x + p.w / 2;
         const contents = cards.get(item.id);
         const cardTop = p.y + p.h - 10 - (contents ? cardH.get(item.id) : 0);
         const dl = item.shape === 'decision' && !contents ? diamondLines(item, p.w) : null;
-        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (dl ? dl.label.dy : item.sub ? -2 : 5);
+        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (dl ? dl.label[0].dy : item.sub ? -2 : 5);
         const shape = item.shape === 'decision'
             ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(p.y + p.h / 2)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(p.y + p.h / 2)}" fill="${fill0}" stroke="${stroke0}"${stroke}/>`
             : item.shape === 'store'
                 ? `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(p.w)} 0 v ${n2(p.h - 24)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(-p.w)} 0 z" fill="${fill0}" stroke="${stroke0}"${stroke}/>` +
                     `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 0 ${n2(p.w)} 0" fill="none" stroke="${stroke0}"${rim}/>`
-                : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
+                : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${port ? ' stroke-dasharray="4 3"' : ''}${stroke}/>`;
+        const opens = at?.owners.has(item.id) && item.shape !== 'decision'
+            ? `<rect x="${n2(p.x + 3)}" y="${n2(p.y + 3)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="var(--bg)" stroke="var(--border)"/>`
+            : '';
         const lines = labelLines(item, p.w);
         const extra = (lines.length - 1) * LABEL_LINE;
-        const firstY = item.shape === 'store' || contents ? labelY : labelY - extra / 2;
-        const label = lines.map((l, i) => `<text x="${n2(cx)}" y="${n2(firstY + i * LABEL_LINE)}" class="label">${esc(l)}</text>`).join('');
+        const firstY = item.shape === 'store' || contents || dl ? labelY : labelY - extra / 2;
+        const label = lines
+            .map((l, i) => `<text x="${n2(cx)}" y="${n2(firstY + i * LABEL_LINE)}"${cls('label', port && 'muted')}>${esc(l)}</text>`)
+            .join('');
         const sub = dl
             ? dl.subs.map((l) => `<text x="${n2(cx)}" y="${n2(p.y + p.h / 2 + l.dy)}" class="sub">${esc(l.text)}</text>`).join('')
             : item.sub
@@ -532,7 +543,7 @@ export function render(spec, opts = {}) {
             : item.mark === 'end'
                 ? `<circle cx="${mx}" cy="${my}" r="6.25" fill="none" stroke="${dot}" stroke-width="1.5"/><circle cx="${mx}" cy="${my}" r="4" fill="${dot}"/>`
                 : '';
-        return tip(shape + label + sub + mark + (contents ? card(p, cardTop, contents) : ''));
+        return tip(opens + shape + label + sub + mark + (contents ? card(p, cardTop, contents) : ''));
     });
     function card(p, top, contents) {
         const id = p.item.id;
@@ -603,9 +614,9 @@ export function render(spec, opts = {}) {
         const tip = edgeTip(r.id, e.source, beats.flat());
         const path0 = r.stub
             ? r.stub.parts
-                .map((d) => `<path d="${d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
-                .join('') + `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="none"/>`
-            : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
+                .map((d) => `<path d="${d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#${sc}arrow)"${lit}/>`)
+                .join('') + `<path id="${pre}p-${esc(r.id)}" d="${r.d}" fill="none" stroke="none"/>`
+            : `<path id="${pre}p-${esc(r.id)}" d="${r.d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#${sc}arrow)"${lit}/>`;
         const path = tip ? `<g><title>${esc(tip)}</title>${path0}</g>` : path0;
         const pillColor = em ? MARK_COLOR[em] : undefined;
         const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="${pillColor ? toneTint(pillColor, 'var(--bg)', 14) : 'var(--bg)'}" stroke="${pillColor ?? 'var(--border)'}"` +
@@ -625,11 +636,11 @@ export function render(spec, opts = {}) {
             fonts.push(11);
             label = pill(r.mid.x, r.mid.y, lw, str(e.label));
         }
-        return marked(em === 'removed' ? em : undefined, hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label);
+        return tagged(em, r.id, marked(em === 'removed' ? em : undefined, hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label));
     });
     const packets = hops.map((h, i) => {
-        const t0 = h.t0 / total, t1 = h.t1 / total, tEnd = h.tEnd / total;
-        const name = `p${i}`;
+        const t0 = h.t0 / total, t1 = Math.min(h.t1 / total, 1), tEnd = h.tEnd / total, reach = n4((t1 - t0) / (h.t1 / total - t0));
+        const name = `${pre}p${i}`;
         css.push(`@keyframes ${name} { 0%,${pct(t0)} { opacity: 0 } ${pct(t0 + 0.0001)},${pct(tEnd - 0.0001)} { opacity: 1 } ${pct(tEnd)},100% { opacity: 0 } }\n` +
             `.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
         const chip = (() => {
@@ -644,8 +655,8 @@ export function render(spec, opts = {}) {
                 lines.map((l, li) => `<text x="0" y="${n2(-boxH - 12 + 15 * li + 15)}" class="chip">${esc(l)}</text>`).join(''));
         })();
         return (`<g${cls(name)} opacity="0"><circle r="10" fill="${h.tone ?? 'var(--accent)'}" opacity="0.2"/><circle r="4.5" fill="${h.tone ?? 'var(--accent)'}"/>${chip}` +
-            `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n4(t0)};${n4(t1)};1" keyPoints="${h.back ? '1;1;0;0' : '0;0;1;1'}" calcMode="linear">` +
-            `<mpath href="#p-${esc(h.edge)}" xlink:href="#p-${esc(h.edge)}"/></animateMotion></g>`);
+            `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n4(t0)};${n4(t1)};1" keyPoints="${h.back ? `1;1;${n4(1 - reach)};${n4(1 - reach)}` : `0;0;${reach};${reach}`}" calcMode="linear">` +
+            `<mpath href="#${pre}p-${esc(h.edge)}" xlink:href="#${pre}p-${esc(h.edge)}"/></animateMotion></g>`);
     });
     let axisSvg = '', lineSvg = '', todaySvg = '';
     if (tl) {
@@ -697,7 +708,7 @@ export function render(spec, opts = {}) {
                     at = home;
                 }
             });
-            const name = `a${seen.size}`;
+            const name = `${pre}a${seen.size}`;
             seen.set('playhead', name);
             const kf = pts.map(([t, x]) => `${pct(t / total)} { transform: translateX(${n2(x - home)}px) }`).join(' ');
             css.push(`@keyframes ${name} { ${kf} }\n.${name} { animation: ${name} ${n2(total)}s infinite linear; }`);
@@ -706,7 +717,7 @@ export function render(spec, opts = {}) {
                 const on = dates.map((x) => x.d === d);
                 const key = `d${d}${on.map((x) => (x ? 1 : 0)).join('')}`;
                 if (!seen.has(key)) {
-                    const nm = `a${seen.size}`;
+                    const nm = `${pre}a${seen.size}`;
                     seen.set(key, nm);
                     const fr = dates
                         .map((x) => `${pct(x.a / total)},${pct(x.b / total - 0.0001)} { opacity: ${x.d === d ? 1 : 0} } ${pct(x.b / total)} { opacity: 0 }`)
@@ -739,17 +750,20 @@ export function render(spec, opts = {}) {
     const H = (only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH) + legendH;
     const shift = (W - (bounds.w + pad * 2 + arcL + arcR)) / 2 + arcL;
     const railX = rail ? (W - rail.width) / 2 : 0;
+    const still = (on) => !!at?.fades && on.every(Boolean);
     const labels = rail || synthetic
         ? []
         : steps.map((_, si) => {
             const on = segs.map((s) => s.si === si);
-            return `<text x="${n2(W / 2)}" y="${n2(H - capH + 16)}" opacity="0"${cls('steplabel', anim(on, 'opacity: 1', 'opacity: 0', 's'))}>${esc(str(steps[si].label))}</text>`;
+            return `<text x="${n2(W / 2)}" y="${n2(H - legendH - capH + 16)}"${still(on) ? '' : ' opacity="0"'}${cls('steplabel', !still(on) && anim(on, 'opacity: 1', 'opacity: 0', 's'))}>${esc(str(steps[si].label))}</text>`;
         });
     const said = [...new Set(captions)].map((text) => {
         const on = captions.map((c) => c === text);
         const lines = wrap(text, wrapW, 13.5);
-        return (`<g opacity="0"${cls(anim(on, 'opacity: 1', 'opacity: 0', 'y'))}>` +
-            lines.map((l, li) => `<text x="${n2(W / 2)}" y="${n2(H - capH + capTop + 16 + li * 20)}" class="caption">${esc(l)}</text>`).join('') +
+        return (`<g${still(on) ? '' : ` opacity="0"${cls(anim(on, 'opacity: 1', 'opacity: 0', 'y'))}`}>` +
+            lines
+                .map((l, li) => `<text x="${n2(W / 2)}" y="${n2(H - legendH - capH + capTop + 16 + li * 20)}" class="caption">${esc(l)}</text>`)
+                .join('') +
             `</g>`);
     });
     const railSvg = !rail
@@ -818,47 +832,15 @@ export function render(spec, opts = {}) {
                     : '';
                 const tip = edgeTip(row.edge, fig.edges[ids.indexOf(row.edge)].source, beats.flat());
                 parts.push(`<g${cls('railrow', moveRow(i))}>${tip ? `<title>${esc(tip)}</title>` : ''}<g${cls(anim(next, 'opacity: .45', 'opacity: 1', 'r'))}>` +
-                    `<path d="M ${n2(x1)} ${n2(ly)} H ${n2(x2)}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}"${row.async ? ' stroke-dasharray="4 3"' : ''} marker-end="url(#arrow)"${cls(lit)}/>` +
+                    `<path d="M ${n2(x1)} ${n2(ly)} H ${n2(x2)}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}"${row.async ? ' stroke-dasharray="4 3"' : ''} marker-end="url(#${sc}arrow)"${cls(lit)}/>` +
                     tag +
                     pill +
                     `</g></g>`);
             });
             return `<g transform="translate(${n2(railX)} 0)">${parts.join('')}</g>`;
         })();
-    const { font, ...t0 } = { ...LIGHT, ...fig.theme, ...opts.theme };
-    const alt = altText(fig);
     const holdAt = beats[0]?.length ? n2(segs[beats[0].length - 1].t1 - 0.1) : 0;
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}" role="img">
-<title>${esc(alt.title)}</title>
-<desc>${esc(alt.desc)}</desc>
-<style>
-svg { ${vars(t0, '#eef5fd')} }
-@media (prefers-color-scheme: dark) { svg { ${vars(DARK, '#1d2733')} } }
-.label { fill: var(--fg); font-size: 14px; font-weight: 500; text-anchor: middle; }
-.sub { fill: var(--muted); font-size: 12px; text-anchor: middle; }
-.frame { fill: var(--muted); font-size: 11px; font-weight: 600; letter-spacing: .04em; }
-.edgelabel { fill: var(--muted); font-size: 11px; text-anchor: middle; font-family: ui-monospace, Menlo, monospace; }
-.row { fill: var(--fg); font-size: 11px; }
-.row.mono { font-size: 10.5px; font-family: ui-monospace, Menlo, monospace; }
-.muted { fill: var(--muted); }
-.bar { fill: var(--fg); font-size: 13px; font-weight: 500; }
-.tick { fill: var(--muted); font-size: 11px; }
-.today { fill: var(--accent); font-size: 11px; font-weight: 600; }
-.tag { font-size: 9px; font-weight: 600; letter-spacing: .03em; text-anchor: middle; }
-.mark { fill: var(--accent); font-size: 11px; font-weight: 600; text-anchor: end; }
-.chip { fill: ${ON_ACCENT}; font-size: 11.5px; text-anchor: middle; }
-.steplabel { fill: var(--fg); font-size: 13px; font-weight: 600; text-anchor: middle; font-family: ui-monospace, Menlo, monospace; }
-.caption { fill: var(--muted); font-size: 13.5px; text-anchor: middle; }
-.railcol { fill: var(--fg); font-size: 12px; font-weight: 500; text-anchor: middle; }
-.railphase { fill: var(--fg); font-size: 13px; font-weight: 600; font-family: ui-monospace, Menlo, monospace; }
-.railphase.muted { fill: var(--muted); }
-.end { text-anchor: end; }
-${css.join('\n')}
-@media (prefers-reduced-motion: reduce) { * { animation-play-state: paused !important; animation-delay: -${holdAt}s !important; } }
-</style>
-<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="context-stroke"/></marker></defs>
-<rect width="100%" height="100%" fill="var(--bg)"/>
-${only
+    const body = `${only
         ? ''
         : `<g transform="translate(${n2(shift)} ${arcT})">
 ${axisSvg}
@@ -872,8 +854,7 @@ ${todaySvg}
 `}${railSvg}
 ${labels.join('\n')}
 ${said.join('\n')}
-${legendSvg(legend, W, H)}</svg>
-`;
+${legendSvg(legend, W, H)}`;
     if (rail)
         fonts.push(12, 13);
     if (legend.length)
@@ -923,7 +904,189 @@ ${legendSvg(legend, W, H)}</svg>
             lanes: placed.filter((p) => p.lane).map((p) => ({ id: str(p.item.label), rect: { x: p.x, y: p.y, w: p.w, h: p.h } })),
         }),
     };
-    return { svg, scene };
+    const frame = { x: shift - arcL, w: bounds.w + pad * 2 + arcL + arcR, h: mapH };
+    return { W, H, css: css.join('\n'), body, holdAt, scene, fig, frame };
+}
+const page = (fig, opts, W, H, css, holdAt, body) => {
+    const { font, ...t0 } = { ...LIGHT, ...fig.theme, ...opts.theme };
+    const alt = altText(fig);
+    return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}" role="img">
+<title>${esc(alt.title)}</title>
+<desc>${esc(alt.desc)}</desc>
+<style>
+svg { ${vars(t0, '#eef5fd')} }
+@media (prefers-color-scheme: dark) { svg { ${vars(DARK, '#1d2733')} } }
+.label { fill: var(--fg); font-size: 14px; font-weight: 500; text-anchor: middle; }
+.sub { fill: var(--muted); font-size: 12px; text-anchor: middle; }
+.frame { fill: var(--muted); font-size: 11px; font-weight: 600; letter-spacing: .04em; }
+.edgelabel { fill: var(--muted); font-size: 11px; text-anchor: middle; font-family: ui-monospace, Menlo, monospace; }
+.row { fill: var(--fg); font-size: 11px; }
+.row.mono { font-size: 10.5px; font-family: ui-monospace, Menlo, monospace; }
+.muted { fill: var(--muted); }
+.bar { fill: var(--fg); font-size: 13px; font-weight: 500; }
+.tick { fill: var(--muted); font-size: 11px; }
+.today { fill: var(--accent); font-size: 11px; font-weight: 600; }
+.tag { font-size: 9px; font-weight: 600; letter-spacing: .03em; text-anchor: middle; }
+.mark { fill: var(--accent); font-size: 11px; font-weight: 600; text-anchor: end; }
+.chip { fill: ${ON_ACCENT}; font-size: 11.5px; text-anchor: middle; }
+.steplabel { fill: var(--fg); font-size: 13px; font-weight: 600; text-anchor: middle; font-family: ui-monospace, Menlo, monospace; }
+.caption { fill: var(--muted); font-size: 13.5px; text-anchor: middle; }
+.railcol { fill: var(--fg); font-size: 12px; font-weight: 500; text-anchor: middle; }
+.railphase { fill: var(--fg); font-size: 13px; font-weight: 600; font-family: ui-monospace, Menlo, monospace; }
+.railphase.muted { fill: var(--muted); }
+.end { text-anchor: end; }
+${css}
+@media (prefers-reduced-motion: reduce) { * { animation-play-state: paused !important; animation-delay: -${holdAt}s !important; } }
+</style>
+<defs><marker id="${opts.scope ?? ''}arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="context-stroke"/></marker></defs>
+<rect width="100%" height="100%" fill="var(--bg)"/>
+${body}</svg>
+`;
+};
+const SCRIPT = `(()=>{const s=document.currentScript.closest('svg'),G=[...s.querySelectorAll('.scene')],S=[G[0]],R=matchMedia('(prefers-reduced-motion: reduce)').matches,
+W=(g,k)=>g.dataset[k].split(' ').map(p=>p.split(',').map(Number));let q=[],L=W(G[0],'loop'),w=[0,-1],o,t=0,p=performance.now();
+const seek=t=>{s.pauseAnimations();s.setCurrentTime(t);for(const a of s.getAnimations({subtree:true}))a.pause(),a.currentTime=t*1e3+a.effect.getTiming().delay},
+tick=n=>{if(t>=w[1]){o=q.length>0;if(!o)q=L.slice();w=q.shift();t=w[0]}seek(R?w[1]:Math.min(t,w[1]));t+=R?(o?1e9:0):(n-p)/1e3;p=n;requestAnimationFrame(tick)},
+show=()=>{const c=S.at(-1);for(const g of G){g.style.pointerEvents=g==c?'':'none';for(const x of g.querySelectorAll('.hit,.back'))x.setAttribute('role','button'),x.setAttribute('tabindex',g==c?0:-1)}},
+go=(a,b)=>{q=a;L=b;w=[0,-1];t=0;show()},
+back=()=>{if(S.length>1){const g=S.pop();go(W(g,'back'),W(S.at(-1),'loop'))}},
+act=e=>{const x=e.target.closest('.hit,.back');if(!x||x.closest('.scene')!=S.at(-1))return;if(x.classList.contains('back'))back();else{const g=G.find(g=>g.id=='s-'+x.dataset.open);S.push(g);go(W(g,'open'),W(g,'loop'))}return 1};
+s.setAttribute('role','group');s.addEventListener('click',act);
+s.addEventListener('keydown',e=>{const k=e.key;if(k=='Escape'||k=='Backspace')back();else if(!((k=='Enter'||k==' ')&&act(e)))return;e.preventDefault()});
+show();requestAnimationFrame(tick)})()`;
+const BAND = 28;
+/** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
+export function render(spec, opts = {}) {
+    const { scene: one, script, ...rest } = opts;
+    const all = scenes(spec);
+    const key = (path) => path.join('>');
+    const under = (list, path) => list.filter((x) => x.path.length === path.length + 1 && key(x.path.slice(0, -1)) === key(path));
+    const at = (s) => ({
+        ports: new Set(s.ports.map((p) => p.id)),
+        owners: new Map(under(all, s.path).map((x) => [x.path.at(-1), x.parts])),
+    });
+    if (one != null) {
+        const s = all.find((x) => x.path.at(-1) === one);
+        if (!s)
+            throw new Error(`box "${one}" has no level to open`);
+        const plain = (g) => ({
+            ...g,
+            children: g.children.map((c) => (isGroup(c) ? plain(c) : { ...c, inside: undefined })),
+        });
+        const d = draw({ ...s.props, layout: plain(s.props.layout) }, rest, at(s));
+        return { svg: page(d.fig, rest, d.W, d.H, d.css, d.holdAt, d.body), scene: d.scene };
+    }
+    if (all.length < 2) {
+        const d = draw(spec, rest);
+        return { svg: page(d.fig, rest, d.W, d.H, d.css, d.holdAt, d.body), scene: d.scene };
+    }
+    const plan = tourPlan(spec, opts.speed ?? spec.speed);
+    const total = plan.ms / 1000, eps = plan.ms / 10000;
+    const { fade, grow, stagger, hide, shrink } = OPEN_MS;
+    const tour = [];
+    const uid = `${opts.scope ?? ''}f${([...JSON.stringify(spec)].reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 7) >>> 0).toString(36)}`;
+    const track = (pts) => {
+        const name = `${uid}t${tour.length}`;
+        const kf = pts.map(([t, v, ease]) => `${pct(t / plan.ms)} { ${v}${ease ? `; animation-timing-function: ${ease}` : ''} }`).join(' ');
+        tour.push(`@keyframes ${name} { ${kf} }\n.${name} { animation: ${name} ${n2(total)}s infinite linear; }`);
+        return name;
+    };
+    const fadeAt = (o) => o.grown - grow - fade;
+    const dips = (path) => under(plan.opens, path).flatMap((n) => [
+        [fadeAt(n), 1],
+        [fadeAt(n) + fade, 0],
+        [n.back[1] - fade, 0],
+        [n.back[1], 1],
+    ]);
+    const drawn = all.map((s, i) => {
+        const o = plan.opens.find((x) => key(x.path) === key(s.path));
+        const props = o ? { ...s.props, steps: o.step === -1 ? [] : [s.props.steps[o.step]] } : spec;
+        const fades = o &&
+            new Map(flowOrder(s).map((id, k) => {
+                const t = o.grown + stagger * k;
+                return [
+                    id,
+                    track([
+                        [0, 'opacity: 0'],
+                        [t, 'opacity: 0'],
+                        [t + fade, 'opacity: 1'],
+                        [plan.ms, 'opacity: 1'],
+                    ]),
+                ];
+            }));
+        const times = o ? o.times : plan.times;
+        return { s, o, props, d: draw(props, rest, { prefix: `${uid}s${i}`, ...at(s), fades, times, total }) };
+    });
+    const W = Math.max(...drawn.map((x) => x.d.W)), H = Math.max(...drawn.map((x) => x.d.H)) + BAND;
+    const off = (d) => [(W - d.W) / 2, (H + BAND - d.H) / 2];
+    const windows = (w, at) => (w.length ? w : [[at, at]]).map(([a, b]) => `${n2(a / 1000)},${n2(b / 1000)}`).join(' ');
+    const groups = drawn.map(({ s, o, d }) => {
+        const shown = o
+            ? [
+                [0, 0],
+                [o.grown, 0],
+                [o.grown + eps, 1],
+                ...dips(s.path),
+                [o.back[1] - fade - shrink - hide, 1],
+                [o.back[1] - fade - shrink, 0],
+                [plan.ms, 0],
+            ]
+            : [[0, 1], ...dips(s.path), [plan.ms, 1]];
+        const band = o
+            ? `<text class="back ${uid}back" x="16" y="19">Back</text><text class="${uid}path" x="${n2(16 + textWidth('Back', 14) + 12)}" y="19">${esc(s.line)}</text>`
+            : '';
+        const area = d.scene.area;
+        const hits = !script
+            ? ''
+            : under(all, s.path)
+                .map((x) => {
+                const r = d.scene.boxes.find((b) => b.id === x.path.at(-1)).rect;
+                return `<rect class="hit" x="${n2(r.x - area.x)}" y="${n2(r.y - area.y)}" width="${n2(r.w)}" height="${n2(r.h)}" fill="transparent" tabindex="0" role="button" aria-label="Open ${esc(x.name)}, ${x.parts} parts" data-open="${esc(x.path.at(-1))}"/>`;
+            })
+                .join('');
+        const data = !script
+            ? ''
+            : o
+                ? ` data-open="${windows([o.open], 0)}" data-loop="${windows(o.loop, o.open[1])}" data-back="${windows([o.back], 0)}"`
+                : ` data-loop="${windows(plan.loop, 0)}"`;
+        return (`<g class="${track(shown.map(([t, v]) => [t, `opacity: ${v}`]))}"><g class="scene"${o ? ` id="s-${esc(s.path.at(-1))}"` : ''}${data}>${band}` +
+            `<g transform="translate(${n2(off(d)[0])} ${n2(off(d)[1])})">\n${d.body}${hits}</g></g></g>`);
+    });
+    const frames = drawn.slice(1).map(({ s, o, d }) => {
+        const parent = drawn.find((x) => key(x.s.path) === key(s.path.slice(0, -1))).d;
+        const r = parent.scene.boxes.find((b) => b.id === s.path.at(-1)).rect;
+        const [px, py] = off(parent), fx = off(d)[0] + d.frame.x, fy = off(d)[1];
+        const dx = px + r.x - parent.scene.area.x - fx, dy = py + r.y - parent.scene.area.y - fy;
+        const small = `transform: translate(${n2(dx)}px, ${n2(dy)}px) scale(${n4(r.w / d.frame.w)}, ${n4(r.h / d.frame.h)})`;
+        const full = 'transform: translate(0px, 0px) scale(1, 1)';
+        const from = fadeAt(o), shut = o.back[1] - fade;
+        const name = track([
+            [0, `opacity: 0; ${small}`],
+            [from, `opacity: 0; ${small}`],
+            [from + eps, `opacity: 1; ${small}`],
+            [from + fade, `opacity: 1; ${small}`, 'cubic-bezier(0.2, 0, 0, 1)'],
+            [o.grown, `opacity: 1; ${full}`],
+            ...dips(s.path).map(([t, v]) => [t, `opacity: ${v}; ${full}`]),
+            [shut - shrink, `opacity: 1; ${full}`, 'cubic-bezier(0.4, 0, 1, 1)'],
+            [shut, `opacity: 1; ${small}`],
+            [shut + eps, `opacity: 0; ${small}`],
+            [plan.ms, `opacity: 0; ${small}`],
+        ]);
+        return (`<rect class="open-frame ${name}" data-for="${esc(s.path.at(-1))}" x="${n2(fx)}" y="${n2(fy)}" width="${n2(d.frame.w)}" height="${n2(d.frame.h)}" rx="10"` +
+            ` fill="none" stroke="var(--border)" vector-effect="non-scaling-stroke" style="transform-box: view-box; transform-origin: ${n2(fx)}px ${n2(fy)}px"/>`);
+    });
+    const root = drawn[0].d;
+    const css = [
+        ...drawn.map((x) => x.d.css),
+        `.${uid}back { fill: var(--accent); font-size: 14px; }\n.${uid}path { fill: var(--fg); font-size: 14px; }`,
+        ...tour,
+    ];
+    const body = `${groups.join('\n')}\n<g pointer-events="none">${frames.join('')}</g>\n${script ? `<script><![CDATA[${SCRIPT}]]></script>\n` : ''}`;
+    return {
+        svg: page(root.fig, rest, W, H, css.join('\n'), root.holdAt, body),
+        scene: root.scene,
+        levels: drawn.map(({ s, props, d }) => ({ line: s.line, props, scene: d.scene })),
+    };
 }
 /** One self-contained animated SVG string for the figure. Needs no React and no browser. */
 export function toSvg(fig, opts = {}) {
@@ -931,5 +1094,6 @@ export function toSvg(fig, opts = {}) {
 }
 /** Every fault `flowfig check` knows about, for this figure as the SVG lays it out. */
 export function check(fig, opts = {}) {
-    return checkRendered(fig, opts, render(fig, opts).scene);
+    const r = render(fig, opts);
+    return checkRendered(fig, opts, r.scene, r.levels);
 }

package/dist/verify.d.ts

@@ -13,8 +13,14 @@ export type Coverage = {
         id: string;
         reason: string;
     }[];
+    /** The coverage of each level inside a box, by path line. */
+    levels?: {
+        path: string;
+        coverage: Coverage;
+    }[];
 };
 export declare const coverageLine: (figure: string, c: Coverage) => string;
+export declare const levelLines: (c: Coverage) => string[];
 export declare const unsureLines: (c: Coverage) => string[];
 export declare const SPEC_MARK = "<metadata id=\"figure-spec\">";
 export declare function detailFindings(fig: FlowProps, root: string, read?: Read): Finding[];