@crvouga/atlas 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.9.0 (2026-10-29)
+## 1.10.0 (2026-10-29)
+
+### Features
+
+- watch a filtered set of scenario recordings as a playlist ([00bac50](https://github.com/crvouga/atlas/commit/00bac503643601dfc54cb97ff1e16ce7ce74bd9f))
+
+## 1.9.0 (2026-10-28)
 
 ### Features
 

package/docs/ui.md

@@ -120,6 +120,27 @@ environment) is unknown unless the producer declared it under the `atlas.failure
 wording. Records of one source whose outcome changed are listed oldest first, and a later pass is never called a fix.
 In the explorer the chosen source is the `source` search parameter (a layer id; unlike `layer` it does not pin a run).
 
+## Watch a filtered set as a playlist
+
+The Artifacts tab and an opened run have a **Watch these N results** button. It opens a Mantine `Modal` (`explorer/playlist.tsx`)
+over the same filtered set the page lists, in the same order (`explorer/playlist-entries.ts` builds the entries).
+
+- Every result of the set is an entry. A failed one is never dropped, and one with no recording, an API-only one or one
+  whose file is missing says so in words (`Recording not available`, `API only`, `No recording`); none of these is shown as
+  demonstrated. A set longer than the page's limit says it is only the newest results.
+- Only the selected clip is read: the list is the metadata the catalog already sent, the selected result's evidence is read
+  when it is selected, and the one `<video>` uses `preload="metadata"`. Opening the playlist downloads no recordings in bulk.
+  Posters and durations of unselected entries are not shown for that reason.
+- One player: selecting another clip replaces it, and the position of the clip left is kept for the session so returning
+  resumes there. Previous/next and advancing on end move over the watchable entries; a result with nothing to play is
+  selected from the list to read why.
+- A clip that fails to load, or whose autoplay the browser blocked, stays in the list and offers Retry, Play and Next clip.
+  Speed, "Play the next clip when one ends" and "Repeat" are labelled controls. Captions (`text/vtt` attachments) are offered
+  as `<track>` elements.
+- The scenario (title, recorded steps, why it failed) sits beside the player with the recording's scope badges
+  (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. Developer
+  details opens the test pinned to that run's record and closes the playlist.
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -188,7 +209,7 @@ The narrowly scoped exceptions are:
 | Area | Screens/interactions | Mantine composition |
 | --- | --- | --- |
 | 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 |
+| Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, 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, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, 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 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 |

package/llms-full.txt

@@ -4030,6 +4030,27 @@ environment) is unknown unless the producer declared it under the `atlas.failure
 wording. Records of one source whose outcome changed are listed oldest first, and a later pass is never called a fix.
 In the explorer the chosen source is the `source` search parameter (a layer id; unlike `layer` it does not pin a run).
 
+## Watch a filtered set as a playlist
+
+The Artifacts tab and an opened run have a **Watch these N results** button. It opens a Mantine `Modal` (`explorer/playlist.tsx`)
+over the same filtered set the page lists, in the same order (`explorer/playlist-entries.ts` builds the entries).
+
+- Every result of the set is an entry. A failed one is never dropped, and one with no recording, an API-only one or one
+  whose file is missing says so in words (`Recording not available`, `API only`, `No recording`); none of these is shown as
+  demonstrated. A set longer than the page's limit says it is only the newest results.
+- Only the selected clip is read: the list is the metadata the catalog already sent, the selected result's evidence is read
+  when it is selected, and the one `<video>` uses `preload="metadata"`. Opening the playlist downloads no recordings in bulk.
+  Posters and durations of unselected entries are not shown for that reason.
+- One player: selecting another clip replaces it, and the position of the clip left is kept for the session so returning
+  resumes there. Previous/next and advancing on end move over the watchable entries; a result with nothing to play is
+  selected from the list to read why.
+- A clip that fails to load, or whose autoplay the browser blocked, stays in the list and offers Retry, Play and Next clip.
+  Speed, "Play the next clip when one ends" and "Repeat" are labelled controls. Captions (`text/vtt` attachments) are offered
+  as `<track>` elements.
+- The scenario (title, recorded steps, why it failed) sits beside the player with the recording's scope badges
+  (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. Developer
+  details opens the test pinned to that run's record and closes the playlist.
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -4098,7 +4119,7 @@ The narrowly scoped exceptions are:
 | Area | Screens/interactions | Mantine composition |
 | --- | --- | --- |
 | 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 |
+| Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, 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, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, 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 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.9.0",
+  "version": "1.10.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/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/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/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;
+}

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

@@ -0,0 +1,441 @@
+/**
+ * @module Watch playlist
+ *
+ * A watch session over a filtered set of recorded results: the player and the plain-language scenario beside an ordered
+ * list of every result in the set. A failed result stays in the list with its outcome, and a result with no recording,
+ * an API-only one or one whose file is missing says so in words instead of being left out or shown as demonstrated.
+ *
+ * Only the clip on screen is read: the list is made of the metadata the catalog already sent, the current result's
+ * evidence is read when it is selected, and its video is loaded with `preload="metadata"`, so opening the playlist of a
+ * large library downloads no recordings in bulk. There is one `<video>`; selecting another clip replaces it and keeps
+ * the position of the one left, so returning resumes there. A clip that will not load (or whose autoplay the browser
+ * blocked) stays in the list and offers Retry, Play and Next. Recordings are always labelled illustrative: playback
+ * length and speed are those of the recording, never production latency.
+ */
+import { attachmentIdentity, isVideoAttachment, type CheckDetail } from '@crvouga/atlas/reports/evidence-detail';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
+import { Alert, Anchor, Badge, Box, Button, Code, Flex, Grid, Group, List, Modal, NativeSelect, Stack, Switch, Text, Title } from '@mantine/core';
+import { IconAlertTriangle, IconPlayerPlay, IconPlayerSkipBack, IconPlayerSkipForward } from '@tabler/icons-react';
+import { useQuery } from '@tanstack/react-query';
+import { Link } from '@tanstack/react-router';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { reportJson } from '../evidence/api';
+import { attachmentSource } from '../evidence/artifacts';
+import { everyAttachment } from '../evidence/artifact-tags';
+import { ScopeNotice } from '../evidence/evidence-scope';
+import { duration, exactTime, plural, statusWord } from '../evidence/format';
+import { StatusMark } from '../evidence/marks';
+import { patched } from './navigate';
+import { playableVideo, playlistCounts, RECORDING_STATE_TEXT, recordingState, stepFrom, type PlaylistEntry } from './playlist-entries';
+
+/** Entries listed before "more"; the selected entry is always listed. */
+const LISTED = 50;
+/** Playback speeds offered. */
+const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const;
+/** Step names are shown with their Gherkin keyword when they have one. */
+const KEYWORDS = new Set(['given', 'when', 'then', 'and', 'but']);
+
+/** The evidence of one entry's check, read when the entry is on screen. */
+function useEntryDetail(entry: PlaylistEntry, enabled: boolean) {
+  return useQuery({
+    queryKey: ['evidence-detail', entry.backend ?? '', entry.layer, entry.kind ?? '', entry.check],
+    queryFn: ({ signal }) =>
+      reportJson<CheckDetail>(
+        `/evidence/detail/${encodeURIComponent(entry.backend!)}/${encodeURIComponent(entry.layer)}?check=${encodeURIComponent(entry.check)}${entry.kind ? `&kind=${encodeURIComponent(entry.kind)}` : ''}`,
+        signal
+      ),
+    enabled: enabled && entry.backend !== null && /^[0-9a-f]{64}$/.test(entry.layer),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+}
+
+/** The scenario in words: the steps the producer recorded, with the Gherkin keyword where it gave one. */
+function Scenario({ entry, detail }: { entry: PlaylistEntry; detail: CheckDetail | undefined }) {
+  const steps = detail?.check.steps ?? [];
+  return (
+    <Stack gap="xs" component="section" aria-label="Scenario">
+      <Title order={3}>{entry.title}</Title>
+      {steps.length > 0 && (
+        <List type="ordered" spacing="xs" aria-label="Steps">
+          {steps.map((step, index) => (
+            <List.Item key={`${step.id ?? step.name}:${index}`}>
+              {step.kind && KEYWORDS.has(step.kind.toLowerCase()) ? `${step.kind.charAt(0).toUpperCase()}${step.kind.slice(1).toLowerCase()} ` : ''}
+              {step.name}
+              {step.status && step.status !== 'passed' ? ` (${step.status})` : ''}
+            </List.Item>
+          ))}
+        </List>
+      )}
+      {entry.status === 'failed' && detail?.check.detail && (
+        <Alert color="red" title="Why it failed" role="status">
+          <Text component="div" lineClamp={4}>
+            {detail.check.detail}
+          </Text>
+        </Alert>
+      )}
+    </Stack>
+  );
+}
+
+/** Who recorded the entry and what it carries, in one line each. */
+function Facts({ entry }: { entry: PlaylistEntry }) {
+  return (
+    <Stack gap="xs" aria-label="Recording facts">
+      <Group gap="xs" wrap="wrap">
+        <StatusMark status={entry.status} size={14} />
+        <Text span inherit fw={600} data-outcome={entry.status}>
+          {statusWord(entry.status)}
+        </Text>
+        <Text span inherit c="dimmed">
+          {[environmentLabel(entry.environment), entry.producer, `recorded ${exactTime(entry.at)}`].join(' · ')}
+        </Text>
+      </Group>
+      {entry.tags.length > 0 && (
+        <Group gap="xs" aria-label="Tags">
+          {entry.tags.map((tag) => (
+            <Badge key={tag} variant="light" tt="none">
+              #{tag}
+            </Badge>
+          ))}
+        </Group>
+      )}
+      {entry.specPath && (
+        <Text component="div" c="dimmed">
+          Spec <Code>{entry.specPath}</Code>
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/** The one player. It is keyed by its entry, so a new clip is a fresh element and the previous one is gone. */
+function Clip({
+  entry,
+  speed,
+  autoPlay,
+  positions,
+  onEnded,
+  onFailed,
+  onNext,
+  onClose
+}: {
+  entry: PlaylistEntry;
+  speed: number;
+  autoPlay: boolean;
+  positions: Map<string, number>;
+  onEnded: () => PlaylistEntry | null;
+  onFailed: (id: string) => void;
+  onNext: (() => void) | null;
+  onClose: () => void;
+}) {
+  const state = recordingState(entry);
+  const detail = useEntryDetail(entry, state === 'playable');
+  const video = useRef<HTMLVideoElement>(null);
+  const [failed, setFailed] = useState(false);
+  const [blocked, setBlocked] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  const chosen = playableVideo(entry);
+  const attachments = useMemo(() => (detail.data ? everyAttachment(detail.data.check) : []), [detail.data]);
+  const movie = useMemo(() => {
+    const videos = attachments.filter(isVideoAttachment);
+    return videos.find((item) => attachmentIdentity(item) === chosen?.recording) ?? videos[0];
+  }, [attachments, chosen]);
+  const captions = useMemo(
+    () => attachments.filter((item) => (item.contentType ?? contentTypeOf(item.name)).toLowerCase().startsWith('text/vtt')),
+    [attachments]
+  );
+  const url = movie ? attachmentSource(movie, entry.layer).url : null;
+
+  useEffect(() => {
+    if (video.current) video.current.playbackRate = speed;
+  }, [speed]);
+
+  const play = () => {
+    const element = video.current;
+    if (!element) return;
+    setBlocked(false);
+    // `play()` rejects when the browser blocks it; a browser without a promise has nothing to catch.
+    const started = element.play() as Promise<void> | undefined;
+    started?.catch(() => setBlocked(true));
+  };
+
+  const developer = (
+    <Anchor
+      renderRoot={(props) => (
+        <Link {...props} to="/" search={patched({ tab: undefined, openRun: undefined, artifact: undefined, test: entry.key, layer: entry.layer })} resetScroll={false} activeOptions={{ exact: true }} onClick={onClose} />
+      )}
+    >
+      Developer details
+    </Anchor>
+  );
+
+  let body;
+  if (state !== 'playable') {
+    body = (
+      <Alert color="orange" title={RECORDING_STATE_TEXT[state].label} icon={<IconAlertTriangle size={16} aria-hidden="true" />} role="status" data-recording-state={state}>
+        {RECORDING_STATE_TEXT[state].meaning}
+      </Alert>
+    );
+  } else if (detail.isPending) {
+    body = (
+      <Text role="status" component="div" c="dimmed">
+        Loading the recording…
+      </Text>
+    );
+  } else if (detail.isError || !url) {
+    body = (
+      <Alert role="alert" color="orange" title="This recording cannot be played" data-clip-failed>
+        <Stack gap="xs" align="flex-start">
+          <Text component="div">{detail.isError ? 'Its evidence could not be read.' : 'The result names a recording, but no file can be played from here.'}</Text>
+          <Group gap="xs">
+            {detail.isError && (
+              <Button type="button" variant="light" onClick={() => void detail.refetch()}>
+                Try again
+              </Button>
+            )}
+            {onNext && (
+              <Button type="button" variant="light" onClick={onNext}>
+                Next clip
+              </Button>
+            )}
+          </Group>
+        </Stack>
+      </Alert>
+    );
+  } else {
+    body = (
+      <Stack gap="xs">
+        <ScopeNotice scope={chosen?.scope} name={movie!.name} />
+        <Box
+          key={attempt}
+          component="video"
+          ref={video}
+          src={url}
+          controls
+          preload="metadata"
+          aria-label={`Recording: ${movie!.description ?? movie!.name}`}
+          maw="100%"
+          w="100%"
+          mah="70vh"
+          data-playing={entry.id}
+          onLoadedMetadata={() => {
+            const element = video.current!;
+            element.playbackRate = speed;
+            const saved = positions.get(entry.id);
+            if (saved !== undefined && saved < (element.duration || Number.POSITIVE_INFINITY)) element.currentTime = saved;
+            if (autoPlay) play();
+          }}
+          onTimeUpdate={() => positions.set(entry.id, video.current!.currentTime)}
+          onEnded={() => {
+            positions.delete(entry.id);
+            const next = onEnded();
+            if (next && next.id === entry.id && video.current) {
+              video.current.currentTime = 0;
+              play();
+            }
+          }}
+          onError={() => {
+            setFailed(true);
+            onFailed(entry.id);
+          }}
+        >
+          {captions.map((caption) => {
+            const source = attachmentSource(caption, entry.layer).url;
+            return source ? <track key={source} kind="captions" src={source} label={caption.description ?? caption.name} /> : null;
+          })}
+        </Box>
+        {movie!.durationMs ? (
+          <Text component="div" c="dimmed">
+            Length of the recording: {duration(movie!.durationMs)}
+          </Text>
+        ) : null}
+        {captions.length > 0 && (
+          <Text component="div" c="dimmed">
+            Captions are offered in the player's captions control: {captions.map((caption) => caption.description ?? caption.name).join(', ')}.
+          </Text>
+        )}
+        {blocked && (
+          <Alert color="blue" role="status" title="Autoplay was blocked" data-autoplay-blocked>
+            <Stack gap="xs" align="flex-start">
+              <Text component="div">The browser did not start this clip by itself. Play it to continue.</Text>
+              <Button type="button" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={play}>
+                Play
+              </Button>
+            </Stack>
+          </Alert>
+        )}
+        {failed && (
+          <Alert color="orange" role="alert" title="This video cannot be played" data-clip-failed>
+            <Stack gap="xs" align="flex-start">
+              <Text component="div">The file could not be loaded, or this browser cannot play its format. It stays in the playlist.</Text>
+              <Group gap="xs">
+                <Button
+                  type="button"
+                  variant="light"
+                  onClick={() => {
+                    setFailed(false);
+                    setAttempt(attempt + 1);
+                  }}
+                >
+                  Retry
+                </Button>
+                {onNext && (
+                  <Button type="button" variant="light" onClick={onNext}>
+                    Next clip
+                  </Button>
+                )}
+              </Group>
+            </Stack>
+          </Alert>
+        )}
+      </Stack>
+    );
+  }
+  return (
+    <Stack gap="md" miw={0} aria-label={`Now showing ${entry.title}`} component="section" data-clip={entry.id}>
+      {body}
+      <Facts entry={entry} />
+      <Scenario entry={entry} detail={detail.data} />
+      <Text component="div" c="dimmed">
+        Illustrative recording of one run. Its length and speed are those of the recording, not production latency, and it does not approve the behavior for production.
+      </Text>
+      {developer}
+    </Stack>
+  );
+}
+
+/**
+ * The watch session for `entries`: opens as a modal over the explorer. `total` is how many results matched when the list
+ * holds only the newest of them, so the session says it is not the whole set. Closing it discards positions.
+ */
+export function WatchPlaylist({ entries, total, onClose }: { entries: readonly PlaylistEntry[]; total?: number; onClose: () => void }) {
+  const first = entries.find((entry) => recordingState(entry) === 'playable') ?? entries[0];
+  const [chosen, setChosen] = useState<string | null>(first?.id ?? null);
+  const [autoPlay, setAutoPlay] = useState(false);
+  const [speed, setSpeed] = useState<number>(1);
+  const [advance, setAdvance] = useState(true);
+  const [repeat, setRepeat] = useState(false);
+  const [failedIds, setFailedIds] = useState<ReadonlySet<string>>(new Set());
+  const [shown, setShown] = useState(LISTED);
+  const positions = useRef(new Map<string, number>());
+  const active = entries.find((entry) => entry.id === chosen) ?? first ?? null;
+  const counts = useMemo(() => playlistCounts(entries), [entries]);
+  const activeAt = active ? entries.indexOf(active) : -1;
+  const next = stepFrom(entries, active?.id ?? null, 1, repeat);
+  const previous = stepFrom(entries, active?.id ?? null, -1, repeat);
+  const select = (entry: PlaylistEntry, play: boolean) => {
+    setAutoPlay(play);
+    setChosen(entry.id);
+  };
+  const listed = entries.slice(0, Math.max(shown, activeAt + 1));
+  return (
+    <Modal opened onClose={onClose} title="Watch recordings" size="xl" centered>
+      <Stack gap="md">
+        <Text role="status" component="div" data-playlist-summary>
+          {plural(entries.length, 'result', 'results')}
+          {total !== undefined && total > entries.length ? ` (the newest of ${total.toLocaleString()} matching)` : ''}: {counts.playable} with a recording
+          {counts.unplayable > 0 ? `, ${counts.unplayable} whose recording is not available` : ''}
+          {counts['api-only'] > 0 ? `, ${counts['api-only']} API only` : ''}
+          {counts.none > 0 ? `, ${counts.none} with no recording` : ''}. {plural(counts.failed, 'failed result', 'failed results')}
+          {counts.failed > 0 ? ' kept in the playlist' : ''}.
+        </Text>
+        {entries.length === 0 && (
+          <Text component="div" c="dimmed">
+            No result is in this set, so there is nothing to watch.
+          </Text>
+        )}
+        {active && (
+          <Group role="group" aria-label="Playlist controls" align="flex-end" gap="md" wrap="wrap">
+            <Button type="button" variant="default" leftSection={<IconPlayerSkipBack size={16} aria-hidden="true" />} disabled={!previous} onClick={() => previous && select(previous, true)}>
+              Previous clip
+            </Button>
+            <Button type="button" variant="default" rightSection={<IconPlayerSkipForward size={16} aria-hidden="true" />} disabled={!next} onClick={() => next && select(next, true)}>
+              Next clip
+            </Button>
+            <NativeSelect
+              label="Playback speed"
+              value={String(speed)}
+              onChange={(event) => setSpeed(Number(event.currentTarget.value))}
+              data={SPEEDS.map((value) => ({ value: String(value), label: `${value}×` }))}
+            />
+            <Switch label="Play the next clip when one ends" checked={advance} onChange={(event) => setAdvance(event.currentTarget.checked)} />
+            <Switch label="Repeat" description="Start over after the last clip, or replay a clip when not advancing" checked={repeat} onChange={(event) => setRepeat(event.currentTarget.checked)} />
+          </Group>
+        )}
+        {active && (
+          <Text c="dimmed" component="div" size="sm">
+            Previous and next skip results with nothing to play; select one in the list to see why.
+          </Text>
+        )}
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, md: 8 }}>
+            {active && (
+              <Clip
+                key={active.id}
+                entry={active}
+                speed={speed}
+                autoPlay={autoPlay}
+                positions={positions.current}
+                onEnded={() => {
+                  const target = advance ? stepFrom(entries, active.id, 1, repeat) : repeat ? active : null;
+                  if (target && target.id !== active.id) select(target, true);
+                  return target;
+                }}
+                onFailed={(id) => setFailedIds((held) => new Set(held).add(id))}
+                onNext={next ? () => select(next, true) : null}
+                onClose={onClose}
+              />
+            )}
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, md: 4 }}>
+            <Stack gap="xs" component="section" aria-label="Playlist">
+              <Title order={3}>Playlist</Title>
+              <List spacing="xs" listStyleType="none">
+                {listed.map((entry, index) => {
+                  const state = recordingState(entry);
+                  const here = entry.id === active?.id;
+                  return (
+                    <List.Item key={entry.id} data-entry={entry.id} data-status={entry.status} data-recording-state={state}>
+                      <Button
+                        type="button"
+                        variant={here ? 'light' : 'subtle'}
+                        fullWidth
+                        h="auto"
+                        py="xs"
+                        justify="flex-start"
+                        aria-current={here ? 'true' : undefined}
+                        aria-label={`${index + 1}. ${entry.title}, ${statusWord(entry.status)}, ${failedIds.has(entry.id) ? 'could not be loaded' : RECORDING_STATE_TEXT[state].label}`}
+                        onClick={() => select(entry, state === 'playable')}
+                      >
+                        <Flex component="span" gap="xs" wrap="nowrap" align="flex-start">
+                          <StatusMark status={entry.status} size={14} />
+                          <Flex component="span" direction="column" align="flex-start">
+                            <Text span inherit ta="left">
+                              {entry.title}
+                            </Text>
+                            <Text span inherit c="dimmed" size="xs" ta="left">
+                              {statusWord(entry.status)} · {environmentLabel(entry.environment)} ·{' '}
+                              {failedIds.has(entry.id) ? 'Could not be loaded' : RECORDING_STATE_TEXT[state].label}
+                            </Text>
+                          </Flex>
+                        </Flex>
+                      </Button>
+                    </List.Item>
+                  );
+                })}
+              </List>
+              {entries.length > listed.length && (
+                <Button type="button" variant="subtle" onClick={() => setShown(listed.length + LISTED)}>
+                  Show more ({entries.length - listed.length} more)
+                </Button>
+              )}
+            </Stack>
+          </Grid.Col>
+        </Grid>
+      </Stack>
+    </Modal>
+  );
+}