@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/src/data/model/journeys.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createIssueSink } from '../parse/issues';
+import { parseSpec, type SpecFile } from '../parse/spec';
+import { createJourneyReplayer } from './journeys';
+
+const parent = (host: string) => `id: Shop
+initial: Home
+states:
+  Home:
+    meta: { description: The home screen. }
+    on:
+      Taps order a drink: { target: '#Ordering' }
+  Ordering:
+${host}
+    on:
+      Drink is ordered: { target: '#Waiting for the drink' }
+      Leaves ordering: { target: '#Home' }
+  Waiting for the drink:
+    meta: { description: A drink on its way. }
+    on:
+      Goes back home: { target: '#Home' }
+`;
+
+const LEGACY_HOST = `    meta:
+      description: Ordering runs as its own chart.
+      childMachine: Ordering flow
+      childFinalEvents:
+        Ordered: Drink is ordered
+        Gave up: Leaves ordering`;
+
+const INVOKE_HOST = `    meta:
+      description: Ordering runs as its own chart.
+    invoke:
+      src: Ordering flow
+      id: ordering`;
+
+const childYaml = (doneEvents: boolean) => `id: Ordering flow
+initial: Picking a drink
+states:
+  Picking a drink:
+    meta: { description: Drinks. }
+    on:
+      Picks a drink: '#Confirming the drink'
+      Closes ordering: '#Gave up'
+  Confirming the drink:
+    meta: { description: Confirm. }
+    on:
+      Confirms the drink: '#Ordered'
+  Ordered:
+    type: final
+    meta: { description: Done.${doneEvents ? ', doneEvent: Drink is ordered' : ''} }
+  Gave up:
+    type: final
+    meta: { description: Left.${doneEvents ? ', doneEvent: Leaves ordering' : ''} }
+`;
+
+const CHILD_SCXML = `<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" xmlns:atlas="https://github.com/crvouga/atlas/ns/1" version="1.0" name="Ordering flow" initial="picking-a-drink">
+  <state id="picking-a-drink" atlas:name="Picking a drink">
+    <atlas:meta><atlas:description>Drinks.</atlas:description></atlas:meta>
+    <transition event="picks-a-drink" atlas:name="Picks a drink" target="confirming-the-drink"/>
+    <transition event="closes-ordering" atlas:name="Closes ordering" target="gave-up"/>
+  </state>
+  <state id="confirming-the-drink" atlas:name="Confirming the drink">
+    <atlas:meta><atlas:description>Confirm.</atlas:description></atlas:meta>
+    <transition event="confirms-the-drink" atlas:name="Confirms the drink" target="ordered"/>
+  </state>
+  <final id="ordered" atlas:name="Ordered" atlas:done-event="Drink is ordered">
+    <atlas:meta><atlas:description>Done.</atlas:description></atlas:meta>
+  </final>
+  <final id="gave-up" atlas:name="Gave up" atlas:done-event="Leaves ordering">
+    <atlas:meta><atlas:description>Left.</atlas:description></atlas:meta>
+  </final>
+</scxml>
+`;
+
+const JOURNEYS = `journeys:
+  Orders a drink:
+    events: [Taps order a drink, Picks a drink, Confirms the drink]
+    endsIn: [Waiting for the drink]
+  Leaves and comes back:
+    events: [Taps order a drink, Closes ordering, Taps order a drink]
+    endsIn: [Ordering, Picking a drink]
+  Impossible event:
+    events: [Taps order a drink, Goes back home, Picks a drink]
+  Lists the hand-off itself:
+    events: [Taps order a drink, Picks a drink, Confirms the drink, Drink is ordered]
+  Ends in the wrong place:
+    events: [Taps order a drink]
+    endsIn: [Waiting for the drink]
+`;
+
+const COMPOSITIONS: [string, SpecFile[]][] = [
+  ['legacy meta.childMachine', [
+    { path: 'shop/ordering/machine.yaml', text: parent(LEGACY_HOST) },
+    { path: 'shop/ordering/ordering-flow.machine.yaml', text: childYaml(false) }
+  ]],
+  ['XState invoke', [
+    { path: 'shop/ordering/machine.yaml', text: parent(INVOKE_HOST) },
+    { path: 'shop/ordering/ordering-flow.machine.yaml', text: childYaml(true) }
+  ]],
+  ['invoke of an SCXML chart', [
+    { path: 'shop/ordering/machine.yaml', text: parent(INVOKE_HOST) },
+    { path: 'shop/ordering/ordering-flow.scxml', text: CHILD_SCXML }
+  ]]
+];
+
+function replayAll(charts: SpecFile[]) {
+  const sink = createIssueSink();
+  const doc = parseSpec({ ref: null, files: [...charts, { path: 'shop/ordering/journeys.yaml', text: JOURNEYS }] }, sink);
+  expect(sink.issues.filter((i) => i.severity !== 'info')).toEqual([]);
+  const replay = createJourneyReplayer(doc, sink);
+  const results = new Map(doc.journeys.map((j) => [j.name, replay(j)]));
+  return { results, issues: sink.issues };
+}
+
+describe.each(COMPOSITIONS)('journey replay with %s', (_label, charts) => {
+  const { results, issues } = replayAll(charts);
+
+  it('inserts the hand-off event when the child chart reaches a final state', () => {
+    const result = results.get('Orders a drink')!;
+    expect(result).toMatchObject({ ok: true, failedAt: null, missingEnds: [] });
+    expect(result.steps.map((s) => [s.event, s.handOff])).toEqual([
+      ['Taps order a drink', false],
+      ['Picks a drink', false],
+      ['Confirms the drink', false],
+      ['Drink is ordered', true]
+    ]);
+    expect(result.steps[3]).toMatchObject({ transitionIds: ['Ordered :: Drink is ordered'], from: expect.arrayContaining(['Ordering', 'Ordered']), to: ['Waiting for the drink'] });
+  });
+
+  it('re-enters the child chart at its start after a hand-off back', () => {
+    const result = results.get('Leaves and comes back')!;
+    expect(result.ok).toBe(true);
+    expect(result.steps.filter((s) => s.handOff).map((s) => s.event)).toEqual(['Leaves ordering']);
+    expect(result.steps.at(-1)?.to).toEqual(['Ordering', 'Picking a drink']);
+  });
+
+  it.each<[string, string, number]>([
+    ['Impossible event', 'Goes back home', 1],
+    ['Lists the hand-off itself', 'Drink is ordered', 4]
+  ])('stops "%s" at the event that cannot happen', (name, failedAt, stepsTaken) => {
+    const result = results.get(name)!;
+    expect(result).toMatchObject({ ok: false, failedAt, missingEnds: [] });
+    expect(result.steps).toHaveLength(stepsTaken);
+    expect(issues).toContainEqual({
+      severity: 'warning',
+      file: 'shop/ordering/journeys.yaml',
+      path: `journeys › ${name}`,
+      message: `"${failedAt}" can't happen at that point in the journey, so the journey stops there on the map.`
+    });
+  });
+
+  it('reports the end states a journey misses', () => {
+    expect(results.get('Ends in the wrong place')).toMatchObject({ ok: false, failedAt: null, missingEnds: ['Waiting for the drink'] });
+    expect(issues.some((i) => i.path === 'journeys › Ends in the wrong place › endsIn' && i.severity === 'info')).toBe(true);
+  });
+});

