@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/README.md

@@ -0,0 +1,154 @@
+# Atlas visualizer
+
+A map of how a product behaves: every screen a user can see, every event that moves them on, the
+named journeys through them, and whether the latest run of the app did what the spec says. It
+reads two independent sources and works with whatever exists:
+
+1. **Spec only.** Charts render from the specs directory alone, with designed placeholders where
+   screenshots will go.
+2. **Partial runs.** Real screenshots and clips replace each placeholder as a run writes them.
+3. **Full runs.** Everything is populated, with history across runs.
+
+The explorer is one header, an open index and one plate. The index lists every place and journey of
+the product; each kind of spec (Gherkin, Quint, DMN, Alloy, OpenSLO) has its own tab, with the
+recorded result of every spec in its index. Local directories, published HTTP files and HTTP APIs
+can supply reports simultaneously. Reports update through file watching, polling or server events.
+Latest includes running reports; one unavailable backend leaves the others usable.
+
+See [report backends and live snapshots](../../docs/report-backends.md) for configuration,
+the API contract, streaming notifications and adding another transport.
+
+## Point it at your project
+
+```sh
+atlas-visualizer dev --specs ./specs --runs ./atlas-runs
+```
+
+| Flag              | Meaning                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `--specs <dir>`   | Statecharts, journeys and notes. Default `./specs`.                                                      |
+| `--runs <dir>`    | One directory per run, each with a `manifest.json` (what `atlas run` writes). Default `./atlas-runs`.    |
+| `--sources <file>` | JSON configuration for additional directories, HTTP files or HTTP API sources. |
+| `--fixture <name>`| Show a bundled example instead: `spec-only`, `partial`, `full`, `failures`, `removed`, `malformed`, `large`. |
+| `--out <dir>`     | `build`: the static site (default `./atlas-site`). `publish-data`: the data only (default `./atlas-data`). |
+| `--keep <n>`      | How many of the newest runs to publish (default 30).                                                     |
+| `--no-data`       | `build`: leave the data out, to host it elsewhere.                                                       |
+| `--port <n>`, `--host <host>` | `dev`: where to listen (default `localhost:5180`, or the next free port).                   |
+
+Relative paths resolve against the directory the command was run from. Without flags the
+environment is read: `ATLAS_SPECS_ROOT`, `ATLAS_RUNS_ROOT` (relative to `INIT_CWD` when your package
+manager sets it to where you ran the command, or the current directory) and `ATLAS_FIXTURE`. With nothing configured and no
+`specs/` directory, the `full` example is shown.
+
+Editing a spec file or a run publishing a snapshot updates the open page in about a second, without a reload,
+keeping selection, zoom and pan.
+
+### Commands
+
+```sh
+atlas-visualizer dev          --specs <dir> --runs <dir>             # live, from disk
+atlas-visualizer build        --specs <dir> --runs <dir> --out site  # static site + its data
+atlas-visualizer publish-data --specs <dir> --runs <dir> --out data  # data only
+```
+
+`build` writes a static site that any file server can host, with the spec and the newest privacy-checked snapshots
+under `<out>/data`. URLs use the hash, so deep links work without server rewrites. A run whose
+privacy check failed or is missing is never published. With `--no-data`, set
+`VITE_ATLAS_BASE_URL` at build time to where `publish-data` output is hosted; `VITE_ATLAS_POLL_MS`
+sets how often the site checks for new runs (default 60 s, plus when the tab regains focus).
+
+### Inside this repository
+
+```sh
+bun run viz:dev                          # ATLAS_SPECS_ROOT / ATLAS_RUNS_ROOT, or the example
+ATLAS_FIXTURE=partial bun run viz:dev    # one of the fixtures
+bun test packages/visualizer/src packages/visualizer/vite   # parsing, composition, statuses, every fixture
+bun run viz:fixtures                     # regenerate the fixtures (needs ImageMagick, cwebp, ffmpeg)
+```
+
+`bun run viz:publish-data` and `bun run viz:build` do the same as the CLI, writing to `public/data` (or
+`ATLAS_OUT`) and `dist`. `ATLAS_SOURCES_FILE` supplies additional sources, and
+`VITE_ATLAS_SOURCES_URL` can point a hosted viewer at a separate source descriptor file.
+
+## What it reads
+
+Open formats first, so specs are not tied to this tool:
+
+- **W3C SCXML** (`*.scxml`): `<state>`, `<parallel>`, `<final>`, `initial`, `<transition event target>`
+  and `<invoke>`. Readable names and business metadata travel in the Atlas namespace
+  (`atlas:name`, `<atlas:meta>`, a final state's `atlas:done-event`), as SCXML allows.
+- **XState v5 machine config** (`*.machine.yaml`, `*.machine.yml`, `*.machine.json`), the JSON
+  form Stately Studio imports and exports. A `machine.json` beside a `machine.yaml` is taken as
+  the same chart.
+- **Child charts** compose with the standard `invoke: { src, id, onDone }` (SCXML `<invoke>` plus a
+  `done.invoke.<id>` transition), or the older `meta.childMachine` with `meta.childFinalEvents`.
+  Each final state at the top of a child hands an event to the state that runs it: its
+  `childFinalEvents` entry, its own `meta.doneEvent`, or `done.invoke.<id>`, handled by a
+  transition of that name or the invoke's `onDone`. This is how the Atlas runner composes charts,
+  so transition ids match the run manifests.
+- **Journeys** (`journeys.yaml` beside a chart): named event lists, replayed through the composed
+  chart with hand-off events inserted.
+- **Notes** beside a chart: `open-questions.md`, `known-issues.md`; a `<chart>.layout.json` pins
+  node positions; an optional `atlas.yaml` at the specs root declares contexts and hand-offs
+  between them (without it, each top-level folder holding a chart is a context).
+- **Run manifests** (`<runs>/<run-id>/manifest.json`, the `@crvouga/atlas/schema` contract):
+  screenshots, clips with WebVTT captions (shown as the video's caption track), timelines,
+  business events with the CloudEvents a source observed, paths, coverage, and links to the
+  JUnit, CTRF and Mermaid reports the run wrote. Unknown fields and newer formats are read as far
+  as they go.
+
+The spec parsing is `@crvouga/atlas/spec`, the browser-safe part of the Atlas core.
+
+## How it fits together
+
+```
+bin/atlas-visualizer.mjs   CLI: dev, build and publish-data through Vite's JS API
+vite/atlas-files.ts        node: resolve the roots, find spec files, summarize run directories, safe paths
+vite/atlas-dev-plugin.ts   dev adapter: serves /__atlas/{specs,runs}, range requests, change events over HMR
+vite/publish.ts            lays out specs/ and runs/ (with index.json files) for a static host
+src/data/adapters          static adapter (HTTP from a base URL) and dev adapter (same + HMR)
+src/data/parse             tolerant parsing: each chart, state, transition, journey and run record on its own
+src/data/model             the view model: spec + selected run → one status per state, event, journey
+src/data/queries.ts        TanStack Query: per-file caching, live invalidation, polling
+src/layout                 chart → ELK graph → positions in ELK's worker, cached by structure
+src/map                    React Flow map: phone-frame screens, regions, child-chart boxes, event chips
+src/components, src/views  header, legend, placeholders, panels, product map
+src/evidence               spec tabs: index, result pages, recordings, sources
+example/specs              the example spec every fixture is generated from
+```
+
+Components read only the view model (`AtlasView`), never raw files.
+
+- **Statuses.** States and events resolve to working (`passed`), unreliable (`flaky`), broken
+  (`failed`), not reached, not run yet (a run exists but didn't cover it), or spec only (no runs).
+  Groups take the worst of themselves and what they contain. Run records the spec no longer has
+  are listed as removed from the spec, never dropped.
+- **Event kinds.** Who sends an event (`user`, `system`, `time`, `hand-off`; the older `member` is
+  read as `user`) comes from, in order: chart `meta.eventKinds`; the structure (hand-offs); chart
+  `meta.timeEvents`; the run record; a guess from the wording. The developer section says which.
+- **Data issues.** Every skipped or guessed piece becomes a plain-language issue with its file and
+  path, listed behind a quiet count in the header.
+- **Layout.** ELK lays out each chart (nested states as regions, parallel states side by side) in
+  its own worker. Positions are cached under a hash of the chart's structure only, so new results
+  never move anything.
+
+## Fixtures
+
+`fixtures/` holds seven scenarios generated by `scripts/make-fixtures.ts` from `example/specs`, a
+coffee-ordering app: an XState root chart with a parallel region that invokes a checkout chart
+written in SCXML. Every screenshot and clip is synthetic. `large` is a generated six-context atlas
+of about 500 states that mixes `invoke`, SCXML children and the legacy composition.
+
+## License
+
+MIT
+
+## Specs and their results
+
+Beside the statechart map, every other kind of spec has its own tab: Gherkin features, Quint models, DMN decision tables, Alloy structures and OpenSLO objectives. A tab appears when the specs folder has files of its kind. The index lists every spec with what was recorded for it, and filters to those with results, those failing, or those with none. A spec page shows each scenario, trace or check with its outcome; opening one shows the recorded steps, the error, the timings, every other run of the same check, and its recording.
+
+Results come from the Atlas reports API (`/api/reports` in dev, `VITE_ATLAS_REPORTS_URL` when hosted elsewhere) or from a static `data/evidence` export. They combine across backends, branches and runs; **Sources** in the header switches any of them off. While a spec suite is running, the header says so and each finished test appears within a couple of seconds. See [Atlas reports](../reports/README.md) for the API and host configuration.
+
+The header title is the product's name, taken from `atlas.yaml`'s `title` up to its first dash or colon, or "Atlas".
+
+`src/evidence/` holds this part of the viewer: `evidence-context.tsx` reads and combines the layers, `spec-index.tsx` is the index, `feature-page.tsx`, `model-page.tsx` and `document-page.tsx` are the three kinds of spec page, `check-detail.tsx` is one check's results, and `recording.tsx` is the recorded timeline. `tests/reports.test.tsx` drives the whole viewer against an in-memory reports API.

package/packages/visualizer/bin/atlas-visualizer.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG_FILE = path.join(APP_ROOT, 'vite.config.ts');
+
+const USAGE = `atlas-visualizer: browse statechart specs and the runs that execute them
+
+Usage
+  atlas-visualizer dev          [--specs <dir>] [--runs <dir>] [--port <n>] [--host <host>]
+  atlas-visualizer build        [--specs <dir>] [--runs <dir>] [--out <dir>] [--keep <n>] [--no-data]
+  atlas-visualizer publish-data [--specs <dir>] [--runs <dir>] [--out <dir>] [--keep <n>]
+
+Options
+  --specs <dir>    all specs: statecharts, Gherkin, Quint, DMN, Alloy, notes   (default: ./specs)
+  --runs <dir>     run directories, each with a manifest.json                              (default: ./atlas-runs)
+  --sources <file> additional directory, HTTP and streaming API report sources (JSON)
+  --fixture <name> show a bundled example instead (spec-only, partial, full, failures, removed, malformed, large)
+  --out <dir>      build: the static site (default ./atlas-site); publish-data: the data (default ./atlas-data)
+  --keep <n>       how many of the newest runs to publish (default 30)
+  --no-data        build: leave the data out; point the site at it with VITE_ATLAS_BASE_URL
+  --port <n>       dev: port to listen on (default 5180, or the next free one)
+  --host <host>    dev: address to listen on (default localhost)
+
+Relative paths resolve against the directory the command was run from. ATLAS_SPECS_ROOT and
+ATLAS_RUNS_ROOT are read when the flags are absent.
+`;
+
+class UsageError extends Error {}
+
+function parse(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      specs: { type: 'string' },
+      runs: { type: 'string' },
+      sources: { type: 'string' },
+      fixture: { type: 'string' },
+      out: { type: 'string' },
+      keep: { type: 'string' },
+      port: { type: 'string' },
+      host: { type: 'string' },
+      'no-data': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false }
+    }
+  });
+  return { command: positionals[0], extra: positionals.slice(1), values };
+}
+
+function integer(name, value, min, max) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min || n > max) throw new UsageError(`--${name} must be a whole number from ${min} to ${max}, got "${value}"`);
+  return n;
+}
+
+/** Point the shared root resolution (vite/atlas-files.ts) at the flags, as absolute paths. */
+function applyRoots(values, base) {
+  if (values.sources) process.env.ATLAS_SOURCES_FILE = path.resolve(base, values.sources);
+  if (values.fixture) {
+    if (values.specs || values.runs) throw new UsageError('--fixture cannot be combined with --specs or --runs');
+    process.env.ATLAS_FIXTURE = values.fixture;
+    return;
+  }
+  if (values.specs || values.runs) delete process.env.ATLAS_FIXTURE;
+  if (values.specs) {
+    const specs = path.resolve(base, values.specs);
+    if (!existsSync(specs) || !statSync(specs).isDirectory()) throw new UsageError(`No specs directory at ${specs}`);
+    process.env.ATLAS_SPECS_ROOT = specs;
+  } else if (process.env.ATLAS_SPECS_ROOT) {
+    process.env.ATLAS_SPECS_ROOT = path.resolve(base, process.env.ATLAS_SPECS_ROOT);
+  }
+  if (values.runs) process.env.ATLAS_RUNS_ROOT = path.resolve(base, values.runs);
+  else if (process.env.ATLAS_RUNS_ROOT) process.env.ATLAS_RUNS_ROOT = path.resolve(base, process.env.ATLAS_RUNS_ROOT);
+  process.env.INIT_CWD = base;
+}
+
+/** Refuse to empty a directory that is not a previous build: the base, its ancestors, home, or anything else with files. */
+function assertSafeOut(out, base) {
+  const rel = path.relative(out, base);
+  if (out === path.parse(out).root || out === os.homedir() || rel === '' || !rel.startsWith('..')) {
+    throw new UsageError(`Refusing to build into ${out}: it holds the directory you ran from. Pass --out <new dir>.`);
+  }
+  if (existsSync(out)) {
+    const entries = readdirSync(out).filter((n) => n !== '.DS_Store');
+    if (entries.length && !entries.includes('index.html')) {
+      throw new UsageError(`Refusing to replace ${out}: it is not empty and is not a previous build. Pass --out <new dir>.`);
+    }
+  }
+}
+
+async function loadNodeSide() {
+  const { runnerImport } = await import('vite');
+  const files = await runnerImport(path.join(APP_ROOT, 'vite/atlas-files.ts'));
+  const publish = await runnerImport(path.join(APP_ROOT, 'vite/publish.ts'));
+  return { resolveRoots: files.module.resolveRoots, publishData: publish.module.publishData };
+}
+
+function publish(publishData, roots, out, keep) {
+  const result = publishData({ roots, out, keep: keep ?? 30 });
+  process.stdout.write(`Published ${result.files.length} spec file(s) and ${result.published.length} run(s) to ${out}\n`);
+  if (result.skipped.length) process.stdout.write(`Not published, privacy check missing or failed: ${result.skipped.join(', ')}\n`);
+}
+
+async function main(argv) {
+  const { command, extra, values } = parse(argv);
+  if (values.help || !command) {
+    process.stdout.write(USAGE);
+    return command || values.help ? 0 : 1;
+  }
+  if (extra.length) throw new UsageError(`Unexpected argument: ${extra.join(' ')}`);
+  const base = process.env.INIT_CWD || process.cwd();
+  const port = integer('port', values.port, 0, 65_535);
+  const keep = integer('keep', values.keep, 0, 10_000);
+  applyRoots(values, base);
+
+  if (command === 'dev') {
+    const { createServer } = await import('vite');
+    const server = await createServer({
+      configFile: CONFIG_FILE,
+      configLoader: 'runner',
+      root: APP_ROOT,
+      server: { ...(port !== undefined ? { port } : {}), ...(values.host ? { host: values.host } : {}), strictPort: false }
+    });
+    await server.listen();
+    server.printUrls();
+    server.bindCLIShortcuts({ print: true });
+    return null;
+  }
+
+  if (command === 'build') {
+    const out = path.resolve(base, values.out ?? 'atlas-site');
+    assertSafeOut(out, base);
+    const { build } = await import('vite');
+    await build({
+      configFile: CONFIG_FILE,
+      configLoader: 'runner',
+      root: APP_ROOT,
+      publicDir: false,
+      build: { outDir: out, emptyOutDir: true }
+    });
+    if (!values['no-data']) {
+      const { resolveRoots, publishData } = await loadNodeSide();
+      publish(publishData, resolveRoots(), path.join(out, 'data'), keep);
+    }
+    process.stdout.write(`Built the site in ${out}; serve it with any static file server.\n`);
+    return 0;
+  }
+
+  if (command === 'publish-data') {
+    const out = path.resolve(base, values.out ?? 'atlas-data');
+    const { resolveRoots, publishData } = await loadNodeSide();
+    publish(publishData, resolveRoots(), out, keep);
+    return 0;
+  }
+
+  throw new UsageError(`Unknown command "${command}"`);
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (typeof code === 'number') process.exitCode = code;
+  },
+  (error) => {
+    const usage = error instanceof UsageError || error?.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' || error?.code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE';
+    process.stderr.write(`atlas-visualizer: ${error instanceof Error ? error.message : String(error)}\n`);
+    if (usage) process.stderr.write(`\n${USAGE}`);
+    process.exitCode = 1;
+  }
+);

