@crvouga/atlas 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 1.5.0 (2026-10-29)
+
+### Features
+
+- connect readable behavior with recordings and coverage gaps (#55) ([0a22022](https://github.com/crvouga/atlas/commit/0a22022dac9f9956aa77214af5de7af4fd2b2d88))
+
 ## 1.4.0 (2026-10-28)
 
 ### Features

package/docs/ui.md

@@ -67,6 +67,26 @@ and component defaults still live only in `ui/theme.tsx`. Quint/Alloy grammar so
 [`ui/grammars/README.md`](../packages/visualizer/src/ui/grammars/README.md). Unknown formats remain plain
 text, and parse failures must leave the source visible. Syntax highlighting never means a spec passed.
 
+## Behaviors: Read, Watch, Inspect
+
+A Gherkin page reads as behaviors: each scenario, or each example row of an outline (never the outline template as an
+extra), is one behavior in one coverage state (`evidence/behavior.ts`). Opening a behavior shows Mantine `Tabs`:
+**Read** (the steps with the example's values filled in), **Watch** (what is expected next to the matched recording,
+its status and provenance) and **Inspect** (the existing check detail: runs, environments, attempts, files). A behavior
+with a playable recording opens on Watch, one in a run in progress on Inspect, otherwise on Read. The video is read only
+when Watch is on screen.
+
+- States stay distinct and none but `demonstrated` is a pass with proof: recording missing, recording of an older spec
+  revision, no recording, API only, failed, running, skipped, parked (tagged `@parked`, `@wip`, `@pending`) and not executed.
+  Counts are in the Coverage section above the source; an empty state is left out except `demonstrated`.
+- The promise's revision (the spec's fingerprint now) and the evidence's revision (the fingerprint the layer recorded)
+  are shown separately. A known difference demotes a recording to "Recording is older" with an alert; a missing
+  fingerprint is "not recorded", never a match.
+- A recording is always labelled illustrative: it shows one run and does not approve a behavior for production.
+  `demo`/`representative` tags only add a "Representative demo" label.
+- The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
+  none are listed under "No domain declared"; the Tests view reports domain problems).
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -127,7 +147,7 @@ The narrowly scoped exceptions are:
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
 | Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
 | Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
-| Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
+| Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |

package/llms-full.txt

@@ -3899,6 +3899,26 @@ and component defaults still live only in `ui/theme.tsx`. Quint/Alloy grammar so
 [`ui/grammars/README.md`](../packages/visualizer/src/ui/grammars/README.md). Unknown formats remain plain
 text, and parse failures must leave the source visible. Syntax highlighting never means a spec passed.
 
+## Behaviors: Read, Watch, Inspect
+
+A Gherkin page reads as behaviors: each scenario, or each example row of an outline (never the outline template as an
+extra), is one behavior in one coverage state (`evidence/behavior.ts`). Opening a behavior shows Mantine `Tabs`:
+**Read** (the steps with the example's values filled in), **Watch** (what is expected next to the matched recording,
+its status and provenance) and **Inspect** (the existing check detail: runs, environments, attempts, files). A behavior
+with a playable recording opens on Watch, one in a run in progress on Inspect, otherwise on Read. The video is read only
+when Watch is on screen.
+
+- States stay distinct and none but `demonstrated` is a pass with proof: recording missing, recording of an older spec
+  revision, no recording, API only, failed, running, skipped, parked (tagged `@parked`, `@wip`, `@pending`) and not executed.
+  Counts are in the Coverage section above the source; an empty state is left out except `demonstrated`.
+- The promise's revision (the spec's fingerprint now) and the evidence's revision (the fingerprint the layer recorded)
+  are shown separately. A known difference demotes a recording to "Recording is older" with an alert; a missing
+  fingerprint is "not recorded", never a match.
+- A recording is always labelled illustrative: it shows one run and does not approve a behavior for production.
+  `demo`/`representative` tags only add a "Representative demo" label.
+- The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
+  none are listed under "No domain declared"; the Tests view reports domain problems).
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -3959,7 +3979,7 @@ The narrowly scoped exceptions are:
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
 | Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
 | Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
-| Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
+| Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/visualizer/src/evidence/artifacts.tsx

@@ -146,6 +146,13 @@ function sizeOf(bytes: number | undefined) {
   if (bytes < 1024) return `${bytes} B`;
   return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(0)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
 }
+/** Where an attachment's bytes are, if a browser can reach them: its stored file in the layer, else its safe `http(s)` address. */
+export function attachmentSource(attachment: Attachment, layer: string): { path: string | null; url: string | null } {
+  const path = attachment.bundleKey
+    ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}`
+    : null;
+  return { path, url: path ? reportAssetUrl(path) : safeUri(attachment.uri) };
+}
 /**
  * One attachment as a card: it plays or shows itself when it can, and always says what it is (name, role, type, size,
  * duration, tags) and how to get it. A file that has no address, has an address that is not a web address, or that
@@ -154,10 +161,7 @@ function sizeOf(bytes: number | undefined) {
  */
 export function ArtifactCard({ attachment, layer, link, note, selected }: { attachment: Attachment; layer: string; link?: ReactNode; note?: ReactNode; selected?: boolean }) {
   const type = mediaType(attachment);
-  const path = attachment.bundleKey
-    ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}`
-    : null;
-  const url = path ? reportAssetUrl(path) : safeUri(attachment.uri);
+  const { path, url } = attachmentSource(attachment, layer);
   const renderer = artifactRenderers.find((candidate) => candidate.matches(attachment, type));
   const body = renderer?.render(attachment, { url, path, type });
   const item = useRef<HTMLLIElement>(null);
@@ -421,20 +425,25 @@ function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: str
     </ScopeProvider>
   );
 }
