@crvouga/atlas 0.2.0 → 0.4.0

package/packages/visualizer/fixtures/partial/specs/coffee/ordering/loyalty.feature

@@ -0,0 +1,7 @@
+Feature: Loyalty stamps
+  A regular earns a free drink. No layer has recorded this yet.
+
+  Scenario: Tenth drink is free
+    Given nine stamps
+    When the customer orders
+    Then the drink is free

package/packages/visualizer/fixtures/partial/specs/coffee/ordering/ordering.feature

@@ -0,0 +1,36 @@
+Feature: Order a drink
+  A customer picks a drink, pays, and picks it up.
+
+  Rule: Paying for the order
+
+    Scenario: Pays by card
+      Given a drink in the cart
+      When the customer pays by card
+      Then the barista can start the drink
+
+    Scenario: Pays with a wallet
+      Given a drink in the cart
+      When the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Card declined, then a wallet works
+      Given a drink in the cart
+      When the card is declined
+      And the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Slow payment
+      Given a drink in the cart
+      When the payment takes longer than a minute
+      Then the customer can check the payment again
+
+    Scenario: Leaves checkout and comes back
+      Given a drink in the cart
+      When the customer closes checkout
+      And the customer starts checkout again
+      Then checkout is open
+
+    Scenario: Drink left too long
+      Given a finished drink
+      When nobody picks it up
+      Then the drink is thrown away and refunded

package/packages/visualizer/fixtures/partial/specs/coffee/ordering/payment.als

@@ -0,0 +1,4 @@
+// An order is paid once.
+sig Order { paid: lone Payment }
+sig Payment {}
+fact { all o: Order | one o.paid }

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/cart.qnt

@@ -0,0 +1,7 @@
+# Cart
+module cart {
+  var items: int
+  var paid: bool
+  action add = items' = items + 1
+  action pay = paid' = true
+}

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/checkout.openslo.yaml

@@ -0,0 +1,10 @@
+# Checkout latency
+apiVersion: openslo/v1
+kind: SLO
+metadata:
+  name: checkout-latency
+spec:
+  description: Checkout answers within a second.
+  objectives:
+    - displayName: Checkout latency
+      target: 0.99

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/drink-price.dmn

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/">
+  <decision id="drink-price" name="Drink price">
+    <decisionTable id="Drink price" hitPolicy="UNIQUE">
+      <input label="Size">
+        <inputExpression typeRef="string"><text>size</text></inputExpression>
+      </input>
+      <input label="Milk">
+        <inputExpression typeRef="string"><text>milk</text></inputExpression>
+      </input>
+      <output label="Price" name="price" />
+      <rule>
+        <inputEntry><text>"Small"</text></inputEntry>
+        <inputEntry><text>"None"</text></inputEntry>
+        <outputEntry><text>3</text></outputEntry>
+      </rule>
+      <rule>
+        <inputEntry><text>"Large"</text></inputEntry>
+        <inputEntry><text>"Oat"</text></inputEntry>
+        <outputEntry><text>5</text></outputEntry>
+      </rule>
+    </decisionTable>
+  </decision>
+</definitions>

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/loyalty.feature

@@ -0,0 +1,7 @@
+Feature: Loyalty stamps
+  A regular earns a free drink. No layer has recorded this yet.
+
+  Scenario: Tenth drink is free
+    Given nine stamps
+    When the customer orders
+    Then the drink is free

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/ordering.feature

@@ -0,0 +1,36 @@
+Feature: Order a drink
+  A customer picks a drink, pays, and picks it up.
+
+  Rule: Paying for the order
+
+    Scenario: Pays by card
+      Given a drink in the cart
+      When the customer pays by card
+      Then the barista can start the drink
+
+    Scenario: Pays with a wallet
+      Given a drink in the cart
+      When the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Card declined, then a wallet works
+      Given a drink in the cart
+      When the card is declined
+      And the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Slow payment
+      Given a drink in the cart
+      When the payment takes longer than a minute
+      Then the customer can check the payment again
+
+    Scenario: Leaves checkout and comes back
+      Given a drink in the cart
+      When the customer closes checkout
+      And the customer starts checkout again
+      Then checkout is open
+
+    Scenario: Drink left too long
+      Given a finished drink
+      When nobody picks it up
+      Then the drink is thrown away and refunded

package/packages/visualizer/fixtures/removed/specs/coffee/ordering/payment.als

@@ -0,0 +1,4 @@
+// An order is paid once.
+sig Order { paid: lone Payment }
+sig Payment {}
+fact { all o: Order | one o.paid }

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/cart.qnt