package/packages/visualizer/example/specs/coffee/ordering/checkout.scxml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- The child chart: W3C SCXML. Readable names travel in atlas:name; a final state's
+     atlas:done-event names the event the parent chart receives when checkout ends there. -->
+<scxml xmlns="http://www.w3.org/2005/07/scxml" xmlns:atlas="https://github.com/crvouga/atlas/ns/1" version="1.0" name="Checkout" initial="choosing-how-to-pay" datamodel="null">
+  <atlas:meta>
+    <atlas:description>Paying for the order, by card or with a wallet.</atlas:description>
+    <atlas:timeEvents>{"Payment takes longer than a minute": "1 minute"}</atlas:timeEvents>
+  </atlas:meta>
+  <state id="choosing-how-to-pay" atlas:name="Choosing how to pay">
+    <atlas:meta>
+      <atlas:description>Card and wallet buttons, and the order total.</atlas:description>
+      <atlas:snapshot>pay-options</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+      <atlas:hints>["A card button", "A wallet button", "The order total"]</atlas:hints>
+    </atlas:meta>
+    <transition event="picks-card" atlas:name="Picks card" target="entering-card-details"/>
+    <transition event="picks-wallet" atlas:name="Picks wallet" target="confirming-with-the-wallet"/>
+    <transition event="closes-checkout" atlas:name="Closes checkout" target="checkout-abandoned"/>
+  </state>
+  <state id="entering-card-details" atlas:name="Entering card details">
+    <atlas:meta>
+      <atlas:description>A form for the card number, expiry and code.</atlas:description>
+      <atlas:snapshot>card-form</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+      <atlas:check>The pay button stays off until the card is complete</atlas:check>
+    </atlas:meta>
+    <transition event="submits-the-card" atlas:name="Submits the card" target="waiting-for-the-payment"/>
+    <transition event="goes-back-to-the-payment-options" atlas:name="Goes back to the payment options" target="choosing-how-to-pay"/>
+  </state>
+  <state id="confirming-with-the-wallet" atlas:name="Confirming with the wallet">
+    <atlas:meta>
+      <atlas:description>The wallet sheet asks the customer to confirm the payment.</atlas:description>
+      <atlas:snapshot>wallet-sheet</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+    </atlas:meta>
+    <transition event="confirms-with-the-wallet" atlas:name="Confirms with the wallet" target="waiting-for-the-payment"/>
+    <transition event="cancels-the-wallet" atlas:name="Cancels the wallet" target="choosing-how-to-pay"/>
+  </state>
+  <state id="waiting-for-the-payment" atlas:name="Waiting for the payment">
+    <atlas:meta>
+      <atlas:description>A spinner while the payment provider answers.</atlas:description>
+      <atlas:snapshot>paying</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+      <atlas:event>Payment requested</atlas:event>
+    </atlas:meta>
+    <transition event="payment-provider-approves-the-payment" atlas:name="Payment provider approves the payment" target="paid"/>
+    <transition event="payment-provider-declines-the-payment" atlas:name="Payment provider declines the payment" target="told-the-payment-was-declined"/>
+    <transition event="payment-takes-longer-than-a-minute" atlas:name="Payment takes longer than a minute" target="told-the-payment-is-slow"/>
+  </state>
+  <state id="told-the-payment-is-slow" atlas:name="Told the payment is slow">
+    <atlas:meta>
+      <atlas:description>A message says the payment is taking longer than usual, with "Check again".</atlas:description>
+      <atlas:snapshot>paying-slow</atlas:snapshot>
+      <atlas:confidence>assumed</atlas:confidence>
+    </atlas:meta>
+    <transition event="checks-the-payment-again" atlas:name="Checks the payment again" target="waiting-for-the-payment"/>
+  </state>
+  <state id="told-the-payment-was-declined" atlas:name="Told the payment was declined">
+    <atlas:meta>
+      <atlas:description>A message says the payment was declined, with "Try another way".</atlas:description>
+      <atlas:snapshot>payment-declined</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+      <atlas:event>Payment declined</atlas:event>
+    </atlas:meta>
+    <transition event="tries-another-way-to-pay" atlas:name="Tries another way to pay" target="choosing-how-to-pay"/>
+  </state>
+  <final id="paid" atlas:name="Paid" atlas:done-event="Payment goes through">
+    <atlas:meta>
+      <atlas:description>A check mark confirms the payment.</atlas:description>
+      <atlas:snapshot>paid</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+      <atlas:event>Payment captured</atlas:event>
+    </atlas:meta>
+  </final>
+  <final id="checkout-abandoned" atlas:name="Checkout abandoned" atlas:done-event="Leaves checkout">
+    <atlas:meta>
+      <atlas:description>Checkout closes and the cart is kept.</atlas:description>
+      <atlas:snapshot>checkout-closed</atlas:snapshot>
+      <atlas:confidence>confirmed</atlas:confidence>
+    </atlas:meta>
+  </final>
+</scxml>

