@crvouga/atlas 1.18.0 → 1.20.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

@@ -1,4 +1,4 @@
-import { IconAlertTriangle, IconArrowLeft, IconPlayerPlay, IconVideo } from '@tabler/icons-react';
+import { IconAlertTriangle, IconArrowLeft, IconCheck, IconPlayerPlay, IconVideo } from '@tabler/icons-react';
 import { Alert, Anchor, Badge, Box, Button, Code, Flex, Group, List, NativeSelect, Stack, Table, Text, TextInput, Title, VisuallyHidden } from '@mantine/core';
 /**
  * @module Runs view
@@ -23,13 +23,14 @@ import { hasFilters, passesFilters, type ParsedSearch, type SearchFilters } from
 import type { FindDoc, Ranked } from '../find/rank';
 import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
 import { Meter, StatusMark } from '../evidence/marks';
-import { useRunDetail, useRunList, useTestCatalog } from './catalog';
+import { useRecordingVerification, useRunDetail, useRunList, useTestCatalog } from './catalog';
+import { allStoredVideosGone, verificationOfRun, type RunVerification } from './recording-verification';
 import { RunArtifacts } from './RunArtifacts';
 import { entriesFromRun } from './playlist-entries';
 import { WatchPlaylist } from './playlist';
 import { FilterBar } from './filters';
 import { SearchNotes, TypedFilters } from './search-notes';
-import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+import { patched, useExplorerNavigate, useExplorerSearch, useWatchAddress } from './navigate';
 import { runName } from './parts';
 import { filtered, filterOf, NO_FILTERS } from './search';
 const RUN_ROWS = 50;
@@ -126,9 +127,30 @@ function RunRecordings({ run }: { run: RunSummary }) {
     </Badge>
   );
 }
+/**
+ * What the server's read-back says about a run's stored videos, apart from its test outcomes: some are gone or damaged
+ * (an orange mark that names the problems), or all were read back and are as published. Nothing when they were never
+ * read back: an unverified run is not shown as verified.
+ */
+function StoredVideos({ verification }: { verification: RunVerification | null }) {
+  if (!verification) return null;
+  const at = `Read back from storage ${exactTime(verification.atMs)}. This checks the stored files, not playback in a browser. The test outcomes are unaffected.`;
+  if (verification.gaps === 0)
+    return (
+      <Text component="div" size="xs" c="dimmed" title={at} data-stored-videos="verified">
+        <IconCheck size={16} aria-hidden="true" /> {verification.checked > 0 ? `${plural(verification.ok, 'stored video', 'stored videos')} verified` : 'No stored videos to verify'}
+      </Text>
+    );
+  return (
+    <Text component="div" size="xs" c="orange.9" title={at} data-stored-videos="unavailable">
+      <IconAlertTriangle size={16} aria-hidden="true" /> Recording unavailable: {verification.gaps} of {plural(verification.checked, 'stored video', 'stored videos')} failed the read-back ({verification.problems.join(', ')}).
+    </Text>
+  );
+}
 /** 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 }) {
+function RunVideos({ run, verification }: { run: RunSummary; verification: RunVerification | null }) {
   const videos = run.videos;
+  const gone = videos !== undefined && allStoredVideosGone(verification, videos.recordings);
   const files = run.attachments ? (
     <Anchor
       aria-label={`Open the ${plural(run.attachments, 'file', 'files')} of run ${runName(run.key)}`}
@@ -151,9 +173,9 @@ function RunVideos({ run }: { run: RunSummary }) {
       </Stack>
     );
   return (
-    <Stack gap={0} data-video={videos.recordings > 0 ? 'available' : 'unavailable'}>
+    <Stack gap={0} data-video={videos.recordings > 0 && !gone ? 'available' : 'unavailable'}>
       {files}
-      {videos.recordings > 0 && (
+      {videos.recordings > 0 && !gone && (
         <Anchor
           aria-label={`Watch ${plural(videos.recordings, 'recording', 'recordings')} in run ${runName(run.key)}`}
           renderRoot={(props) => (
@@ -169,6 +191,7 @@ function RunVideos({ run }: { run: RunSummary }) {
         </Text>
       )}
       <Unavailable videos={videos} />
+      <StoredVideos verification={verification} />
     </Stack>
   );
 }
@@ -258,6 +281,7 @@ function RunTable() {
   }, [search]);
   const narrow = filtered(search);
   const runs = useRunList(true, filter, searching);
+  const stored = useRecordingVerification();
   const now = useNow();
   const [shown, setShown] = useState(RUN_ROWS);
   const docs = useMemo(() => (runs.data?.runs ?? []).map((run) => runDoc(run, runLabel(run))), [runs.data]);
@@ -406,7 +430,7 @@ function RunTable() {
                 </Table.Td>
                 <Table.Td>{formatMs(run.spanMs)}</Table.Td>
                 <Table.Td>
-                  <RunVideos run={run} />
+                  <RunVideos run={run} verification={verificationOfRun(stored.data, run.key)} />
                   <RunRecordings run={run} />
                 </Table.Td>
                 <Table.Td data-tags>{run.artifactTags?.map((tag) => `#${tag}`).join(' ') || '—'}</Table.Td>
@@ -461,6 +485,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
   const go = useExplorerNavigate();
   const video = search.video === true;
   const detail = useRunDetail(runKey);
+  const stored = useRecordingVerification();
   const now = useNow();
   const [status, setStatus] = useState('');
   const [shown, setShown] = useState(RESULT_ROWS);
@@ -496,7 +521,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[]>();
@@ -598,6 +623,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
           <Unavailable videos={run.videos} />
         </Text>
       )}
+      <StoredVideos verification={verificationOfRun(stored.data, run.key)} />
       <RunArtifacts detail={detail.data} />
       <Flex gap="xs" align="center" wrap="wrap">
         <Anchor
@@ -676,11 +702,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/catalog.tsx

@@ -44,7 +44,7 @@ import {
   type TestHistoryDocument,
   type TestSummary
 } from '@crvouga/atlas/reports/test-catalog';
-import { isStatechartFile } from '@crvouga/atlas/schema';
+import { isStatechartFile, type RecordingVerification } from '@crvouga/atlas/schema';
 import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 
@@ -373,6 +373,29 @@ export function useRunDetail(key: string | undefined) {
   });
 }
 
+/**
+ * What the server last read back of the stored videos, per layer (`GET /recordings/verification`; see
+ * `recording-verification.ts`). The question is only asked of a server, never reads a blob, and an older server (no route)
+ * or an unanswered request means nothing is known: `null`, which is never shown as verified.
+ */
+export function useRecordingVerification() {
+  const catalog = useTestCatalog();
+  return useQuery({
+    queryKey: ['recording-verification', catalog.version],
+    queryFn: async ({ signal }): Promise<RecordingVerification | null> => {
+      try {
+        return await reportJson<RecordingVerification>('/recordings/verification', signal);
+      } catch (error) {
+        if (signal.aborted) throw error;
+        return null;
+      }
+    },
+    enabled: catalog.source === 'server',
+    staleTime: 30_000,
+    retry: false
+  });
+}
+
 /** What the Catalog health tab reads: the diagnostics, or that this server is too old to give them. */
 export type HealthAnswer = { readonly unsupported: false; readonly health: CatalogHealth } | { readonly unsupported: true };
 

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) => ({