@crvouga/atlas 1.17.0 → 1.19.0

package/packages/visualizer/src/evidence/scoped-summary.test.ts

@@ -0,0 +1,62 @@
+import type { TestResultEntry } from '@crvouga/atlas/reports/test-catalog';
+import { expect, test } from 'bun:test';
+
+import { entriesInScope, scopedFigures } from './scoped-summary';
+
+const entry = (i: number, over: Partial<TestResultEntry> = {}): TestResultEntry => ({
+  at: 1_000 + i, status: 'passed', durationMs: 9_000, environment: 'desktop-web', producer: 'web', kind: 'checks', parameters: {}, branch: 'main',
+  sha: 'a'.repeat(40), runUrl: null, run: `run:r${i}`, layer: `l${i}`, backend: 'one', detail: '', ...over
+});
+const KEY = '["specs/a.feature","a"]';
+const latency = (value: number, over: Record<string, unknown> = {}) => ({ name: 'save', kind: 'product-latency', unit: 'ms', value, from: 'tap', to: 'saved', ...over });
+
+test('no history leaves reliability and product latency unknown, never good', () => {
+  const figures = scopedFigures(KEY, [], { environment: 'desktop-web' });
+  expect(figures.reliability.tone).toBe('unknown');
+  expect(figures.reliability.headline).toContain('unknown');
+  expect(figures.latency).toHaveLength(1);
+  expect(figures.latency[0]!.headline).toContain('unknown');
+  // The duration of the test is not a stand-in for the product's response time.
+  expect(figures.latency[0]!.qualifiers.join(' ')).toContain('not product latency');
+});
+
+test('a rate always names its independent executions and a small sample is insufficient evidence', () => {
+  const figures = scopedFigures(KEY, [entry(0), entry(1), entry(2, { status: 'failed' })], { environment: 'desktop-web' });
+  expect(figures.reliability.headline).toBe('2 of 3 independent executions passed in the end (66.7%).');
+  expect(figures.reliability.tone).toBe('weak');
+  expect(figures.reliability.qualifiers.join(' ')).toContain('Insufficient evidence');
+  expect(figures.reliability.qualifiers.join(' ')).toContain('First-try success is unknown');
+});
+
+test('the scope is the shown result\'s environment: another environment is not pooled into it', () => {
+  const history = [entry(0), entry(1, { environment: 'ios', status: 'failed' }), entry(2, { environment: 'ios', status: 'failed' })];
+  expect(entriesInScope(history, { environment: 'desktop-web' })).toHaveLength(1);
+  expect(entriesInScope(history, { environment: null })).toHaveLength(3);
+  const scoped = scopedFigures(KEY, history, { environment: 'desktop-web' });
+  expect(scoped.reliability.headline).toContain('1 of 1 independent execution passed');
+  expect(scoped.reliability.qualifiers[0]).toContain('desktop-web');
+  // With no environment named the executions are pooled, and the figure says so.
+  const pooled = scopedFigures(KEY, history, { environment: null });
+  expect(pooled.reliability.qualifiers.join(' ')).toMatch(/environments are pooled/i);
+});
+
+test('product latency is read only from named measurements, with withheld percentiles explained', () => {
+  const history = [entry(0, { latency: [latency(300)] }), entry(1, { latency: [latency(500, { limit: 400 })] }), entry(2)];
+  const [line] = scopedFigures(KEY, history, { environment: 'desktop-web' }).latency;
+  expect(line!.headline).toContain('save');
+  expect(line!.headline).toContain('no percentile can be stated');
+  expect(line!.tone).toBe('weak');
+  const text = line!.qualifiers.join(' ');
+  expect(text).toContain('2 observations');
+  expect(text).toContain('1 observation over it');
+  expect(text).toContain('p50 needs 5 observations');
+});
+
+test('enough observations state p50 and p95 with the budget and its breaches', () => {
+  const history = Array.from({ length: 20 }, (_, i) => entry(i, { latency: [latency(100 + i * 10, { limit: 250 })] }));
+  const [line] = scopedFigures(KEY, history, { environment: 'desktop-web' }).latency;
+  expect(line!.headline).toContain('p50');
+  expect(line!.headline).toContain('p95');
+  expect(line!.tone).toBe('figure');
+  expect(line!.qualifiers.join(' ')).toContain('20 observations');
+});