package/packages/visualizer/src/data/model/journeys.ts

@@ -0,0 +1,29 @@
+import type { IssueSink } from '../parse/issues';
+import type { ParsedJourney, SpecDocument } from '../parse/spec';
+import { createSimulationFactory } from './simulation';
+import type { JourneyStep } from './types';
+
+export type ReplayResult = { steps: JourneyStep[]; ok: boolean; failedAt: string | null; missingEnds: string[] };
+
+export function createJourneyReplayer(doc: SpecDocument, sink: IssueSink) {
+  const simulation = createSimulationFactory(doc);
+  return (journey: ParsedJourney): ReplayResult => {
+    const group = doc.groups.find((g) => g.dir === journey.dir);
+    const top = doc.charts.find((c) => group?.chartIds.includes(c.id) && !c.parent);
+    if (!top) return { steps: [], ok: false, failedAt: journey.events[0] ?? null, missingEnds: journey.endsIn };
+    try {
+      const result = simulation(top.id).replay(journey.events);
+      if (result.failedAt) {
+        sink.add('warning', journey.file, ['journeys', journey.name], `"${result.failedAt}" can't happen at that point in the journey, so the journey stops there on the map.`);
+        return { steps: result.steps, ok: false, failedAt: result.failedAt, missingEnds: [] };
+      }
+      if (result.error) sink.add('warning', journey.file, ['journeys', journey.name], result.error);
+      const missingEnds = journey.endsIn.filter((s) => !result.config.active.includes(s));
+      if (missingEnds.length) sink.add('info', journey.file, ['journeys', journey.name, 'endsIn'], `The journey should end in ${missingEnds.map((s) => `"${s}"`).join(', ')}, but the chart doesn't take it there.`);
+      return { steps: result.steps, ok: !result.error && missingEnds.length === 0, failedAt: null, missingEnds };
+    } catch (error) {
+      sink.add('warning', top.file, [], `Journeys can't be traced through this chart: ${error instanceof Error ? error.message : 'unknown problem'}.`);
+      return { steps: [], ok: false, failedAt: journey.events[0] ?? null, missingEnds: journey.endsIn };
+    }
+  };
+}

