@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/core/src/report/formats.d.ts

@@ -0,0 +1,69 @@
+import type { MachineConfig } from '../spec/types.js';
+import type { TimelineEntry } from '../run/types.js';
+type ManifestLike = {
+    run: {
+        id: string;
+        startedAt: string;
+        durationMs: number;
+        mode: string;
+    };
+    paths: {
+        id: string;
+        name: string;
+        kind: string;
+        status: string;
+        steps: {
+            event: string;
+            status: string;
+            reason: string | null;
+        }[];
+        attempts: {
+            error: string | null;
+            trace: string | null;
+        }[];
+    }[];
+};
+/** JUnit XML (the format every CI system reads): one test case per path. */
+export declare function toJUnit(manifest: ManifestLike): string;
+/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+export declare function toCtrf(manifest: ManifestLike): {
+    reportFormat: string;
+    specVersion: string;
+    results: {
+        tool: {
+            name: string;
+        };
+        summary: {
+            tests: number;
+            passed: number;
+            failed: number;
+            pending: number;
+            skipped: number;
+            other: number;
+            start: number;
+            stop: number;
+        };
+        tests: {
+            steps: {
+                name: string;
+                status: string;
+            }[];
+            attachments?: {
+                name: string;
+                contentType: string;
+                path: string;
+            }[] | undefined;
+            message?: string | undefined;
+            name: string;
+            status: string;
+            duration: number;
+            suite: string;
+            flaky: boolean;
+        }[];
+    };
+};
+/** WebVTT captions for a clip, one cue per timeline entry. */
+export declare function toWebVtt(timeline: TimelineEntry[], durationMs: number): string;
+/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+export declare function toMermaid(machine: MachineConfig): string;
+export {};

package/dist/core/src/report/formats.js

