@delurio/cli 0.0.0-stage → 0.1.0

package/dist/spine.js

@@ -0,0 +1,149 @@
+import ElkModule from 'elkjs/lib/elk.bundled.js';
+import { collectEdges, kindOf, nodeLine, wrap } from './edges.js';
+import { titleOf } from './graph.js';
+// elkjs ships CommonJS: under Node ESM the default import is module.exports, which is the constructor
+const Elk = ElkModule;
+const START = '__start';
+const CHAR_TITLE = 8.4; // 14px semibold sans
+const CHAR_LINE = 6.9; // 11.5px monospace
+const CHAR_LABEL = 7.1; // 13px sans
+const LABEL_WRAP = { main: 26, full: 22 };
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const r1 = (n) => Math.round(n * 10) / 10;
+function labelLines(e, view) {
+    return e.labels.flatMap((l) => wrap(l, LABEL_WRAP[view]));
+}
+export async function renderSpine(g, ex, view, story) {
+    const all = collectEdges(g, ex);
+    // main view: the story without failure branches and without "the user closes the page"
+    const edges = view === 'full' ? all : all.filter((e) => e.kind !== 'fail' && !e.leave);
+    const visible = new Set([g.flow.initial]);
+    for (const e of edges) {
+        visible.add(e.from);
+        visible.add(e.to);
+    }
+    const names = Object.keys(g.flow.states).filter((n) => visible.has(n));
+    const mainEdges = new Set();
+    const mainNodes = new Set();
+    (story ?? []).forEach((s, k) => {
+        mainNodes.add(s.state);
+        if (k > 0)
+            mainEdges.add(`${story?.[k - 1].state}>${s.state}`);
+    });
+    const children = [{ id: START, width: 14, height: 14 }];
+    for (const name of names) {
+        const width = Math.ceil(Math.max(150, titleOf(g.flow, name).length * CHAR_TITLE, nodeLine(g, name).length * CHAR_LINE) + 36);
+        const node = { id: name, width, height: 58 };
+        if (kindOf(g, name) === 'exit')
+            node.layoutOptions = { 'elk.layered.layering.layerConstraint': 'LAST' };
+        children.push(node);
+    }
+    const elkEdges = [{ id: 'e_start', sources: [START], targets: [g.flow.initial] }];
+    edges.forEach((e, i) => {
+        const lines = labelLines(e, view);
+        elkEdges.push({
+            id: `e${i}`,
+            sources: [e.from],
+            targets: [e.to],
+            labels: lines.length === 0
+                ? []
+                : [{ text: lines.join('\n'), width: Math.ceil(Math.max(...lines.map((l) => l.length)) * CHAR_LABEL + 14), height: lines.length * 17 + 6 }],
+        });
+    });
+    const root = {
+        id: 'root',
+        layoutOptions: {
+            'elk.algorithm': 'layered',
+            'elk.direction': 'DOWN',
+            'elk.edgeRouting': 'ORTHOGONAL',
+            'elk.padding': '[top=24,left=24,bottom=24,right=24]',
+            'elk.spacing.nodeNode': '36',
+            'elk.spacing.edgeNode': '22',
+            'elk.spacing.edgeEdge': '16',
+            'elk.spacing.edgeLabel': '6',
+            'elk.layered.spacing.nodeNodeBetweenLayers': '56',
+            'elk.layered.spacing.edgeNodeBetweenLayers': '22',
+            'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+        },
+        children,
+        edges: elkEdges,
+    };
+    const laid = await new Elk().layout(root);
+    const width = Math.ceil(laid.width ?? 800);
+    const height = Math.ceil(laid.height ?? 400);
+    const out = [];
+    out.push(`<svg class="spine" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" style="${view === 'full' ? `width:${width}px;max-width:none` : `max-width:${width}px`}" role="img" aria-label="Flowchart of ${esc(g.flow.title ?? g.flow.id)}${view === 'main' ? ' without failure paths' : ' with failure paths'}. The text sections of this page describe every step.">`);
+    out.push('<defs>');
+    for (const kind of ['user', 'system', 'route', 'fail', 'main']) {
+        out.push(`<marker id="arrow-${view}-${kind}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path class="arrow arrow-${kind}" d="M0 0 L10 5 L0 10 z"/></marker>`);
+    }
+    out.push('</defs>');
+    const byId = new Map();
+    edges.forEach((e, i) => byId.set(`e${i}`, e));
+    const drawn = (laid.edges ?? []).filter((e) => e.sections?.[0] !== undefined);
+    const isMain = (e) => e !== undefined && mainEdges.has(`${e.from}>${e.to}`);
+    const path = (e) => {
+        const section = e.sections?.[0];
+        if (section === undefined)
+            return '';
+        const pts = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint];
+        return pts.map((p, i) => `${i === 0 ? 'M' : 'L'}${r1(p.x)} ${r1(p.y)}`).join(' ');
+    };
+    for (const e of drawn) {
+        if (e.id === 'e_start')
+            out.push(`<path class="edge edge-system" d="${path(e)}" marker-end="url(#arrow-${view}-system)"/>`);
+    }
+    for (const pass of [false, true]) {
+        for (const e of drawn) {
+            const viz = byId.get(e.id);
+            if (viz === undefined || isMain(viz) !== pass)
+                continue;
+            const kind = pass ? 'main' : viz.kind;
+            out.push(`<path class="edge edge-${kind}${viz.unused ? ' edge-unused' : ''}" d="${path(e)}" marker-end="url(#arrow-${view}-${kind})"/>`);
+        }
+    }
+    for (const e of drawn) {
+        const viz = byId.get(e.id);
+        const label = e.labels?.[0];
+        if (viz === undefined || label === undefined)
+            continue;
+        const lines = labelLines(viz, view);
+        const x = label.x ?? 0;
+        const y = label.y ?? 0;
+        out.push(`<g class="elabel${isMain(viz) ? ' elabel-main' : ''}${viz.kind === 'fail' ? ' elabel-fail' : ''}"><rect x="${r1(x)}" y="${r1(y)}" width="${label.width ?? 0}" height="${label.height ?? 0}" rx="4"/>`);
+        lines.forEach((l, i) => out.push(`<text x="${r1(x + 7)}" y="${r1(y + 17 + i * 17)}">${esc(l)}</text>`));
+        out.push('</g>');
+    }
+    for (const n of laid.children ?? []) {
+        const x = r1(n.x ?? 0);
+        const y = r1(n.y ?? 0);
+        const w = n.width ?? 0;
+        const h = n.height ?? 0;
+        if (n.id === START) {
+            out.push(`<circle class="start" cx="${r1(x + 7)}" cy="${r1(y + 7)}" r="7"><title>start</title></circle>`);
+            continue;
+        }
+        const kind = kindOf(g, n.id);
+        const st = g.flow.states[n.id];
+        const exitClass = kind === 'exit' ? ` exit-${st.leavesPage === true ? 'left' : (st.redirect ?? 'error')}` : '';
+        const unreachable = !ex.atState.has(n.id);
+        const open = kind === 'screen' ? `<a href="#screen-${esc(n.id)}">` : '';
+        const close = kind === 'screen' ? '</a>' : '';
+        const by = st.by === undefined ? '' : ` by-${st.by}`;
+        const tip = [st.description ?? n.id, ...(st.includes ?? []).map((s) => `+ ${s}`)].join('\n');
+        out.push(`${open}<g class="node node-${kind}${by}${st.goal === true ? ' goal' : ''}${exitClass}${mainNodes.has(n.id) ? ' on-main' : ''}${unreachable ? ' node-unreachable' : ''}"><title>${esc(tip)}</title>`);
+        const rx = kind === 'exit' || st.by === 'ai' ? 28 : st.by === 'ci' ? 0 : 8;
+        out.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="${rx}"/>`);
+        if (st.by === 'agent')
+            out.push(`<rect class="inner" x="${r1(x + 4)}" y="${r1(y + 4)}" width="${w - 8}" height="${h - 8}" rx="5"/>`);
+        if ((st.includes ?? []).length > 0)
+            out.push(`<text class="nmore" x="${r1(x + w - 8)}" y="${r1(y + 14)}" text-anchor="end">+${st.includes?.length}</text>`);
+        if (kind === 'subflow')
+            out.push(`<rect class="inner" x="${r1(x + 4)}" y="${r1(y + 4)}" width="${w - 8}" height="${h - 8}" rx="5"/>`);
+        out.push(`<text class="nname" x="${r1(x + w / 2)}" y="${r1(y + 25)}" text-anchor="middle">${esc(titleOf(g.flow, n.id))}</text>`);
+        out.push(`<text class="nline" x="${r1(x + w / 2)}" y="${r1(y + 44)}" text-anchor="middle">${esc(nodeLine(g, n.id))}${unreachable ? ' · unreachable' : ''}</text>`);
+        out.push(`</g>${close}`);
+    }
+    out.push('</svg>');
+    return out.join('\n');
+}

package/dist/starts.js

@@ -0,0 +1,81 @@
+// `starts:` on a transition: this flow starts another one and does not wait for it (SPEC.md §2, "Several flows").
+// The started flow is looked up by id among the graphs beside this one. When it is found, every situation in which the
+// transition is taken must give it a beginning it accepts; when it is not written yet, that is a note, not a failure.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parse } from 'yaml';
+import { alternatives } from './graph.js';
+const SKIP = new Set(['viz', 'video', 'node_modules', '.git']);
+// the root to search: the nearest folder called `graphs` above the graph, else the graph's parent
+function rootOf(dir) {
+    for (let d = dir, i = 0; i < 5; i++, d = dirname(d))
+        if (basename(d) === 'graphs')
+            return d;
+    return dirname(dir);
+}
+function flowsUnder(root, depth = 4, out = new Map()) {
+    const file = join(root, 'flow.yaml');
+    if (existsSync(file)) {
+        const f = parse(readFileSync(file, 'utf8'));
+        if (typeof f?.id === 'string')
+            out.set(f.id, { ...f, context: f.context ?? {} });
+    }
+    if (depth === 0)
+        return out;
+    for (const name of readdirSync(root)) {
+        if (SKIP.has(name))
+            continue;
+        const sub = join(root, name);
+        if (statSync(sub).isDirectory())
+            flowsUnder(sub, depth - 1, out);
+    }
+    return out;
+}
+export function checkStarts(g, m, ex) {
+    const out = [];
+    let flows = null;
+    for (const [name, st] of Object.entries(g.flow.states)) {
+        const ways = [
+            ...(st.always ?? []).map((t, i) => [null, i, t]),
+            ...Object.entries(st.on ?? {}).flatMap(([event, spec]) => alternatives(spec).map((t, i) => [event, i, t])),
+        ];
+        for (const [event, i, t] of ways) {
+            if (t.starts === undefined)
+                continue;
+            flows ??= flowsUnder(rootOf(g.dir));
+            const given = t.starts.given ?? {};
+            const started = flows.get(t.starts.flow);
+            const hand = { from: name, event, flow: t.starts.flow, given, found: started !== undefined, problems: [] };
+            out.push(hand);
+            if (started === undefined)
+                continue;
+            const problem = (p) => {
+                if (!hand.problems.includes(p))
+                    hand.problems.push(p);
+            };
+            for (const k of Object.keys(given))
+                if (started.context[k] === undefined)
+                    problem(`${k} is not a variable of ${started.id}`);
+            const taken = `${name}|${event ?? 'always'}|${i}`;
+            for (const c of ex.configs) {
+                if (c.state !== name)
+                    continue;
+                for (const s of m.steps(c.state, c.ctx)) {
+                    if (s.taken !== taken)
+                        continue;
+                    for (const [k, expr] of Object.entries(given)) {
+                        const cv = started.context[k];
+                        if (cv === undefined)
+                            continue;
+                        const v = typeof expr === 'string' ? m.value(expr, name, s.ctx) : expr;
+                        if (!cv.values.includes(v))
+                            problem(`${k} would be ${JSON.stringify(v)}, which is not a value of ${started.id}'s ${k}`);
+                        else if (cv.initial !== 'any' && cv.initial !== v)
+                            problem(`${started.id} begins with ${k} = ${String(cv.initial)}, and here it would be ${String(v)}`);
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/story.js

@@ -0,0 +1,109 @@
+import { alternatives, titleOf } from './graph.js';
+import { kindOf, pressLabel } from './edges.js';
+export function stepsTo(m, ex, index) {
+    const chain = [];
+    for (let i = index; i >= 0; i = ex.configs[i].parent)
+        chain.push(i);
+    chain.reverse();
+    return chain.map((ci, k) => {
+        const c = ex.configs[ci];
+        let taken = null;
+        if (k > 0) {
+            const prev = ex.configs[chain[k - 1]];
+            const hit = m.steps(prev.state, prev.ctx).find((s) => s.target === c.state && s.event === c.event && s.ctx.join(',') === c.ctx.join(','));
+            taken = hit?.taken ?? null;
+        }
+        return { state: c.state, ctx: c.ctx, event: c.event, taken };
+    });
+}
+// The main story the graph declares: from a starting situation, send the events in order (`always` rules run by themselves).
+export function stepsByEvents(m, main) {
+    const events = Array.isArray(main) ? main : main.events;
+    const given = Array.isArray(main) ? {} : (main.given ?? {});
+    for (const init of m.initials()) {
+        if (Object.entries(given).some(([k, v]) => init[m.vars.indexOf(k)] !== v))
+            continue;
+        const path = walk(m, [{ state: m.flow.initial, ctx: init, event: null, taken: null }], events, 0);
+        if (path !== null)
+            return path;
+    }
+    return null;
+}
+// Depth first, in document order, so the first walk that sends every event wins; when an effect leaves several
+// situations (havoc), one that cannot go on gives way to the next.
+function walk(m, path, events, i) {
+    if (path.length > 500)
+        return null;
+    const cur = path[path.length - 1];
+    const steps = m.steps(cur.state, cur.ctx);
+    const autos = steps.filter((s) => s.event === null);
+    const next = autos.length > 0 ? autos : i < events.length ? steps.filter((s) => s.event === events[i]) : [];
+    if (next.length === 0)
+        return i === events.length ? path : null;
+    for (const s of next) {
+        const found = walk(m, [...path, { state: s.target, ctx: s.ctx, event: s.event, taken: s.taken }], events, autos.length > 0 ? i : i + 1);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+// The first success exit reachable through at least one screen: the story a person expects to read first.
+export function mainStoryIndex(g, ex) {
+    const viaScreen = [];
+    ex.configs.forEach((c, i) => {
+        viaScreen[i] = kindOf(g, c.state) === 'screen' || (c.parent >= 0 && viaScreen[c.parent]);
+    });
+    for (const [name, st] of Object.entries(g.flow.states)) {
+        if (st.type !== 'final' || st.redirect !== 'success')
+            continue;
+        const i = ex.configs.findIndex((c, idx) => c.state === name && viaScreen[idx]);
+        if (i >= 0)
+            return i;
+    }
+    return null;
+}
+function sayOf(g, taken) {
+    if (taken === null)
+        return null;
+    const [state, event, idx] = taken.split('|');
+    const st = g.flow.states[state];
+    const a = event === 'always' ? st.always?.[Number(idx)] : alternatives(st.on?.[event] ?? []).at(Number(idx));
+    return a?.say ?? null;
+}
+const capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+export function narrate(g, m, steps) {
+    const start = steps[0];
+    const parts = [];
+    m.vars.forEach((v, i) => {
+        const cv = g.flow.context[v];
+        if (cv.initial !== 'any')
+            return;
+        const said = cv.say?.[String(start.ctx[i])];
+        if (said === undefined)
+            parts.push(`${v} is ${start.ctx[i]}`);
+        else if (said !== '')
+            parts.push(said);
+    });
+    const lines = [];
+    steps.forEach((s, k) => {
+        if (g.flow.states[s.state].type === 'final')
+            return;
+        const next = steps[k + 1];
+        let line = titleOf(g.flow, s.state);
+        if (next !== undefined) {
+            const say = sayOf(g, next.taken);
+            const press = next.event === null ? null : pressLabel(g, s.state, next.event);
+            if (press !== null)
+                line += `: the user presses “${press}”`;
+            else if (say !== null)
+                line += next.event?.startsWith('FAIL') === true ? `: it fails, because ${say}` : `: ${say}`;
+        }
+        lines.push(line);
+    });
+    const last = steps[steps.length - 1];
+    return {
+        given: parts.length > 0 ? capital(parts.join(', ')) : 'Any request',
+        steps: lines,
+        result: titleOf(g.flow, last.state),
+    };
+}

package/dist/wireframe.js

@@ -0,0 +1,252 @@
+import { titleOf } from './graph.js';
+import { drawWith, mark } from './kit.js';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+function fill(g, key, warn) {
+    const raw = g.catalog[key];
+    if (raw === undefined) {
+        warn(`catalog key ${key} is missing`);
+        return `⟨missing ${key}⟩`;
+    }
+    return raw.replace(/\{(\w+)\}/g, (_m, p) => {
+        const sample = g.ui.samples[p];
+        if (sample === undefined) {
+            warn(`no sample value for {${p}} in ${key}`);
+            return `⟨${p}⟩`;
+        }
+        return sample;
+    });
+}
+function texts(g, n, warn) {
+    const t = n.text;
+    if (t === undefined)
+        return [];
+    if (t.key !== undefined)
+        return [fill(g, t.key, warn)];
+    if (t.oneOf !== undefined)
+        return t.oneOf.map((k) => fill(g, k, warn));
+    if (t.literal !== undefined)
+        return [t.literal];
+    return [];
+}
+function accessibleName(g, n, warn) {
+    const nm = n.name;
+    if (nm?.key !== undefined)
+        return fill(g, nm.key, warn);
+    if (nm?.literal !== undefined)
+        return nm.literal;
+    if (nm?.labelledBy !== undefined) {
+        const ref = g.ui.nodes[nm.labelledBy];
+        return ref === undefined ? undefined : texts(g, ref, warn).join(' ');
+    }
+    if (n.role === 'button' || n.role === 'heading' || n.role === 'status' || n.role === 'alert')
+        return texts(g, n, warn)[0];
+    return undefined;
+}
+function shownIn(n, state) {
+    return (n.in ?? []).includes(state) && !(n.unless ?? []).includes(state);
+}
+function chips(it) {
+    const n = it.node;
+    const parts = [n.role ?? n.type];
+    if (n.emits !== undefined)
+        parts.push(`emits ${n.emits}`);
+    if (it.disabled)
+        parts.push('disabled');
+    if (n.when !== undefined)
+        parts.push(`when ${n.when}`);
+    if (it.focus)
+        parts.push('first focus');
+    return `<span class="chip">${esc(parts.join(' · '))}</span>`;
+}
+function renderWireframe(g, state, items, warn, clean = false, kit = null) {
+    // clean: no annotation chips and no dashed or focus outlines, for the tutorial stage
+    const item = (it, inner) => {
+        const cls = clean ? 'wf-item' : ['wf-item', it.node.when !== undefined ? 'wf-cond' : '', it.focus ? 'wf-focus' : ''].filter((c) => c !== '').join(' ');
+        return `<div class="${cls}" data-node="${esc(it.id)}">${inner}${clean ? '' : chips(it)}</div>`;
+    };
+    const out = [];
+    let inList = false;
+    let inRow = false;
+    let kitList = null; // a List drawn with the kit waits for its items
+    const closeList = () => {
+        if (kitList !== null)
+            out.push(drawKitList(kitList.it, kitList.items));
+        else if (inList)
+            out.push('</ul>');
+        kitList = null;
+        inList = false;
+    };
+    const fill = (it, text) => {
+        const n = it.node;
+        const name = accessibleName(g, n, warn);
+        // the role the expected tree gives the node, which picks a template from the component's `roles`
+        const role = n.role ?? (n.type === 'text' ? undefined : n.type);
+        return { id: it.id, text, name: name ?? text, intent: n.intent, role, disabled: it.disabled, named: name !== undefined && name !== text, conditional: n.when !== undefined };
+    };
+    const drawKitList = (it, drawn) => {
+        const f = { ...fill(it, texts(g, it.node, warn)[0] ?? ''), children: drawn.map((d) => `\n${d}`).join('') + '\n' };
+        return mark(drawWith(kit, 'List', f, warn) ?? '', it.id, '');
+    };
+    const closeRow = () => {
+        if (inRow)
+            out.push('</div>');
+        inRow = false;
+    };
+    for (const it of items) {
+        const n = it.node;
+        const t = texts(g, n, warn);
+        const text = esc(t[0] ?? '');
+        if (n.component !== 'ListItem')
+            closeList();
+        if (n.component !== 'Button')
+            closeRow();
+        if (kit !== null && n.component !== undefined && n.component !== 'Page') {
+            if (kit.components[n.component] !== undefined) {
+                if (n.component === 'List') {
+                    kitList = { it, items: [] };
+                    inList = true;
+                }
+                else if (n.component === 'ListItem') {
+                    if (!inList)
+                        warn(`${it.id}: ListItem outside a List in ${state}`);
+                    for (const line of t)
+                        (kitList?.items ?? out).push(mark(drawWith(kit, 'ListItem', fill(it, line), warn) ?? '', it.id, clean ? '' : chips(it)));
+                }
+                else {
+                    if (n.component === 'Button' && !inRow)
+                        out.push('<div class="wf-row">');
+                    if (n.component === 'Button')
+                        inRow = true;
+                    out.push(item(it, drawWith(kit, n.component, fill(it, t[0] ?? ''), warn) ?? ''));
+                }
+                continue;
+            }
+            warn(`kit ${kit.id} has no template for ${n.component} (node ${it.id}); drawn with the fixed component`);
+        }
+        switch (n.component) {
+            case 'Page':
+                break;
+            case 'Heading':
+                out.push(item(it, `<h4 class="wf-h">${text}</h4>`));
+                break;
+            case 'Text':
+                out.push(item(it, `<p class="wf-t">${text}</p>`));
+                break;
+            case 'Button':
+                if (!inRow)
+                    out.push('<div class="wf-row">');
+                inRow = true;
+                out.push(item(it, `<button type="button" class="wf-btn wf-${esc(n.intent ?? 'secondary')}"${it.disabled ? ' disabled' : ''}>${text}</button>`));
+                break;
+            case 'LinkButton':
+                out.push(item(it, `<button type="button" class="wf-link"${it.disabled ? ' disabled' : ''}>${text}</button>`));
+                break;
+            case 'TextField':
+                // the visible text is the label; the input is named by it, as a <label> around it does
+                out.push(item(it, `<label class="wf-field"><span>${text}</span><input type="text" class="wf-input" tabindex="-1"${it.disabled ? ' disabled' : ''}></label>`));
+                break;
+            case 'List':
+                out.push(`<ul class="wf-list" data-node="${esc(it.id)}">`);
+                inList = true;
+                break;
+            case 'ListItem':
+                if (!inList)
+                    warn(`${it.id}: ListItem outside a List in ${state}`);
+                for (const line of t)
+                    (kitList?.items ?? out).push(`<li data-node="${esc(it.id)}">${esc(line)}${clean ? '' : chips(it)}</li>`);
+                break;
+            case 'Status':
+                out.push(item(it, `<div class="wf-status" role="status">${text}</div>`));
+                break;
+            case 'Alert':
+                out.push(item(it, `<div class="wf-alert" role="alert">${text}</div>`));
+                break;
+            default:
+                warn(`${it.id}: component ${n.component ?? '(none)'} has no wireframe renderer`);
+                out.push(item(it, `<div class="wf-unmapped">${esc(n.component ?? n.type)} ${esc(it.id)}</div>`));
+        }
+    }
+    closeList();
+    closeRow();
+    return out.join('\n');
+}
+function renderTree(g, items, warn) {
+    const lines = [];
+    for (const it of items) {
+        const n = it.node;
+        const depth = n.component === 'Page' ? 0 : n.component === 'ListItem' ? 2 : 1;
+        const flags = [it.disabled ? 'disabled' : '', n.when !== undefined ? `when ${n.when}` : '', it.focus ? 'first focus' : '', n.emits !== undefined ? `→ ${n.emits}` : '']
+            .filter((f) => f !== '')
+            .join(', ');
+        const suffix = flags === '' ? '' : `  [${flags}]`;
+        const pad = '  '.repeat(depth);
+        if (n.component === 'ListItem') {
+            for (const line of texts(g, n, warn))
+                lines.push(`${pad}listitem "${line}"${suffix}`);
+            continue;
+        }
+        const role = n.role ?? (n.type === 'text' ? 'text' : n.type);
+        const name = role === 'text' ? texts(g, n, warn)[0] : accessibleName(g, n, warn);
+        lines.push(`${pad}${role}${name === undefined ? '' : ` "${name}"`}${suffix}`);
+    }
+    return lines.join('\n');
+}
+export function renderScreens(g, warn, kit = null) {
+    const out = [];
+    for (const [state, st] of Object.entries(g.flow.states)) {
+        const shown = Object.entries(g.ui.nodes).filter(([, n]) => shownIn(n, state));
+        if (shown.length === 0)
+            continue;
+        const focusTargets = new Set(shown.map(([, n]) => n.initialFocus).filter((f) => f !== undefined));
+        const items = shown.map(([id, node]) => ({
+            id,
+            node,
+            disabled: (node.disabledIn ?? []).includes(state),
+            focus: focusTargets.has(id),
+        }));
+        out.push(`<article class="screen" id="screen-${esc(state)}"><header><h3>${esc(titleOf(g.flow, state))}</h3><span class="tag">${st.type === 'final' ? 'ends here, page shown' : 'screen'}</span><span class="mono muted">${esc(state)}</span></header>`);
+        if (st.description !== undefined)
+            out.push(`<p class="muted">${esc(st.description)}</p>`);
+        out.push(`<div class="wf${kit === null ? '' : ' kit'}" role="group" aria-label="Wireframe of ${esc(titleOf(g.flow, state))}">`);
+        out.push(renderWireframe(g, state, items, warn, false, kit));
+        out.push('</div>');
+        out.push(`<details class="ax-wrap"><summary>Expected accessibility tree</summary><pre class="ax">${esc(renderTree(g, items, warn))}</pre></details>`);
+        out.push('</article>');
+    }
+    return out.join('\n');
+}
+// One state's screen for the tutorial stage. Nodes that depend on a flag (`when`) appear only when named in `reveal`.
+export function renderStageScreen(g, state, reveal, warn, kit = null) {
+    const shown = Object.entries(g.ui.nodes).filter(([id, n]) => shownIn(n, state) && (n.when === undefined || reveal.includes(id)));
+    const items = shown.map(([id, node]) => ({ id, node, disabled: (node.disabledIn ?? []).includes(state), focus: false }));
+    return `<div class="wf${kit === null ? '' : ' kit'}" role="group" aria-label="Screen: ${esc(titleOf(g.flow, state))}">${renderWireframe(g, state, items, warn, true, kit)}</div>`;
+}
+// For `kit check`: every screen with all its nodes (flags revealed, no annotations), and what each node must expose.
+export function renderCheckScreens(g, kit, warn) {
+    const html = [];
+    const expected = [];
+    for (const state of Object.keys(g.flow.states)) {
+        const shown = Object.entries(g.ui.nodes).filter(([, n]) => shownIn(n, state));
+        if (shown.length === 0)
+            continue;
+        const items = shown.map(([id, node]) => ({ id, node, disabled: (node.disabledIn ?? []).includes(state), focus: false }));
+        html.push(`<section class="screen" data-state="${esc(state)}"><div class="wf${kit === null ? '' : ' kit'}">${renderWireframe(g, state, items, warn, true, kit)}</div></section>`);
+        for (const it of items) {
+            const n = it.node;
+            if (n.component === 'Page')
+                continue; // the screen itself: nothing is drawn for it
+            if (n.component === 'ListItem') {
+                texts(g, n, warn).forEach((line, index) => expected.push({ state, id: it.id, index, role: n.role ?? 'listitem', name: line, disabled: it.disabled }));
+                continue;
+            }
+            const role = n.role ?? (n.type === 'text' ? 'text' : n.type);
+            expected.push({ state, id: it.id, index: 0, role, name: role === 'text' ? texts(g, n, warn)[0] : accessibleName(g, n, warn), disabled: it.disabled });
+        }
+    }
+    return { html: html.join('\n'), expected };
+}
+// the visible words of a node, for narration: a node with several texts gives several entries
+export function nodeTexts(g, id, warn) {
+    const n = g.ui.nodes[id];
+    return n === undefined ? [] : texts(g, n, warn);
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@delurio/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The open checker and page of delurio-graph/0: check every graph in a project's own CI, offline, with GNU error lines and SARIF.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": { "delurio": "dist/cli.js" },
+  "files": ["dist", "SPEC.md", "NOTICE"],
+  "engines": { "node": ">=22.18" },
+  "repository": { "type": "git", "url": "git+https://github.com/delurio-labs/delurio.git" },
+  "homepage": "https://delur.io",
+  "bugs": "https://github.com/delurio-labs/delurio/issues",
+  "keywords": ["statechart", "graph", "spec", "checker", "sarif", "ci"],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node src/cli.ts check examples --strict"
+  },
+  "dependencies": {
+    "elkjs": "0.12.0",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "7.0.2"
+  }
+}