package/packages/visualizer/src/data/model/simulation.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'bun:test';
+import { parseSpec } from '../parse/spec';
+import { ChartSimulation } from './simulation';
+
+const root = {
+  id: 'Product', initial: 'App', states: {
+    App: { type: 'parallel', states: {
+      Identity: { initial: 'Guest', states: {
+        Guest: { on: { 'Signs in': '#Account', 'A broadcast arrives': '#Account' } },
+        Account: { on: { 'Signs out': '#Guest' } }
+      } },
+      Place: { initial: 'Home', states: {
+        Home: { on: { 'Opens checkout': '#Checkout host', 'A broadcast arrives': '#News' } },
+        News: { on: { 'Returns home': '#Home' } },
+        'Checkout host': { invoke: { src: 'Checkout' }, on: { 'Paid': '#Receipt', 'Closes checkout': '#Home' } },
+        Receipt: { on: { 'Returns home': '#Home' } },
+        Unreachable: {}
+      } }
+    } }
+  }
+};
+const child = { id: 'Checkout', initial: 'Card form', states: {
+  'Card form': { on: { 'Pays successfully': '#Payment complete' } },
+  'Payment complete': { type: 'final', meta: { doneEvent: 'Paid' } }
+} };
+const document = () => parseSpec({ ref: null, files: [
+  { path: 'product.machine.json', text: JSON.stringify(root) },
+  { path: 'checkout.machine.json', text: JSON.stringify(child) }
+] });
+
+describe('free exploration of composed statecharts', () => {
+  it('keeps parallel active states and broadcasts one event to both regions', () => {
+    const simulation = new ChartSimulation(document(), 'Product');
+    expect(simulation.leaves(simulation.initial().config)).toEqual(['Guest', 'Home']);
+    const result = simulation.replay(['A broadcast arrives']);
+    expect(result.error).toBeNull();
+    expect(simulation.leaves(result.config)).toEqual(['Account', 'News']);
+    expect(result.steps[0]?.transitionIds).toEqual(['Guest :: A broadcast arrives', 'Home :: A broadcast arrives']);
+  });
+
+  it('shares the composed root from a nested chart and settles child hand-offs', () => {
+    const simulation = new ChartSimulation(document(), 'Checkout');
+    expect(simulation.rootId).toBe('Product');
+    const result = simulation.replay(['Signs in', 'Opens checkout', 'Pays successfully']);
+    expect(simulation.leaves(result.config)).toEqual(['Account', 'Receipt']);
+    expect(result.steps.map((s) => [s.event, s.handOff])).toEqual([
+      ['Signs in', false], ['Opens checkout', false], ['Pays successfully', false], ['Paid', true]
+    ]);
+    expect(simulation.enabled(result.config)).not.toContain('Paid');
+  });
+
+  it('rejects unavailable events and preserves the exact previous configuration', () => {
+    const simulation = new ChartSimulation(document(), 'Product');
+    const initial = simulation.initial();
+    const result = simulation.advance(initial.config, 'Pays successfully');
+    expect(result).toMatchObject({ steps: [], failedAt: 'Pays successfully' });
+    expect(result.config).toBe(initial.config);
+    expect(result.error).toContain('unavailable');
+  });
+
+  it('finds a shortest route through nested states including automatic hand-offs', () => {
+    const simulation = new ChartSimulation(document(), 'Product');
+    const start = simulation.initial().config;
+    expect(simulation.route(start, 'Card form')).toMatchObject({ status: 'found', events: ['Opens checkout'] });
+    const route = simulation.route(start, 'Receipt');
+    expect(route).toMatchObject({ status: 'found', events: ['Opens checkout', 'Pays successfully'] });
+    expect(simulation.replay(route.events).config.active).toContain('Receipt');
+    expect(simulation.route(start, 'Payment complete')).toMatchObject({ status: 'found', events: ['Opens checkout', 'Pays successfully'], transient: true });
+    expect(simulation.route(start, 'Guest')).toMatchObject({ status: 'found', events: [] });
+  });
+
+  it('distinguishes exhaustive unreachability, a search limit and an unknown state', () => {
+    const simulation = new ChartSimulation(document(), 'Product');
+    const start = simulation.initial().config;
+    expect(simulation.route(start, 'Unreachable')).toMatchObject({ status: 'unreachable', events: [] });
+    expect(simulation.route(start, 'Receipt', 1)).toMatchObject({ status: 'limit', visited: 1, events: [] });
+    expect(simulation.route(start, 'Unknown')).toMatchObject({ status: 'invalid', visited: 0, events: [] });
+  });
+
+  it('replays a history prefix without retaining later choices or mutating the initial state', () => {
+    const simulation = new ChartSimulation(document(), 'Product');
+    const choices = ['Signs in', 'Opens checkout', 'Pays successfully'];
+    expect(simulation.leaves(simulation.replay(choices.slice(0, 1)).config)).toEqual(['Account', 'Home']);
+    expect(simulation.leaves(simulation.replay([]).config)).toEqual(['Guest', 'Home']);
+    expect(simulation.leaves(simulation.replay(choices).config)).toEqual(['Account', 'Receipt']);
+  });
+
+  it('preserves a chart whose root is parallel', () => {
+    const doc = parseSpec({ ref: null, files: [{ path: 'parallel.machine.json', text: JSON.stringify({ id: 'Parallel', type: 'parallel', states: {
+      Left: { initial: 'Left start', states: { 'Left start': {} } },
+      Right: { initial: 'Right start', states: { 'Right start': {} } }
+    } }) }] });
+    const simulation = new ChartSimulation(doc, 'Parallel');
+    expect(simulation.leaves(simulation.initial().config)).toEqual(['Left start', 'Right start']);
+  });
+
+  it('keeps a tolerant map but refuses to simulate guards that the model cannot execute', () => {
+    const doc = parseSpec({ ref: null, files: [{ path: 'guarded.machine.json', text: JSON.stringify({ id: 'Guarded', initial: 'A', states: {
+      A: { on: { Go: { target: '#B', guard: 'Has account' } } }, B: {}
+    } }) }] });
+    expect(doc.states.has('A')).toBe(true);
+    expect(() => new ChartSimulation(doc, 'Guarded')).toThrow('cannot be explored safely');
+  });
+
+  // regression: atlas-automatic-handoff-cycle
+  it('stops a literal automatic hand-off cycle instead of hanging', () => {
+    const doc = parseSpec({ ref: null, files: [
+      { path: 'cycle.machine.json', text: JSON.stringify({ id: 'Cycle', initial: 'Host', states: { Host: { invoke: { src: 'Child' }, on: { Again: '#Host' } } } }) },
+      { path: 'child.machine.json', text: JSON.stringify({ id: 'Child', initial: 'Done', states: { Done: { type: 'final', meta: { doneEvent: 'Again' } } } }) }
+    ] });
+    const result = new ChartSimulation(doc, 'Cycle').initial();
+    expect(result.error).toContain('cycle');
+    expect(result.steps).toHaveLength(1);
+  });
+});

