@crvouga/atlas 1.8.0 → 1.10.0

package/packages/visualizer/src/evidence/artifact-tags.tsx

@@ -50,7 +50,7 @@ function shownTags(attachment: Attachment, context: TagsContext | null): Artifac
 }
 
 /** Every attachment a holder carries, on its steps and attempts too. */
-function everyAttachment(holder: EvidenceHolder): Attachment[] {
+export function everyAttachment(holder: EvidenceHolder): Attachment[] {
   const out: Attachment[] = [...(holder.attachments ?? [])];
   for (const step of holder.steps ?? []) out.push(...(step.attachments ?? []));
   for (const attempt of holder.attempts ?? []) {

package/packages/visualizer/src/explorer/ArtifactsView.tsx

@@ -7,7 +7,7 @@
  * untagged. Each row opens that exact result in the test detail. An empty answer for a filter says nothing matches and
  * offers to clear it; it never says the project has nothing recorded.
  */
-import { IconVideo } from '@tabler/icons-react';
+import { IconPlayerPlay, IconVideo } from '@tabler/icons-react';
 import { Alert, Anchor, Box, Button, Code, Stack, Table, Text } from '@mantine/core';
 import { videoCounts } from '@crvouga/atlas/reports/evidence-detail';
 import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
@@ -20,6 +20,8 @@ import { useArtifactList } from './catalog';
 import { FilterBar } from './filters';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { runName } from './parts';
+import { entriesFromArtifacts } from './playlist-entries';
+import { WatchPlaylist } from './playlist';
 import { filtered, filterOf, NO_FILTERS } from './search';
 
 const ARTIFACT_ROWS = 50;
@@ -33,6 +35,8 @@ export function ArtifactsView() {
   const answer = useArtifactList(filter);
   const now = useNow();
   const [shown, setShown] = useState(ARTIFACT_ROWS);
+  const [watching, setWatching] = useState(false);
+  const entries = useMemo(() => (answer.data && !answer.data.unsupported ? entriesFromArtifacts(answer.data.list.results) : []), [answer.data]);
   if (answer.isPending)
     return (
       <Text role="status" component="div" c="dimmed">
@@ -77,6 +81,12 @@ export function ArtifactsView() {
           </Button>
         </Stack>
       )}
+      {list.results.length > 0 && (
+        <Button type="button" variant="filled" my="sm" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => setWatching(true)}>
+          Watch these {plural(list.results.length, 'result', 'results')}
+        </Button>
+      )}
+      {watching && <WatchPlaylist entries={entries} total={list.total} onClose={() => setWatching(false)} />}
       {list.results.length > 0 && (
         <Table.ScrollContainer minWidth={700}>
           <Table data-artifacts>

package/packages/visualizer/src/explorer/Reliability.tsx

@@ -0,0 +1,337 @@
+/**
+ * @module Reliability of a test
+ *
+ * The open test's reliability, qualified: how many independent executions it rests on (not snapshots, not tries), for
+ * which environment, branch, spec revision and time window, how often it passed first time and in the end, and why the
+ * figure may not be what it looks like (a small sample, pooled environments, failed cases published again, bounded
+ * history). The scope is in the address and the executions behind the figure (its denominator) open in place, so a link
+ * shows the same figure and the same executions. It is worked out from the history the page already holds
+ * (`reliability` in the reports library), so it needs no further request.
+ */
+import { Accordion, Alert, Anchor, Badge, Box, Button, Checkbox, Code, CopyButton, Flex, List, MultiSelect, SimpleGrid, Stack, Table, Text, TextInput, Title, VisuallyHidden } from '@mantine/core';
+import { IconLink } from '@tabler/icons-react';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import { reliability, type ReliabilityExecution } from '@crvouga/atlas/reports/reliability';
+import type { TestResultEntry } from '@crvouga/atlas/reports/test-catalog';
+import { Link } from '@tanstack/react-router';
+import { useMemo } from 'react';
+import { exactTime, plural, shortSha, STATUS_WORD } from '../evidence/format';
+import { StatusMark } from '../evidence/marks';
+import { joined, reliabilityScopeOf, values } from './search';
+import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+
+/** A recorded status as a mark and a word; one this viewer does not know is shown by its own name and as unknown, never as a pass. */
+const known = (status: string) => (Object.hasOwn(STATUS_WORD, status) && status !== 'none' ? (status as keyof typeof STATUS_WORD) : 'none');
+const word = (status: string) => (known(status) === 'none' ? status : STATUS_WORD[known(status)]);
+const percent = (rate: number | null) => (rate === null ? 'no rate' : `${Math.round(rate * 1000) / 10}%`);
+const outOf = (passed: number, executions: number) => `${passed} of ${plural(executions, 'execution', 'executions')} passed`;
+const REASONS: Record<string, string> = {
+  'not-run': 'Did not run',
+  unfinished: 'Not finished',
+  'unknown-status': 'Status not understood',
+  'historical-revision': 'Earlier spec revision',
+  'revision-not-recorded': 'Spec revision not recorded'
+};
+
+function Choice({ label, param, options, chosen }: { label: string; param: 'relEnv' | 'relProducer' | 'relBranch' | 'relParam'; options: readonly { value: string; label: string }[]; chosen: string[] }) {
+  const go = useExplorerNavigate();
+  if (options.length < 2 && !chosen.length) return null;
+  return (
+    <MultiSelect
+      label={label}
+      data={options as { value: string; label: string }[]}
+      value={chosen}
+      searchable
+      clearable
+      placeholder={chosen.length ? undefined : `Any ${label.toLowerCase()}`}
+      nothingFoundMessage="Nothing found"
+      onChange={(next) => go({ [param]: joined(next) } as never, { replace: true })}
+    />
+  );
+}
+
+function Denominator({ executions, layer }: { executions: readonly ReliabilityExecution[]; layer: string | undefined }) {
+  return (
+    <Table.ScrollContainer minWidth={760}>
+      <Table>
+        <Table.Caption>Independent executions of this test in the scope, newest first. Snapshots of one execution are one row.</Table.Caption>
+        <Table.Thead>
+          <Table.Tr>
+            <Table.Th scope="col">Recorded</Table.Th>
+            <Table.Th scope="col">Environment</Table.Th>
+            <Table.Th scope="col">Status</Table.Th>
+            <Table.Th scope="col">Tries</Table.Th>
+            <Table.Th scope="col">Snapshots</Table.Th>
+            <Table.Th scope="col">Branch</Table.Th>
+            <Table.Th scope="col">Commit</Table.Th>
+            <Table.Th scope="col">Counted</Table.Th>
+            <Table.Th scope="col">
+              <VisuallyHidden>Evidence</VisuallyHidden>
+            </Table.Th>
+          </Table.Tr>
+        </Table.Thead>
+        <Table.Tbody>
+          {executions.map((execution) => (
+            <Table.Tr key={`${execution.layer}|${execution.kind}|${execution.producer}|${execution.environment}|${JSON.stringify(execution.parameters)}`} data-status={execution.status} data-counted={execution.counted}>
+              <Table.Td title={exactTime(execution.at)}>{exactTime(execution.at)}</Table.Td>
+              <Table.Td>
+                {environmentLabel(execution.environment)}
+                {Object.entries(execution.parameters).map(([name, value]) => (
+                  <Text key={name} span inherit c="dimmed">
+                    {' '}
+                    {name}: {value}
+                  </Text>
+                ))}
+              </Table.Td>
+              <Table.Td>
+                <Flex component="span" display="inline-flex" gap="xs" align="center" wrap="wrap">
+                  <StatusMark status={known(execution.status)} size={12} />
+                  {word(execution.status)}
+                </Flex>
+              </Table.Td>
+              <Table.Td>{execution.attempts ? execution.attempts.map(word).join(' → ') : 'Not recorded'}</Table.Td>
+              <Table.Td>
+                {execution.snapshots}
+                {execution.republished && (
+                  <Text span inherit c="dimmed">
+                    {' '}
+                    (published again after a failure)
+                  </Text>
+                )}
+              </Table.Td>
+              <Table.Td c="dimmed">{execution.branch ?? '—'}</Table.Td>
+              <Table.Td>
+                <Code>{shortSha(execution.sha) ?? '—'}</Code>
+              </Table.Td>
+              <Table.Td>{execution.counted ? 'Yes' : `No: ${REASONS[execution.excluded ?? ''] ?? execution.excluded}`}</Table.Td>
+              <Table.Td>
+                <Anchor
+                  aria-label={`Open the ${word(execution.status)} result recorded ${exactTime(execution.at)} in ${environmentLabel(execution.environment)}`}
+                  aria-current={execution.layer === layer ? 'true' : undefined}
+                  renderRoot={(props) => <Link {...props} to="/" search={patched({ layer: execution.layer })} resetScroll={false} activeOptions={{ exact: true }} />}
+                >
+                  Open this result
+                </Anchor>
+              </Table.Td>
+            </Table.Tr>
+          ))}
+        </Table.Tbody>
+      </Table>
+    </Table.ScrollContainer>
+  );
+}
+
+/**
+ * The reliability section of an open test: scope choices, the qualified figures, why they may mislead, and the
+ * executions they count. `entries` is every recorded result of the test the page holds, newest first; while it is
+ * `undefined` the history is still being read.
+ */
+export function Reliability({ testKey, entries }: { testKey: string; entries: readonly TestResultEntry[] | undefined }) {
+  const search = useExplorerSearch();
+  const go = useExplorerNavigate();
+  const scope = useMemo(() => reliabilityScopeOf(search), [search]);
+  const document = useMemo(() => (entries ? reliability(testKey, entries, scope) : null), [testKey, entries, scope]);
+  const parameters = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const entry of entries ?? []) for (const [name, value] of Object.entries(entry.parameters)) counts.set(`${name}=${value}`, (counts.get(`${name}=${value}`) ?? 0) + 1);
+    return [...counts].map(([value, count]) => ({ value, label: `${value} (${count})` }));
+  }, [entries]);
+  if (!document)
+    return (
+      <Box aria-label="Reliability" component="section" mb="lg">
+        <Title order={3} mb="sm" c="dimmed">
+          Reliability
+        </Title>
+        <Text role="status" component="div" c="dimmed">
+          Reading the history…
+        </Text>
+      </Box>
+    );
+  const { eventual, firstAttempt } = document;
+  const label = (list: readonly { value: string; count: number }[], format: (value: string) => string = (value) => value) => list.map(({ value, count }) => ({ value, label: `${format(value)} (${count})` }));
+  const warnings = document.notes.filter((note) => note.severity === 'warning');
+  const infos = document.notes.filter((note) => note.severity === 'info');
+  const scoped = Object.keys(scope).length > 0;
+  return (
+    <Box aria-label="Reliability" component="section" mb="lg">
+      <Title order={3} mb="sm" c="dimmed">
+        Reliability
+      </Title>
+      <Text component="div" c="dimmed" mb="sm">
+        Counted over independent executions: the snapshots one run recorded for one environment are one execution, and a retry is a try of it, not another
+        execution. This describes the checks Atlas holds, not how often the product fails in production.
+      </Text>
+      <Stack gap="sm" mb="md">
+        <SimpleGrid cols={{ base: 1, sm: 2, md: 3 }}>
+          <Choice label="Environment" param="relEnv" options={label(document.available.environments, environmentLabel)} chosen={values(search.relEnv)} />
+          <Choice label="Producer" param="relProducer" options={label(document.available.producers)} chosen={values(search.relProducer)} />
+          <Choice label="Branch" param="relBranch" options={label(document.available.branches)} chosen={values(search.relBranch)} />
+          <Choice label="Parameters" param="relParam" options={parameters} chosen={values(search.relParam)} />
+          <TextInput type="date" label="Executions from" value={search.relSince ?? ''} onChange={(event) => go({ relSince: event.target.value || undefined }, { replace: true })} />
+          <TextInput type="date" label="Executions until" value={search.relUntil ?? ''} onChange={(event) => go({ relUntil: event.target.value || undefined }, { replace: true })} />
+        </SimpleGrid>
+        {document.available.specRevisions.length > 0 && (
+          <Checkbox
+            label="Include earlier revisions of the spec"
+            description={document.currentRevision ? 'Off: only executions of the newest recorded spec revision count; earlier ones are shown as context.' : 'On: every revision is pooled, though the behavior may have changed between them.'}
+            checked={search.relRevision === 'any'}
+            onChange={(event) => go({ relRevision: event.currentTarget.checked ? 'any' : undefined }, { replace: true })}
+          />
+        )}
+      </Stack>
+
+      <Flex gap="xs" align="center" wrap="wrap" mb="sm" role="status" aria-label="Reliability sample">
+        <Badge color={document.sample === 'sufficient' ? 'gray' : 'orange'} variant="light">
+          {document.sample === 'none' ? 'No independent executions' : document.sample === 'insufficient' ? 'Insufficient evidence' : 'Sample large enough to read as a rate'}
+        </Badge>
+        <Text span inherit fw={600}>
+          {plural(eventual.executions, 'independent execution', 'independent executions')}
+        </Text>
+        <Text span inherit c="dimmed">
+          {scoped ? 'in this scope' : 'in all recorded history'}
+          {document.sample === 'insufficient' ? `; at least ${document.minimumExecutions} are needed before a rate means much` : ''}
+        </Text>
+      </Flex>
+
+      <SimpleGrid component="dl" cols={{ base: 1, sm: 2, md: 3 }}>
+        <Stack gap="sm">
+          <Box component="dt">Eventual success</Box>
+          <Box component="dd" m={0}>
+            {eventual.executions ? `${outOf(eventual.passed, eventual.executions)} (${percent(eventual.rate)})` : 'No rate: nothing completed in this scope'}
+          </Box>
+        </Stack>
+        <Stack gap="sm">
+          <Box component="dt">First-try success</Box>
+          <Box component="dd" m={0}>
+            {firstAttempt.executions ? `${outOf(firstAttempt.passed, firstAttempt.executions)} first time (${percent(firstAttempt.rate)})` : 'Unknown: no tries recorded'}
+            {document.unrecordedAttempts > 0 && firstAttempt.executions > 0 && (
+              <Text span inherit c="dimmed">
+                {' '}
+                · {document.unrecordedAttempts} recorded no tries
+              </Text>
+            )}
+          </Box>
+        </Stack>
+        <Stack gap="sm">
+          <Box component="dt">Tries</Box>
+          <Box component="dd" m={0}>
+            {document.attempts.total
+              ? `${document.attempts.total} recorded; ${plural(document.attempts.retried, 'execution', 'executions')} retried, ${document.attempts.recovered} failed first and passed after`
+              : 'None recorded'}
+          </Box>
+        </Stack>
+        <Stack gap="sm">
+          <Box component="dt">Interval (95%)</Box>
+          <Box component="dd" m={0} title={document.interval?.assumptions}>
+            {document.interval ? `${percent(document.interval.lower)} to ${percent(document.interval.upper)} (Wilson)` : '—'}
+          </Box>
+        </Stack>
+        <Stack gap="sm">
+          <Box component="dt">Recorded snapshots</Box>
+          <Box component="dd" m={0}>
+            {document.snapshots} behind the counted {plural(eventual.executions, 'execution', 'executions')}
+          </Box>
+        </Stack>
+        <Stack gap="sm">
+          <Box component="dt">Not counted</Box>
+          <Box component="dd" m={0}>
+            {document.outsideScope} outside the scope
+            {Object.entries(document.excluded)
+              .filter(([, count]) => count > 0)
+              .map(([reason, count]) => `, ${count} ${(REASONS[reason] ?? reason).toLowerCase()}`)
+              .join('')}
+          </Box>
+        </Stack>
+      </SimpleGrid>
+
+      {warnings.length > 0 && (
+        <Alert color="orange" title="Read this figure with care" mt="sm">
+          <List>
+            {warnings.map((note) => (
+              <List.Item key={note.code}>{note.message}</List.Item>
+            ))}
+          </List>
+        </Alert>
+      )}
+      {infos.length > 0 && (
+        <List mt="sm" c="dimmed">
+          {infos.map((note) => (
+            <List.Item key={note.code}>{note.message}</List.Item>
+          ))}
+        </List>
+      )}
+      {document.interval && (
+        <Text component="div" c="dimmed" mt="sm">
+          Interval assumes: {document.interval.assumptions}
+        </Text>
+      )}
+      {document.historical.executions > 0 && (
+        <Text component="div" c="dimmed" mt="sm">
+          Earlier spec revisions, shown as context and not counted: {outOf(document.historical.passed, document.historical.executions)}.
+        </Text>
+      )}
+
+      {document.cohorts.length > 1 && (
+        <Table.ScrollContainer minWidth={500} mt="sm">
+          <Table>
+            <Table.Caption>Each environment, producer and parameter set on its own</Table.Caption>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th scope="col">Environment</Table.Th>
+                <Table.Th scope="col">Producer</Table.Th>
+                <Table.Th scope="col">Executions</Table.Th>
+                <Table.Th scope="col">Passed</Table.Th>
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>
+              {document.cohorts.map((cohort) => (
+                <Table.Tr key={JSON.stringify([cohort.environment, cohort.producer, cohort.parameters])}>
+                  <Table.Td>
+                    {environmentLabel(cohort.environment)}
+                    {Object.entries(cohort.parameters).map(([name, value]) => (
+                      <Text key={name} span inherit c="dimmed">
+                        {' '}
+                        {name}: {value}
+                      </Text>
+                    ))}
+                  </Table.Td>
+                  <Table.Td>{cohort.producer}</Table.Td>
+                  <Table.Td>{cohort.executions}</Table.Td>
+                  <Table.Td>
+                    {cohort.passed} ({percent(cohort.rate)})
+                  </Table.Td>
+                </Table.Tr>
+              ))}
+            </Table.Tbody>
+          </Table>
+        </Table.ScrollContainer>
+      )}
+
+      <Accordion variant="separated" mt="sm" value={search.relOpen ? 'denominator' : null} onChange={(value) => go({ relOpen: value ? true : undefined }, { replace: true })}>
+        <Accordion.Item value="denominator">
+          <Accordion.Control>
+            Executions behind this figure: {document.executions.filter((execution) => execution.counted).length} counted
+            {document.executions.some((execution) => !execution.counted) ? `, ${document.executions.filter((execution) => !execution.counted).length} not counted` : ''}
+          </Accordion.Control>
+          <Accordion.Panel>
+            <Stack gap="sm">
+              <Flex gap="xs" align="center" wrap="wrap">
+                <CopyButton value={typeof window === 'undefined' ? '' : window.location.href}>
+                  {({ copied, copy }) => (
+                    <Button type="button" variant="default" onClick={copy} leftSection={<IconLink size={16} aria-hidden="true" />}>
+                      {copied ? 'Link copied' : 'Copy link to this scope'}
+                    </Button>
+                  )}
+                </CopyButton>
+                <Text span inherit c="dimmed">
+                  The link opens this scope and these executions.
+                </Text>
+              </Flex>
+              {document.executions.length > 0 ? <Denominator executions={document.executions} layer={search.layer} /> : <Text c="dimmed">No execution of this test matches the scope.</Text>}
+            </Stack>
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    </Box>
+  );
+}

package/packages/visualizer/src/explorer/RunsView.tsx

@@ -1,4 +1,4 @@
-import { IconAlertTriangle, IconArrowLeft, IconVideo } from '@tabler/icons-react';
+import { IconAlertTriangle, IconArrowLeft, IconPlayerPlay, IconVideo } from '@tabler/icons-react';
 import { Alert, Anchor, Badge, Box, Button, Code, Flex, Group, List, NativeSelect, Stack, Table, Text, TextInput, Title, VisuallyHidden } from '@mantine/core';
 /**
  * @module Runs view
@@ -25,6 +25,8 @@ import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidenc
 import { Meter, StatusMark } from '../evidence/marks';
 import { useRunDetail, useRunList, useTestCatalog } from './catalog';
 import { RunArtifacts } from './RunArtifacts';
+import { entriesFromRun } from './playlist-entries';
+import { WatchPlaylist } from './playlist';
 import { FilterBar } from './filters';
 import { SearchNotes, TypedFilters } from './search-notes';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
@@ -469,6 +471,8 @@ function RunDetailView({ runKey }: { runKey: string }) {
       ),
     [narrowedResults, status, statusFilters, model]
   );
+  const [watching, setWatching] = useState(false);
+  const playlist = useMemo(() => entriesFromRun(filtered, detail.data?.layers), [filtered, detail.data]);
   const bySpec = useMemo(() => {
     const groups = new Map<string, RunResult[]>();
     for (const result of filtered.slice(0, shown)) {
@@ -636,6 +640,12 @@ function RunDetailView({ runKey }: { runKey: string }) {
           No result matches.
         </Text>
       )}
+      {filtered.length > 0 && (
+        <Button type="button" variant="filled" my="sm" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => setWatching(true)}>
+          Watch these {plural(filtered.length, 'result', 'results')}
+        </Button>
+      )}
+      {watching && <WatchPlaylist entries={playlist} onClose={() => setWatching(false)} />}
       {bySpec.map(([spec, list]) => (
         <Box key={spec} data-open aria-label={spec || 'No spec'} component="section" mb="lg">
           <Button data-static variant="default" fullWidth h="auto" py="sm" justify="flex-start">

package/packages/visualizer/src/explorer/TestDetail.tsx

@@ -21,6 +21,7 @@ import { outcomeHeadline, selectedResult } from '../evidence/outcome';
 import { useTestHistory } from './catalog';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { Badges, runName } from './parts';
+import { Reliability } from './Reliability';
 import { ProductLatency } from './ProductLatency';
 import { usePinnedResult, type PinnedResult } from './pinned';
 const RecordingPage = lazy(() => import('../evidence/recording-page').then((module) => ({ default: module.RecordingPage })));
@@ -405,6 +406,8 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
         {entries.length > 1 && <Trend entries={entries} />}
       </Box>
 
+      {!history.isError && <Reliability testKey={test.key} entries={history.data === null ? [] : history.data?.history} />}
+
       <ProductLatency entries={entries} />
 
       {(test.tags.length > 0 || Object.keys(test.labels).length > 0) && (

package/packages/visualizer/src/explorer/catalog.tsx

@@ -180,7 +180,7 @@ function usePageHistory(layers: readonly LayerEvidence[] | null): PageHistory |
       const key = `${entry.layer.backend}|${entry.layer.id}`;
       if (current.rows.has(key)) continue;
       current.rows.set(key, entry.rows);
-      current.history.add(entry.layer, entry.rows, [], entry.layer.backend);
+      current.history.add(entry.layer, entry.rows, [], entry.layer.backend, entry.fingerprints);
     }
     return { history: current.history, stamp: `page:${current.gen}:${current.history.rev}` };
   }, [layers]);

package/packages/visualizer/src/explorer/playlist-entries.test.ts

@@ -0,0 +1,51 @@
+import type { VideoRef } from '@crvouga/atlas/reports/evidence-types';
+import { expect, test } from 'bun:test';
+
+import { entriesFromRun, playlistCounts, recordingState, stepFrom, type PlaylistEntry } from './playlist-entries';
+
+const video = (recording?: string): VideoRef => ({ name: 'a.webm', owner: 'check', available: recording !== undefined, ...(recording ? { recording } : {}) });
+const entry = (id: string, extra: Partial<PlaylistEntry> = {}): PlaylistEntry => ({
+  id, title: id, key: id, specPath: null, status: 'passed', environment: 'desktop-web', producer: 'web', at: 1, layer: 'l', backend: 'local', check: id, kind: null, tags: [], videos: [], ...extra
+});
+
+test('a recording state never says more than what is stored', () => {
+  expect(recordingState(entry('a', { videos: [video('sha256:1')] }))).toBe('playable');
+  expect(recordingState(entry('a', { videos: [video()] }))).toBe('unplayable');
+  // Bytes exist, but nothing says which backend to read them from.
+  expect(recordingState(entry('a', { videos: [video('sha256:1')], backend: null }))).toBe('unplayable');
+  expect(recordingState(entry('a', { environment: 'api-rest' }))).toBe('api-only');
+  expect(recordingState(entry('a', { environment: null }))).toBe('none');
+  expect(recordingState(entry('a'))).toBe('none');
+});
+
+test('counts keep failures and gaps visible', () => {
+  const counts = playlistCounts([
+    entry('a', { videos: [video('sha256:1')] }),
+    entry('b', { status: 'failed', videos: [video('sha256:2')] }),
+    entry('c', { status: 'failed' }),
+    entry('d', { environment: 'api' })
+  ]);
+  expect(counts).toEqual({ playable: 2, unplayable: 0, 'api-only': 1, none: 1, failed: 2 });
+});
+
+test('previous and next walk the watchable entries, skip gaps, wrap only when asked and work from a gap', () => {
+  const play = { videos: [video('sha256:1')] };
+  const list = [entry('a', play), entry('gap'), entry('b', play), entry('c', play)];
+  expect(stepFrom(list, 'a', 1, false)?.id).toBe('b');
+  expect(stepFrom(list, 'c', 1, false)).toBeNull();
+  expect(stepFrom(list, 'c', 1, true)?.id).toBe('a');
+  expect(stepFrom(list, 'a', -1, false)).toBeNull();
+  expect(stepFrom(list, 'a', -1, true)?.id).toBe('c');
+  expect(stepFrom(list, 'gap', 1, false)?.id).toBe('b');
+  expect(stepFrom(list, 'gap', -1, false)?.id).toBe('a');
+  expect(stepFrom([list[0]!], 'a', 1, true)?.id).toBe('a');
+  expect(stepFrom([entry('gap')], 'gap', 1, true)).toBeNull();
+});
+
+test('a run result gets its backend from the layers of the run, and none when they are not known', () => {
+  const result = { key: 'k', id: 'c', title: 'T', specPath: null, environment: 'ios', producer: 'p', status: 'failed' as const, durationMs: null, at: 1, layer: 'abc', detail: '', videos: [{ ...video('sha256:1'), tags: ['demo'] }] };
+  const layers = [{ id: 'abc', backend: 'shared', producer: 'p', environment: 'ios', recordedAtMs: 1, checks: 1, attachments: 0 }];
+  expect(entriesFromRun([result], layers)[0]).toMatchObject({ backend: 'shared', check: 'c', status: 'failed', tags: ['demo'] });
+  expect(entriesFromRun([result], undefined)[0]!.backend).toBeNull();
+  expect(recordingState(entriesFromRun([result], undefined)[0]!)).toBe('unplayable');
+});

package/packages/visualizer/src/explorer/playlist-entries.ts

@@ -0,0 +1,134 @@
+/**
+ * @module Recording playlist
+ *
+ * The order and the honesty of a watch session: a filtered set of recorded results becomes an ordered list of entries,
+ * each with what can be said about its recording before anything is downloaded. Every result of the set is an entry
+ * (a failed one is never dropped, and one without a recording says so) and the order is the order of the set it came
+ * from, so the same filters give the same playlist. Pure functions; the player is `playlist.tsx`.
+ */
+import { videoCounts } from '@crvouga/atlas/reports/evidence-detail';
+import type { VideoRef } from '@crvouga/atlas/reports/evidence-types';
+import type { EvidenceStatus } from '@crvouga/atlas/reports/explorer-types';
+import type { ArtifactResult, RunLayer, RunResult } from '@crvouga/atlas/reports/test-catalog';
+
+/** One recorded result in a playlist: where to read its evidence, what to say about it, and its video references. */
+export type PlaylistEntry = {
+  /** Identifies the entry for as long as the set is the same; selection follows it, never a position. */
+  readonly id: string;
+  readonly title: string;
+  /** The test's key, to open it. */
+  readonly key: string;
+  readonly specPath: string | null;
+  readonly status: EvidenceStatus;
+  readonly environment: string | null;
+  readonly producer: string;
+  /** When it was recorded, epoch ms. */
+  readonly at: number;
+  /** The layer that recorded it and the backend to read it from; null when the backend is not known (an older server). */
+  readonly layer: string;
+  readonly backend: string | null;
+  /** The check's id and, when known, the kind of its part: with the layer they name the evidence to read. */
+  readonly check: string;
+  readonly kind: string | null;
+  /** The tags its attachments carry. */
+  readonly tags: readonly string[];
+  /** Every video its evidence references. */
+  readonly videos: readonly VideoRef[];
+};
+
+/**
+ * What is known about an entry's recording: `playable` (a stored file can be tried), `unplayable` (referenced, but no
+ * bytes were published, or the backend to read them from is unknown), `api-only` (no recording and recorded through
+ * an API, so there is no screen) or `none`.
+ */
+export type RecordingState = 'playable' | 'unplayable' | 'api-only' | 'none';
+
+/** Environments a reader cannot watch: a result recorded only through these has no screen. */
+const API_ENVIRONMENT = /^(api|http|rest|graphql|service|backend)(-|$)/;
+
+/** The state of an entry's recording. Only `playable` means there is something to watch; none of the others is a pass with proof. */
+export function recordingState(entry: Pick<PlaylistEntry, 'videos' | 'backend' | 'environment'>): RecordingState {
+  const counts = videoCounts(entry.videos);
+  if (counts && counts.recordings > 0) return entry.backend === null ? 'unplayable' : 'playable';
+  if (counts) return 'unplayable';
+  return entry.environment !== null && API_ENVIRONMENT.test(entry.environment) ? 'api-only' : 'none';
+}
+
+/** What each state says to a person. A recording is never described as demonstrating anything it does not. */
+export const RECORDING_STATE_TEXT: Record<RecordingState, { readonly label: string; readonly meaning: string }> = {
+  playable: { label: 'Recording', meaning: 'A recording is stored for this result.' },
+  unplayable: { label: 'Recording not available', meaning: 'This result references a recording, but no stored file can be played, so it is not demonstrated.' },
+  'api-only': { label: 'API only', meaning: 'This result was recorded through an API, so there is no screen to watch. It is not demonstrated by a recording.' },
+  none: { label: 'No recording', meaning: 'No recording was published for this result, so it is not demonstrated by one.' }
+};
+
+/** The first video of an entry that names bytes: the one that is played. */
+export function playableVideo(entry: Pick<PlaylistEntry, 'videos'>): VideoRef | undefined {
+  return entry.videos.find((video) => video.available && video.recording !== undefined);
+}
+
+/** The recorded results of the Artifacts tab as playlist entries, in their order. */
+export function entriesFromArtifacts(results: readonly ArtifactResult[]): PlaylistEntry[] {
+  return results.map((result) => ({
+    id: `${result.layer}|${result.key}|${result.kind}|${result.producer}|${result.environment ?? ''}`,
+    title: result.title,
+    key: result.key,
+    specPath: result.specPath,
+    status: result.status,
+    environment: result.environment,
+    producer: result.producer,
+    at: result.at,
+    layer: result.layer,
+    backend: result.backend,
+    check: result.id,
+    kind: result.kind,
+    tags: result.artifactTags,
+    videos: result.videos ?? []
+  }));
+}
+
+/** The results of one run as playlist entries, in their order; `layers` say which backend each result's layer was read from. */
+export function entriesFromRun(results: readonly RunResult[], layers: readonly RunLayer[] | undefined): PlaylistEntry[] {
+  const backends = new Map((layers ?? []).map((layer) => [layer.id, layer.backend]));
+  return results.map((result) => ({
+    id: `${result.layer}|${result.key}||${result.producer}|${result.environment ?? ''}`,
+    title: result.title,
+    key: result.key,
+    specPath: result.specPath,
+    status: result.status,
+    environment: result.environment,
+    producer: result.producer,
+    at: result.at,
+    layer: result.layer,
+    backend: backends.get(result.layer) ?? null,
+    check: result.id,
+    kind: null,
+    tags: [...new Set((result.videos ?? []).flatMap((video) => video.tags ?? []))].sort(),
+    videos: result.videos ?? []
+  }));
+}
+
+/** How many entries are in each state, and how many failed (a failure is counted whether or not it was recorded). */
+export function playlistCounts(entries: readonly PlaylistEntry[]): Record<RecordingState, number> & { readonly failed: number } {
+  const counts = { playable: 0, unplayable: 0, 'api-only': 0, none: 0, failed: 0 };
+  for (const entry of entries) {
+    counts[recordingState(entry)] += 1;
+    if (entry.status === 'failed') counts.failed += 1;
+  }
+  return counts;
+}
+
+/**
+ * The entry to go to from `from`, over the entries that can be watched. `step` is 1 for next, -1 for previous. Past the
+ * end it wraps to the other end when `wrap`, else it is null. From an entry that cannot be watched (selected from the
+ * list to read why), it is the nearest watchable one in that direction.
+ */
+export function stepFrom(entries: readonly PlaylistEntry[], from: string | null, step: 1 | -1, wrap: boolean): PlaylistEntry | null {
+  const at = from === null ? -1 : entries.findIndex((entry) => entry.id === from);
+  const watchable = (entry: PlaylistEntry) => recordingState(entry) === 'playable';
+  const ordered = step === 1 ? entries.map((entry, index) => [entry, index] as const) : entries.map((entry, index) => [entry, index] as const).reverse();
+  const after = ordered.filter(([entry, index]) => watchable(entry) && (at < 0 ? true : step === 1 ? index > at : index < at));
+  if (after.length > 0) return after[0]![0];
+  if (!wrap) return null;
+  return ordered.find(([entry]) => watchable(entry))?.[0] ?? null;
+}