@crvouga/atlas 1.18.0 → 1.20.0

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/recording-verification.ts

@@ -0,0 +1,58 @@
+/**
+ * @module Recording verification of a run
+ *
+ * What the server's read-back of stored videos says about one run, for the Runs tab: how many of its stored videos were
+ * read back, how many passed, and which problems the others have. It is evidence about storage, kept apart from the run's
+ * test outcomes: it never changes how a run is counted, and "never read back" is `null`, not "verified".
+ */
+import type { RecordingVerification } from '@crvouga/atlas/schema';
+
+/** The words for each way a stored recording can be wrong; an unknown problem is still a gap and is named as it came. */
+const PROBLEMS: Readonly<Record<string, string>> = {
+  'blob-missing': 'file gone from storage',
+  'not-in-bundle': 'file missing from the run’s bundle',
+  unreadable: 'storage could not be read',
+  'size-mismatch': 'size differs from what was published',
+  'checksum-mismatch': 'content differs from what was published',
+  undecodable: 'not the video format it claims to be'
+};
+
+/** What was read back of one run's stored recordings. */
+export type RunVerification = {
+  /** Videos read back: those that name a stored file. */
+  readonly checked: number;
+  readonly ok: number;
+  /** Each problem in words, with how many videos have it, most common first. */
+  readonly problems: readonly string[];
+  readonly gaps: number;
+  /** When the server last read the run's layers back, epoch milliseconds (the oldest of them). */
+  readonly atMs: number;
+};
+
+/**
+ * What the read-back found for the run with this key, or `null` when none of its layers was read back (the page then says
+ * nothing about its stored files). A run is as unavailable as its worst layer: gaps add up across its layers.
+ */
+export function verificationOfRun(document: RecordingVerification | null | undefined, runKey: string): RunVerification | null {
+  const layers = document?.layers.filter((layer) => layer.run === runKey) ?? [];
+  if (!layers.length) return null;
+  const counts = new Map<string, number>();
+  let checked = 0, ok = 0, gaps = 0, atMs = Infinity;
+  for (const layer of layers) {
+    checked += layer.checked;
+    ok += layer.ok;
+    atMs = Math.min(atMs, layer.verifiedAtMs);
+    for (const gap of layer.gaps) {
+      gaps += 1;
+      const word = PROBLEMS[gap.problem] ?? gap.problem;
+      counts.set(word, (counts.get(word) ?? 0) + 1);
+    }
+  }
+  const problems = [...counts].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([word, count]) => `${count} ${word}`);
+  return { checked, ok, problems, gaps, atMs };
+}
+
+/** Whether a run's stored videos were read back and none of them can be played: its Watch action would lead nowhere. */
+export function allStoredVideosGone(verification: RunVerification | null, playable: number): boolean {
+  return verification !== null && verification.gaps > 0 && verification.ok === 0 && verification.checked >= playable;
+}

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. */

package/packages/visualizer/src/find/Finder.tsx

@@ -1,14 +1,13 @@
 import { Badge, Button, Group, Kbd, List, Modal, Stack, Text } from '@mantine/core';
 import { Spotlight, useSpotlight } from '@mantine/spotlight';
-import { useQueryClient } from '@tanstack/react-query';
 import { useNavigate, useSearch } from '@tanstack/react-router';
 import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
 import { useAtlas } from '../app/atlas-context';
 import { useTestCatalog } from '../explorer/catalog';
 import { SearchNotes } from '../explorer/search-notes';
-import { keys, specKey, useAdapter } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
 import { plural } from '../evidence/format';
+import { useSpecTexts } from '../evidence/spec-texts';
 import { StatusMark } from '../evidence/marks';
 import { kindOfFile } from '../spec-kind';
 import { describeHit } from './behaviors';
@@ -51,66 +50,6 @@ function isTypingTarget(target: EventTarget | null) {
   const tag = target.tagName;
   return target.isContentEditable || tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A';
 }
-/**
- * Reads the text of every spec for search, 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.
- */
-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;
-    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([pull(), pull(), pull(), 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 };
-}
 export function Finder() {
   const open = useFinderOpen();
   const help = useHelpOpen();