package/packages/visualizer/src/data/model/simulation.ts

@@ -0,0 +1,187 @@
+import { createMachine, initialTransition, transition, type AnyMachineSnapshot } from 'xstate';
+
+import type { SpecDocument } from '../parse/spec';
+import type { JourneyStep } from './types';
+
+type XNode = { id: string; initial?: string; type?: 'parallel' | 'final'; states?: Record<string, XNode>; on?: Record<string, { target: string }> };
+export type Exploration = { active: string[]; snapshot: AnyMachineSnapshot };
+export type ExplorationResult = { config: Exploration; steps: JourneyStep[]; error: string | null; failedAt: string | null };
+export type RouteResult = { status: 'found'; events: string[]; visited: number; transient?: boolean } | { status: 'unreachable' | 'limit' | 'invalid'; events: []; visited: number };
+
+/** One pure composed model shared by free exploration and named journey replay. */
+export class ChartSimulation {
+  readonly rootId: string;
+  private readonly machine;
+  private readonly nameOf = new Map<string, string>();
+  private readonly parentOf = new Map<string, string | null>();
+  private readonly handlers = new Map<string, Map<string, string>>();
+  private readonly handOffs = new Map<string, { event: string; transitionId: string }>();
+
+  constructor(doc: SpecDocument, chartId: string) {
+    let top = doc.charts.find((c) => c.id === chartId);
+    const parents = new Set<string>();
+    while (top?.parent && !parents.has(top.id)) {
+      parents.add(top.id);
+      top = doc.charts.find((c) => c.id === top!.parent!.chartId);
+    }
+    if (!top || !top.rootStates.length) throw new Error('This chart has no starting states.');
+    this.rootId = top.id;
+    if (top.explorationError) throw new Error(top.explorationError);
+    const keyOf = new Map<string, string>();
+    const key = (name: string) => {
+      if (!keyOf.has(name)) {
+        const id = `s${keyOf.size}`;
+        keyOf.set(name, id);
+        this.nameOf.set(id, name);
+      }
+      return keyOf.get(name)!;
+    };
+    const visiting = new Set<string>();
+    const build = (name: string, parent: string | null): XNode => {
+      const state = doc.states.get(name);
+      if (!state || visiting.has(name)) throw new Error(`Cannot compose the state “${name}”.`);
+      visiting.add(name);
+      this.parentOf.set(name, parent);
+      const node: XNode = { id: key(name) };
+      const on: Record<string, { target: string }> = {};
+      const handled = new Map<string, string>();
+      for (const tid of state.transitions) {
+        const t = doc.transitions.get(tid);
+        if (!t?.target || t.carriedBy) continue;
+        on[t.event] = { target: `#${key(t.target)}` };
+        handled.set(t.event, tid);
+        if (t.handOff) this.handOffs.set(name, { event: t.event, transitionId: tid });
+      }
+      const child = state.childChartId ? doc.charts.find((c) => c.id === state.childChartId) : null;
+      if (child?.explorationError) throw new Error(child.explorationError);
+      const children = child ? child.rootStates : state.children;
+      if (children.length) {
+        node.states = {};
+        for (const name of children) {
+          const built = build(name, state.name);
+          node.states[built.id] = built;
+        }
+        if (state.type === 'parallel' || child?.type === 'parallel') node.type = 'parallel';
+        else node.initial = key(child?.initial ?? state.initial ?? children[0]!);
+      } else if (state.type === 'final' && !this.handOffs.has(name)) node.type = 'final';
+      if (Object.keys(on).length) node.on = on;
+      this.handlers.set(name, handled);
+      visiting.delete(name);
+      return node;
+    };
+    const root: XNode = { id: 'root', states: {} };
+    for (const name of top.rootStates) {
+      const node = build(name, null);
+      root.states![node.id] = node;
+    }
+    if (top.type === 'parallel') root.type = 'parallel';
+    else root.initial = key(top.initial ?? top.rootStates[0]!);
+    this.machine = createMachine(root as Parameters<typeof createMachine>[0]);
+  }
+
+  private config(snapshot: AnyMachineSnapshot): Exploration {
+    const active: string[] = [];
+    const walk = (value: unknown) => {
+      if (typeof value === 'string') active.push(this.nameOf.get(value) ?? value);
+      else if (value && typeof value === 'object') for (const [key, child] of Object.entries(value)) {
+        active.push(this.nameOf.get(key) ?? key);
+        walk(child);
+      }
+    };
+    walk(snapshot.value);
+    return { active, snapshot };
+  }
+
+  private descendant(name: string, ancestor: string) {
+    for (let p = this.parentOf.get(name); p; p = this.parentOf.get(p)) if (p === ancestor) return true;
+    return false;
+  }
+
+  leaves(config: Exploration) {
+    return config.active.filter((name) => !config.active.some((other) => other !== name && this.descendant(other, name)));
+  }
+
+  enabled(config: Exploration) {
+    return [...new Set(config.active.flatMap((name) => [...(this.handlers.get(name)?.keys() ?? [])]))];
+  }
+
+  private step(config: Exploration, event: string, handOff: boolean): { config: Exploration; step: JourneyStep } | null {
+    const candidates = config.active.filter((name) => this.handlers.get(name)?.has(event));
+    const fired = candidates.filter((name) => !candidates.some((other) => other !== name && this.descendant(other, name)));
+    if (!fired.length) return null;
+    const [snapshot] = transition(this.machine, config.snapshot, { type: event });
+    const next = this.config(snapshot);
+    return { config: next, step: { index: 0, event, handOff, transitionIds: fired.map((name) => this.handlers.get(name)!.get(event)!), from: config.active, to: next.active } };
+  }
+
+  private settle(result: ExplorationResult): ExplorationResult {
+    const seen = new Set<string>();
+    for (let count = 0; count < 100; count++) {
+      const pending = result.config.active.find((name) => this.handOffs.has(name));
+      if (!pending) return result;
+      const key = JSON.stringify(result.config.snapshot.value);
+      if (seen.has(key)) return { ...result, error: 'Automatic hand-offs form a cycle. The model stopped safely.' };
+      seen.add(key);
+      const event = this.handOffs.get(pending)!.event;
+      const next = this.step(result.config, event, true);
+      if (!next) return { ...result, error: `The automatic hand-off “${event}” cannot complete.` };
+      result = { ...result, config: next.config, steps: [...result.steps, { ...next.step, index: result.steps.length }] };
+    }
+    return { ...result, error: 'The model exceeded 100 automatic hand-offs. Exploration stopped safely.' };
+  }
+
+  initial(): ExplorationResult {
+    const [snapshot] = initialTransition(this.machine);
+    return this.settle({ config: this.config(snapshot), steps: [], error: null, failedAt: null });
+  }
+
+  advance(config: Exploration, event: string): ExplorationResult {
+    const next = this.step(config, event, false);
+    if (!next) return { config, steps: [], error: `“${event}” is unavailable in the current states.`, failedAt: event };
+    return this.settle({ config: next.config, steps: [next.step], error: null, failedAt: null });
+  }
+
+  replay(events: readonly string[]): ExplorationResult {
+    let result = this.initial();
+    if (result.error) return result;
+    for (const event of events) {
+      const next = this.advance(result.config, event);
+      result = { ...next, steps: [...result.steps, ...next.steps].map((step, index) => ({ ...step, index })) };
+      if (result.error) return result;
+    }
+    return result;
+  }
+
+  /** Bounded BFS, including automatic hand-offs; no arbitrary teleporting to a state. */
+  route(start: Exploration, target: string, maxConfigs = 2000): RouteResult {
+    if (!this.handlers.has(target)) return { status: 'invalid', events: [], visited: 0 };
+    const key = (config: Exploration) => JSON.stringify(config.snapshot.value);
+    const budget = Number.isFinite(maxConfigs) ? Math.max(1, Math.min(20_000, Math.floor(maxConfigs))) : 2000;
+    const queue = [{ config: start, events: [] as string[] }];
+    const seen = new Set([key(start)]);
+    for (let head = 0; head < queue.length; head++) {
+      const here = queue[head]!;
+      if (here.config.active.includes(target)) return { status: 'found', events: here.events, visited: seen.size };
+      for (const event of this.enabled(here.config)) {
+        const next = this.advance(here.config, event);
+        if (next.error) continue;
+        const events = [...here.events, event];
+        if (next.config.active.includes(target)) return { status: 'found', events, visited: seen.size + 1 };
+        if (next.steps.some((step) => step.to.includes(target))) return { status: 'found', events, visited: seen.size + 1, transient: true };
+        if (seen.has(key(next.config))) continue;
+        if (seen.size >= budget) return { status: 'limit', events: [], visited: seen.size };
+        seen.add(key(next.config));
+        queue.push({ config: next.config, events });
+      }
+    }
+    return { status: 'unreachable', events: [], visited: seen.size };
+  }
+}
+
+export function createSimulationFactory(doc: SpecDocument) {
+  const cache = new Map<string, ChartSimulation>();
+  return (chartId: string) => {
+    if (!cache.has(chartId)) cache.set(chartId, new ChartSimulation(doc, chartId));
+    return cache.get(chartId)!;
+  };
+}