package/packages/visualizer/src/evidence/scoped-summary.ts

@@ -0,0 +1,118 @@
+/**
+ * @module Scoped behavior summary
+ *
+ * The short account that sits beside a behavior's written promise and recording: what the selected result says, how
+ * reliable the check has been, and how quickly the product responded. It does not compute anything of its own. The
+ * outcome is {@link outcomeHeadline}; reliability is `reliability` and product latency is `latencyReview` from the
+ * reports library, read over the history of the same check in the same environment as the recording shown. This module
+ * only chooses the scope and puts the qualified figures into short sentences, keeping every qualification that makes a
+ * figure honest: how many independent executions it rests on, that a small sample is not established, which notes warn
+ * against reading it as representative, and that absent evidence is unknown, never good.
+ */
+import { formatLatency, latencyReview, type LatencyReview } from '@crvouga/atlas/reports/latency';
+import { reliability, scopeText, type ReliabilityDocument, type ReliabilityScope } from '@crvouga/atlas/reports/reliability';
+import type { TestResultEntry } from '@crvouga/atlas/reports/test-catalog';
+
+import { plural } from './format';
+
+/** One line of the summary: the figure in words, and what qualifies it. */
+export type SummaryLine = {
+  readonly headline: string;
+  /** What a reader must keep in mind: sample size, scope, warnings. Never empty for a figure. */
+  readonly qualifiers: readonly string[];
+  /** `figure`: a number supported by evidence. `unknown`: there is no evidence to state. `weak`: a figure that its own qualifiers say not to rely on. */
+  readonly tone: 'figure' | 'weak' | 'unknown';
+};
+
+/** The scope the summary describes: the environment of the shown result, so environments are never pooled silently. */
+export type SummaryScope = {
+  /** The environment of the result shown; null when it recorded none (then every environment is pooled and the summary says so). */
+  readonly environment: string | null;
+};
+
+const percent = (rate: number | null) => (rate === null ? 'no rate' : `${Math.round(rate * 1000) / 10}%`);
+
+/** The reliability scope for a summary scope. */
+export function reliabilityScope(scope: SummaryScope): ReliabilityScope {
+  return scope.environment === null ? {} : { environment: [scope.environment] };
+}
+
+/** The recorded results of the summary's scope: those of its environment, or all when it names none. */
+export function entriesInScope(entries: readonly TestResultEntry[], scope: SummaryScope): readonly TestResultEntry[] {
+  return scope.environment === null ? entries : entries.filter((entry) => entry.environment === scope.environment);
+}
+
+/**
+ * Reliability in one sentence and its qualifiers. A count of independent executions always comes with the figure;
+ * fewer than the minimum is "Insufficient evidence"; none is unknown. The library's warning notes are carried over.
+ */
+export function reliabilityLine(document: ReliabilityDocument): SummaryLine {
+  const { eventual, firstAttempt } = document;
+  const where = scopeText(document.scope);
+  if (document.sample === 'none') {
+    return {
+      headline: 'Reliability is unknown: no independent execution is recorded in this scope.',
+      qualifiers: [`Scope: ${where}.`],
+      tone: 'unknown'
+    };
+  }
+  const qualifiers = [`Scope: ${where}.`];
+  if (document.sample === 'insufficient') {
+    qualifiers.push(`Insufficient evidence: at least ${document.minimumExecutions} independent executions are needed before a rate means much.`);
+  }
+  qualifiers.push(
+    firstAttempt.executions
+      ? `${firstAttempt.passed} of ${plural(firstAttempt.executions, 'execution', 'executions')} passed first time.`
+      : 'First-try success is unknown: no tries were recorded.'
+  );
+  for (const note of document.notes) if (note.severity === 'warning') qualifiers.push(note.message);
+  return {
+    headline: `${eventual.passed} of ${plural(eventual.executions, 'independent execution', 'independent executions')} passed in the end (${percent(eventual.rate)}).`,
+    qualifiers,
+    tone: document.sample === 'insufficient' || document.notes.some((note) => note.severity === 'warning') ? 'weak' : 'figure'
+  };
+}
+
+/**
+ * Product latency: one line per measurement a producer named as product latency. The test's own duration is never read
+ * here. Percentiles the evidence cannot support are said to be withheld with their reason; with no measurement the
+ * answer is unknown, not fast.
+ */
+export function latencyLines(review: LatencyReview): readonly SummaryLine[] {
+  if (review.metrics.length === 0) {
+    return [
+      {
+        headline: 'Product latency is unknown: no product-latency measurement is recorded.',
+        qualifiers: ['The duration of the test is not product latency and is not shown here.'],
+        tone: 'unknown'
+      }
+    ];
+  }
+  return review.metrics.flatMap(({ metric, groups }) =>
+    groups.map<SummaryLine>((summary) => {
+      const figures = [
+        summary.p50 === undefined ? undefined : `p50 ${formatLatency(summary.p50, metric.unit)}`,
+        summary.p95 === undefined ? undefined : `p95 ${formatLatency(summary.p95, metric.unit)}`
+      ].filter((figure): figure is string => figure !== undefined);
+      const qualifiers = [`${plural(summary.samples, 'observation', 'observations')}${summary.lowerBound ? ', including some that did not complete (lower bounds)' : ''}.`];
+      if (summary.budget !== undefined) {
+        qualifiers.push(`Budget ${formatLatency(summary.budget, metric.unit)}: ${plural(summary.breaches, 'observation', 'observations')} over it.`);
+      }
+      qualifiers.push(...summary.withheld, ...summary.gaps);
+      return {
+        headline: `${metric.name}${metric.boundary.label ? ` (${metric.boundary.label})` : ''}: ${figures.length ? figures.join(', ') : 'no percentile can be stated'}.`,
+        qualifiers,
+        tone: figures.length > 0 && summary.gaps.length === 0 ? 'figure' : 'weak'
+      };
+    })
+  );
+}
+
+/** Reliability and product latency of one check in a scope, worked out from its recorded history. */
+export function scopedFigures(key: string, history: readonly TestResultEntry[], scope: SummaryScope) {
+  const entries = entriesInScope(history, scope);
+  return {
+    reliability: reliabilityLine(reliability(key, history, reliabilityScope(scope))),
+    latency: latencyLines(latencyReview(entries))
+  };
+}

