@crvouga/atlas 1.18.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,7 +20,7 @@ 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';
@@ -40,7 +40,7 @@ export function ArtifactsView() {
   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)
@@ -89,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 && (
@@ -99,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;
@@ -496,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[]>();
@@ -676,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/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) => ({

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

@@ -7,7 +7,8 @@
  *
  * 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
+ * large library downloads no recordings in bulk. A row shows a poster (lazily loaded) and a length only when the catalog
+ * already carried them for its clip; none is read to find out. 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.
@@ -16,7 +17,7 @@ import { attachmentIdentity, isVideoAttachment, type CheckDetail } from '@crvoug
 import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
 import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
 import type { Attachment, Step } from '@crvouga/atlas/schema';
-import { Alert, Anchor, Badge, Box, Button, Code, Flex, Grid, Group, List, Modal, NativeSelect, Stack, Switch, Text, Title } from '@mantine/core';
+import { Alert, Anchor, Badge, Box, Button, Code, Flex, Grid, Group, Image, 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';
@@ -31,7 +32,7 @@ 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';
+import { clipHints, 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;
@@ -70,6 +71,14 @@ export function useEntryDetail(entry: PlaylistEntry, enabled: boolean) {
   });
 }
 
+/** The poster the catalog named for a clip, loaded only when its row is near the screen (`loading="lazy"`); a poster that will not load is left out. */
+function Poster({ entry, bundleKey }: { entry: PlaylistEntry; bundleKey: string }) {
+  const [broken, setBroken] = useState(false);
+  const url = attachmentSource({ name: 'poster', bundleKey }, entry.layer).url;
+  if (!url || broken) return null;
+  return <Image src={url} alt="" loading="lazy" decoding="async" w={80} fit="contain" radius="sm" data-poster onError={() => setBroken(true)} />;
+}
+
 /** One step of the scenario: in words, with a control to show it in the recording and a mark while it is playing. */
 function ScenarioStep({ step }: { step: Step }) {
   const playing = useIsPlaying(step);
@@ -269,7 +278,7 @@ function Clip({
   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} />
+        <Link {...props} to="/" search={patched({ tab: undefined, openRun: undefined, artifact: undefined, watch: undefined, watchClip: undefined, test: entry.key, layer: entry.layer })} resetScroll={false} activeOptions={{ exact: true }} onClick={onClose} />
       )}
     >
       Developer details
@@ -412,7 +421,7 @@ function Clip({
       steps={steps}
       attachments={placedIn}
       layer={entry.layer}
-      linkSearch={{ test: entry.key, layer: entry.layer, tab: undefined, openRun: undefined, artifact: undefined }}
+      linkSearch={{ test: entry.key, layer: entry.layer, tab: undefined, openRun: undefined, artifact: undefined, watch: undefined, watchClip: undefined }}
     >
       <Stack gap="md" miw={0} aria-label={`Now showing ${entry.title}`} component="section" data-clip={entry.id}>
         {body}
@@ -432,9 +441,26 @@ function Clip({
  * 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.
+ * `focus`, and `title` the heading. `onSelect` is told the id of the entry on screen when the session opens and each time it
+ * changes, so the address can name it. 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 }) {
+export function WatchPlaylist({
+  entries,
+  total,
+  focus,
+  onClose,
+  onSelect,
+  initial,
+  title = 'Watch recordings'
+}: {
+  entries: readonly PlaylistEntry[];
+  total?: number;
+  focus?: RecordingFocus;
+  onClose: () => void;
+  onSelect?: (id: string) => 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.
@@ -449,6 +475,12 @@ export function WatchPlaylist({ entries, total, focus, onClose, initial, title =
   const active = entries.find((entry) => entry.id === chosen) ?? first ?? null;
   const counts = useMemo(() => playlistCounts(entries), [entries]);
   const activeAt = active ? entries.indexOf(active) : -1;
+  const activeId = active?.id;
+  const selected = useRef(onSelect);
+  selected.current = onSelect;
+  useEffect(() => {
+    if (activeId !== undefined && !focus) selected.current?.(activeId);
+  }, [activeId, focus]);
   const next = stepFrom(entries, active?.id ?? null, 1, repeat);
   const previous = stepFrom(entries, active?.id ?? null, -1, repeat);
   const select = (entry: PlaylistEntry, play: boolean) => {
@@ -524,6 +556,7 @@ export function WatchPlaylist({ entries, total, focus, onClose, initial, title =
                 {listed.map((entry, index) => {
                   const state = recordingState(entry);
                   const here = entry.id === active?.id;
+                  const hints = clipHints(entry);
                   return (
                     <List.Item key={entry.id} data-entry={entry.id} data-status={entry.status} data-recording-state={state}>
                       <Button
@@ -534,11 +567,12 @@ export function WatchPlaylist({ entries, total, focus, onClose, initial, title =
                         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}`}
+                        aria-label={`${index + 1}. ${entry.title}, ${statusWord(entry.status)}, ${failedIds.has(entry.id) ? 'could not be loaded' : RECORDING_STATE_TEXT[state].label}${hints.durationMs ? `, ${duration(hints.durationMs)} long` : ''}`}
                         onClick={() => select(entry, state === 'playable')}
                       >
                         <Flex component="span" gap="xs" wrap="nowrap" align="flex-start">
                           <StatusMark status={entry.status} size={14} />
+                          {hints.poster && <Poster entry={entry} bundleKey={hints.poster} />}
                           <Flex component="span" direction="column" align="flex-start">
                             <Text span inherit ta="left">
                               {entry.title}
@@ -546,6 +580,7 @@ export function WatchPlaylist({ entries, total, focus, onClose, initial, title =
                             <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}
+                              {hints.durationMs ? ` · ${duration(hints.durationMs)} recording` : ''}
                             </Text>
                           </Flex>
                         </Flex>

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

@@ -2,7 +2,7 @@
  * @module Explorer address
  *
  * Everything the test explorer shows is in the address of the `/` route, so a link reproduces the view: the open test,
- * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the Catalog health tab with the root mappings it tries (`root`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), and the one file of a run's layer its Artifacts select. Filters that
+ * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the Catalog health tab with the root mappings it tries (`root`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), the watch playlist that is open over the list or run and the clip it is on (`watch`, `watchClip`), and the one file of a run's layer its Artifacts select. Filters that
  * take several values are comma-separated (`status=failed,flaky`); a comma or backslash inside a value is written `\,`
  * or `\\`, and the router encodes `#` and spaces. Anything unreadable is dropped, never an error.
  *
@@ -109,6 +109,10 @@ export const ExplorerSearchFields = {
   relRevision: z.enum(['any']).optional().catch(undefined),
   /** The reliability's independent executions (its denominator) are open. */
   relOpen: z.preprocess((value) => (value === 'true' ? true : value), z.literal(true)).optional().catch(undefined),
+  /** The watch playlist is open over the list, opened run or collection the rest of the address names. A link with it restores the playlist; without it the page is as it was before. */
+  watch: z.preprocess((value) => (value === 'true' ? true : value), z.literal(true)).optional().catch(undefined),
+  /** With `watch`: the entry of the playlist that is playing (its id, which names the result and the layer that recorded it). Unknown or absent: the first one that can be watched. */
+  watchClip: text,
   /** Words to find inside the recordings of the Artifacts tab (what was said or shown, from the text producers supplied). Not a filter of the list. */
   inside: text,
   /** Only the runs, and the results of an opened run, that have a playable video recording. */
@@ -166,6 +170,8 @@ export type ExplorerSearch = {
   readonly relOpen?: true;
   readonly inside?: string;
   readonly video?: true;
+  readonly watch?: true;
+  readonly watchClip?: string;
 };
 
 /** The values of a comma-separated filter, empty when it is not set. */