package/packages/visualizer/src/data/model/status.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'bun:test';
+
+import { emptyCounts, worstOf } from './status';
+import { ITEM_STATUSES, type ItemStatus } from './types';
+
+describe('worstOf', () => {
+  it.each<[ItemStatus[], ItemStatus, ItemStatus]>([
+    [[], 'spec-only', 'spec-only'],
+    [[], 'not-yet-run', 'not-yet-run'],
+    [['passed'], 'not-yet-run', 'passed'],
+    [['passed', 'failed', 'flaky'], 'not-yet-run', 'failed'],
+    [['flaky', 'passed'], 'not-yet-run', 'flaky'],
+    [['passed', 'not-reached', 'not-yet-run'], 'not-yet-run', 'passed'],
+    [['not-reached', 'not-yet-run'], 'not-yet-run', 'not-reached'],
+    [['not-yet-run', 'spec-only'], 'spec-only', 'not-yet-run'],
+    [['spec-only', 'spec-only'], 'not-yet-run', 'spec-only'],
+    [['not-reached', 'failed', 'not-yet-run'], 'not-yet-run', 'failed']
+  ])('%j (empty: %s) is %s', (statuses, empty, expected) => {
+    expect(worstOf(statuses, empty)).toBe(expected);
+  });
+
+  it('does not depend on order', () => {
+    const statuses = [...ITEM_STATUSES];
+    expect(worstOf(statuses, 'spec-only')).toBe(worstOf([...statuses].reverse(), 'spec-only'));
+  });
+});
+
+describe('emptyCounts', () => {
+  it('has a zero for every status and the total', () => {
+    const counts = emptyCounts();
+    expect(Object.keys(counts).sort()).toEqual([...ITEM_STATUSES, 'total'].sort());
+    expect(Object.values(counts).every((n) => n === 0)).toBe(true);
+  });
+});