package/packages/visualizer/example/specs/coffee/ordering/journeys.yaml

@@ -0,0 +1,129 @@
+# Named paths through the composed chart. Hand-off events from Checkout are inserted automatically.
+journeys:
+  Orders a drink and pays by card:
+    description: The everyday order, from the menu to picking the drink up.
+    tour: true
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks card
+      - Submits the card
+      - Payment provider approves the payment
+      - Barista starts the drink
+      - Barista finishes the drink
+      - Picks up the drink
+    endsIn:
+      - Order complete
+  Pays with a wallet:
+    description: The wallet confirms the payment instead of a card.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks wallet
+      - Confirms with the wallet
+      - Payment provider approves the payment
+    endsIn:
+      - Paid, waiting for the barista
+      - Updates on
+  Card declined, then a wallet works:
+    description: The card is declined and the wallet goes through.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks card
+      - Submits the card
+      - Payment provider declines the payment
+      - Tries another way to pay
+      - Picks wallet
+      - Confirms with the wallet
+      - Payment provider approves the payment
+    endsIn:
+      - Paid, waiting for the barista
+  Slow payment:
+    description: The payment provider takes more than a minute to answer.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks card
+      - Submits the card
+      - Payment takes longer than a minute
+      - Checks the payment again
+      - Payment provider approves the payment
+    endsIn:
+      - Paid, waiting for the barista
+  Leaves checkout and comes back:
+    description: The customer closes checkout, then starts it again.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Closes checkout
+      - Starts checkout
+    endsIn:
+      - Checking out
+      - Choosing how to pay
+  Drink left too long:
+    description: Nobody picks the drink up, so it is thrown away and refunded.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks card
+      - Submits the card
+      - Payment provider approves the payment
+      - Barista starts the drink
+      - Barista finishes the drink
+      - Drink sits ready for ten minutes
+      - Orders again
+    endsIn:
+      - Browsing the menu
+  Turns off updates while waiting:
+    description: Updates go off while the drink is in the queue; the drink is still made.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Starts checkout
+      - Picks wallet
+      - Confirms with the wallet
+      - Payment provider approves the payment
+      - Turns off updates
+      - Barista starts the drink
+    endsIn:
+      - Updates off
+      - Drink being made
+  Changes their mind about the drink:
+    description: The customer backs out while choosing the drink.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Goes back to the menu
+    endsIn:
+      - Browsing the menu
+  Empties the cart:
+    description: The only drink is removed from the cart.
+    events:
+      - Picks a drink
+      - Picks a size
+      - Picks a milk
+      - Adds the drink to the cart
+      - Removes the last drink
+    endsIn:
+      - Browsing the menu

package/packages/visualizer/example/specs/coffee/ordering/known-issues.md

@@ -0,0 +1,14 @@
+# Known issues
+
+## Drink being made
+
+- The progress bar jumps back once. It settles after a second.
+
+## Drink ready for pickup → Picks up the drink
+
+- The pickup button needs two taps on small screens.
+
+## Other
+
+- `Updates off` shows the wrong icon.
+- Nothing named here.