@crvouga/atlas 1.20.0 → 1.22.0

package/packages/visualizer/src/app/AppShell.tsx

@@ -24,6 +24,8 @@ function Index() {
   const kind = kindOfAddress(pathname);
   return pathname === '/catalog' ? (
     <UiCatalogFilters />
+  ) : pathname === '/critiques' ? (
+    <Box component="nav" aria-label="Critiques" />
   ) : kind ? (
     <SpecIndex kind={kind} />
   ) : pathname.startsWith('/specs/') || pathname === '/behaviors' ? (
@@ -39,7 +41,7 @@ function Body() {
   const { view, spec } = useAtlas();
   const { pathname } = useLocation();
   if (pathname === '/' && evidence.ready && !evidence.filesPending && !evidence.files.some(isStatechartFile)) return <Explorer />;
-  if (!pathname.startsWith('/specs/') && pathname !== '/catalog' && pathname !== '/behaviors' && !view && spec.error)
+  if (!pathname.startsWith('/specs/') && pathname !== '/catalog' && pathname !== '/critiques' && pathname !== '/behaviors' && !view && spec.error)
     return (
       <Container py="xl">
         <Alert color="red" title="The spec couldn’t be loaded">

package/packages/visualizer/src/app/router.tsx

@@ -12,6 +12,8 @@ import {
 import { z } from 'zod/v4';
 import { CatalogSearchFields } from '../catalog/search';
 import { UiCatalogPage } from '../catalog/UiCatalogPage';
+import { CritiquesPage } from '../critiques/CritiquesPage';
+import { CritiqueSearchFields } from '../critiques/search';
 import { COVERAGE_ORDER } from '../evidence/behavior';
 import { BehaviorsPage } from '../evidence/behaviors-page';
 import { SpecPage } from '../evidence/spec-page';
@@ -29,6 +31,13 @@ const ChartSearch = RootSearch.extend({
 export type ChartSearch = z.infer<typeof ChartSearch>;
 /** The project home: the test explorer's filters, grouping, order, open test and open run (see `explorer/search.ts`). */
 const HomeSearch = RootSearch.extend(ExplorerSearchFields);
+/** The release evidence is read against: its build, commit and platform, and the evidence filter (see `evidence/applicability.ts`). A build such as `90` is read from a typed link as a number: coerced back to its text. */
+const ReleaseSearch = {
+  release: z.coerce.string().min(1).optional().catch(undefined),
+  releaseSha: z.coerce.string().min(1).optional().catch(undefined),
+  releasePlatform: z.coerce.string().min(1).optional().catch(undefined),
+  evidence: z.enum(['stale']).optional().catch(undefined)
+};
 /** A spec document, the check opened in it, one layer's record of that check, and a recorded moment. */
 const SpecSearch = RootSearch.extend({
   spec: z.string().min(1).optional().catch(undefined),
@@ -39,11 +48,7 @@ const SpecSearch = RootSearch.extend({
   clipAt: z.coerce.number().nonnegative().optional().catch(undefined),
   view: z.enum(['recording']).optional().catch(undefined),
   moment: z.coerce.number().int().positive().optional().catch(undefined),
-  /** The release evidence is read against: its build, commit and platform, and the evidence filter (see `evidence/applicability.ts`). A build such as `90` is read from a typed link as a number: coerced back to its text. */
-  release: z.coerce.string().min(1).optional().catch(undefined),
-  releaseSha: z.coerce.string().min(1).optional().catch(undefined),
-  releasePlatform: z.coerce.string().min(1).optional().catch(undefined),
-  evidence: z.enum(['stale']).optional().catch(undefined)
+  ...ReleaseSearch
 });
 export type SpecSearch = z.infer<typeof SpecSearch>;
 /**
@@ -58,7 +63,8 @@ const BehaviorsSearch = RootSearch.extend({
   workspace: z.preprocess((value) => (value === 'true' ? true : value), z.literal(true)).optional().catch(undefined),
   layer: z.string().min(1).optional().catch(undefined),
   clip: z.coerce.string().min(1).optional().catch(undefined),
-  clipAt: z.coerce.number().nonnegative().optional().catch(undefined)
+  clipAt: z.coerce.number().nonnegative().optional().catch(undefined),
+  ...ReleaseSearch
 });
 export type BehaviorsSearch = z.infer<typeof BehaviorsSearch>;
 /** A fresh route tree per router, so a test can run its own viewer beside the page's. */
@@ -120,7 +126,14 @@ function routeTree() {
     validateSearch: (search) => BehaviorsSearch.parse(search),
     component: BehaviorsPage
   });
-  return rootRoute.addChildren([productRoute, chartRoute, specRoute, catalogRoute, behaviorsRoute]);
+  /** Needs polish: the opinions of automated reviewers about the captured states, ranked (see `critiques/`). */
+  const critiquesRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/critiques',
+    validateSearch: (search) => RootSearch.extend(CritiqueSearchFields).parse(search),
+    component: CritiquesPage
+  });
+  return rootRoute.addChildren([productRoute, chartRoute, specRoute, catalogRoute, behaviorsRoute, critiquesRoute]);
 }
 export function createAtlasRouter(history: RouterHistory) {
   return createRouter({ routeTree: routeTree(), history, defaultPreload: false, scrollRestoration: true });

package/packages/visualizer/src/catalog/Picture.tsx

@@ -0,0 +1,32 @@
+/**
+ * @module UI catalog picture
+ *
+ * The picture of one captured cell, shared by the catalog's cards, the open state and the comparison. A picture is shown only
+ * for a cell that was captured, or that failed (a picture of what the page showed, for diagnosis); every other cell says in
+ * words what it is instead of showing an empty frame. Pictures are `loading="lazy"`, so only what is on screen is fetched.
+ */
+import type { UiCell, UiImage } from '@crvouga/atlas/reports/ui-catalog';
+import { Image, Text } from '@mantine/core';
+
+import { reportAssetUrl } from '../evidence/api';
+import { safeUri } from '../evidence/format';
+import { coverageWord } from './words';
+
+/** Where a browser loads a picture from: its stored file in the layer, else its safe web address. */
+export function imageSource(image: UiImage | null | undefined): string | null {
+  if (!image) return null;
+  return image.path ? reportAssetUrl(image.path) : safeUri(image.uri);
+}
+
+/** The picture of a cell, or the words that say why there is none. `label` names the side of a comparison it belongs to. */
+export function Picture({ cell, title, height, label }: { cell: UiCell; title: string; height?: number; label?: string }) {
+  const image = cell.capture?.image;
+  const source = cell.coverage === 'captured' || cell.coverage === 'failed' ? imageSource(image) : null;
+  const name = `${title}, ${label ?? cell.profile.label}`;
+  if (source) return <Image src={source} alt={name} loading="lazy" fit="contain" {...(height ? { h: height } : {})} {...(image?.width ? { w: 'auto', maw: '100%' } : {})} />;
+  return (
+    <Text c="dimmed" fz="sm" role="img" aria-label={`${name}: no picture`}>
+      {cell.coverage === 'captured' ? (image?.omitted ? `Picture left out (${image.omitted})` : 'Captured without a picture') : coverageWord(cell.coverage)}
+    </Text>
+  );
+}

package/packages/visualizer/src/catalog/UiCatalogCompare.tsx

@@ -0,0 +1,289 @@
+/**
+ * @module UI catalog comparison
+ *
+ * The catalog set against itself: two commits (what the same states looked like when each commit was recorded) or two profiles
+ * (desktop against mobile, light against dark). Both sides are in the address (`compare`, `from`, `to`), so a link reproduces the
+ * comparison. Pictures are compared by their stored bytes, and the page says so: "changed" is not a measure of pixels. A state only
+ * one side has is not called a regression (the other side may not have captured it), a capture that did not pass is a change of
+ * coverage and never compared by picture, a layer that could not be read is named and never taken to be unchanged, and a picture
+ * with no content hash is "cannot tell".
+ */
+import { filterUiCatalog, type UiCatalog, type UiCatalogQuery } from '@crvouga/atlas/reports/ui-catalog';
+import { UI_CELL_CHANGES, changedUiEntries, diffUiCatalogs, diffUiProfiles, uiCatalogCommits, type UiCatalogDiff, type UiCellChange, type UiDiffEntry } from '@crvouga/atlas/reports/ui-catalog-diff';
+import { Alert, Anchor, Badge, Button, Card, Code, Group, NativeSelect, SegmentedControl, SimpleGrid, Stack, Switch, Text, Title } from '@mantine/core';
+import { Link } from '@tanstack/react-router';
+import { useMemo, useState } from 'react';
+
+import { useEvidence } from '../evidence/evidence-context';
+import { ago, plural, shortSha, useNow } from '../evidence/format';
+import { Picture } from './Picture';
+import { useCommitCatalog, useLayerHeaders } from './history';
+import { useCatalogNavigate, useCatalogSearch } from './search';
+import { coverageWord } from './words';
+
+const ENTRIES = 24;
+
+const CHANGE: Readonly<Record<UiCellChange, { label: string; color: string; meaning: string }>> = {
+  coverage: { label: 'Coverage changed', color: 'orange', meaning: 'It stands differently on the two sides, such as captured on one and failed on the other.' },
+  picture: { label: 'Picture changed', color: 'blue', meaning: 'Captured on both sides, and the stored picture is not the same file. This says the bytes differ, not how many pixels.' },
+  unverified: { label: 'Cannot tell', color: 'gray', meaning: 'Captured on both sides, but a picture has no content hash (it is given only by address), so whether it changed is unknown.' },
+  added: { label: 'Only after', color: 'green', meaning: 'Only the after side has it. It may be new, or the before side may not have captured it.' },
+  removed: { label: 'Only before', color: 'gray', meaning: 'Only the before side has it. It is not a regression: the after side may not have captured it, or it may have been renamed.' },
+  unchanged: { label: 'Unchanged', color: 'gray', meaning: 'The same coverage and, when captured, the same stored picture.' }
+};
+
+/**
+ * The query a comparison narrows by: the catalog's filters except coverage, because the comparison is about coverage changing, and
+ * (when profiles are what is compared) except the profile, because the two sides are the profiles.
+ */
+function narrowedBy(query: UiCatalogQuery, mode: 'commit' | 'profile'): UiCatalogQuery {
+  const { coverage: _coverage, profile: _profile, ...rest } = query;
+  return mode === 'profile' ? rest : { ...rest, ...(query.profile ? { profile: query.profile } : {}) };
+}
+
+function Entry({ entry, before, after }: { entry: UiDiffEntry; before: string; after: string }) {
+  const change = CHANGE[entry.change];
+  return (
+    <Card withBorder role="listitem" data-state={entry.id} data-change={entry.change}>
+      <Stack gap="sm">
+        <Group justify="space-between" align="flex-start" wrap="nowrap">
+          <Stack gap={2}>
+            <Anchor fw={700} aria-label={`Open ${entry.title}`} renderRoot={(props) => <Link {...props} to="/catalog" search={((prev: Record<string, unknown>) => ({ ...prev, state: entry.id })) as never} resetScroll={false} />}>
+              {entry.title}
+            </Anchor>
+            <Text c="dimmed" fz="xs">
+              {entry.id}
+              {entry.profile ? ` · ${entry.profile.label}` : ''}
+            </Text>
+          </Stack>
+          <Badge variant="light" color={change.color} title={change.meaning}>
+            {entry.change === 'coverage' && entry.before && entry.after ? `${coverageWord(entry.before.coverage)} → ${coverageWord(entry.after.coverage)}` : change.label}
+          </Badge>
+        </Group>
+        <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+          {([['Before', before, entry.before], ['After', after, entry.after]] as const).map(([side, name, cell]) => (
+            <Stack key={side} gap="xs" component="section" aria-label={`${side}: ${name}`}>
+              <Text fw={600} fz="sm">
+                {side}: {name}
+              </Text>
+              {cell ? (
+                <>
+                  <Picture cell={cell} title={entry.title} label={`${side.toLowerCase()}, ${name}`} height={180} />
+                  <Text c="dimmed" fz="xs">
+                    {coverageWord(cell.coverage)}
+                    {cell.capture ? ` · layer ${cell.capture.origin.layer.slice(0, 12)} in ${cell.capture.origin.backend}` : ''}
+                  </Text>
+                </>
+              ) : (
+                <Text c="dimmed" fz="sm">
+                  Not on this side
+                </Text>
+              )}
+            </Stack>
+          ))}
+        </SimpleGrid>
+      </Stack>
+    </Card>
+  );
+}
+
+function Results({ diff, before, after }: { diff: UiCatalogDiff; before: string; after: string }) {
+  const { search } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  const [shown, setShown] = useState(ENTRIES);
+  const all = search.all === '1';
+  const entries = all ? diff.entries : changedUiEntries(diff);
+  return (
+    <Stack gap="md">
+      <Group gap="xs" role="status" aria-label="Comparison summary">
+        {UI_CELL_CHANGES.map((name) =>
+          diff.summary[name] > 0 ? (
+            <Badge key={name} variant="light" color={CHANGE[name].color} title={CHANGE[name].meaning}>
+              {diff.summary[name]} {CHANGE[name].label.toLowerCase()}
+            </Badge>
+          ) : null
+        )}
+        {diff.summary.total === 0 && <Text c="dimmed">There is nothing to compare.</Text>}
+      </Group>
+      <Switch label="Show unchanged" checked={all} onChange={(event) => go({ all: event.currentTarget.checked ? '1' : undefined })} />
+      {diff.summary.total > 0 && entries.length === 0 && (
+        <Text role="status" data-no-change>
+          Nothing differs between the two sides.
+        </Text>
+      )}
+      {entries.length > 0 && (
+        <SimpleGrid role="list" aria-label="Differences" cols={1} spacing="md">
+          {entries.slice(0, shown).map((entry) => (
+            <Entry key={`${entry.id}|${entry.profile?.key ?? ''}|${entry.before?.profile.key ?? ''}`} entry={entry} before={before} after={after} />
+          ))}
+        </SimpleGrid>
+      )}
+      {entries.length > shown && (
+        <Button type="button" variant="subtle" onClick={() => setShown(shown + ENTRIES)}>
+          Show more ({entries.length - shown} more)
+        </Button>
+      )}
+    </Stack>
+  );
+}
+
+function CommitComparison({ whole, query }: { whole: UiCatalog; query: UiCatalogQuery }) {
+  const { search } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  const now = useNow();
+  const evidence = useEvidence();
+  const history = useLayerHeaders(true);
+  const incomplete = evidence.notices.length > 0 || evidence.backends.some((backend) => !backend.available);
+  const producers = useMemo(() => new Set(whole.states.flatMap((state) => state.producers)), [whole]);
+  const headers = useMemo(() => history.headers.filter((layer) => producers.has(layer.producer)), [history.headers, producers]);
+  const commits = useMemo(() => uiCatalogCommits(headers), [headers]);
+  const from = useCommitCatalog(headers, search.from);
+  const to = useCommitCatalog(headers, search.to);
+  const diff = useMemo(() => (from.catalog && to.catalog ? diffUiCatalogs(filterUiCatalog(from.catalog, query), filterUiCatalog(to.catalog, query)) : null), [from.catalog, to.catalog, query]);
+  const unreadable = [...from.failed, ...to.failed];
+  const pending = from.pending + to.pending;
+  const options = (value: string | undefined) => (
+    <>
+      <option value="">Choose a commit</option>
+      {value && !commits.some((commit) => commit.sha === value) && <option value={value}>{shortSha(value)} (no layers of this catalog&rsquo;s producers)</option>}
+      {commits.map((commit) => (
+        <option key={commit.sha} value={commit.sha}>
+          {[shortSha(commit.sha), commit.branch, plural(commit.layers, 'layer', 'layers'), ago(commit.recordedAtMs, now)].filter(Boolean).join(' · ')}
+        </option>
+      ))}
+    </>
+  );
+  return (
+    <Stack gap="md">
+      <Text c="dimmed">
+        The states each commit recorded, set side by side. A layer recorded from a checkout with uncommitted changes is not a commit&rsquo;s own result and is left out.
+      </Text>
+      {history.error && (
+        <Alert role="alert" color="red" title="The recorded layers cannot be read">
+          <Group gap="sm">
+            <Text span inherit>{history.error}</Text>
+            <Button type="button" variant="subtle" onClick={history.retry}>Try again</Button>
+          </Group>
+        </Alert>
+      )}
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+        <NativeSelect label="Before" value={search.from ?? ''} onChange={(event) => go({ from: event.currentTarget.value || undefined })} data-compare-picker="before">
+          {options(search.from)}
+        </NativeSelect>
+        <NativeSelect label="After" value={search.to ?? ''} onChange={(event) => go({ to: event.currentTarget.value || undefined })} data-compare-picker="after">
+          {options(search.to)}
+        </NativeSelect>
+      </SimpleGrid>
+      {!search.from && !search.to && commits.length >= 2 && (
+        <Group>
+          <Button type="button" variant="light" onClick={() => go({ from: commits[1]!.sha, to: commits[0]!.sha })}>
+            Compare the two newest commits
+          </Button>
+        </Group>
+      )}
+      {!history.loading && commits.length < 2 && (
+        <Text c="dimmed" role="status" data-no-commits>
+          {commits.length === 0 ? 'No layer of this catalog records the commit it was captured at, so there is nothing to compare by commit.' : 'Only one commit has recorded layers, so there is nothing to compare it with.'}
+        </Text>
+      )}
+      {search.from && search.from === search.to && <Alert color="gray" role="status">The same commit is on both sides.</Alert>}
+      {unreadable.length > 0 && (
+        <Alert role="status" color="orange" title="Some layers could not be read">
+          {plural(unreadable.length, 'layer', 'layers')} at these commits could not be read ({unreadable.map((layer) => layer.id.slice(0, 12)).join(', ')}). What they hold is unknown here, not unchanged, so this comparison may be incomplete.
+        </Alert>
+      )}
+      {incomplete && (
+        <Alert role="status" color="orange" title="This comparison may be incomplete">
+          Some results or backends could not be read (named above). A state missing from a side may be one that could not be read, so it is unknown there, not absent.
+        </Alert>
+      )}
+      {pending > 0 && (
+        <Text role="status" c="dimmed">
+          Reading {plural(pending, 'more layer', 'more layers')}; the comparison fills in as they arrive.
+        </Text>
+      )}
+      {diff && search.from !== search.to && <Results diff={diff} before={`commit ${shortSha(search.from ?? null)}`} after={`commit ${shortSha(search.to ?? null)}`} />}
+      {search.from && search.to && !diff && !history.loading && pending === 0 && <Text c="dimmed">There is nothing recorded at those commits.</Text>}
+    </Stack>
+  );
+}
+
+function ProfileComparison({ whole, query }: { whole: UiCatalog; query: UiCatalogQuery }) {
+  const { search } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  const known = (key: string | undefined) => whole.profiles.some((profile) => profile.key === key);
+  const diff = useMemo(
+    () => (search.from && search.to && search.from !== search.to && whole.profiles.some((p) => p.key === search.from) && whole.profiles.some((p) => p.key === search.to) ? diffUiProfiles(filterUiCatalog(whole, query), search.from, search.to) : null),
+    [whole, query, search.from, search.to]
+  );
+  const label = (key: string | undefined) => whole.profiles.find((profile) => profile.key === key)?.label ?? 'a profile';
+  const options = (value: string | undefined) => (
+    <>
+      <option value="">Choose a profile</option>
+      {value && !known(value) && <option value={value}>Not a profile of this catalog</option>}
+      {whole.profiles.map((profile) => (
+        <option key={profile.key} value={profile.key}>
+          {profile.label}
+        </option>
+      ))}
+    </>
+  );
+  return (
+    <Stack gap="md">
+      <Text c="dimmed">Each state in one profile set beside the same state in another: desktop against mobile, light against dark.</Text>
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+        <NativeSelect label="Before" value={search.from ?? ''} onChange={(event) => go({ from: event.currentTarget.value || undefined })} data-compare-picker="before">
+          {options(search.from)}
+        </NativeSelect>
+        <NativeSelect label="After" value={search.to ?? ''} onChange={(event) => go({ to: event.currentTarget.value || undefined })} data-compare-picker="after">
+          {options(search.to)}
+        </NativeSelect>
+      </SimpleGrid>
+      {whole.profiles.length < 2 && (
+        <Text c="dimmed" role="status" data-no-profiles>
+          This catalog has {whole.profiles.length === 1 ? 'one profile' : 'no profiles'}, so there is nothing to compare it with.
+        </Text>
+      )}
+      {search.from && search.from === search.to && <Alert color="gray" role="status">The same profile is on both sides.</Alert>}
+      {diff && <Results diff={diff} before={label(search.from)} after={label(search.to)} />}
+    </Stack>
+  );
+}
+
+/** The comparison of the catalog with itself: its mode (commits or profiles) and both sides are the address. */
+export function UiCatalogCompare({ whole }: { whole: UiCatalog }) {
+  const { search, query } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  const mode = search.compare === 'profile' ? 'profile' : 'commit';
+  const narrowed = useMemo(() => narrowedBy(query, mode), [query, mode]);
+  return (
+    <Stack gap="md" component="section" aria-label="Compare">
+      <Group justify="space-between" align="flex-end">
+        <Title order={2}>Compare</Title>
+        <Group gap="sm">
+          <SegmentedControl
+            aria-label="What to compare"
+            value={mode}
+            onChange={(value) => go({ compare: value, from: undefined, to: undefined })}
+            data={[
+              { value: 'commit', label: 'Two commits' },
+              { value: 'profile', label: 'Two profiles' }
+            ]}
+          />
+          <Button type="button" variant="subtle" onClick={() => go({ compare: undefined, from: undefined, to: undefined, all: undefined })}>
+            Back to the catalog
+          </Button>
+        </Group>
+      </Group>
+      {query.coverage?.length || (mode === 'profile' && query.profile?.length) ? (
+        <Text c="dimmed" fz="sm">
+          {mode === 'profile' ? 'The coverage and profile filters do not apply here: coverage is what is compared, and the profiles are chosen below.' : 'The coverage filter does not apply to a comparison, which is about coverage changing.'} The other filters do.
+        </Text>
+      ) : null}
+      {mode === 'commit' ? <CommitComparison whole={whole} query={narrowed} /> : <ProfileComparison whole={whole} query={narrowed} />}
+      <Text c="dimmed" fz="xs">
+        Pictures are compared by their stored bytes: <Code>Picture changed</Code> means the file is not the same, not how many pixels differ.
+      </Text>
+    </Stack>
+  );
+}

package/packages/visualizer/src/catalog/UiCatalogPage.tsx

@@ -7,18 +7,19 @@
  * capture exists; a backend or layer that could not be read is named, and nothing that depended on it is shown as captured.
  * Pictures are loaded lazily, only for the cards on screen.
  */
-import { IconDownload } from '@tabler/icons-react';
-import type { UiCapture, UiCatalog, UiCatalogState, UiCell, UiImage } from '@crvouga/atlas/reports/ui-catalog';
+import { IconArrowsExchange, IconDownload } from '@tabler/icons-react';
+import type { UiCapture, UiCatalog, UiCatalogState, UiCell } from '@crvouga/atlas/reports/ui-catalog';
 import { UI_COVERAGE, filterUiCatalog, isUiCatalogFiltered } from '@crvouga/atlas/reports/ui-catalog';
-import { Accordion, Alert, Anchor, Badge, Button, Card, Code, Container, Drawer, Group, Image, SimpleGrid, Stack, Table, Text, Title } from '@mantine/core';
+import { Accordion, Alert, Anchor, Badge, Button, Card, Code, Container, Drawer, Group, SimpleGrid, Stack, Table, Text, Title } from '@mantine/core';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 
-import { reportAssetUrl } from '../evidence/api';
 import { useEvidence } from '../evidence/evidence-context';
-import { ago, exactTime, plural, safeUri, shortSha, useNow } from '../evidence/format';
+import { ago, exactTime, plural, shortSha, useNow } from '../evidence/format';
 import { EvidenceIncomplete, EvidenceWaiting } from '../evidence/load-state';
 import { StatusMark } from '../evidence/marks';
+import { Picture, imageSource } from './Picture';
+import { UiCatalogCompare } from './UiCatalogCompare';
 import { useUiCatalog } from './provider';
 import { useCatalogNavigate, useCatalogSearch } from './search';
 import { coverageStatus, coverageWord } from './words';
@@ -26,25 +27,6 @@ import { coverageStatus, coverageWord } from './words';
 /** How many state cards are drawn before "Show more". */
 const CARDS = 48;
 
-/** Where a browser loads a picture from: its stored file in the layer, else its safe web address. */
-export function imageSource(image: UiImage | null | undefined): string | null {
-  if (!image) return null;
-  return image.path ? reportAssetUrl(image.path) : safeUri(image.uri);
-}
-
-function Picture({ cell, title, height }: { cell: UiCell; title: string; height?: number }) {
-  const image = cell.capture?.image;
-  // A failed capture may carry a picture of what the page showed, for diagnosis; nothing else has one worth showing.
-  const source = cell.coverage === 'captured' || cell.coverage === 'failed' ? imageSource(image) : null;
-  if (source)
-    return <Image src={source} alt={`${title}, ${cell.profile.label}`} loading="lazy" fit="contain" {...(height ? { h: height } : {})} {...(image?.width ? { w: 'auto', maw: '100%' } : {})} />;
-  return (
-    <Text c="dimmed" fz="sm" role="img" aria-label={`${title}, ${cell.profile.label}: no picture`}>
-      {cell.coverage === 'captured' ? (image?.omitted ? `Picture left out (${image.omitted})` : 'Captured without a picture') : coverageWord(cell.coverage)}
-    </Text>
-  );
-}
-
 function CoverageBadge({ cell }: { cell: UiCell }) {
   return (
     <Badge variant="light" color={cell.coverage === 'captured' ? 'green' : cell.coverage === 'failed' ? 'red' : cell.coverage === 'capturing' ? 'blue' : 'gray'} leftSection={<StatusMark status={coverageStatus(cell.coverage)} size={12} />}>
@@ -266,9 +248,16 @@ export function UiCatalogPage() {
             <Text c="dimmed">Each state of the product&rsquo;s interface, captured once per profile, with where every picture came from.</Text>
           </Stack>
           {catalog && catalog.states.length > 0 && (
-            <Button type="button" leftSection={<IconDownload size={16} aria-hidden="true" />} onClick={() => download(catalog)}>
-              Download the manifest
-            </Button>
+            <Group gap="sm">
+              {!search.compare && (
+                <Button type="button" variant="default" leftSection={<IconArrowsExchange size={16} aria-hidden="true" />} onClick={() => go({ compare: 'commit' })}>
+                  Compare
+                </Button>
+              )}
+              <Button type="button" leftSection={<IconDownload size={16} aria-hidden="true" />} onClick={() => download(catalog)}>
+                Download the manifest
+              </Button>
+            </Group>
           )}
         </Group>
         {evidence.unavailable && (
@@ -296,7 +285,8 @@ export function UiCatalogPage() {
             Reading {plural(evidence.pending, 'more layer', 'more layers')}; states appear here as they arrive.
           </Text>
         )}
-        {catalog && whole && (
+        {catalog && whole && search.compare && <UiCatalogCompare whole={whole} />}
+        {catalog && whole && !search.compare && (
           <>
             <Summary catalog={catalog} narrowed={narrowed} />
             <Surfaces catalog={whole} />

package/packages/visualizer/src/catalog/history.ts

@@ -0,0 +1,61 @@
+/**
+ * @module UI catalog history
+ *
+ * What a comparison of two commits needs and the report the viewer holds does not: the layers of an earlier commit. A newer layer
+ * replaces the older one of its slot, so the effective report keeps only the newest capture of every state. The layer list
+ * (`/evidence`) and a layer's rows (`/evidence/rows/<backend>/<id>`) still hold the rest, and are read here only while a
+ * comparison is open: the list once, and the rows of the layers of the commits being compared. The rows share their cache with the
+ * rest of the viewer, so a layer is never read twice.
+ */
+import type { EvidencePage, LayerEvidence, LayerHeader, LayerRows } from '@crvouga/atlas/reports/evidence-types';
+import { distinctHeaders } from '@crvouga/atlas/reports/layer-merge';
+import { uiCatalog, type UiCatalog } from '@crvouga/atlas/reports/ui-catalog';
+import { useInfiniteQuery, useQueries } from '@tanstack/react-query';
+import { useEffect, useMemo } from 'react';
+
+import { reportJson } from '../evidence/api';
+import { rowsKey } from '../evidence/evidence-context';
+
+/** Every layer header the stores hold (superseded layers included), read page by page while `enabled`. */
+export function useLayerHeaders(enabled: boolean): { readonly headers: readonly LayerHeader[]; readonly loading: boolean; readonly error: string | null; readonly retry: () => void } {
+  const index = useInfiniteQuery({
+    queryKey: ['catalog-layers'],
+    enabled,
+    initialPageParam: null as string | null,
+    queryFn: ({ pageParam, signal }) => reportJson<EvidencePage>(`/evidence${pageParam ? `?cursor=${encodeURIComponent(pageParam)}` : ''}`, signal),
+    getNextPageParam: (page) => page.cursor,
+    staleTime: 30_000,
+    retry: false
+  });
+  const { hasNextPage, isFetching, isError, fetchNextPage } = index;
+  useEffect(() => {
+    if (enabled && hasNextPage && !isFetching && !isError) void fetchNextPage();
+  }, [enabled, hasNextPage, isFetching, isError, fetchNextPage]);
+  const pages = index.data?.pages;
+  const headers = useMemo(() => distinctHeaders(pages?.flatMap((page) => page.layers) ?? []), [pages]);
+  return { headers, loading: enabled && (index.isPending || hasNextPage), error: index.error ? index.error.message : null, retry: () => void index.refetch() };
+}
+
+/** The catalog recorded at one commit, from the rows of that commit's layers. `pending` layers are still being read; `failed` ones could not be read and are absent from the catalog. */
+export function useCommitCatalog(headers: readonly LayerHeader[], sha: string | undefined): { readonly catalog: UiCatalog | null; readonly pending: number; readonly failed: readonly LayerHeader[] } {
+  const wanted = useMemo(() => (sha ? headers.filter((layer) => layer.sha === sha && layer.freshness !== 'modified') : []), [headers, sha]);
+  const rows = useQueries({
+    queries: wanted.map((layer) => ({
+      queryKey: rowsKey(layer),
+      queryFn: ({ signal }: { signal: AbortSignal }) => reportJson<LayerRows>(`/evidence/rows/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`, signal),
+      staleTime: Number.POSITIVE_INFINITY,
+      retry: 1
+    })),
+    combine: (results) => ({ data: results.map((result) => result.data), failed: results.map((result) => result.isError && result.data === undefined), stamp: results.map((result) => result.dataUpdatedAt).join(',') })
+  });
+  return useMemo(() => {
+    const loaded: LayerEvidence[] = [];
+    wanted.forEach((layer, i) => {
+      const read = rows.data[i];
+      if (read) loaded.push({ ...read, layer });
+    });
+    const failed = wanted.filter((_, i) => rows.failed[i]);
+    return { catalog: sha ? uiCatalog(loaded) : null, pending: Math.max(0, wanted.length - loaded.length - failed.length), failed };
+    // `stamp` changes exactly when a layer's rows do.
+  }, [wanted, rows.stamp, sha]);
+}

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

@@ -2,7 +2,7 @@
  * @module UI catalog address
  *
  * Everything the UI catalog shows is in the address of the `/catalog` route, so a link reproduces the view: the words searched,
- * the filters and the open state. Filters take comma-separated values (a comma or backslash inside a value is written `\,` or
+ * the filters, the open state and an open comparison (`compare`, `from`, `to`). Filters take comma-separated values (a comma or backslash inside a value is written `\,` or
  * `\\`), the same form `GET /api/reports/ui-catalog` takes. Anything unreadable is dropped, never an error.
  */
 import { parseUiCatalogQuery, uiCatalogParams, type UiCatalogQuery } from '@crvouga/atlas/reports/ui-catalog';
@@ -28,16 +28,27 @@ export const CatalogSearchFields = {
   surface: text,
   producer: text,
   /** The open state: a state id. */
-  state: text
+  state: text,
+  /** A comparison is open: `commit` (two commits of the same profiles) or `profile` (two profiles of this report). */
+  compare: text,
+  /** The comparison's before side: a commit id, or a profile key. */
+  from: text,
+  /** The comparison's after side. */
+  to: text,
+  /** `1` shows the pairs that did not change too. */
+  all: text
 };
 
+/** The parts of the address that are not filters of the catalog's states. */
+const NOT_FILTERS = ['state', 'compare', 'from', 'to', 'all'];
+
 /** The address's parts, as the router holds them. */
 export type CatalogSearch = { readonly [K in keyof typeof CatalogSearchFields]?: string | undefined };
 
 /** The query an address asks for. */
 export function catalogQueryOf(search: CatalogSearch): UiCatalogQuery {
   const params = new URLSearchParams();
-  for (const [name, value] of Object.entries(search)) if (name !== 'state' && typeof value === 'string') params.set(name, value);
+  for (const [name, value] of Object.entries(search)) if (!NOT_FILTERS.includes(name) && typeof value === 'string') params.set(name, value);
   return parseUiCatalogQuery(params);
 }
 

package/packages/visualizer/src/components/Header.tsx

@@ -1,5 +1,5 @@
 import { SpecLogo } from './SpecLogo';
-import { IconDots, IconLayoutGrid, IconListSearch } from '@tabler/icons-react';
+import { IconDots, IconLayoutGrid, IconListSearch, IconSparkles } from '@tabler/icons-react';
 import { isUiKind } from '@crvouga/atlas/reports/ui-state';
 import { isStatechartFile } from '@crvouga/atlas/schema';
 import { ActionIcon, Anchor, Badge, Box, Button, Group, Menu, NativeSelect, Popover, Stack, Tooltip } from '@mantine/core';
@@ -139,10 +139,13 @@ export function Header() {
   );
   const project = currentProject();
   const catalogOpen = pathname === '/catalog';
+  const critiquesOpen = pathname === '/critiques';
   const behaviorsOpen = pathname === '/behaviors';
   const hasFeatures = evidence.files.some(SPEC_KINDS[0]!.accepts);
   // The catalog is offered once the report holds a state or a plan for one.
   const hasCatalog = useMemo(() => evidence.evidence.some((layer) => layer.rows.some((row) => isUiKind(row.kind))), [evidence.evidence]);
+  // Needs polish is offered once a critic has recorded an opinion.
+  const hasCritiques = useMemo(() => evidence.evidence.some((layer) => layer.rows.some((row) => row.critique !== undefined)), [evidence.evidence]);
   return (
     <Group flex={1} miw={0} justify="space-between" wrap="nowrap" gap="xs">
       <Group gap="xs" wrap="nowrap" miw={0}>
@@ -157,13 +160,13 @@ export function Header() {
               leftSection={kind ? <SpecLogo kind={kind} /> : undefined}
               rightSection={<ChevronDownIcon aria-hidden="true" size={12} />}
             >
-              {catalogOpen ? 'UI catalog' : behaviorsOpen ? 'Behaviors' : (kind?.label ?? (hasCharts ? 'Statecharts' : evidence.ready && !tabs.length ? 'Tests' : 'Specs'))}
+              {catalogOpen ? 'UI catalog' : critiquesOpen ? 'Needs polish' : behaviorsOpen ? 'Behaviors' : (kind?.label ?? (hasCharts ? 'Statecharts' : evidence.ready && !tabs.length ? 'Tests' : 'Specs'))}
             </Button>
           </Menu.Target>
           <Menu.Dropdown>
             <Box component="nav" aria-label="Spec type">
               <Menu.Item
-                aria-current={pathname.startsWith('/specs/') || catalogOpen || behaviorsOpen ? undefined : 'page'}
+                aria-current={pathname.startsWith('/specs/') || catalogOpen || behaviorsOpen || critiquesOpen ? undefined : 'page'}
                 renderRoot={(props) => <Link {...props} to="/" search={(prev) => runOnly(prev)} />}
               >
                 {hasCharts || !evidence.ready ? 'Statecharts' : 'Tests'}
@@ -203,6 +206,15 @@ export function Header() {
                   UI catalog
                 </Menu.Item>
               )}
+              {(hasCritiques || critiquesOpen) && (
+                <Menu.Item
+                  leftSection={<IconSparkles size={16} aria-hidden="true" />}
+                  aria-current={critiquesOpen ? 'page' : undefined}
+                  renderRoot={(props) => <Link {...props} to="/critiques" search={{}} />}
+                >
+                  Needs polish
+                </Menu.Item>
+              )}
             </Box>
           </Menu.Dropdown>
         </Menu>
@@ -274,7 +286,7 @@ function SpecBreadcrumb() {
         name: item.name,
         running: (evidence.view.specs.get(outlinePath(item.file))?.summary.counts.running ?? 0) > 0
       }));
-  if (!options.length || pathname === '/catalog' || pathname === '/behaviors') return null;
+  if (!options.length || pathname === '/catalog' || pathname === '/behaviors' || pathname === '/critiques') return null;
   return (
     <NativeSelect
       data-running={options.some((option) => option.running) || undefined}