@@ -0,0 +1,7 @@
+# Cart
+module cart {
+  var items: int
+  var paid: bool
+  action add = items' = items + 1
+  action pay = paid' = true
+}

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/checkout.openslo.yaml

@@ -0,0 +1,10 @@
+# Checkout latency
+apiVersion: openslo/v1
+kind: SLO
+metadata:
+  name: checkout-latency
+spec:
+  description: Checkout answers within a second.
+  objectives:
+    - displayName: Checkout latency
+      target: 0.99

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/drink-price.dmn

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/">
+  <decision id="drink-price" name="Drink price">
+    <decisionTable id="Drink price" hitPolicy="UNIQUE">
+      <input label="Size">
+        <inputExpression typeRef="string"><text>size</text></inputExpression>
+      </input>
+      <input label="Milk">
+        <inputExpression typeRef="string"><text>milk</text></inputExpression>
+      </input>
+      <output label="Price" name="price" />
+      <rule>
+        <inputEntry><text>"Small"</text></inputEntry>
+        <inputEntry><text>"None"</text></inputEntry>
+        <outputEntry><text>3</text></outputEntry>
+      </rule>
+      <rule>
+        <inputEntry><text>"Large"</text></inputEntry>
+        <inputEntry><text>"Oat"</text></inputEntry>
+        <outputEntry><text>5</text></outputEntry>
+      </rule>
+    </decisionTable>
+  </decision>
+</definitions>

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/loyalty.feature

@@ -0,0 +1,7 @@
+Feature: Loyalty stamps
+  A regular earns a free drink. No layer has recorded this yet.
+
+  Scenario: Tenth drink is free
+    Given nine stamps
+    When the customer orders
+    Then the drink is free

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/ordering.feature

@@ -0,0 +1,36 @@
+Feature: Order a drink
+  A customer picks a drink, pays, and picks it up.
+
+  Rule: Paying for the order
+
+    Scenario: Pays by card
+      Given a drink in the cart
+      When the customer pays by card
+      Then the barista can start the drink
+
+    Scenario: Pays with a wallet
+      Given a drink in the cart
+      When the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Card declined, then a wallet works
+      Given a drink in the cart
+      When the card is declined
+      And the customer pays with a wallet
+      Then the order is paid
+
+    Scenario: Slow payment
+      Given a drink in the cart
+      When the payment takes longer than a minute
+      Then the customer can check the payment again
+
+    Scenario: Leaves checkout and comes back
+      Given a drink in the cart
+      When the customer closes checkout
+      And the customer starts checkout again
+      Then checkout is open
+
+    Scenario: Drink left too long
+      Given a finished drink
+      When nobody picks it up
+      Then the drink is thrown away and refunded

package/packages/visualizer/fixtures/spec-only/specs/coffee/ordering/payment.als

@@ -0,0 +1,4 @@
+// An order is paid once.
+sig Order { paid: lone Payment }
+sig Payment {}
+fact { all o: Order | one o.paid }

package/packages/visualizer/scripts/make-fixtures.ts

@@ -30,6 +30,8 @@ import { APP_ROOT, FIXTURES_ROOT, listSpecFiles } from '../vite/atlas-files';
  * Regenerates every fixture from the example spec in `example/specs` (a coffee-ordering app: an
  * XState root chart with a parallel region that invokes an SCXML checkout chart) and a generated
  * large atlas. All media is synthetic: ImageMagick draws the screens and ffmpeg the clips.
+ * Gherkin, Quint, DMN, Alloy and OpenSLO documents in that spec are copied with the charts.
+ * The visualizer dev server serves the layered report for them; this script does not rebuild it.
  */
 
 const EXAMPLE_SPECS = path.join(APP_ROOT, 'example/specs');

package/packages/visualizer/scripts/publish-data.ts

