@crvouga/atlas 1.9.0 → 1.11.0

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

@@ -0,0 +1,163 @@
+/**
+ * @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 { ReviewAvailability, ReviewCollection } from '@crvouga/atlas/reports/review-collection';
+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 ?? []
+  }));
+}
+
+/**
+ * The entries of a review collection as playlist entries, in the collection's order (never re-sorted). Each is what the
+ * collection froze: its recorded status and time. An entry whose layer is gone has no backend to read, so it is said to
+ * have no recording that can be played rather than dropped. An entry that names one recording lists only that one.
+ */
+export function entriesFromCollection(collection: Pick<ReviewCollection, 'entries'>, availability: readonly ReviewAvailability[]): PlaylistEntry[] {
+  const gone = new Set(availability.filter((item) => item.state === 'unavailable').map((item) => item.entry));
+  return collection.entries.map((entry) => {
+    const videos = ((entry.snapshot.videos ?? []) as readonly VideoRef[]).filter((video) => entry.source.recording === undefined || video.recording === entry.source.recording);
+    return {
+      id: entry.id,
+      title: entry.snapshot.title,
+      key: entry.snapshot.testKey,
+      specPath: entry.snapshot.specPath,
+      status: entry.snapshot.status,
+      environment: entry.snapshot.environment,
+      producer: entry.snapshot.producer,
+      at: entry.snapshot.recordedAtMs,
+      layer: entry.source.layer,
+      backend: gone.has(entry.id) ? null : entry.snapshot.backend,
+      check: entry.source.check,
+      kind: entry.source.kind ?? null,
+      tags: [...new Set(videos.flatMap((video) => video.tags ?? []))].sort(),
+      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,500 @@
+/**
+ * @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 { clock, TEXT_KIND_WORD, type RecordingFocus } from './recording-text';
+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']);
+
+/** Where the evidence of an entry's check is read from, or null when the entry names no layer that can be read. */
+export function entryDetailQuery(entry: PlaylistEntry) {
+  if (entry.backend === null || !/^[0-9a-f]{64}$/.test(entry.layer)) return null;
+  const backend = entry.backend;
+  return {
+    queryKey: ['evidence-detail', backend, entry.layer, entry.kind ?? '', entry.check],
+    queryFn: ({ signal }: { signal?: AbortSignal }) =>
+      reportJson<CheckDetail>(
+        `/evidence/detail/${encodeURIComponent(backend)}/${encodeURIComponent(entry.layer)}?check=${encodeURIComponent(entry.check)}${entry.kind ? `&kind=${encodeURIComponent(entry.kind)}` : ''}`,
+        signal
+      ),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  };
+}
+
+/** The evidence of one entry's check, read when the entry is on screen. */
+function useEntryDetail(entry: PlaylistEntry, enabled: boolean) {
+  const query = entryDetailQuery(entry);
+  return useQuery({
+    queryKey: query?.queryKey ?? ['evidence-detail', '', entry.layer, entry.kind ?? '', entry.check],
+    queryFn: query?.queryFn ?? (() => Promise.reject(new Error('no evidence to read'))),
+    enabled: enabled && query !== null,
+    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>
+  );
+}
+
+/** Where a search result opened: which words, from what, in which attempt, and whether the player could go to the time. */
+function FoundMoment({ focus, seek }: { focus: RecordingFocus; seek: 'applied' | 'unavailable' | null }) {
+  const timed = focus.startMs !== null && focus.endMs !== null;
+  return (
+    <Alert color="blue" variant="light" title="Found in this recording" role="status" data-found-moment>
+      <Stack gap="xs">
+        <Text component="div">
+          {TEXT_KIND_WORD[focus.kind]}
+          {focus.attemptLabel ? ` · ${focus.attemptLabel}` : ''}
+          {timed ? ` · ${clock(focus.startMs!)}–${clock(focus.endMs!)}` : ''}
+        </Text>
+        <Text component="div">Indexed text: {focus.text}</Text>
+        {focus.generated && (
+          <Text component="div" c="dimmed">
+            Generated text; it may contain errors.
+          </Text>
+        )}
+        {seek === 'unavailable' && (
+          <Text component="div" data-seek-unavailable>
+            Seeking is unavailable: {focus.startMs === null ? 'the text has no usable time' : 'the recording it belongs to or its time could not be reached'}, so the recording is opened at its start and not at a guessed moment.
+          </Text>
+        )}
+      </Stack>
+    </Alert>
+  );
+}
+
+/** 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,
+  focus,
+  positions,
+  onEnded,
+  onFailed,
+  onNext,
+  onClose
+}: {
+  entry: PlaylistEntry;
+  speed: number;
+  autoPlay: boolean;
+  /** A moment found by searching inside recordings: its video is selected and, when its time is usable, played from there. */
+  focus: RecordingFocus | null;
+  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 [seek, setSeek] = useState<'applied' | 'unavailable' | null>(null);
+  const chosen = playableVideo(entry);
+  const attachments = useMemo(() => (detail.data ? everyAttachment(detail.data.check) : []), [detail.data]);
+  const videos = useMemo(() => attachments.filter(isVideoAttachment), [attachments]);
+  const found = focus?.recording ? videos.find((item) => attachmentIdentity(item) === focus.recording) : undefined;
+  const movie = useMemo(() => found ?? videos.find((item) => attachmentIdentity(item) === chosen?.recording) ?? videos[0], [found, videos, 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">
+        {focus && <FoundMoment focus={focus} seek={seek} />}
+        <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;
+            if (focus) {
+              // Seek only to a time the track gave and the recording can reach; otherwise open it at the start and say so.
+              const reachable = (found !== undefined || !focus.recording) && focus.startMs !== null && (!Number.isFinite(element.duration) || focus.startMs / 1000 < element.duration);
+              if (reachable) element.currentTime = focus.startMs! / 1000;
+              setSeek(reachable ? 'applied' : 'unavailable');
+              if (autoPlay) play();
+              return;
+            }
+            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. `focus` opens it on one found moment: that
+ * result, that attempt's video and, when the time is usable, that time. `initial` is the entry to start on when there is no
+ * `focus`, and `title` the heading. Closing it discards positions.
+ */
+export function WatchPlaylist({ entries, total, focus, onClose, initial, title = 'Watch recordings' }: { entries: readonly PlaylistEntry[]; total?: number; focus?: RecordingFocus; onClose: () => void; initial?: string; title?: string }) {
+  const first = entries.find((entry) => entry.id === initial) ?? entries.find((entry) => recordingState(entry) === 'playable') ?? entries[0];
+  const [chosen, setChosen] = useState<string | null>(focus && entries.some((entry) => entry.id === focus.entryId) ? focus.entryId : (first?.id ?? null));
+  // Selecting anything else leaves the found moment behind: it describes one video and one time.
+  const [moment, setMoment] = useState<RecordingFocus | null>(focus ?? 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) => {
+    setMoment(null);
+    setAutoPlay(play);
+    setChosen(entry.id);
+  };
+  const listed = entries.slice(0, Math.max(shown, activeAt + 1));
+  return (
+    <Modal opened onClose={onClose} title={title} 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}
+                focus={moment && moment.entryId === active.id ? moment : null}
+                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>
+  );
+}