package/packages/visualizer/src/evidence/spec-texts.ts

@@ -0,0 +1,88 @@
+/**
+ * @module Reading spec texts for search and indexes
+ *
+ * The finder and the project-wide behavior index both need the text of many specs, not only the one on screen. They
+ * read it here: a few files at a time, each landing as it arrives so a search can use what is read so far, through the
+ * same query cache the spec pages use (so a file is never fetched twice and a page opened afterwards finds it ready).
+ */
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { keys, specKey, useAdapter } from '../data/queries';
+
+/** How many spec files are read at once. */
+const READERS = 4;
+
+/**
+ * Reads the text of every spec in `files`, a few at a time, once `enabled`. Each file lands as it arrives, so a search
+ * can use what is read so far; `read` of `total` say how far it is, and `failed` how many could not be read at all
+ * (`texts` holds an empty text for them). Files the query cache already holds are available at once, without a request.
+ * Setting `open` (the finder opening) gives the files that could not be read another chance.
+ */
+export function useSpecTexts(files: readonly string[], enabled: boolean, open: boolean) {
+  const adapter = useAdapter();
+  const client = useQueryClient();
+  const source = specKey(adapter);
+  const cache = useRef(new Map<string, string>());
+  const unreadable = useRef(new Set<string>());
+  const [texts, setTexts] = useState<ReadonlyMap<string, string>>(() => new Map());
+  const [pending, setPending] = useState(false);
+  const [failedFiles, setFailedFiles] = useState<ReadonlySet<string>>(() => new Set());
+  const key = files.join('\n');
+  // Opening the finder is another chance for the files that could not be read.
+  useEffect(() => {
+    if (!open || unreadable.current.size === 0) return;
+    for (const file of unreadable.current) cache.current.delete(file);
+    unreadable.current.clear();
+    setFailedFiles(new Set());
+  }, [open]);
+  useEffect(() => {
+    if (!enabled) return;
+    const wanted = key.length === 0 ? [] : key.split('\n');
+    let cancelled = false;
+    // What the pages already read is not asked for again.
+    let seeded = false;
+    for (const file of wanted) {
+      if (cache.current.has(file)) continue;
+      const held = client.getQueryData<string>(keys.specFile(source, file));
+      if (typeof held === 'string') {
+        cache.current.set(file, held);
+        seeded = true;
+      }
+    }
+    if (seeded) setTexts(new Map(cache.current));
+    const missing = wanted.filter((file) => !cache.current.has(file));
+    if (missing.length === 0) {
+      setPending(false);
+      return;
+    }
+    setPending(true);
+    let cursor = 0;
+    const pull = async () => {
+      for (;;) {
+        const file = missing[cursor++];
+        if (file === undefined || cancelled) return;
+        let text = '';
+        try {
+          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file), retry: false });
+        } catch {
+          text = '';
+          unreadable.current.add(file);
+        }
+        if (cancelled) return;
+        cache.current.set(file, text);
+        setTexts(new Map(cache.current));
+        if (unreadable.current.has(file)) setFailedFiles(new Set(unreadable.current));
+      }
+    };
+    void Promise.all(Array.from({ length: READERS }, pull)).then(() => {
+      if (!cancelled) setPending(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [adapter, client, enabled, key, source]);
+  const read = useMemo(() => files.filter((file) => texts.has(file)).length, [files, texts]);
+  const failed = useMemo(() => files.filter((file) => failedFiles.has(file)).length, [files, failedFiles]);
+  return { texts, pending, total: files.length, read, failed };
+}

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

@@ -20,13 +20,13 @@ import { StatusMark } from '../evidence/marks';
 import { useArtifactList } from './catalog';
 import { FreezeCollection } from './collections';
 import { FilterBar } from './filters';
-import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+import { patched, useExplorerNavigate, useExplorerSearch, useWatchAddress } from './navigate';
 import { runName } from './parts';
 import { entriesFromArtifacts } from './playlist-entries';
 import { WatchPlaylist } from './playlist';
 import { RecordingTextSearch } from './RecordingTextSearch';
 import { filtered, filterOf, NO_FILTERS } from './search';
-import { filterParams } from '@crvouga/atlas/reports/artifact-query';
+import { filterParams, forArtifacts } from '@crvouga/atlas/reports/artifact-query';
 
 const ARTIFACT_ROWS = 50;
 
@@ -34,12 +34,13 @@ const ARTIFACT_ROWS = 50;
 export function ArtifactsView() {
   const search = useExplorerSearch();
   const go = useExplorerNavigate();
-  const filter = useMemo(() => filterOf(search), [search]);
+  // Recording completeness belongs to a run, not to a recorded result: the Artifacts tab never asks for it.
+  const filter = useMemo(() => forArtifacts(filterOf(search)), [search]);
   const narrow = filtered(search);
   const answer = useArtifactList(filter);
   const now = useNow();
   const [shown, setShown] = useState(ARTIFACT_ROWS);
-  const [watching, setWatching] = useState(false);
+  const watch = useWatchAddress();
   const [freezing, setFreezing] = useState(false);
   const entries = useMemo(() => (answer.data && !answer.data.unsupported ? entriesFromArtifacts(answer.data.list.results) : []), [answer.data]);
   if (answer.isPending)
@@ -88,7 +89,7 @@ export function ArtifactsView() {
       )}
       {list.results.length > 0 && (
         <Group my="sm" gap="sm">
-          <Button type="button" variant="filled" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => setWatching(true)}>
+          <Button type="button" variant="filled" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => watch.open()}>
             Watch these {plural(list.results.length, 'result', 'results')}
           </Button>
           {!staticEvidence && (
@@ -98,7 +99,7 @@ export function ArtifactsView() {
           )}
         </Group>
       )}