-/** Everything one result carries beyond its outcome, read when it is opened, and what the run around it carried. */
-export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerRow }) {
+/** The full evidence of one result, read only when `enabled` and the result has some to read (an archived layer). Shared by every view of the result, so it is read once. */
+export function useCheckDetail(layer: LayerHeader, row: LayerRow, enabled = true) {
   const wanted = row.evidence !== undefined || layer.evidence !== undefined;
-  const detail = useQuery({
+  return useQuery({
     queryKey: ['evidence-detail', layer.backend, layer.id, row.kind, row.id],
     queryFn: ({ signal }) =>
       reportJson<CheckDetail>(
         `/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}?check=${encodeURIComponent(row.id)}&kind=${encodeURIComponent(row.kind)}`,
         signal
       ),
-    enabled: wanted && /^[0-9a-f]{64}$/.test(layer.id),
+    enabled: enabled && wanted && /^[0-9a-f]{64}$/.test(layer.id),
     staleTime: Number.POSITIVE_INFINITY,
     retry: false
   });
+}
+/** Everything one result carries beyond its outcome, read when it is opened, and what the run around it carried. */
+export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerRow }) {
+  const wanted = row.evidence !== undefined || layer.evidence !== undefined;
+  const detail = useCheckDetail(layer, row);
   if (!wanted) return null;
   if (detail.isLoading)
     return (

package/packages/visualizer/src/evidence/behavior-panel.tsx

@@ -0,0 +1,291 @@
+/**
+ * @module Behavior panel
+ *
+ * How a product reader meets one behavior of a feature: Read (the promise and what is expected, with an outline's
+ * concrete example filled in), Watch (the matched recording beside what it should show) and Inspect (the technical
+ * record: run, environment, source, attempts). Also the coverage summary of the whole feature. A recording is always
+ * labelled as illustrative evidence with its own status, provenance and revision; it never stands for approval.
+ */
+import type { EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
+import { isVideoAttachment } from '@crvouga/atlas/reports/evidence-detail';
+import { effectiveScope } from '@crvouga/atlas/reports/evidence-scope';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import type { Attachment } from '@crvouga/atlas/schema';
+import { Alert, Badge, Box, Group, List, Paper, Stack, Tabs, Text, Title } from '@mantine/core';
+import { useMemo, type ReactNode } from 'react';
+
+import { attachmentSource, useCheckDetail } from './artifacts';
+import { COVERAGE, COVERAGE_ORDER, type Behavior, type CoverageCounts, type CoverageState, type Revision } from './behavior';
+import { PlainSteps } from './check-detail';
+import { useEvidence } from './evidence-context';
+import { ScopeNotice } from './evidence-scope';
+import { plural, statusWord, useNow } from './format';
+import { exampleIndexFor, exampleRows, fillExample, type FeatureStep } from './gherkin';
+import { Origin, StatusMark } from './marks';
+
+/** The short, readable form of a spec fingerprint (`<length>:<hash>:<hash>`): its length and the start of its hash. */
+export function shortRevision(fingerprint: string): string {
+  const [length, hash] = fingerprint.split(':');
+  return hash ? `${hash.slice(0, 8)} (${length} characters)` : fingerprint.slice(0, 12);
+}
+
+/** A behavior's coverage state, always in words. */
+export function CoverageBadge({ state }: { state: CoverageState }) {
+  return (
+    <Badge data-coverage={state} color={COVERAGE[state].color} variant="light" title={COVERAGE[state].meaning}>
+      {COVERAGE[state].label}
+    </Badge>
+  );
+}
+
+/**
+ * The promise and the evidence side by side, each with its own revision. A mismatch is stated, not hidden; a missing
+ * fingerprint is stated as unknown rather than treated as a match.
+ */
+export function RevisionLine({ revision }: { revision: Revision }) {
+  return (
+    <Stack gap="xs" data-revision={revision.match}>
+      <Group gap="md" wrap="wrap" c="dimmed">
+        <Text span inherit>
+          Promise revision:{' '}
+          <Text span inherit fw={600}>
+            {revision.promise ? shortRevision(revision.promise) : 'not recorded'}
+          </Text>
+        </Text>
+        <Text span inherit>
+          Evidence revision:{' '}
+          <Text span inherit fw={600}>
+            {revision.evidence ? shortRevision(revision.evidence) : 'not recorded'}
+          </Text>
+        </Text>
+      </Group>
+      {revision.match === 'different' && (
+        <Alert color="orange" role="status">
+          This evidence was recorded against an earlier revision of the spec. It does not show that the current promise holds.
+        </Alert>
+      )}
+      {revision.match === 'unknown' && (
+        <Text component="div" c="dimmed">
+          The revisions cannot be compared, so this evidence is not tied to the current promise.
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/** The `Then` steps (and the `And`/`But` after them): what should be true when the behavior has run. */
+function expectedSteps(steps: readonly FeatureStep[]): FeatureStep[] {
+  const at = steps.findIndex((step) => step.keyword === 'Then');
+  return at < 0 ? [] : steps.slice(at);
+}
+
+function videosIn(holder: EvidenceHolder | undefined): Attachment[] {
+  if (!holder) return [];
+  const own = (holder.attachments ?? []).filter(isVideoAttachment);
+  return [
+    ...own,
+    ...(holder.steps ?? []).flatMap((step) => (step.attachments ?? []).filter(isVideoAttachment)),
+    ...(holder.attempts ?? []).flatMap((attempt) => [
+      ...(attempt.attachments ?? []).filter(isVideoAttachment),
+      ...(attempt.steps ?? []).flatMap((step) => (step.attachments ?? []).filter(isVideoAttachment))
+    ])
+  ];
+}
+
+/** The recording of one result, read only when this is on screen. */
+function Player({ result }: { result: EvidenceResult }) {
+  const detail = useCheckDetail(result.layer, result.row);
+  const videos = useMemo(() => videosIn(detail.data?.check), [detail.data]);
+  const sources = videos.flatMap((attachment) => {
+    const { url } = attachmentSource(attachment, result.layer.id);
+    return url ? [{ attachment, url }] : [];
+  });
+  if (detail.isLoading) {
+    return (
+      <Text role="status" component="div" c="dimmed">
+        Loading the recording…
+      </Text>
+    );
+  }
+  if (detail.isError) {
+    return (
+      <Alert role="alert" color="red">
+        The recording could not be read.
+      </Alert>
+    );
+  }
+  if (!sources.length) {
+    return (
+      <Text component="div" c="dimmed">
+        This result names a recording, but no file can be played from here.
+      </Text>
+    );
+  }
+  return (
+    <Stack gap="sm">
+      {sources.slice(0, 1).map(({ attachment, url }) => (
+        <Stack key={url} gap="xs">
+          {/* What the recording does and does not show, as its producer declared it; undeclared says unknown. */}
+          <ScopeNotice
+            scope={effectiveScope(attachment.scope, detail.data?.check.scope, detail.data?.inheritedScope)}
+            name={attachment.name}
+          />
+          <Box
+            component="video"
+            src={url}
+            controls
+            preload="metadata"
+            aria-label={`Recording: ${attachment.description ?? attachment.name}`}
+            maw="100%"
+            w="100%"
+            mah="70vh"
+          />
+        </Stack>
+      ))}
+      {sources.length > 1 && (
+        <Text component="div" c="dimmed">
+          {plural(sources.length - 1, 'more recording', 'more recordings')} in Inspect.
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/** Read, Watch and Inspect for one behavior. `inspect` is the technical record, shown only under Inspect. */
+export function BehaviorPanel({
+  behavior,
+  inspect,
+  start
+}: {
+  behavior: Behavior;
+  inspect: ReactNode;
+  /** The tab to open on; by default Watch when there is something to watch, Inspect while a run is in progress (its progress lives there), else Read. */ start?:
+    'read' | 'watch' | 'inspect';
+}) {
+  const { backends } = useEvidence();
+  const now = useNow();
+  const { scenario, example, demo, subject, revision, state } = behavior;
+  const at = example === null ? -1 : exampleIndexFor(scenario, example);
+  const entry = at < 0 ? null : exampleRows(scenario)[at]!;
+  const steps = useMemo(() => (entry ? fillExample(scenario.steps, entry) : scenario.steps), [scenario, entry]);
+  const expected = expectedSteps(steps);
+  const named = example !== null && entry === null;
+  return (
+    <Tabs
+      defaultValue={start ?? (demo ? 'watch' : state === 'running' || behavior.slot?.live ? 'inspect' : 'read')}
+      keepMounted={false}
+      aria-label={`${scenario.name}${example ? `: ${example}` : ''}`}
+    >
+      <Tabs.List mb="sm">
+        <Tabs.Tab value="read">Read</Tabs.Tab>
+        <Tabs.Tab value="watch">Watch</Tabs.Tab>
+        <Tabs.Tab value="inspect">Inspect</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="read">
+        <Stack gap="sm" miw={0}>
+          <Group gap="sm">
+            <CoverageBadge state={state} />
+            <Text component="span" c="dimmed">
+              {COVERAGE[state].meaning}
+            </Text>
+          </Group>
+          {example !== null && (
+            <Text component="div" c="dimmed">
+              Example: {example}
+            </Text>
+          )}
+          <PlainSteps steps={steps} examples={entry ? [] : scenario.examples} />
+          {named && (
+            <Text component="div" c="dimmed">
+              The recorded example name does not match one row of the examples, so the values are not filled in.
+            </Text>
+          )}
+        </Stack>
+      </Tabs.Panel>
+      <Tabs.Panel value="watch">
+        <Stack gap="sm" miw={0}>
+          <Group gap="sm">
+            <CoverageBadge state={state} />
+            {behavior.representative && <Badge variant="outline">Representative demo</Badge>}
+          </Group>
+          {expected.length > 0 && (
+            <Box component="section" aria-label="Expected outcome">
+              <Title order={4} mb="xs">
+                Expected
+              </Title>
+              <PlainSteps steps={expected} />
+            </Box>
+          )}
+          {demo ? (
+            <>
+              <Player result={demo} />
+              <Text component="div" c="dimmed">
+                Illustrative recording of one run. It shows what happened in that run and does not approve the behavior for production.
+              </Text>
+            </>
+          ) : (
+            <Text component="div" c="dimmed">
+              Nothing to watch. {COVERAGE[state].meaning}
+            </Text>
+          )}
+          {subject && (
+            <Group gap="xs" wrap="wrap" align="center">
+              <StatusMark status={subject.row.status} size={14} />
+              <Text span inherit fw={600}>
+                {statusWord(subject.row.status)}
+              </Text>
+              <Text span inherit c="dimmed">
+                in {environmentLabel(subject.layer.environment)}
+              </Text>
+              <Origin layer={subject.layer} backends={backends} now={now} />
+            </Group>
+          )}
+          <RevisionLine revision={revision} />
+        </Stack>
+      </Tabs.Panel>
+      <Tabs.Panel value="inspect">
+        <Stack gap="sm" miw={0}>
+          <RevisionLine revision={revision} />
+          {inspect}
+        </Stack>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+
+/**
+ * What the feature's behaviors add up to, one count per state. A state with none is left out except
+ * `demonstrated`, which is always named so its absence is not mistaken for a pass.
+ */
+export function CoverageSummary({ counts, total }: { counts: CoverageCounts; total: number }) {
+  if (total === 0) return null;
+  return (
+    <Paper component="section" aria-label="Coverage" withBorder p="md" my="md">
+      <Stack gap="xs">
+        <Title order={2}>Coverage</Title>
+        <Text component="div">
+          {counts.demonstrated} of {plural(total, 'behavior', 'behaviors')} demonstrated with a recording of the current spec.
+        </Text>
+        <List listStyleType="none" spacing="xs">
+          {COVERAGE_ORDER.filter((state) => state === 'demonstrated' || counts[state] > 0).map((state) => (
+            <List.Item key={state} data-coverage={state}>
+              <Group gap="sm" wrap="wrap">
+                <CoverageBadge state={state} />
+                <Text span inherit fw={600}>
+                  {counts[state]}
+                </Text>
+                <Text span inherit c="dimmed">
+                  {COVERAGE[state].meaning}
+                </Text>
+              </Group>
+            </List.Item>
+          ))}
+        </List>
+        <Text component="div" c="dimmed">
+          A recording shows one run. It is illustrative evidence and does not mean the behavior is live or ready for production.
+        </Text>
+      </Stack>
+    </Paper>
+  );
+}

package/packages/visualizer/src/evidence/behavior.test.ts

@@ -0,0 +1,99 @@
+import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+import { expect, test } from 'bun:test';
+
+import { behaviorOf, compareRevisions, coverageCounts, isRepresentative, scenarioBehaviors, type RevisionSource } from './behavior';
+import { exampleIndexFor, featureModel, fillExample, exampleRows } from './gherkin';
+
+const FEATURE = featureModel(`Feature: Lists
+  @demo
+  Scenario: Add
+    When adding tea
+
+  @parked
+  Scenario: Archive
+    When archiving
+
+  Scenario Outline: Several
+    When adding "<item>" for <who>
+    Examples:
+      | item | who |
+      | Tea  | Ann |
+      | Milk | Bo  |
+`)!;
+const [ADD, ARCHIVE, SEVERAL] = FEATURE.rules[0]!.scenarios;
+
+const header = (layer: string, environment: string | null = 'desktop-web'): LayerHeader => ({
+  id: layer, backend: 'b', producer: 'p', packageDir: null, recordedAtMs: 1, sha: null, branch: null, environment, runUrl: null, parameters: {},
+  recording: null, live: false, counts: { passed: 0, failed: 0, running: 0, 'not-run': 0 }, execution: layer
+});
+function result(layer: string, row: Partial<LayerRow>, environment: string | null = 'desktop-web'): EvidenceResult {
+  return {
+    key: layer, slot: 's', layer: header(layer, environment), parameters: {}, warning: null,
+    row: { kind: 'behavior', id: 'x', title: 'Lists: Add', status: 'passed', specPath: 'specs/a.feature', detail: '', measurements: [], testId: null, variant: {}, durationMs: null, ...row }
+  };
+}
+const slot = (status: CheckSlot['status'], outcomes: EvidenceResult[], title = 'Lists: Add'): CheckSlot => ({
+  key: title, id: title, title, specPath: 'specs/a.feature', status, outcomes, diagnostics: [], latestAtMs: 1, live: false
+});
+const VIDEO = { attachments: 1, steps: 0, annotations: 0, attempts: 0, links: 0, tags: [], labels: {}, roles: ['video'], videos: [{ name: 'a.webm', owner: 'check' as const, recording: 'sha256:1', available: true }] };
+const revisions = (current: string | null, recorded: Record<string, string> = {}): RevisionSource => ({ current, recorded: (id) => recorded[id] });
+const stateOf = (s: CheckSlot | null, rev = revisions('f1', { l1: 'f1', l2: 'f0' }), scenario = ADD!) => behaviorOf(scenario, s, null, rev, 'k').state;
+
+test('revisions compare only when both are known', () => {
+  expect(compareRevisions('a', 'a').match).toBe('same');
+  expect(compareRevisions('a', 'b').match).toBe('different');
+  expect(compareRevisions('a', undefined).match).toBe('unknown');
+  expect(compareRevisions(null, 'a').match).toBe('unknown');
+});
+
+test('only a passing result with a playable recording of the current promise is demonstrated', () => {
+  expect(stateOf(slot('passed', [result('l1', { evidence: VIDEO })]))).toBe('demonstrated');
+  // The same recording of an older revision is not proof of the new promise.
+  expect(stateOf(slot('passed', [result('l2', { evidence: VIDEO })]))).toBe('outdated-recording');
+  // An unplayable reference is a gap, and a pass with nothing to watch says so.
+  expect(stateOf(slot('passed', [result('l1', { evidence: { ...VIDEO, videos: [{ ...VIDEO.videos[0]!, available: false }] } })]))).toBe('recording-missing');
+  expect(stateOf(slot('passed', [result('l1', { recording: { state: 'skipped', reason: 'too-large' } })]))).toBe('recording-missing');
+  expect(stateOf(slot('passed', [result('l1', {})]))).toBe('no-recording');
+  expect(stateOf(slot('passed', [result('l1', {}, 'api')]))).toBe('api-only');
+  // A video on the API does not turn it into API-only evidence: it can be watched.
+  expect(stateOf(slot('passed', [result('l1', { evidence: VIDEO }, 'api')]))).toBe('demonstrated');
+});
+
+test('failed, running, skipped, parked and unexecuted stay distinct and never read as passes', () => {
+  expect(stateOf(slot('failed', [result('l1', { status: 'failed', evidence: VIDEO })]))).toBe('failed');
+  expect(stateOf(slot('running', [result('l1', { status: 'running' })]))).toBe('running');
+  expect(stateOf(slot('not-run', [result('l1', { status: 'not-run' })]))).toBe('skipped');
+  expect(stateOf(null, undefined, ARCHIVE)).toBe('parked');
+  expect(stateOf(null)).toBe('unexecuted');
+  // One environment passing with a clip does not hide another that failed.
+  expect(stateOf(slot('failed', [result('l1', { evidence: VIDEO }), result('l3', { status: 'failed' })]))).toBe('failed');
+});
+
+test('a demo tag marks the scenario as the representative one', () => {
+  expect(isRepresentative(['#Demo'])).toBe(true);
+  expect(isRepresentative(['smoke'])).toBe(false);
+  expect(behaviorOf(ADD!, null, null, revisions(null), 'k').representative).toBe(true);
+  expect(behaviorOf(ARCHIVE!, null, null, revisions(null), 'k').representative).toBe(false);
+});
+
+test('an outline is one behavior per example, never the template as well', () => {
+  const tea = slot('passed', [result('l1', {})], 'Lists: Several — Tea');
+  const behaviors = scenarioBehaviors(SEVERAL!, [tea], 'Lists', revisions('f1'));
+  expect(behaviors.map((behavior) => [behavior.example, behavior.state])).toEqual([
+    ['Tea', 'no-recording'],
+    ['Milk, Bo', 'unexecuted']
+  ]);
+  expect(coverageCounts(behaviors).unexecuted).toBe(1);
+  // With nothing recorded there are still only the two examples.
+  expect(scenarioBehaviors(SEVERAL!, [], 'Lists', revisions(null))).toHaveLength(2);
+});
+
+test('a recorded example is matched to its row by cells or column pairs, and its values are filled in', () => {
+  expect(exampleIndexFor(SEVERAL!, 'Milk')).toBe(1);
+  expect(exampleIndexFor(SEVERAL!, 'item=Tea, who=Ann')).toBe(0);
+  expect(exampleIndexFor(SEVERAL!, 'Unrelated wording')).toBe(-1);
+  const filled = fillExample(SEVERAL!.steps, exampleRows(SEVERAL!)[1]!);
+  expect(filled[0]!.text).toBe('adding "Milk" for Bo');
+});

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

@@ -0,0 +1,268 @@
+/**
+ * @module Behavior coverage
+ *
+ * Reads a feature the way a product reader does: each scenario (or each concrete example of an outline) is one
+ * behavior, and each behavior is in exactly one coverage state. The states keep apart what a green count would blur:
+ * a passing test with a playable recording of the current promise is `demonstrated`; a passing test with no
+ * recording, with a recording of an older revision of the spec, or only in API environments is not. Nothing here
+ * decides an outcome: statuses and winners come from the combined report, and a state is a reading of them.
+ * A missing fingerprint, recording or result is unknown or missing, never a pass.
+ */
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+
+import { exampleIndexFor, exampleRows, scenarioLabel, type FeatureScenario } from './gherkin';
+
+/** Where a behavior stands, from the most reassuring to the least. */
+export type CoverageState =
+  | 'demonstrated'
+  | 'outdated-recording'
+  | 'recording-missing'
+  | 'no-recording'
+  | 'api-only'
+  | 'failed'
+  | 'running'
+  | 'skipped'
+  | 'parked'
+  | 'unexecuted';
+
+/** What each state is called and why, in the order a summary lists them. */
+export const COVERAGE: Readonly<Record<CoverageState, { readonly label: string; readonly meaning: string; readonly color: string }>> = {
+  demonstrated: {
+    label: 'Demonstrated',
+    meaning: 'A passing result with a recording of the current promise.',
+    color: 'green'
+  },
+  'outdated-recording': {
+    label: 'Recording is older',
+    meaning: 'A passing result, but the recording is of an earlier revision of the spec.',
+    color: 'orange'
+  },
+  'recording-missing': {
+    label: 'Recording missing',
+    meaning: 'A passing result whose expected recording was not published or cannot be played.',
+    color: 'orange'
+  },
+  'no-recording': {
+    label: 'No recording',
+    meaning: 'A passing result with nothing to watch.',
+    color: 'gray'
+  },
+  'api-only': {
+    label: 'API only',
+    meaning: 'A passing result recorded only through the API, so there is no screen to watch.',
+    color: 'gray'
+  },
+  failed: {
+    label: 'Failed',
+    meaning: 'The latest result failed.',
+    color: 'red'
+  },
+  running: {
+    label: 'Running',
+    meaning: 'A run is checking it now.',
+    color: 'blue'
+  },
+  skipped: {
+    label: 'Skipped',
+    meaning: 'It was reported as skipped or not run.',
+    color: 'gray'
+  },
+  parked: {
+    label: 'Parked',
+    meaning: 'The scenario is tagged as parked or work in progress, and has no result.',
+    color: 'gray'
+  },
+  unexecuted: {
+    label: 'Not executed',
+    meaning: 'No test reported a result for it.',
+    color: 'gray'
+  }
+};
+
+/** The order a coverage summary lists states in. */
+export const COVERAGE_ORDER = Object.keys(COVERAGE) as CoverageState[];
+
+/** How the spec the evidence was recorded against compares with the spec now. */
+export type Revision = {
+  /** Fingerprint of the spec now (the promise). Null when the outline has none. */
+  readonly promise: string | null;
+  /** Fingerprint of the spec when the evidence was recorded. Null when the layer did not record one. */
+  readonly evidence: string | null;
+  /** `same`, `different`, or `unknown` when either side is missing. */
+  readonly match: 'same' | 'different' | 'unknown';
+};
+
+/** Compares two fingerprints: unknown unless both are there. */
+export function compareRevisions(promise: string | null | undefined, evidence: string | null | undefined): Revision {
+  const now = promise || null;
+  const then = evidence || null;
+  return {
+    promise: now,
+    evidence: then,
+    match: now === null || then === null ? 'unknown' : now === then ? 'same' : 'different'
+  };
+}
+
+/** The tags that mark a scenario as deliberately not running, and the state each gives it. */
+const TAG_STATE: Readonly<Record<string, CoverageState>> = {
+  parked: 'parked',
+  wip: 'parked',
+  pending: 'parked',
+  skip: 'skipped',
+  skipped: 'skipped',
+  ignore: 'skipped'
+};
+
+/** The tags that say a recording was picked to stand for a behavior. */
+const REPRESENTATIVE = new Set(['demo', 'representative']);
+
+/** Whether a recorded result or its scenario is tagged as the representative demo. */
+export function isRepresentative(tags: readonly string[]): boolean {
+  return tags.some((tag) => REPRESENTATIVE.has(tag.replace(/^[#@]/, '').toLowerCase()));
+}
+
+/** A result's playable video references: those that name bytes. */
+function playable(result: EvidenceResult): number {
+  return result.row.evidence?.videos?.filter((video) => video.available).length ?? 0;
+}
+
+/** Environments a reader cannot watch: a result recorded only through these has no screen. */
+function isApi(environment: string | null): boolean {
+  return environment !== null && /^(api|http|rest|graphql|service|backend)(-|$)/.test(environment);
+}
+
+/** What is known about one behavior. */
+export type Behavior = {
+  /** Stable within the page: the scenario and its example. */
+  readonly key: string;
+  readonly scenario: FeatureScenario;
+  /** The example label of an outline's row (what the producer named it), or null for a plain scenario. */
+  readonly example: string | null;
+  /** The recorded check, or null when nothing reported on it. */
+  readonly slot: CheckSlot | null;
+  readonly state: CoverageState;
+  /** The result to watch: the newest of those with a playable recording, preferring one of the current revision. */
+  readonly demo: EvidenceResult | null;
+  /** The result the revision line and provenance describe: the demo, else the newest. */
+  readonly subject: EvidenceResult | null;
+  readonly revision: Revision;
+  /** Whether the scenario or the recorded result is tagged as the representative demo. */
+  readonly representative: boolean;
+};
+
+/** What the page knows about the spec as it is now and as each layer recorded it. */
+export type RevisionSource = {
+  /** The spec's fingerprint now. */
+  readonly current: string | null;
+  /** The fingerprint a layer recorded for this spec, if it did. */
+  readonly recorded: (layerId: string) => string | undefined;
+};
+
+/**
+ * The state of one behavior from its recorded check (or none). A failing, running or skipped result is that, whatever
+ * recordings exist. A pass is `demonstrated` only with a playable recording that is not known to be of another
+ * revision; a recording whose revision cannot be compared is still shown, with the revision stated as unknown.
+ */
+export function behaviorOf(
+  scenario: FeatureScenario,
+  slot: CheckSlot | null,
+  example: string | null,
+  revisions: RevisionSource,
+  key: string
+): Behavior {
+  const outcomes = slot?.outcomes ?? [];
+  const revisionOf = (result: EvidenceResult | null) =>
+    compareRevisions(revisions.current, result ? revisions.recorded(result.layer.id) : undefined);
+  const withVideo = outcomes.filter((result) => result.row.status === 'passed' && playable(result) > 0);
+  const demo = withVideo.find((result) => revisionOf(result).match !== 'different') ?? withVideo[0] ?? null;
+  const subject = demo ?? outcomes[0] ?? null;
+  const revision = revisionOf(subject);
+  const representative =
+    isRepresentative(scenario.tags) ||
+    outcomes.some((result) => isRepresentative([...(result.row.evidence?.tags ?? []), ...(result.row.evidence?.artifactTags ?? [])]));
+  const base = {
+    key,
+    scenario,
+    example,
+    slot,
+    demo,
+    subject,
+    revision,
+    representative
+  };
+  if (!slot || outcomes.length === 0) {
+    const tagged = scenario.tags.map((tag) => TAG_STATE[tag.toLowerCase()]).find((state) => state !== undefined);
+    return { ...base, state: tagged ?? 'unexecuted' };
+  }
+  if (slot.status === 'failed') return { ...base, state: 'failed' };
+  if (slot.status === 'running') return { ...base, state: 'running' };
+  if (slot.status === 'not-run') return { ...base, state: 'skipped' };
+  if (demo)
+    return {
+      ...base,
+      state: revision.match === 'different' ? 'outdated-recording' : 'demonstrated'
+    };
+  const passed = outcomes.filter((result) => result.row.status === 'passed');
+  // A recording was promised and is not here, or is referenced without bytes: that is a gap, not an API test.
+  if (
+    passed.some((result) => result.row.recording && !['uploaded', 'referenced', 'not-applicable'].includes(result.row.recording.state)) ||
+    passed.some((result) => (result.row.evidence?.videos?.length ?? 0) > 0)
+  ) {
+    return { ...base, state: 'recording-missing' };
+  }
+  if (passed.length > 0 && passed.every((result) => isApi(result.layer.environment))) return { ...base, state: 'api-only' };
+  return { ...base, state: 'no-recording' };
+}
+
+/**
+ * Every behavior of a scenario. A plain scenario is one. An outline is one per example row, never the template as an
+ * extra: a recorded example is filed under the row it names; a row nothing reported on is `unexecuted` (or parked);
+ * a recorded example whose label names no row is kept as its own behavior and the unclaimed rows are counted against
+ * the recorded results that remain, so the total never exceeds the rows by inventing a template.
+ */
+export function scenarioBehaviors(
+  scenario: FeatureScenario,
+  slots: readonly CheckSlot[],
+  feature: string,
+  revisions: RevisionSource
+): Behavior[] {
+  const rows = exampleRows(scenario);
+  if (rows.length === 0) {
+    // A scenario with no examples fills one slot per environment/parameter set, which the slot already groups.
+    const slot = slots[0] ?? null;
+    if (slots.length <= 1) return [behaviorOf(scenario, slot, null, revisions, scenario.name)];
+    return slots.map((each) => behaviorOf(scenario, each, null, revisions, each.key));
+  }
+  const claimed = new Map<number, CheckSlot[]>();
+  const loose: CheckSlot[] = [];
+  for (const slot of slots) {
+    const label = scenarioLabel(feature, slot.title).slice(scenario.name.length + 3);
+    const at = exampleIndexFor(scenario, label);
+    if (at < 0) loose.push(slot);
+    else claimed.set(at, [...(claimed.get(at) ?? []), slot]);
+  }
+  const behaviors: Behavior[] = [];
+  const unmatched = rows.map((_, at) => at).filter((at) => !claimed.has(at));
+  // Results whose wording matches no row stand in for the rows nothing claimed, in order, before any row is called unexecuted.
+  const spare = [...loose];
+  rows.forEach((entry, at) => {
+    const found = claimed.get(at) ?? (unmatched.includes(at) && spare.length ? [spare.shift()!] : []);
+    const label = found[0] ? scenarioLabel(feature, found[0].title).slice(scenario.name.length + 3) : entry.row.join(', ');
+    if (found.length === 0) behaviors.push(behaviorOf(scenario, null, label, revisions, `${scenario.name}:${at}`));
+    for (const slot of found) behaviors.push(behaviorOf(scenario, slot, label, revisions, slot.key));
+  });
+  for (const slot of spare)
+    behaviors.push(behaviorOf(scenario, slot, scenarioLabel(feature, slot.title).slice(scenario.name.length + 3), revisions, slot.key));
+  return behaviors;
+}
+
+/** Behaviors counted by state. Every state is present, so an absent one reads as zero, not as unknown. */
+export type CoverageCounts = Readonly<Record<CoverageState, number>>;
+
+/** Counts behaviors by coverage state; only `demonstrated` is a demonstrated pass. */
+export function coverageCounts(behaviors: readonly Behavior[]): CoverageCounts {
+  const counts = Object.fromEntries(COVERAGE_ORDER.map((state) => [state, 0])) as Record<CoverageState, number>;
+  for (const behavior of behaviors) counts[behavior.state] += 1;
+  return counts;
+}

package/packages/visualizer/src/evidence/check-detail.tsx

@@ -61,12 +61,15 @@ export function ResultRow({
   slot,
   open,
   onToggle,
+  badge,
   children
 }: {
   label: string;
   slot: CheckSlot | null;
   open: boolean;
   onToggle: () => void;
+  /** A short extra mark after the label, such as a coverage state. */
+  badge?: ReactNode;
   children: ReactNode;
 }) {
   const now = useNow();
@@ -96,6 +99,7 @@ export function ResultRow({
                   </Flex>
                 )}
               </Text>
+              {badge}
               {slot?.live && (
                 <Text span inherit>
                   Running now

package/packages/visualizer/src/evidence/feature-page.tsx

@@ -1,8 +1,11 @@
 import type { CheckSlot, SpecEvidence } from '@crvouga/atlas/reports/evidence-view';
 import { Alert, Box, Container, List, Stack, Text, Title } from '@mantine/core';
 import { useMemo } from 'react';
-import type { SpecKind } from '../spec-kind';
+import { outlinePath, type SpecKind } from '../spec-kind';
 import { CheckDetail, PlainSteps, ResultRow, type CheckSelection, type SelectCheck } from './check-detail';
+import { behaviorOf, coverageCounts, scenarioBehaviors, type Behavior, type RevisionSource } from './behavior';
+import { BehaviorPanel, CoverageBadge, CoverageSummary } from './behavior-panel';
+import { useEvidence } from './evidence-context';
 import { featureModel, scenarioLabel, slotsByScenario, type FeatureModel, type FeatureScenario } from './gherkin';
 import { Bounded } from './marks';
 import { SpecHeader } from './spec-header';
@@ -23,7 +26,10 @@ function parse(text: string): {
   try {
     return { feature: featureModel(text), error: null };
   } catch (error) {
-    return { feature: null, error: error instanceof Error ? error.message : String(error) };
+    return {
+      feature: null,
+      error: error instanceof Error ? error.message : String(error)
+    };
   }
 }
 /** A feature read as its rules and scenarios, each scenario with what was recorded when it ran. */
@@ -35,43 +41,81 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
     () => (feature ? slotsByScenario(feature, slots) : { byScenario: new Map<string, CheckSlot[]>(), leftOver: slots }),
     [feature, slots]
   );
-  const scenarios = feature?.rules.flatMap((rule) => rule.scenarios.filter((scenario) => !scenario.background)) ?? [];
-  const planned =
-    scenarios.reduce((count, scenario) => count + Math.max(1, filed.byScenario.get(scenario.name)?.length ?? 0), 0) + filed.leftOver.length;
+  const { specs, evidence } = useEvidence();
+  const specPath = outlinePath(file);
+  const revisions = useMemo<RevisionSource>(() => {
+    const recorded = new Map(evidence.map((layer) => [layer.layer.id, layer.fingerprints[specPath]]));
+    return {
+      current: specs.find((spec) => spec.path === specPath)?.fingerprint ?? null,
+      recorded: (id) => recorded.get(id)
+    };
+  }, [specs, evidence, specPath]);
+  const behaviors = useMemo(() => {
+    const byScenario = new Map<FeatureScenario, Behavior[]>();
+    for (const scenario of feature?.rules.flatMap((rule) => rule.scenarios.filter((each) => !each.background)) ?? []) {
+      byScenario.set(scenario, scenarioBehaviors(scenario, filed.byScenario.get(scenario.name) ?? [], feature!.name, revisions));
+    }
+    // A result no scenario claims is still a behavior that was checked, so it is counted.
+    const stray: FeatureScenario = {
+      keyword: 'Scenario',
+      name: '',
+      description: '',
+      background: false,
+      tags: [],
+      steps: [],
+      examples: []
+    };
+    const other = filed.leftOver.map((slot) => behaviorOf({ ...stray, name: slot.title }, slot, null, revisions, slot.key));
+    return { byScenario, all: [...[...byScenario.values()].flat(), ...other] };
+  }, [feature, filed, revisions]);
+  const counts = useMemo(() => coverageCounts(behaviors.all), [behaviors]);
+  const planned = behaviors.all.length;
   const toggle = (id: string) => select({ check: selection.check === id ? null : id, layer: null });
-  const rows = (scenario: FeatureScenario) => {
-    const written = <PlainSteps steps={scenario.steps} examples={scenario.examples} />;
-    const recorded = (filed.byScenario.get(scenario.name) ?? []).filter((slot) => !runningOnly || slot.status === 'running');
-    if (!recorded.length) {
-      if (runningOnly) return null;
-      const id = `scenario:${scenario.name}`;
+  const rows = (scenario: FeatureScenario) =>
+    (behaviors.byScenario.get(scenario) ?? []).map((behavior) => {
+      if (runningOnly && behavior.slot?.status !== 'running') return null;
+      const { slot } = behavior;
+      const written = <PlainSteps steps={scenario.steps} examples={scenario.examples} />;
+      const id = slot ? slot.id : `scenario:${scenario.name}${behavior.example ? `:${behavior.example}` : ''}`;
+      const label = slot
+        ? scenarioLabel(feature!.name, slot.title)
+        : behavior.example
+          ? `${scenario.name} — ${behavior.example}`
+          : scenario.name;
       return (
-        <ResultRow key={id} label={scenario.name} slot={null} open={selection.check === id} onToggle={() => toggle(id)}>
-          <Text component="div" c="dimmed">
-            No completed test report for this scenario yet.
-          </Text>
-          {written}
+        <ResultRow
+          key={id}
+          label={label}
+          slot={slot}
+          badge={<CoverageBadge state={behavior.state} />}
+          open={selection.check === id}
+          onToggle={() => toggle(id)}
+        >
+          <BehaviorPanel
+            behavior={behavior}
+            start={selection.check === id && selection.layer ? 'inspect' : undefined}
+            inspect={
+              slot ? (
+                <CheckDetail
+                  slot={slot}
+                  layerId={selection.check === id ? selection.layer : undefined}
+                  select={(patch) => select({ check: id, ...patch })}
+                  reads="steps"
+                  written={written}
+                />
+              ) : (
+                <>
+                  <Text component="div" c="dimmed">
+                    No completed test report for this scenario yet.
+                  </Text>
+                  {written}
+                </>
+              )
+            }
+          />
         </ResultRow>
       );
-    }
-    return recorded.map((slot) => (
-      <ResultRow
-        key={slot.key}
-        label={scenarioLabel(feature!.name, slot.title)}
-        slot={slot}
-        open={selection.check === slot.id}
-        onToggle={() => toggle(slot.id)}
-      >
-        <CheckDetail
-          slot={slot}
-          layerId={selection.check === slot.id ? selection.layer : undefined}
-          select={(patch) => select({ check: slot.id, ...patch })}
-          reads="steps"
-          written={written}
-        />
-      </ResultRow>
-    ));
-  };
+    });
   return (
     <Container component="article" size="xl" w="100%" py="xl">
       <SpecHeader
@@ -87,6 +131,7 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
           </Text>
         )}
       </SpecHeader>
+      <CoverageSummary counts={counts} total={behaviors.all.length} />
       <SourceText text={text} file={file} withResults />
       <Box component="section" id="spec-results" aria-label="Recorded results" tabIndex={-1}>
         <TestFilter slots={slots} />
@@ -112,7 +157,8 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
               .map((scenario, at) => (
                 <Stack key={at} gap="sm" miw={0}>
                   <Text component="div" c="dimmed">
-                    Before each scenario{scenario.name ? `: ${scenario.name}` : ''}
+                    Before each scenario
+                    {scenario.name ? `: ${scenario.name}` : ''}
                   </Text>
                   <PlainSteps steps={scenario.steps} />
                 </Stack>

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

@@ -13,6 +13,8 @@ export type FeatureScenario = {
   readonly name: string;
   readonly description: string;
   readonly background: boolean;
+  /** The scenario's own tags, without the `@` (a parked or skipped scenario says so here). */
+  readonly tags: readonly string[];
   readonly steps: readonly FeatureStep[];
   readonly examples: readonly FeatureExamples[];
 };
@@ -50,13 +52,14 @@ export function featureModel(text: string): FeatureModel | null {
     for (const entry of child.rule ? child.rule.children : [child]) {
       const background = entry.background;
       const scenario = entry.scenario;
-      if (background) group.scenarios.push({ keyword: background.keyword, name: background.name, description: prose(background.description), background: true, steps: steps(background.steps), examples: [] });
+      if (background) group.scenarios.push({ keyword: background.keyword, name: background.name, description: prose(background.description), background: true, tags: [], steps: steps(background.steps), examples: [] });
       if (scenario) {
         group.scenarios.push({
           keyword: scenario.keyword,
           name: scenario.name,
           description: prose(scenario.description),
           background: false,
+          tags: [...new Set([...feature.tags, ...(child.rule?.tags ?? []), ...scenario.tags].map((tag) => tag.name.replace(/^@/, '')))],
           steps: steps(scenario.steps),
           examples: scenario.examples.map((example) => ({ name: example.name, header: cells(example.tableHeader), rows: example.tableBody.map(cells) }))
         });
@@ -96,3 +99,30 @@ export function slotsByScenario(feature: FeatureModel, slots: readonly CheckSlot
   }
   return { byScenario, leftOver };
 }
+
+/** The rows of an outline's examples, each with the names of its columns. */
+export function exampleRows(scenario: Pick<FeatureScenario, 'examples'>): { readonly header: readonly string[]; readonly row: readonly string[] }[] {
+  return scenario.examples.flatMap((example) => example.rows.map((row) => ({ header: example.header, row })));
+}
+
+/** Whether a recorded example label (what follows `Scenario — `) names one row: by its cells, joined, or by `column=value` pairs. */
+function namesRow(label: string, entry: { readonly header: readonly string[]; readonly row: readonly string[] }) {
+  const joined = [entry.row.join(', '), entry.row.join(' '), entry.row.join(' | '), entry.header.map((name, at) => `${name}=${entry.row[at] ?? ''}`).join(', ')];
+  return joined.includes(label) || entry.row.includes(label);
+}
+
+/** The index (in {@link exampleRows}) of the row a recorded label stands for, or -1 when the label names no single row (the producer worded it its own way, or two rows read alike). */
+export function exampleIndexFor(scenario: Pick<FeatureScenario, 'examples'>, label: string): number {
+  const rows = exampleRows(scenario);
+  const found = rows.flatMap((entry, at) => (namesRow(label, entry) ? [at] : []));
+  return found.length === 1 ? found[0]! : -1;
+}
+
+/** The steps of a scenario with one example's values put in for its `<column>` placeholders, so the concrete inputs read as written. */
+export function fillExample(steps: readonly FeatureStep[], entry: { readonly header: readonly string[]; readonly row: readonly string[] }): FeatureStep[] {
+  const fill = (text: string) => text.replace(/<([^<>]+)>/g, (whole, name: string) => {
+    const at = entry.header.indexOf(name);
+    return at < 0 ? whole : (entry.row[at] ?? whole);
+  });
+  return steps.map((step) => ({ ...step, text: fill(step.text), docString: step.docString === null ? null : fill(step.docString), table: step.table.map((row) => row.map(fill)) }));
+}

package/packages/visualizer/src/evidence/spec-index.tsx

@@ -1,7 +1,7 @@
 import { addSummaries, NO_EVIDENCE, type SpecSummary } from '@crvouga/atlas/reports/evidence-view';
-import { Box, Button, Group, NavLink, Stack, Text, Title } from '@mantine/core';
+import { Box, Button, Group, NavLink, SegmentedControl, Stack, Text, TextInput, Title } from '@mantine/core';
 import { Link, useSearch } from '@tanstack/react-router';
-import { useMemo } from 'react';
+import { useMemo, useState } from 'react';
 import { folderOf, outlinePath, specFile, type SpecKind } from '../spec-kind';
 import { useUiStore, type ResultFilter } from '../state/ui-store';
 import { useEvidence } from './evidence-context';
@@ -17,30 +17,42 @@ const FILTERS: readonly {
   { id: 'failed', label: 'Failing', keeps: (summary) => summary.counts.failed > 0 },
   { id: 'none', label: 'None', keeps: (summary) => summary.status === 'none' }
 ];
+const NO_DOMAIN = 'No domain declared';
 /** Every spec of one kind, grouped by folder, each with what the combined report holds for it. */
 export function SpecIndex({ kind }: { kind: SpecKind }) {
   const evidence = useEvidence();
   const search = useSearch({ strict: false });
   const filter = useUiStore((s) => s.resultFilter);
   const setFilter = useUiStore((s) => s.setResultFilter);
+  const [query, setQuery] = useState('');
+  const [grouping, setGrouping] = useState<'folder' | 'domain'>('folder');
   const open = typeof search.spec === 'string' ? specFile(search.spec) : '';
+  // The domain a spec declares in its metadata is used as given; a spec that declares none is not given one.
+  const domains = useMemo(() => new Map(evidence.specs.map((spec) => [spec.path, spec.domain])), [evidence.specs]);
   const rows = useMemo(
     () =>
       evidence.files.filter(kind.accepts).map((file) => ({
         file,
         title: evidence.titleOf(file),
+        domain: domains.get(outlinePath(file)) || '',
         summary: evidence.view.specs.get(outlinePath(file))?.summary ?? NO_EVIDENCE
       })),
     // `titleOf` reads the outline the view was built from.
-    [evidence.files, evidence.view, kind]
+    [evidence.files, evidence.view, kind, domains]
   );
   const keeps = FILTERS.find((entry) => entry.id === filter)!.keeps;
-  const visible = rows.filter((row) => keeps(row.summary));
+  const needle = query.trim().toLowerCase();
+  const visible = rows.filter(
+    (row) => keeps(row.summary) && (!needle || `${row.title} ${row.file} ${row.domain}`.toLowerCase().includes(needle))
+  );
   const groups = useMemo(() => {
-    const byFolder = new Map<string, typeof visible>();
-    for (const row of visible) byFolder.set(folderOf(row.file), [...(byFolder.get(folderOf(row.file)) ?? []), row]);
-    return [...byFolder];
-  }, [visible]);
+    const byGroup = new Map<string, typeof visible>();
+    for (const row of visible) {
+      const group = grouping === 'domain' ? row.domain || NO_DOMAIN : folderOf(row.file);
+      byGroup.set(group, [...(byGroup.get(group) ?? []), row]);
+    }
+    return [...byGroup];
+  }, [visible, grouping]);
   return (
     <Box aria-label={`${kind.label} ${kind.many}`} component="nav" p="md">
       <Group role="group" aria-label="Show" gap="xs" mb="md">
@@ -59,19 +71,40 @@ export function SpecIndex({ kind }: { kind: SpecKind }) {
           </Button>
         ))}
       </Group>
+      <Group gap="md" align="end" mb="md">
+        <TextInput
+          label={`Search ${kind.many}`}
+          type="search"
+          value={query}
+          onChange={(event) => setQuery(event.currentTarget.value)}
+          flex={1}
+          miw="12rem"
+        />
+        <SegmentedControl
+          aria-label="Group by"
+          value={grouping}
+          onChange={(value) => setGrouping(value === 'domain' ? 'domain' : 'folder')}
+          data={[
+            { label: 'Folder', value: 'folder' },
+            { label: 'Domain', value: 'domain' }
+          ]}
+        />
+      </Group>
       {evidence.filesPending && <Text component="div">Loading…</Text>}
       {evidence.filesError && <Text component="div">The file list could not be loaded.</Text>}
       {!evidence.filesPending && !evidence.filesError && visible.length === 0 && (
         <Text component="div">
           {rows.length === 0
             ? `No ${kind.many} in this spec set.`
-            : filter === 'running'
-              ? `No running ${kind.many}.`
-              : filter === 'failed'
-                ? `No failing ${kind.many}.`
-                : filter === 'results'
-                  ? `No ${kind.many} with results yet.`
-                  : `Every ${kind.one} has results.`}
+            : needle
+              ? `No ${kind.many} match "${query.trim()}".`
+              : filter === 'running'
+                ? `No running ${kind.many}.`
+                : filter === 'failed'
+                  ? `No failing ${kind.many}.`
+                  : filter === 'results'
+                    ? `No ${kind.many} with results yet.`
+                    : `Every ${kind.one} has results.`}
         </Text>
       )}
       {groups.map(([folder, entries]) => (