@@ -5,8 +5,7 @@ import { publishData } from '../vite/publish';
 
 /**
  * `pnpm publish-data`: the spec and the newest runs into `public/data` (or `ATLAS_OUT`), where
- * `pnpm build` picks them up. Roots come from `ATLAS_SPECS_ROOT` / `ATLAS_RUNS_ROOT` or
- * `ATLAS_FIXTURE`, as for the dev server.
+ * `pnpm build` picks them up. Roots come from `ATLAS_SPECS_ROOT` / `ATLAS_RUNS_ROOT`, as for the dev server.
  */
 try {
   const roots = resolveRoots();

package/packages/visualizer/src/app/AppShell.tsx

@@ -6,9 +6,9 @@ import { SourcesPanel } from '../evidence/sources-panel';
 import { SpecIndex } from '../evidence/spec-index';
 import { kindOfAddress } from '../spec-kind';
 import styles from '../views/views.module.css';
+import { Finder } from '../find/Finder';
 import { AtlasProvider, useAtlas } from './atlas-context';
 import { Gazetteer } from './gazetteer';
-import { SearchQueryProvider } from './search-query';
 
 function Index() {
   const { pathname } = useLocation();
@@ -38,18 +38,17 @@ export function AppShell() {
   return (
     <AtlasProvider run={run}>
       <EvidenceProvider>
-        <SearchQueryProvider>
-          <div className={styles.app}>
-            <Header />
-            <div className={styles.frame}>
-              <Index />
-              <main className={styles.main}>
-                <Body />
-              </main>
-            </div>
-            <SourcesPanel />
+        <div className={styles.app}>
+          <Header />
+          <div className={styles.frame}>
+            <Index />
+            <main className={styles.main}>
+              <Body />
+            </main>
           </div>
-        </SearchQueryProvider>
+          <SourcesPanel />
+          <Finder />
+        </div>
       </EvidenceProvider>
     </AtlasProvider>
   );

package/packages/visualizer/src/app/gazetteer.module.css

@@ -29,8 +29,8 @@
 .row {
   display: flex;
   justify-content: space-between;
-  align-items: baseline;
-  gap: 12px;
+  align-items: center;
+  gap: 10px;
   padding: 6px 10px;
   border-radius: 8px;
   color: inherit;
@@ -38,6 +38,16 @@
   text-decoration: none;
 }
 
+.thumb {
+  flex: none;
+  width: 28px;
+}
+
+.name {
+  flex: 1;
+  min-width: 0;
+}
+
 .chart {
   color: var(--ink-2);
   font-weight: 600;

package/packages/visualizer/src/app/gazetteer.tsx

@@ -1,13 +1,17 @@
 import { Link, useLocation, useParams, useSearch } from '@tanstack/react-router';
 
+import { ScreenImage } from '../components/Screen';
 import { STATUS_LABEL, type AtlasView, type StateView } from '../data/model';
 import { useAtlas } from './atlas-context';
-import { useSearchQuery } from './search-query';
 import styles from './gazetteer.module.css';
 
-function hit(query: string, text: string) {
-  const needle = query.trim().toLowerCase();
-  return needle.length === 0 || text.toLowerCase().includes(needle);
+function openingScreen(view: AtlasView, steps: readonly { transitionIds: readonly string[] }[]) {
+  for (const step of steps) {
+    const transition = view.transitions.get(step.transitionIds[0] ?? '');
+    const landing = transition?.target ? view.states.get(transition.target) : undefined;
+    if (landing && (landing.kind === 'screen' || landing.kind === 'final')) return landing;
+  }
+  return undefined;
 }
 
 function screensOf(view: AtlasView, chartId: string) {
@@ -19,7 +23,6 @@ function screensOf(view: AtlasView, chartId: string) {
 }
 
 export function Gazetteer() {
-  const { query } = useSearchQuery();
   const { view } = useAtlas();
   const params = useParams({ strict: false });
   const search = useSearch({ strict: false });
@@ -27,7 +30,7 @@ export function Gazetteer() {
   const screen = typeof search.screen === 'string' ? search.screen : undefined;
   const journeyId = typeof search.journey === 'string' ? search.journey : undefined;
   const group = typeof search.group === 'string' ? search.group : undefined;
-  const journeys = (view?.journeys ?? []).filter((journey) => journey.chartIds.length > 0 && hit(query, journey.name));
+  const journeys = (view?.journeys ?? []).filter((journey) => journey.chartIds.length > 0);
   return (
     <nav className={styles.index} aria-label="Places">
       <h2>Places</h2>
@@ -38,9 +41,7 @@ export function Gazetteer() {
           {context.chartIds.map((chartId) => {
             const chart = view.charts.get(chartId);
             if (!chart) return null;
-            const screens = screensOf(view, chartId).filter((state) => hit(query, `${state.name} ${chart.name} ${context.name}`));
-            const chartHit = hit(query, `${chart.name} ${context.name}`);
-            if (query.trim() && screens.length === 0 && !chartHit) return null;
+            const screens = screensOf(view, chartId);
             return (
               <div key={chartId}>
                 <Link className={styles.chart} to="/chart/$chartId" params={{ chartId }} search={(prev) => ({ run: prev.run, screen: undefined, journey: undefined, group: undefined })} activeOptions={{ includeSearch: true, explicitUndefined: true }} aria-current={params.chartId === chartId && !screen && !journeyId && !group ? 'page' : undefined}>
@@ -57,7 +58,10 @@ export function Gazetteer() {
                         search={(prev) => ({ run: prev.run, screen: state.name, journey: prev.journey })}
                         aria-current={params.chartId === chartId && screen === state.name ? 'page' : undefined}
                       >
-                        <span>{state.name}</span>
+                        <span className={styles.thumb} aria-hidden="true">
+                          <ScreenImage state={state} size="thumb" description={false} lines={false} caption={false} />
+                        </span>
+                        <span className={styles.name}>{state.name}</span>
                         <span className={styles.status}>{STATUS_LABEL[state.status]}</span>
                       </Link>
                     </li>
@@ -72,21 +76,29 @@ export function Gazetteer() {
         <section>
           <h3>Journeys</h3>
           <ul>
-            {journeys.map((journey) => (
-              <li key={journey.id}>
-                <Link
-                  className={styles.row}
-                  data-status={journey.status}
-                  to="/chart/$chartId"
-                  params={{ chartId: journey.chartIds[0] ?? '' }}
-                  search={(prev) => ({ run: prev.run, journey: journey.id })}
-                  aria-current={journeyId === journey.id && pathname.startsWith('/chart') ? 'page' : undefined}
-                >
-                  <span>{journey.name}</span>
-                  <span className={styles.status}>{STATUS_LABEL[journey.status]}</span>
-                </Link>
-              </li>
-            ))}
+            {journeys.map((journey) => {
+              const opening = view ? openingScreen(view, journey.steps) : undefined;
+              return (
+                <li key={journey.id}>
+                  <Link
+                    className={styles.row}
+                    data-status={journey.status}
+                    to="/chart/$chartId"
+                    params={{ chartId: journey.chartIds[0] ?? '' }}
+                    search={(prev) => ({ run: prev.run, journey: journey.id })}
+                    aria-current={journeyId === journey.id && pathname.startsWith('/chart') ? 'page' : undefined}
+                  >
+                    {opening && (
+                      <span className={styles.thumb} aria-hidden="true">
+                        <ScreenImage state={opening} size="thumb" description={false} lines={false} caption={false} />
+                      </span>
+                    )}
+                    <span className={styles.name}>{journey.name}</span>
+                    <span className={styles.status}>{STATUS_LABEL[journey.status]}</span>
+                  </Link>
+                </li>
+              );
+            })}
           </ul>
         </section>
       )}
@@ -94,7 +106,7 @@ export function Gazetteer() {
         <section>
           <h2>Not in the spec yet</h2>
           <ul>
-            {view.excluded.filter((item) => hit(query, item)).map((item) => (
+            {view.excluded.map((item) => (
               <li key={item} className={styles.excluded}>{item}</li>
             ))}
           </ul>

package/packages/visualizer/src/components/Header.module.css

@@ -137,23 +137,39 @@
 }
 
 .search {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
   width: min(15rem, 28vw);
   height: 2.125rem;
-  padding: 0 14px;
+  padding: 0 8px 0 14px;
   border: 1px solid transparent;
   border-radius: var(--pill);
   background: var(--bg-2);
+  color: var(--ink-3);
   font-size: 0.875rem;
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
 }
 
-.search::placeholder {
+.search kbd {
+  margin-left: auto;
+  padding: 0 0.35rem;
+  border: 1px solid var(--line-2);
+  border-radius: 0.35rem;
   color: var(--ink-3);
+  font-family: var(--font);
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1.35rem;
 }
 
-.search:focus {
+.search:hover,
+.search:focus-visible {
   border-color: var(--place);
   background: var(--bg);
-  outline: none;
+  color: var(--ink);
 }
 
 @media (max-width: 760px) {

package/packages/visualizer/src/components/Header.tsx

@@ -2,7 +2,8 @@ import { Link, useLocation, useNavigate, useSearch } from '@tanstack/react-route
 import { useEffect, useMemo } from 'react';
 
 import { useAtlas } from '../app/atlas-context';
-import { useSearchQuery } from '../app/search-query';
+import { commandKey } from '../find/Finder';
+import { setFinderOpen } from '../find/open';
 import type { AtlasView } from '../data/model';
 import { LATEST } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
@@ -76,7 +77,7 @@ function SourcesButton() {
   return (
     <button type="button" className={styles.sources} data-filtered={off > 0 || undefined} onClick={() => setOpen(true)}>
       Sources
-      <span>{unavailable ? 'unavailable' : off > 0 ? `${off} off` : plural(layers.length, 'run', 'runs')}</span>
+      <span>{unavailable ? 'unavailable' : off > 0 ? `${off} off` : plural(layers.length, 'layer', 'layers')}</span>
     </button>
   );
 }
@@ -85,7 +86,6 @@ export function Header() {
   const { view } = useAtlas();
   const evidence = useEvidence();
   const { pathname } = useLocation();
-  const { query, setQuery } = useSearchQuery();
   const kind = kindOfAddress(pathname);
   const product = productName(view?.title);
   useEffect(() => {
@@ -120,7 +120,10 @@ export function Header() {
         {!kind && view && <RunPicker view={view} />}
         {!kind && view && <DataIssues issues={view.issues} />}
         <SourcesButton />
-        <input className={styles.search} type="search" value={query} aria-label="Find" placeholder={kind ? `Find a ${kind.one}` : 'Find a place'} onChange={(event) => setQuery(event.target.value)} />
+        <button type="button" className={styles.search} aria-keyshortcuts="Meta+K Control+K" onClick={() => setFinderOpen(true)}>
+          Find a flow
+          <kbd>{commandKey()}</kbd>
+        </button>
       </div>
     </header>
   );

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

@@ -108,12 +108,24 @@ export function buildAtlasView(input: BuildInput): AtlasView {
 
   const processing = input.runProgress === 'running' || run?.info.finishedAt === null;
   const itemStatus = (status: ItemStatus | undefined) => processing && status === 'not-reached' ? 'not-yet-run' : status ?? unrun;
+  const shotOf = (img: { png: string; webp?: string | undefined; client?: string | undefined }) => {
+    const full = input.resolveMedia(run!.id, img.png) || null;
+    const thumb = img.webp ? input.resolveMedia(run!.id, img.webp) || full : full;
+    if (!full && !thumb) return null;
+    return { client: img.client ?? null, thumb, full };
+  };
   const image = (img: Image | null | undefined, marked: string | undefined): ImageMedia => {
-    if (!run || !img) return { state: marked === 'processing' || processing ? 'processing' : 'missing', thumb: null, full: null };
-    if (marked === 'processing') return { state: 'processing', thumb: null, full: null };
-    const full = input.resolveMedia(run.id, img.png) || null;
-    const thumb = img.webp ? input.resolveMedia(run.id, img.webp) || full : full;
-    return { state: full || thumb ? 'available' : 'missing', thumb, full };
+    const empty = (state: ImageMedia['state']): ImageMedia => ({ state, thumb: null, full: null, client: img?.client ?? null, also: [] });
+    if (!run || !img) return empty(marked === 'processing' || processing ? 'processing' : 'missing');
+    if (marked === 'processing') return empty('processing');
+    const main = shotOf(img);
+    const also = (img.also ?? []).flatMap((extra) => {
+      if (!extra.png) return [];
+      const shot = shotOf({ png: extra.png, webp: extra.webp, client: extra.client });
+      return shot ? [shot] : [];
+    });
+    if (!main) return { state: 'missing', thumb: null, full: null, client: img.client ?? null, also };
+    return { state: 'available', thumb: main.thumb, full: main.full, client: main.client, also };
   };
   const pathRef = (id: string): PathRef => ({ id, name: run?.paths.find((p) => p.id === id)?.name ?? id });
 

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

@@ -25,7 +25,16 @@ export type SpecChange = 'same' | 'added' | 'removed' | 'changed';
 
 export type MediaState = 'available' | 'missing' | 'processing';
 
-export type ImageMedia = { state: MediaState; thumb: string | null; full: string | null };
+/** One client's still of a screen. `also` on ImageMedia holds the other clients at the same moment. */
+export type ImageShot = { client: string | null; thumb: string | null; full: string | null };
+
+export type ImageMedia = {
+  state: MediaState;
+  thumb: string | null;
+  full: string | null;
+  client: string | null;
+  also: ImageShot[];
+};
 
 export type VideoMedia = {
   state: MediaState;

package/packages/visualizer/src/evidence/api.ts

@@ -19,8 +19,13 @@ function explain(status: number) {
   return `Evidence could not be read (${status}).`;
 }
 
+/** A captured file's address in the browser. Pictures and video use it directly; fetches use the same address. */
+export function reportAssetUrl(path: string): string {
+  return staticEvidence ? `${reportsBase}/${evidenceFile(path).split('/').map(encodeURIComponent).join('/')}` : `${reportsBase}${path}`;
+}
+
 export async function reportResponse(path: string, signal?: AbortSignal) {
-  const url = staticEvidence ? `${reportsBase}/${evidenceFile(path).split('/').map(encodeURIComponent).join('/')}` : `${reportsBase}${path}`;
+  const url = reportAssetUrl(path);
   let response: Response;
   try {
     response = await fetch(url, { signal });