-      {watching && <WatchPlaylist entries={entries} total={list.total} onClose={() => setWatching(false)} />}
+      {watch.watching && <WatchPlaylist entries={entries} total={list.total} initial={watch.clip} onSelect={watch.select} onClose={watch.close} />}
       {freezing && <FreezeCollection results={list.results} total={list.total} filterQuery={filterParams(filter).toString()} onClose={() => setFreezing(false)} />}
       {list.results.length > 0 && <RecordingTextSearch entries={entries} total={list.total} />}
       {list.results.length > 0 && (

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

@@ -198,7 +198,7 @@ export function Explorer() {
           {model && (model.tests.length > 0 || model.summary.runs > 0) && (
             <Tabs
               value={search.tab ?? 'tests'}
-              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' || value === 'collections' || value === 'compare' || value === 'health' ? value : undefined, test: undefined, openRun: undefined, layer: undefined, artifact: undefined, collection: undefined, rev: undefined, pair: undefined })}
+              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' || value === 'collections' || value === 'compare' || value === 'health' ? value : undefined, test: undefined, openRun: undefined, layer: undefined, artifact: undefined, collection: undefined, rev: undefined, pair: undefined, watch: undefined, watchClip: undefined })}
             >
               <Tabs.List aria-label="Explorer view">
                 <Tabs.Tab

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

@@ -29,7 +29,7 @@ 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';
+import { patched, useExplorerNavigate, useExplorerSearch, useWatchAddress } from './navigate';
 import { runName } from './parts';
 import { filtered, filterOf, NO_FILTERS } from './search';
 const RUN_ROWS = 50;
@@ -93,15 +93,39 @@ function ownerText(video: VideoRef): string {
   return 'the test';
 }
 const UNAVAILABLE = 'Listed in the report, but its file was never stored, so it cannot be played.';
-/** The unavailable references of a video summary and why they cannot be watched. */
+const MISSING = 'The run says it stored this file, but its bundle no longer holds it, so it cannot be played.';
+/** The unavailable references of a video summary and why they cannot be watched: never stored, or stored and then gone. */
 function Unavailable({ videos }: { videos: VideoCounts }) {
   if (!videos.unavailable) return null;
+  const missing = Math.min(videos.missing ?? 0, videos.unavailable);
   return (
     <Text component="div" size="xs" c="dimmed" data-video-unavailable>
-      <IconAlertTriangle size={16} aria-hidden="true" /> {plural(videos.unavailable, 'video', 'videos')} unavailable. {UNAVAILABLE}
+      <IconAlertTriangle size={16} aria-hidden="true" /> {plural(videos.unavailable, 'video', 'videos')} unavailable.{' '}
+      {missing > 0 && <Text span inherit data-video-missing>{missing === videos.unavailable ? MISSING : `${plural(missing, 'video', 'videos')}: ${MISSING}`}{' '}</Text>}
+      {missing < videos.unavailable && UNAVAILABLE}
     </Text>
   );
 }
+/** Words for a run's recording completeness, apart from how its tests went. */
+const COMPLETENESS_WORDS: Record<string, string> = { complete: 'complete', incomplete: 'incomplete', 'none-expected': 'none expected', unknown: 'unknown' };
+/** A run's recording completeness in its row: how many expected recordings were published, said in words and independent of its outcomes. Nothing when its layers declared no expectations (unknown is not shown as complete). */
+function RunRecordings({ run }: { run: RunSummary }) {
+  const recordings = run.recordings;
+  if (!recordings) return null;
+  const word = COMPLETENESS_WORDS[recordings.state] ?? 'unknown';
+  const text = recordings.expected > 0 ? `Recordings ${recordings.published} of ${recordings.expected}: ${word}` : `Recordings: ${word}`;
+  return (
+    <Badge
+      size="sm"
+      variant="light"
+      color={recordings.state === 'incomplete' ? 'orange' : 'gray'}
+      data-recordings={recordings.state}
+      title={recordings.state === 'incomplete' ? 'Some expected recordings were not published. The test outcomes are unaffected.' : undefined}
+    >
+      {text}
+    </Badge>
+  );
+}
 /** A run's videos in its row: a link to the recordings, how many references they come from, and what cannot be played. */
 function RunVideos({ run }: { run: RunSummary }) {
   const videos = run.videos;
@@ -210,7 +234,7 @@ const RUN_SORTS = [
   { id: 'relevance', label: 'Best match' }
 ] as const;
 /** What a filter is called when a page says a server could not apply it. */
-const FILTER_WORDS: Partial<Record<FilterName, string>> = { artifactTag: 'tag', type: 'media type', label: 'label', domain: 'domain', spec: 'spec' };
+const FILTER_WORDS: Partial<Record<FilterName, string>> = { artifactTag: 'tag', type: 'media type', label: 'label', domain: 'domain', spec: 'spec', recordings: 'recording completeness' };
 /** Says which filters the list is not narrowed by, because the server that answered ignored them. */
 export function NotApplied({ names, noun }: { names: readonly FilterName[]; noun: string }) {
   if (!names.length) return null;
@@ -383,6 +407,7 @@ function RunTable() {
                 <Table.Td>{formatMs(run.spanMs)}</Table.Td>
                 <Table.Td>
                   <RunVideos run={run} />
+                  <RunRecordings run={run} />
                 </Table.Td>
                 <Table.Td data-tags>{run.artifactTags?.map((tag) => `#${tag}`).join(' ') || '—'}</Table.Td>
                 <Table.Td>
@@ -471,7 +496,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
       ),
     [narrowedResults, status, statusFilters, model]
   );
-  const [watching, setWatching] = useState(false);
+  const watch = useWatchAddress();
   const playlist = useMemo(() => entriesFromRun(filtered, detail.data?.layers), [filtered, detail.data]);
   const bySpec = useMemo(() => {
     const groups = new Map<string, RunResult[]>();
@@ -651,11 +676,11 @@ function RunDetailView({ runKey }: { runKey: string }) {
         </Text>
       )}
       {filtered.length > 0 && (
-        <Button type="button" variant="filled" my="sm" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => setWatching(true)}>
+        <Button type="button" variant="filled" my="sm" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => watch.open()}>
           Watch these {plural(filtered.length, 'result', 'results')}
         </Button>
       )}
-      {watching && <WatchPlaylist entries={playlist} onClose={() => setWatching(false)} />}
+      {watch.watching && <WatchPlaylist entries={playlist} initial={watch.clip} onSelect={watch.select} onClose={watch.close} />}
       {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/collections.tsx

@@ -22,7 +22,7 @@ import { reportAssetUrl, reportJson, ReportsError } from '../evidence/api';
 import { exactTime, plural, shortSha, statusWord } from '../evidence/format';
 import { StatusMark } from '../evidence/marks';
 import { formatTimecode, parseTagsField, parseTimecode, sourceSpread } from './collection-model';
-import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+import { patched, useExplorerNavigate, useExplorerSearch, useWatchAddress } from './navigate';
 import { runName } from './parts';
 import { WatchPlaylist } from './playlist';
 import { entriesFromCollection, RECORDING_STATE_TEXT, recordingState } from './playlist-entries';
@@ -155,7 +155,7 @@ function CollectionPage({ id, revision }: { id: string; revision: number | undef
   const go = useExplorerNavigate();
   const client = useQueryClient();
   const [token, setToken] = usePublishToken();
-  const [watching, setWatching] = useState<string | null | false>(false);
+  const watch = useWatchAddress();
   const detail = useQuery({
     queryKey: ['review-collection', id, revision ?? 'newest'],
     queryFn: ({ signal }) => reportJson<ReviewCollectionDetail>(`/review-collections/detail?id=${encodeURIComponent(id)}${revision ? `&revision=${revision}` : ''}`, signal),
@@ -235,7 +235,7 @@ function CollectionPage({ id, revision }: { id: string; revision: number | undef
         </Text>
       </Alert>
       <Group gap="sm" align="flex-end" wrap="wrap">
-        <Button type="button" variant="filled" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => setWatching(null)} disabled={collection.entries.length === 0}>
+        <Button type="button" variant="filled" leftSection={<IconPlayerPlay size={16} aria-hidden="true" />} onClick={() => watch.open()} disabled={collection.entries.length === 0}>
           Watch these {plural(collection.entries.length, 'entry', 'entries')}
         </Button>
         <Button component="a" href={exportHref} download leftSection={<IconDownload size={16} aria-hidden="true" />}>
@@ -244,7 +244,7 @@ function CollectionPage({ id, revision }: { id: string; revision: number | undef
         <TextInput label="Share link" description="Opening it needs the same read access as this report." value={shareLink} readOnly onFocus={(event) => event.currentTarget.select()} miw={280} />
       </Group>
       <TokenField token={token} onChange={setToken} />
-      {watching !== false && <WatchPlaylist title={collection.title} entries={playlist} initial={watching ?? undefined} onClose={() => setWatching(false)} />}
+      {watch.watching && <WatchPlaylist title={collection.title} entries={playlist} initial={watch.clip} onSelect={watch.select} onClose={watch.close} />}
       {notesOf(undefined).length > 0 && (
         <Stack gap="xs" component="section" aria-label="Notes on the collection">
           <Title order={3}>Notes on the collection</Title>
@@ -309,7 +309,7 @@ function CollectionPage({ id, revision }: { id: string; revision: number | undef
                       {RECORDING_STATE_TEXT[state].label}
                     </Text>
                     {state === 'playable' && (
-                      <Button type="button" size="compact-sm" variant="light" leftSection={<IconPlayerPlay size={14} aria-hidden="true" />} onClick={() => setWatching(entry.id)}>
+                      <Button type="button" size="compact-sm" variant="light" leftSection={<IconPlayerPlay size={14} aria-hidden="true" />} onClick={() => watch.open(entry.id)}>
                         Watch entry {index + 1}
                       </Button>
                     )}

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

@@ -2,7 +2,7 @@
  * @module Run and artifact filters
  *
  * The filter bar of the Runs and Artifacts tabs: words, artifact tag, media type, label, environment, branch, outcome,
- * feature domain and a time range, each offering the values the report has with counts in the scope of the list. What is
+ * feature domain and a time range (and, for runs, the completeness of their recordings, apart from their outcome), each offering the values the report has with counts in the scope of the list. What is
  * chosen shows as removable chips and is the address, so copying it or reloading restores the same view; named views keep
  * a query to open again. Choices combine with AND across the controls and OR within one.
  */
@@ -18,7 +18,7 @@ import { patched, useExplorerNavigate } from './navigate';
 import { filtered, joined, NO_FILTERS, toggled, values, type ExplorerSearch } from './search';
 import { filtersOf, isView, readViews, writeViews, type SavedView } from './views';
 
-type Param = 'artifactTag' | 'type' | 'label' | 'env' | 'branch' | 'outcome' | 'domain' | 'producer';
+type Param = 'artifactTag' | 'type' | 'label' | 'env' | 'branch' | 'outcome' | 'recordings' | 'domain' | 'producer';
 
 const NOUN: Record<Param, string> = {
   artifactTag: 'Tag',
@@ -27,13 +27,18 @@ const NOUN: Record<Param, string> = {
   env: 'Environment',
   branch: 'Branch',
   outcome: 'Outcome',
+  recordings: 'Recordings',
   domain: 'Domain',
   producer: 'Producer'
 };
 
+/** How the completeness of a run's recordings reads. */
+const COMPLETENESS: Record<string, string> = { complete: 'Complete', incomplete: 'Incomplete', 'none-expected': 'None expected', unknown: 'Unknown' };
+
 /** How a chosen value reads: tags with their hash, environments by name. */
 function shown(param: Param, value: string): string {
   if (param === 'artifactTag') return `#${value}`;
+  if (param === 'recordings') return COMPLETENESS[value] ?? value;
   if (param === 'env') return environmentLabel(value);
   if (param === 'domain' && value === '(no spec)') return 'No spec';
   return value;
@@ -178,7 +183,7 @@ export function FilterBar({
   const [draft, setDraft] = useState(search.q ?? '');
   // The address may change from elsewhere (a link, a saved view, back): follow it.
   useEffect(() => setDraft((current) => (current.trim() === (search.q ?? '').trim() ? current : (search.q ?? ''))), [search.q]);
-  const params: Param[] = ['artifactTag', 'type', 'label', 'env', 'branch', 'outcome', ...(tab === 'artifacts' ? (['domain'] as const) : []), 'producer'];
+  const params: Param[] = ['artifactTag', 'type', 'label', 'env', 'branch', 'outcome', ...(tab === 'runs' ? (['recordings'] as const) : []), ...(tab === 'artifacts' ? (['domain'] as const) : []), 'producer'];
   const chips = [
     ...params.flatMap((param) =>
       values(search[param]).map((value) => ({ label: `${NOUN[param]}: ${shown(param, value)}`, clear: { [param]: toggled(search[param], value) } as never }))
@@ -233,6 +238,9 @@ export function FilterBar({
           <Facet param="env" facets={facets.environments} search={search} />
           <Facet param="branch" facets={facets.branches} search={search} />
           <Facet param="outcome" facets={facets.outcomes} search={search} />
+          {tab === 'runs' && (facets.recordings || values(search.recordings).length > 0) && (
+            <Facet param="recordings" facets={facets.recordings ?? []} search={search} />
+          )}
           {tab === 'artifacts' && facets.domains && <Facet param="domain" facets={facets.domains} search={search} />}
           {facets.producers.length > 1 && <Facet param="producer" facets={facets.producers} search={search} />}
           <TextInput type="date" label="From" value={search.since ?? ''} onChange={(event) => go({ since: event.target.value || undefined })} />

package/packages/visualizer/src/explorer/navigate.ts

@@ -34,3 +34,20 @@ export function useExplorerNavigate() {
 export function patched(patch: ExplorerPatch) {
   return ((prev: Record<string, unknown>) => ({ ...prev, ...patch })) as never;
 }
+
+/**
+ * The open watch playlist as the address holds it, so a link restores it: `watching` is true while the address says it is
+ * open and `clip` is the entry it is on. `open` pushes a history entry (Back closes it), `select` and `close` replace the
+ * current one, so stepping through clips does not fill the history. `open(clip)` starts on that entry.
+ */
+export function useWatchAddress() {
+  const search = useExplorerSearch();
+  const go = useExplorerNavigate();
+  return {
+    watching: search.watch === true,
+    clip: search.watchClip,
+    open: (clip?: string) => go({ watch: true, watchClip: clip }),
+    select: (clip: string) => go({ watchClip: clip }, { replace: true }),
+    close: () => go({ watch: undefined, watchClip: undefined }, { replace: true })
+  };
+}

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

@@ -1,7 +1,7 @@
 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';
+import { clipHints, 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 => ({
@@ -49,3 +49,12 @@ test('a run result gets its backend from the layers of the run, and none when th
   expect(entriesFromRun([result], undefined)[0]!.backend).toBeNull();
   expect(recordingState(entriesFromRun([result], undefined)[0]!)).toBe('unplayable');
 });
+
+test('clip hints are the poster and length the catalog already named for the clip that would play, and nothing otherwise', () => {
+  const hinted: VideoRef = { ...video('sha256:1'), poster: 'attachments/p', durationMs: 4_000 };
+  expect(clipHints(entry('a', { videos: [hinted] }))).toEqual({ poster: 'attachments/p', durationMs: 4_000 });
+  expect(clipHints(entry('a', { videos: [video('sha256:1')] }))).toEqual({});
+  // A reference that names no bytes is not the clip that would play.
+  expect(clipHints(entry('a', { videos: [{ ...video(), durationMs: 9 }] }))).toEqual({});
+  expect(clipHints(entry('a'))).toEqual({});
+});

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

@@ -68,6 +68,16 @@ export function playableVideo(entry: Pick<PlaylistEntry, 'videos'>): VideoRef |
   return entry.videos.find((video) => video.available && video.recording !== undefined);
 }
 
+/**
+ * What the catalog already says about the clip an entry would play, before anything is read or downloaded: the bundle key
+ * of its poster image and its declared length. Each is absent when the producer declared none (or the server predates the
+ * hints); they are hints to recognise a clip, never a reading of the recording and never a latency.
+ */
+export function clipHints(entry: Pick<PlaylistEntry, 'videos'>): { readonly poster?: string; readonly durationMs?: number } {
+  const video = playableVideo(entry);
+  return { ...(video?.poster ? { poster: video.poster } : {}), ...(video?.durationMs ? { durationMs: video.durationMs } : {}) };
+}
+
 /** The recorded results of the Artifacts tab as playlist entries, in their order. */
 export function entriesFromArtifacts(results: readonly ArtifactResult[]): PlaylistEntry[] {
   return results.map((result) => ({