@@ -0,0 +1,109 @@
+import { targetOf } from '../spec/types.js';
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** JUnit XML (the format every CI system reads): one test case per path. */
+export function toJUnit(manifest) {
+    const cases = manifest.paths.map((p) => {
+        const body = p.status === 'failed'
+            ? `<failure message="${xml(p.attempts.at(-1)?.error ?? 'failed')}"/>`
+            : p.status === 'not-reached'
+                ? `<skipped message="${xml(p.steps.find((s) => s.reason?.startsWith('Blocked'))?.reason ?? 'not reached')}"/>`
+                : p.status === 'flaky'
+                    ? `<system-out>${xml('Passed on retry (flaky)')}</system-out>`
+                    : '';
+        return `    <testcase classname="${xml(p.kind)}" name="${xml(p.name)}" id="${xml(p.id)}">${body}</testcase>`;
+    });
+    const failures = manifest.paths.filter((p) => p.status === 'failed').length;
+    const skipped = manifest.paths.filter((p) => p.status === 'not-reached').length;
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuites name="atlas" tests="${manifest.paths.length}" failures="${failures}" skipped="${skipped}" time="${(manifest.run.durationMs / 1000).toFixed(3)}">`,
+        `  <testsuite name="${xml(manifest.run.id)}" tests="${manifest.paths.length}" failures="${failures}" skipped="${skipped}" timestamp="${manifest.run.startedAt}">`,
+        ...cases,
+        '  </testsuite>',
+        '</testsuites>',
+        ''
+    ].join('\n');
+}
+/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+export function toCtrf(manifest) {
+    const status = (s) => (s === 'passed' ? 'passed' : s === 'failed' ? 'failed' : s === 'flaky' ? 'passed' : 'skipped');
+    const tests = manifest.paths.map((p) => ({
+        name: p.name,
+        status: status(p.status),
+        duration: 0,
+        suite: p.kind,
+        flaky: p.status === 'flaky',
+        ...(p.status === 'failed' ? { message: p.attempts.at(-1)?.error ?? undefined } : {}),
+        ...(p.attempts.at(-1)?.trace ? { attachments: [{ name: 'trace', contentType: 'application/zip', path: p.attempts.at(-1).trace }] } : {}),
+        steps: p.steps.map((s) => ({ name: s.event, status: status(s.status) }))
+    }));
+    const start = Date.parse(manifest.run.startedAt);
+    return {
+        reportFormat: 'CTRF',
+        specVersion: '0.0.0',
+        results: {
+            tool: { name: 'atlas' },
+            summary: {
+                tests: tests.length,
+                passed: tests.filter((t) => t.status === 'passed').length,
+                failed: tests.filter((t) => t.status === 'failed').length,
+                pending: 0,
+                skipped: tests.filter((t) => t.status === 'skipped').length,
+                other: 0,
+                start,
+                stop: start + manifest.run.durationMs
+            },
+            tests
+        }
+    };
+}
+function vttTime(ms) {
+    const d = new Date(Math.max(0, ms));
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}.${pad(d.getUTCMilliseconds(), 3)}`;
+}
+/** WebVTT captions for a clip, one cue per timeline entry. */
+export function toWebVtt(timeline, durationMs) {
+    const cues = timeline.map((e, i) => {
+        const end = Math.min(timeline[i + 1]?.atMs ?? durationMs, e.atMs + 4_000);
+        const text = `${e.label}${e.text ? `: “${e.text}”` : ''}`;
+        return `${i + 1}\n${vttTime(e.atMs)} --> ${vttTime(Math.max(end, e.atMs + 500))}\n${text}`;
+    });
+    return `WEBVTT\n\n${cues.join('\n\n')}\n`;
+}
+/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+export function toMermaid(machine) {
+    const ids = new Map();
+    const id = (name) => {
+        if (!ids.has(name))
+            ids.set(name, `s${ids.size}`);
+        return ids.get(name);
+    };
+    const label = (s) => s.replace(/"/g, "'");
+    const lines = ['stateDiagram-v2', '  direction TB', `  [*] --> ${id(machine.initial ?? Object.keys(machine.states ?? {})[0] ?? '')}`];
+    const edges = [];
+    const emit = (name, node, indent) => {
+        for (const [event, t] of Object.entries(node.on ?? {})) {
+            edges.push(`  ${id(name)} --> ${id(targetOf(t))} : ${event.replace(/[:;]/g, ' ')}`);
+        }
+        if (!node.states) {
+            lines.push(`${indent}state "${label(name)}" as ${id(name)}`);
+            if (node.type === 'final')
+                lines.push(`${indent}${id(name)} --> [*]`);
+            return;
+        }
+        lines.push(`${indent}state "${label(name)}" as ${id(name)} {`);
+        const entries = Object.entries(node.states);
+        if (node.type !== 'parallel')
+            lines.push(`${indent}  [*] --> ${id(node.initial ?? entries[0]?.[0] ?? '')}`);
+        entries.forEach(([k, v], i) => {
+            if (node.type === 'parallel' && i > 0)
+                lines.push(`${indent}  --`);
+            emit(k, v, `${indent}  `);
+        });
+        lines.push(`${indent}}`);
+    };
+    for (const [k, v] of Object.entries(machine.states ?? {}))
+        emit(k, v, '  ');
+    return `${[...lines, ...edges].join('\n')}\n`;
+}

package/dist/core/src/report/markdown.d.ts

@@ -0,0 +1,8 @@
+import type { Journey, MachineConfig } from '../spec/types.js';
+/**
+ * A readable map of a chart for the people who own the product: one section per area (parallel
+ * regions apart), each state with what it means, what the user sees, and every event that can
+ * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
+ * code host and diffs with the chart.
+ */
+export declare function toMarkdown(machine: MachineConfig, journeys?: Journey[]): string;

package/dist/core/src/report/markdown.js

@@ -0,0 +1,140 @@
+import { targetOf } from '../spec/types.js';
+/** GitHub's heading anchors: lowercase, punctuation dropped, spaces to hyphens, repeats numbered. */
+function anchors() {
+    const seen = new Map();
+    return (heading) => {
+        const base = heading
+            .toLowerCase()
+            .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+            .replace(/\s/g, '-');
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        return count ? `${base}-${count}` : base;
+    };
+}
+/** Top-level states, with every parallel state split into its regions, so each area reads alone. */
+function sectionsOf(machine) {
+    const out = [];
+    const visit = (name, node, title) => {
+        if (node.type === 'parallel' && node.states) {
+            out.push({ title, node, name, regions: true });
+            for (const [k, v] of Object.entries(node.states))
+                visit(k, v, `${title} › ${k}`);
+            return;
+        }
+        out.push({ title, node, name });
+    };
+    for (const [k, v] of Object.entries(machine.states ?? {}))
+        visit(k, v, k);
+    return out;
+}
+function entriesOf(section) {
+    const out = [{ name: section.name, node: section.node, trail: [] }];
+    if (section.regions)
+        return out;
+    const walk = (node, trail) => {
+        for (const [k, v] of Object.entries(node.states ?? {})) {
+            out.push({ name: k, node: v, trail });
+            walk(v, [...trail, k]);
+        }
+    };
+    walk(section.node, [section.name]);
+    return out;
+}
+const cell = (text) => text.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
+/**
+ * A readable map of a chart for the people who own the product: one section per area (parallel
+ * regions apart), each state with what it means, what the user sees, and every event that can
+ * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
+ * code host and diffs with the chart.
+ */
+export function toMarkdown(machine, journeys = []) {
+    const sections = sectionsOf(machine);
+    const sectionOf = new Map();
+    const stateAnchor = new Map();
+    const sectionAnchors = [];
+    const anchor = anchors();
+    anchor(machine.id);
+    anchor('Areas');
+    sections.forEach((section) => {
+        const own = anchor(section.title);
+        sectionAnchors.push(own);
+        for (const { name } of entriesOf(section)) {
+            sectionOf.set(name, section.title);
+            stateAnchor.set(name, name === section.name ? own : anchor(name));
+        }
+    });
+    const journeysAnchor = journeys.length ? anchor('Journeys') : '';
+    const link = (name, from) => {
+        const where = sectionOf.get(name);
+        const ref = stateAnchor.has(name) ? `[${name}](#${stateAnchor.get(name)})` : name;
+        return where && where !== from ? `${ref} (${where})` : ref;
+    };
+    const lines = [`# ${machine.id}`, ''];
+    if (machine.meta?.description)
+        lines.push(machine.meta.description.trim(), '');
+    const total = sections.reduce((n, s) => n + entriesOf(s).length, 0);
+    const transitions = sections.reduce((n, s) => n + entriesOf(s).reduce((m, e) => m + Object.keys(e.node.on ?? {}).length, 0), 0);
+    lines.push(`${sections.filter((s) => !s.regions).length} areas, ${total} states, ${transitions} transitions, ${journeys.length} journeys.`, '');
+    lines.push('## Areas', '');
+    sections.forEach((s, i) => lines.push(`- [${s.title}](#${sectionAnchors[i]})`));
+    if (journeys.length)
+        lines.push(`- [Journeys](#${journeysAnchor})`);
+    lines.push('');
+    const describe = (node, from) => {
+        const meta = node.meta ?? {};
+        const out = [];
+        if (meta.confidence === 'assumed')
+            out.push('_Assumed: not yet confirmed by the product owner._', '');
+        if (meta.description)
+            out.push(meta.description.trim(), '');
+        if (meta.snapshot && /\s/.test(meta.snapshot.trim()))
+            out.push(`**On screen:** ${meta.snapshot.trim()}`, '');
+        if (meta.events?.length)
+            out.push(`**Records:** ${meta.events.join('; ')}.`, '');
+        if (node.type === 'final')
+            out.push('**Final:** the flow ends here.', '');
+        if (meta.deadEnd)
+            out.push(`**Ends here:** ${meta.deadEnd.trim()}`, '');
+        if (node.type === 'parallel' && node.states) {
+            out.push(`**Runs side by side:** ${Object.keys(node.states).map((k) => link(k, from)).join(', ')}.`, '');
+        }
+        else if (node.states) {
+            const initial = node.initial ?? Object.keys(node.states)[0];
+            if (initial)
+                out.push(`**Starts at:** ${link(initial, from)}.`, '');
+        }
+        const on = Object.entries(node.on ?? {});
+        if (on.length) {
+            out.push('| When | Goes to |', '| --- | --- |');
+            for (const [event, t] of on)
+                out.push(`| ${cell(event)} | ${cell(link(targetOf(t) ?? '', from))} |`);
+            out.push('');
+        }
+        return out;
+    };
+    sections.forEach((section) => {
+        lines.push(`## ${section.title}`, '');
+        for (const entry of entriesOf(section)) {
+            if (entry.name !== section.name) {
+                lines.push(`### ${entry.name}`, '');
+                if (entry.trail.length > 1)
+                    lines.push(`_In ${entry.trail.join(' › ')}_`, '');
+            }
+            lines.push(...describe(entry.node, section.title));
+        }
+    });
+    if (journeys.length) {
+        lines.push('## Journeys', '');
+        for (const journey of journeys) {
+            lines.push(`### ${journey.name}`, '');
+            if (journey.description)
+                lines.push(journey.description.trim(), '');
+            lines.push(`**Ends in:** ${journey.endsIn.map((s) => link(s, '')).join(', ')}.`, '');
+            lines.push('<details><summary>Steps</summary>', '');
+            journey.events.forEach((event, i) => lines.push(`${i + 1}. ${event}`));
+            lines.push('', '</details>', '');
+        }
+    }
+    return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}

package/dist/core/src/run/clients.d.ts

@@ -0,0 +1,42 @@
+import type { Driver, EventImplementation, Implementation, StateImplementation } from './types.js';
+export type CombineDriversOptions = {
+    /**
+     * `focused` (default) screenshots the client a state is recognised on; `all` also screenshots
+     * every other client at the same moment, kept in the image's `also`.
+     */
+    screens?: 'focused' | 'all';
+};
+/**
+ * Run several drivers as the clients of one run: a member on an iOS simulator (WebDriver/Appium
+ * or Detox), an operator on a desktop browser (Playwright, Bun WebView), a partner system over
+ * HTTP. Each client gets its own context, keyed by name; events and states say which client they
+ * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
+ * screen. Timeline entries are tagged with the client that made them.
+ *
+ *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ */
+export declare function combineDrivers<M extends Record<string, unknown>>(drivers: {
+    [K in keyof M]: Driver<M[K]>;
+}, options?: CombineDriversOptions): Driver<M>;
+/** A state implementation written for one client's context, lifted to a multi-client context. */
+export declare function onClient<K extends string, C>(client: K, impl: StateImplementation<C>): StateImplementation<Record<K, C>>;
+/** An event implementation written for one client's context, lifted to a multi-client context. */
+export declare function onClient<K extends string, C>(client: K, impl: EventImplementation<C>): EventImplementation<Record<K, C>>;
+/** Part of an implementation: what one client does and shows, or what spans clients. */
+export type ImplementationPart<C> = Partial<Implementation<C>>;
+/**
+ * Merge per-client implementations into one. Each client's part is written against that client's
+ * own context (a Playwright page, a WebDriver session, an HTTP client), so the helpers of every
+ * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
+ * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
+ * in the order the clients are listed. An event or state implemented twice is an error.
+ */
+export declare function combineImplementations<M extends Record<string, unknown>>(parts: {
+    [K in keyof M]?: ImplementationPart<M[K]>;
+}, shared?: ImplementationPart<M>): Implementation<M>;
+/**
+ * Merge parts of one implementation written against the same context, such as one file per area
+ * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
+ * implemented once; setups run in order, and correlation ids are pooled.
+ */
+export declare function mergeImplementations<C>(...parts: ImplementationPart<C>[]): Implementation<C>;

package/dist/core/src/run/clients.js

@@ -0,0 +1,250 @@
+import path from 'node:path';
+const inClientDirectory = (file, client) => path.join(path.dirname(file), client, path.basename(file));
+/**
+ * Run several drivers as the clients of one run: a member on an iOS simulator (WebDriver/Appium
+ * or Detox), an operator on a desktop browser (Playwright, Bun WebView), a partner system over
+ * HTTP. Each client gets its own context, keyed by name; events and states say which client they
+ * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
+ * screen. Timeline entries are tagged with the client that made them.
+ *
+ *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ */
+export function combineDrivers(drivers, options = {}) {
+    const names = Object.keys(drivers);
+    if (!names.length)
+        throw new Error('combineDrivers needs at least one client');
+    const driverOf = (name) => drivers[name];
+    const pick = (focus, can) => {
+        const capable = names.filter(can);
+        const focused = focus?.client && capable.includes(focus.client) ? focus.client : undefined;
+        return { primary: focused ?? capable[0], capable };
+    };
+    const pacing = names.map((n) => driverOf(n).pacing).find(Boolean);
+    return {
+        name: names.map((n) => `${n}:${driverOf(n).name}`).join(' + '),
+        clients: Object.fromEntries(names.map((n) => [n, driverOf(n).name])),
+        ...(pacing ? { pacing } : {}),
+        concurrency: Math.min(...names.map((n) => driverOf(n).concurrency ?? 1)),
+        async open(input) {
+            const settled = await Promise.allSettled(names.map(async (name) => [name, await driverOf(name).open({ ...input, directory: path.join(input.directory, name), timeline: input.timeline.for(name) })]));
+            const opened = settled.flatMap((s) => (s.status === 'fulfilled' ? [s.value] : []));
+            const failure = settled.find((s) => s.status === 'rejected');
+            if (failure) {
+                await Promise.all(opened.map(([name, ctx]) => driverOf(name).close(ctx, { failed: true, traceFile: '' }).catch(() => undefined)));
+                const reason = failure.reason instanceof Error ? failure.reason.message : String(failure.reason);
+                const client = names[settled.indexOf(failure)];
+                throw new Error(`The "${client}" client could not open: ${reason}`);
+            }
+            return Object.fromEntries(opened);
+        },
+        async close(ctx, { failed, traceFile }) {
+            const traces = {};
+            await Promise.all(names.map(async (name) => {
+                const closed = await driverOf(name)
+                    .close(ctx[name], { failed, traceFile: inClientDirectory(traceFile, name) })
+                    .catch(() => undefined);
+                if (closed && closed.trace)
+                    traces[name] = closed.trace;
+            }));
+            const first = Object.values(traces)[0];
+            return first ? { trace: first, traces } : undefined;
+        },
+        async screenshot(ctx, file, focus) {
+            const { primary, capable } = pick(focus, (n) => Boolean(driverOf(n).screenshot));
+            if (!primary)
+                return null;
+            const shoot = async (name, target) => {
+                const image = await driverOf(name).screenshot(ctx[name], target).catch(() => null);
+                return image ? { ...image, client: name } : null;
+            };
+            const others = options.screens === 'all' ? capable.filter((n) => n !== primary) : [];
+            const [main, ...rest] = await Promise.all([shoot(primary, file), ...others.map((n) => shoot(n, inClientDirectory(file, n)))]);
+            if (!main)
+                return null;
+            const also = rest.filter((x) => Boolean(x));
+            return also.length ? { ...main, also } : main;
+        },
+        async record(ctx, workDirectory, focus) {
+            const { primary } = pick(focus, (n) => Boolean(driverOf(n).record));
+            if (!primary)
+                return { stop: async () => null };
+            const recording = await driverOf(primary).record(ctx[primary], workDirectory);
+            return {
+                async stop(output) {
+                    const clip = await recording.stop(output);
+                    return clip ? { ...clip, client: primary } : null;
+                }
+            };
+        },
+        async text(ctx, focus) {
+            const { primary, capable } = pick(focus, (n) => Boolean(driverOf(n).text));
+            const read = focus?.client && primary === focus.client ? [primary] : capable;
+            const texts = await Promise.all(read.map((n) => driverOf(n).text(ctx[n]).catch(() => '')));
+            return texts.join('\n');
+        },
+        async hold(ctx, ms, focus) {
+            const { primary } = pick(focus, (n) => Boolean(driverOf(n).hold));
+            if (primary && (!focus?.client || primary === focus.client))
+                await driverOf(primary).hold(ctx[primary], ms);
+            else
+                await new Promise((r) => setTimeout(r, ms));
+        },
+        async dispose() {
+            await Promise.all(names.map((n) => driverOf(n).dispose?.().catch(() => undefined)));
+        }
+    };
+}
+const scoped = (tools, client) => ({ ...tools, timeline: tools.timeline.for(client) });
+export function onClient(client, impl) {
+    if ('recognize' in impl) {
+        const { recognize, lookIn, settle, checks, ...rest } = impl;
+        return {
+            ...rest,
+            client,
+            recognize: (ctx) => recognize(ctx[client]),
+            ...(lookIn ? { lookIn: (ctx) => lookIn(ctx[client]) } : {}),
+            ...(settle ? { settle: (ctx) => settle(ctx[client]) } : {}),
+            ...(checks ? { checks: (ctx) => checks(ctx[client]) } : {})
+        };
+    }
+    const { run, prepare, ...rest } = impl;
+    return {
+        ...rest,
+        client,
+        run: (ctx, tools) => run(ctx[client], scoped(tools, client)),
+        ...(prepare ? { prepare: (ctx, tools) => prepare(ctx[client], scoped(tools, client)) } : {})
+    };
+}
+/**
+ * Merge per-client implementations into one. Each client's part is written against that client's
+ * own context (a Playwright page, a WebDriver session, an HTTP client), so the helpers of every
+ * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
+ * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
+ * in the order the clients are listed. An event or state implemented twice is an error.
+ */
+export function combineImplementations(parts, shared = {}) {
+    const clients = Object.keys(parts);
+    const events = { ...shared.events };
+    const states = { ...shared.states };
+    const owner = new Map([
+        ...Object.keys(shared.events ?? {}).map((k) => [`event:${k}`, 'shared']),
+        ...Object.keys(shared.states ?? {}).map((k) => [`state:${k}`, 'shared'])
+    ]);
+    const claim = (key, client) => {
+        const previous = owner.get(key);
+        if (previous)
+            throw new Error(`${key.replace(':', ' "')}" is implemented by both "${previous}" and "${client}"`);
+        owner.set(key, client);
+    };
+    for (const client of clients) {
+        const part = parts[client];
+        for (const [name, ev] of Object.entries(part?.events ?? {})) {
+            claim(`event:${name}`, client);
+            events[name] = onClient(client, ev);
+        }
+        for (const [name, st] of Object.entries(part?.states ?? {})) {
+            claim(`state:${name}`, client);
+            states[name] = onClient(client, st);
+        }
+    }
+    const seedNames = [...new Set([...Object.keys(shared.seeds ?? {}), ...clients.flatMap((c) => Object.keys(parts[c]?.seeds ?? {}))])];
+    const seeds = {};
+    for (const name of seedNames) {
+        const shares = [shared.seeds?.[name], ...clients.map((c) => parts[c]?.seeds?.[name])].filter((s) => s !== undefined);
+        const first = shares[0];
+        const blocked = shares.find((s) => s.blocked)?.blocked;
+        const shows = shares.find((s) => s.shows)?.shows;
+        const variantOf = shares.find((s) => s.for)?.for;
+        seeds[name] = {
+            at: first.at,
+            how: shares.map((s) => s.how).join('; '),
+            ...(blocked ? { blocked } : {}),
+            ...(shows ? { shows } : {}),
+            ...(variantOf ? { for: variantOf } : {}),
+            async run(ctx, input) {
+                await shared.seeds?.[name]?.run(ctx, input);
+                for (const client of clients)
+                    await parts[client]?.seeds?.[name]?.run(ctx[client], { path: input.path, tools: scoped(input.tools, client) });
+            }
+        };
+    }
+    const hasSetup = Boolean(shared.setup) || clients.some((c) => parts[c]?.setup);
+    const correlators = [shared.correlate ? (ctx) => shared.correlate(ctx) : null, ...clients.map((c) => (parts[c]?.correlate ? (ctx) => parts[c].correlate(ctx[c]) : null))].filter((f) => f !== null);
+    return {
+        events,
+        states,
+        ...(seedNames.length ? { seeds } : {}),
+        ...(hasSetup
+            ? {
+                async setup(ctx, input) {
+                    await shared.setup?.(ctx, input);
+                    for (const client of clients)
+                        await parts[client]?.setup?.(ctx[client], { path: input.path, tools: scoped(input.tools, client) });
+                }
+            }
+            : {}),
+        ...(correlators.length ? { correlate: async (ctx) => (await Promise.all(correlators.map((f) => f(ctx)))).flat() } : {}),
+        canStart(active) {
+            for (const check of [shared.canStart, ...clients.map((c) => parts[c]?.canStart)]) {
+                const verdict = check?.(active) ?? true;
+                if (verdict !== true)
+                    return verdict;
+            }
+            return true;
+        }
+    };
+}
+/**
+ * Merge parts of one implementation written against the same context, such as one file per area
+ * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
+ * implemented once; setups run in order, and correlation ids are pooled.
+ */
+export function mergeImplementations(...parts) {
+    const events = {};
+    const states = {};
+    const seeds = {};
+    const owner = new Map();
+    const claim = (key, part) => {
+        const previous = owner.get(key);
+        if (previous !== undefined)
+            throw new Error(`${key.replace(':', ' "')}" is implemented by part ${previous + 1} and part ${part + 1}`);
+        owner.set(key, part);
+    };
+    parts.forEach((part, i) => {
+        for (const [name, ev] of Object.entries(part.events ?? {}))
+            (claim(`event:${name}`, i), (events[name] = ev));
+        for (const [name, st] of Object.entries(part.states ?? {}))
+            (claim(`state:${name}`, i), (states[name] = st));
+        for (const [name, seed] of Object.entries(part.seeds ?? {}))
+            (claim(`seed:${name}`, i), (seeds[name] = seed));
+    });
+    const setups = parts.flatMap((p) => (p.setup ? [p.setup] : []));
+    const checks = parts.flatMap((p) => (p.canStart ? [p.canStart] : []));
+    const correlators = parts.flatMap((p) => (p.correlate ? [p.correlate] : []));
+    return {
+        events,
+        states,
+        ...(Object.keys(seeds).length ? { seeds } : {}),
+        ...(setups.length
+            ? {
+                async setup(ctx, input) {
+                    for (const setup of setups)
+                        await setup(ctx, input);
+                }
+            }
+            : {}),
+        ...(checks.length
+            ? {
+                canStart(active) {
+                    for (const check of checks) {
+                        const verdict = check(active);
+                        if (verdict !== true)
+                            return verdict;
+                    }
+                    return true;
+                }
+            }
+            : {}),
+        ...(correlators.length ? { correlate: async (ctx) => [...new Set((await Promise.all(correlators.map((f) => f(ctx)))).flat())] } : {})
+    };
+}