@crvouga/atlas 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 1.6.0 (2026-10-29)
+
+### Features
+
+- unify fuzzy semantic search with complete filterable sortable results ([3b0b90e](https://github.com/crvouga/atlas/commit/3b0b90e4960dcbcbcfee924f33aca4ce02beaaec))
+
+## 1.5.0 (2026-10-28)
+
+### 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;
@@ -81,6 +101,16 @@ visible notation label; marks are decorative. Sources, licenses and the DMN nota
 and update this mapping when adding a format. Brand artwork preserves upstream colors independently of
 Atlas's theme. SVG data plots and statechart arrow markers are geometry, not handcrafted UI icons.
 
+## Search
+
+All search boxes (finder, test list, Runs tab, an opened run) use `src/find/query.ts` for the query language and
+`src/find/rank.ts` for matching; do not add a second matcher or filter on `includes`. Build documents from
+`src/find/behaviors.ts` so a behavior has the same fields and facets everywhere. Match first, then count, filter and sort
+the whole set, then page. Show filters typed in the box as removable chips, show what was not understood
+(`SearchNotes`), show why a result matched and mark exact ones, and say when matching is words only (no embedder, or
+a failed one). A bounded list says it is bounded and offers all results. Selection follows result identity, never a
+position, when results change. The query, filters and sort stay in the address.
+
 ## Accessibility and responsive behavior
 
 The shell collapses its index below Mantine's `md` breakpoint; its named Burger toggles mobile navigation.
@@ -127,11 +157,11 @@ 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 |
-| Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
+| Search/help | Ranked, filterable and semantic search across behaviors, runs and results; complete results; shortcut help, recording shortcuts | Spotlight, TextInput, NativeSelect, Button chips, Alert, Modal, Kbd |
 | Administration | Token access, S3 storage notice, garbage collection policy (saved in S3), live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
 
 The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,

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;
@@ -3913,6 +3933,16 @@ visible notation label; marks are decorative. Sources, licenses and the DMN nota
 and update this mapping when adding a format. Brand artwork preserves upstream colors independently of
 Atlas's theme. SVG data plots and statechart arrow markers are geometry, not handcrafted UI icons.
 
+## Search
+
+All search boxes (finder, test list, Runs tab, an opened run) use `src/find/query.ts` for the query language and
+`src/find/rank.ts` for matching; do not add a second matcher or filter on `includes`. Build documents from
+`src/find/behaviors.ts` so a behavior has the same fields and facets everywhere. Match first, then count, filter and sort
+the whole set, then page. Show filters typed in the box as removable chips, show what was not understood
+(`SearchNotes`), show why a result matched and mark exact ones, and say when matching is words only (no embedder, or
+a failed one). A bounded list says it is bounded and offers all results. Selection follows result identity, never a
+position, when results change. The query, filters and sort stay in the address.
+
 ## Accessibility and responsive behavior
 
 The shell collapses its index below Mantine's `md` breakpoint; its named Burger toggles mobile navigation.
@@ -3959,11 +3989,11 @@ 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 |
-| Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
+| Search/help | Ranked, filterable and semantic search across behaviors, runs and results; complete results; shortcut help, recording shortcuts | Spotlight, TextInput, NativeSelect, Button chips, Alert, Modal, Kbd |
 | Administration | Token access, S3 storage notice, garbage collection policy (saved in S3), live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
 
 The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.4.0",
+  "version": "1.6.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/README.md

@@ -154,6 +154,34 @@ Components read only the view model (`AtlasView`), never raw files.
   its own worker. Positions are cached under a hash of the chart's structure only, so new results
   never move anything.
 
+## Searching behaviors, runs and recordings
+
+Every search box (the finder opened with `Ctrl+K` or `/`, the test list, the Runs tab and the results of an opened
+run) reads one query language and matches with one engine (`src/find/query.ts`, `src/find/rank.ts`), so the same words
+make the same behaviors eligible everywhere.
+
+- **Words** match titles, steps, descriptions, specs, tags, environments and failure messages by stem, everyday synonym
+  and close spelling (`savde answer` finds "Keep a saved answer"), and the start of a longer word while it is typed.
+  Every distinctive word must be found; a word present in most behaviors is optional. When an embedder is available the
+  results are also re-ranked by meaning and a paraphrase with no word in common is added (`Similar meaning`); when none
+  is, or it fails, the box says it is matching words and spellings only.
+- **Exact matches.** `"a quoted phrase"` and identifiers with `/`, `_` or `.` (`memory/keep`) must appear as written, are
+  marked `Exact` and are listed first.
+- **Filters** narrow by structure instead of matching words: `status:failed` (`passed`, `failed`, `flaky`, `not-run`,
+  `running`), `env:ios` (also `platform:`, `environment:`, `device:`), `producer:`, `domain:`, `spec:`, `tag:`, `branch:`
+  and `has:video` (a playable recording, not the word). Values of one field are alternatives (`status:failed,flaky`);
+  different fields all hold. Each shows as a removable chip, and the status, environment and Has video buttons are the
+  same filters without the syntax.
+- **Nothing is dropped silently.** An unknown operator, an unknown status, an unclosed quote, or a filter a list does not
+  have (`domain:` on runs) is listed under the box with what to type instead.
+- **Complete results.** Counts, filters and sorting (including Best match, offered with words to match) apply to the whole
+  dataset before anything is shown in pages. The finder shows its first 40 results, says so, and opens all of them
+  (`Shift+Enter`, or the explorer's list for the same query). The query, filters and sort are in the address, so a link
+  and the back button restore them. Results that change under the cursor keep the highlighted result highlighted by
+  identity, and say so when it is no longer listed.
+
+The standing rules are in [the UI conventions](../../docs/ui.md#search).
+
 ## Fixtures
 
 `fixtures/` holds seven scenarios generated by `scripts/make-fixtures.ts` from `example/specs`, a

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');
+});