package/packages/visualizer/src/data/model/status.ts

@@ -0,0 +1,43 @@
+import { ITEM_STATUSES, type ItemStatus, type StatusCounts } from './types';
+
+export function emptyCounts(): StatusCounts {
+  return { passed: 0, flaky: 0, failed: 0, 'not-reached': 0, 'not-yet-run': 0, 'spec-only': 0, total: 0 };
+}
+
+const SEVERITY: Record<ItemStatus, number> = {
+  failed: 5,
+  flaky: 4,
+  passed: 3,
+  'not-reached': 2,
+  'not-yet-run': 1,
+  'spec-only': 0
+};
+
+/**
+ * One status for a group of items: a failure anywhere shows, then flakiness; a group counts as
+ * passed when something in it passed and nothing failed.
+ */
+export function worstOf(statuses: readonly ItemStatus[], empty: ItemStatus): ItemStatus {
+  if (statuses.length === 0) return empty;
+  return statuses.reduce((worst, s) => (SEVERITY[s] > SEVERITY[worst] ? s : worst));
+}
+
+export const STATUS_LABEL: Record<ItemStatus, string> = {
+  passed: 'Working',
+  flaky: 'Unreliable',
+  failed: 'Broken',
+  'not-reached': 'Not reached',
+  'not-yet-run': 'Not run yet',
+  'spec-only': 'Spec only'
+};
+
+/** A sentence only when the status word does not already say it, or when the run gave its own reason. */
+export function statusNote(status: ItemStatus, reason?: string | null): string | null {
+  const specific = reason?.trim();
+  if (specific) return specific;
+  if (status === 'flaky') return 'It worked only on a retry.';
+  if (status === 'spec-only') return 'No run has checked it yet.';
+  return null;
+}
+
+export { ITEM_STATUSES };