@crvouga/atlas 1.13.0 → 1.14.0

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

@@ -2,6 +2,8 @@ import { isStatechartFile } from '@crvouga/atlas/schema';
 import { Alert, Box, Burger, Button, Container, Group, AppShell as MantineAppShell, ScrollArea, Stack, Text } from '@mantine/core';
 import { Outlet, useLocation, useSearch } from '@tanstack/react-router';
 import { lazy, Suspense, useEffect, useState } from 'react';
+import { UiCatalogFilters } from '../catalog/UiCatalogFilters';
+import { UiCatalogProvider } from '../catalog/provider';
 import { Header } from '../components/Header';
 import { EvidenceProvider, useEvidence } from '../evidence/evidence-context';
 import { SourcesPanel } from '../evidence/sources-panel';
@@ -20,7 +22,9 @@ function Index() {
   const evidence = useEvidence();
   const { pathname } = useLocation();
   const kind = kindOfAddress(pathname);
-  return kind ? (
+  return pathname === '/catalog' ? (
+    <UiCatalogFilters />
+  ) : kind ? (
     <SpecIndex kind={kind} />
   ) : pathname.startsWith('/specs/') ? (
     <Box component="nav" aria-label="Specs" />
@@ -35,7 +39,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/') && !view && spec.error)
+  if (!pathname.startsWith('/specs/') && pathname !== '/catalog' && !view && spec.error)
     return (
       <Container py="xl">
         <Alert color="red" title="The spec couldn’t be loaded">
@@ -53,34 +57,36 @@ function Layout() {
   const location = useLocation();
   useEffect(() => setOpened(false), [location.href]);
   return (
-    <MantineAppShell header={{ height: 64 }} navbar={{ width: 288, breakpoint: 'md', collapsed: { mobile: !opened } }} padding={0}>
-      <MantineAppShell.Header>
-        <Group h="100%" px="md" gap="sm" wrap="nowrap">
-          <Burger
-            aria-expanded={opened}
-            aria-controls="atlas-navigation"
-            opened={opened}
-            onClick={() => setOpened((v) => !v)}
-            hiddenFrom="md"
-            size="sm"
-            aria-label="Toggle navigation"
-          />
-          <Header />
-        </Group>
-      </MantineAppShell.Header>
-      <MantineAppShell.Navbar id="atlas-navigation" component="div">
-        <ScrollArea h="100%">
-          <Index />
-        </ScrollArea>
-      </MantineAppShell.Navbar>
-      <MantineAppShell.Main>
-        <Body />
-      </MantineAppShell.Main>
-      <SourcesPanel />
-      <Suspense fallback={null}>
-        <Finder />
-      </Suspense>
-    </MantineAppShell>
+    <UiCatalogProvider enabled={location.pathname === '/catalog'}>
+      <MantineAppShell header={{ height: 64 }} navbar={{ width: 288, breakpoint: 'md', collapsed: { mobile: !opened } }} padding={0}>
+        <MantineAppShell.Header>
+          <Group h="100%" px="md" gap="sm" wrap="nowrap">
+            <Burger
+              aria-expanded={opened}
+              aria-controls="atlas-navigation"
+              opened={opened}
+              onClick={() => setOpened((v) => !v)}
+              hiddenFrom="md"
+              size="sm"
+              aria-label="Toggle navigation"
+            />
+            <Header />
+          </Group>
+        </MantineAppShell.Header>
+        <MantineAppShell.Navbar id="atlas-navigation" component="div">
+          <ScrollArea h="100%">
+            <Index />
+          </ScrollArea>
+        </MantineAppShell.Navbar>
+        <MantineAppShell.Main>
+          <Body />
+        </MantineAppShell.Main>
+        <SourcesPanel />
+        <Suspense fallback={null}>
+          <Finder />
+        </Suspense>
+      </MantineAppShell>
+    </UiCatalogProvider>
   );
 }
 export function AppShell() {

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

@@ -10,6 +10,8 @@ import {
   type RouterHistory
 } from '@tanstack/react-router';
 import { z } from 'zod/v4';
+import { CatalogSearchFields } from '../catalog/search';
+import { UiCatalogPage } from '../catalog/UiCatalogPage';
 import { SpecPage } from '../evidence/spec-page';
 import { ExplorerSearchFields } from '../explorer/search';
 import { ProductPage } from '../views/ProductPage';
@@ -87,7 +89,14 @@ function routeTree() {
     validateSearch: (search) => SpecSearch.parse(search),
     component: SpecPage
   });
-  return rootRoute.addChildren([productRoute, chartRoute, specRoute]);
+  /** The UI catalog: the captured states of the interface, filtered by the address (see `catalog/search.ts`). */
+  const catalogRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/catalog',
+    validateSearch: (search) => RootSearch.extend(CatalogSearchFields).parse(search),
+    component: UiCatalogPage
+  });
+  return rootRoute.addChildren([productRoute, chartRoute, specRoute, catalogRoute]);
 }
 export function createAtlasRouter(history: RouterHistory) {
   return createRouter({ routeTree: routeTree(), history, defaultPreload: false, scrollRestoration: true });

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

@@ -0,0 +1,65 @@
+/**
+ * @module UI catalog filters
+ *
+ * The controls beside the catalog: words, coverage, profile, area, route, cohort, feature flag, surface and producer. Each offers
+ * the values the catalog has with how many states have them. What is chosen is the address, so copying it or reloading restores
+ * the same view; choices combine with AND across the controls and OR within one.
+ */
+import { UI_COVERAGE, isUiCatalogFiltered, type UiCatalogQuery, type UiFacetValue } from '@crvouga/atlas/reports/ui-catalog';
+import { joinList } from '@crvouga/atlas/reports/artifact-query';
+import { Button, MultiSelect, Stack, TextInput, Title } from '@mantine/core';
+import { useMemo } from 'react';
+
+import { useUiCatalog } from './provider';
+import { useCatalogNavigate, useCatalogSearch } from './search';
+import { coverageWord } from './words';
+
+type Field = 'coverage' | 'profile' | 'area' | 'route' | 'cohort' | 'flag' | 'surface' | 'producer';
+
+function Facet({ field, label, options, query }: { field: Field; label: string; options: readonly UiFacetValue[]; query: UiCatalogQuery }) {
+  const go = useCatalogNavigate();
+  const chosen = (query[field] ?? []) as readonly string[];
+  const data = useMemo(() => options.map((option) => ({ value: option.value, label: `${option.label ?? (field === 'coverage' ? coverageWord(option.value) : option.value)} (${option.count})` })), [options, field]);
+  if (!data.length && !chosen.length) return null;
+  return (
+    <MultiSelect
+      label={label}
+      data={data}
+      value={[...chosen]}
+      searchable
+      clearable
+      placeholder={chosen.length ? undefined : `Any ${label.toLowerCase()}`}
+      nothingFoundMessage="Nothing found"
+      onChange={(next) => go({ [field]: joinList(next) })}
+    />
+  );
+}
+
+/** The navigation column of the catalog page. */
+export function UiCatalogFilters() {
+  const catalog = useUiCatalog();
+  const { query } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  if (!catalog) return null;
+  const { facets } = catalog;
+  const coverage = UI_COVERAGE.map((value) => facets.coverage.find((facet) => facet.value === value) ?? { value, count: 0 }).filter((facet) => facet.count > 0 || query.coverage?.includes(facet.value as never));
+  return (
+    <Stack component="nav" aria-label="UI catalog filters" p="md" gap="sm">
+      <Title order={2}>Find states</Title>
+      <TextInput label="Search states" description="Id, title, route, fixture, cohort, flag or surface" value={query.q ?? ''} onChange={(event) => go({ q: event.currentTarget.value || undefined }, { replace: true })} />
+      <Facet field="coverage" label="Coverage" options={coverage} query={query} />
+      <Facet field="profile" label="Profile" options={facets.profiles} query={query} />
+      <Facet field="area" label="Area" options={facets.areas} query={query} />
+      <Facet field="route" label="Route" options={facets.routes} query={query} />
+      <Facet field="cohort" label="Cohort" options={facets.cohorts} query={query} />
+      <Facet field="flag" label="Feature flag" options={facets.flags} query={query} />
+      <Facet field="surface" label="Surface" options={facets.surfaces} query={query} />
+      <Facet field="producer" label="Producer" options={facets.producers} query={query} />
+      {isUiCatalogFiltered(query) && (
+        <Button type="button" variant="subtle" onClick={() => go({ q: undefined, coverage: undefined, profile: undefined, area: undefined, route: undefined, cohort: undefined, flag: undefined, surface: undefined, producer: undefined })}>
+          Clear filters
+        </Button>
+      )}
+    </Stack>
+  );
+}

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

@@ -0,0 +1,342 @@
+/**
+ * @module UI catalog page
+ *
+ * A browsable inventory of the product's user interface: each state captured once per profile (viewport, color scheme, device),
+ * with where each picture came from, and what is expected and not captured yet. It reads the report the viewer already holds, so
+ * states appear as layers arrive and no reload or rebuilt file is needed. A state is shown as captured only when a passing
+ * 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 { 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 { 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 { EvidenceIncomplete, EvidenceWaiting } from '../evidence/load-state';
+import { StatusMark } from '../evidence/marks';
+import { useUiCatalog } from './provider';
+import { useCatalogNavigate, useCatalogSearch } from './search';
+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} />}>
+      {cell.profile.label}: {coverageWord(cell.coverage)}
+    </Badge>
+  );
+}
+
+function StateCard({ state, shown }: { state: UiCatalogState; shown: UiCell }) {
+  return (
+    <Card withBorder role="listitem" data-state={state.id}>
+      <Card.Section p="sm">
+        <Picture cell={shown} title={state.title} height={160} />
+      </Card.Section>
+      <Stack gap="xs" mt="sm">
+        <Anchor
+          fw={700}
+          aria-label={`Open ${state.title}`}
+          renderRoot={(props) => <Link {...props} to="/catalog" search={((prev: Record<string, unknown>) => ({ ...prev, state: state.id })) as never} resetScroll={false} />}
+        >
+          {state.title}
+        </Anchor>
+        <Text c="dimmed" fz="xs">
+          {state.id}
+          {state.route ? ` · ${state.route}` : ''}
+        </Text>
+        <Group gap="xs" aria-label={`${state.title} by profile`}>
+          {state.cells.map((cell) => (
+            <CoverageBadge key={cell.profile.key} cell={cell} />
+          ))}
+        </Group>
+      </Stack>
+    </Card>
+  );
+}
+
+function Origin({ capture, now }: { capture: UiCapture; now: number }) {
+  const { origin } = capture;
+  const sha = shortSha(origin.sha);
+  return (
+    <Text c="dimmed" fz="xs" component="div">
+      From layer <Code>{origin.layer.slice(0, 12)}</Code> in backend <Code>{origin.backend}</Code>, producer {origin.producer}
+      {capture.labels.shard ? `, shard ${capture.labels.shard}` : ''}
+      {origin.branch ? `, ${origin.branch}` : ''}
+      {sha ? <> at <Code>{sha}</Code></> : ''}
+      {', '}
+      <time dateTime={new Date(origin.recordedAtMs).toISOString()} title={exactTime(origin.recordedAtMs)}>
+        {ago(origin.recordedAtMs, now)}
+      </time>
+      {origin.freshness === 'modified' ? ', recorded with local changes' : origin.freshness === 'unknown' ? ', origin not captured' : ''}
+      {capture.alternatives > 0 ? `, ${plural(capture.alternatives, 'other capture', 'other captures')} from other producers` : ''}
+    </Text>
+  );
+}
+
+function CellColumn({ cell, state, now }: { cell: UiCell; state: UiCatalogState; now: number }) {
+  const source = cell.coverage === 'captured' || cell.coverage === 'failed' ? imageSource(cell.capture?.image) : null;
+  return (
+    <Stack gap="xs" component="section" aria-label={`${state.title} in ${cell.profile.label}`}>
+      <Title order={3}>{cell.profile.label}</Title>
+      <Group gap="xs">
+        <StatusMark status={coverageStatus(cell.coverage)} size={16} />
+        <Text fw={600}>{coverageWord(cell.coverage)}</Text>
+        {cell.expected === 'undeclared' && <Badge variant="outline">Not in the expected set</Badge>}
+        {cell.expected === 'declared' && cell.coverage !== 'captured' && <Badge variant="outline">Expected</Badge>}
+      </Group>
+      <Picture cell={cell} title={state.title} />
+      {source && (
+        <Anchor href={source} target="_blank" rel="noreferrer noopener" fz="sm">
+          Open the picture{cell.capture?.image?.width && cell.capture.image.height ? ` (${cell.capture.image.width}×${cell.capture.image.height})` : ''}
+        </Anchor>
+      )}
+      {cell.capture?.detail && (
+        <Text fz="sm" role="note">
+          {cell.capture.detail}
+        </Text>
+      )}
+      {cell.capture ? <Origin capture={cell.capture} now={now} /> : cell.planned ? <Text c="dimmed" fz="xs">Expected by plan layer <Code>{cell.planned.layer.slice(0, 12)}</Code> in backend <Code>{cell.planned.backend}</Code>. Nothing has been captured.</Text> : null}
+    </Stack>
+  );
+}
+
+/** The open state: every profile side by side, with the facts declared about it and where each picture came from. */
+function StateDetail({ state, onClose }: { state: UiCatalogState; onClose: () => void }) {
+  const now = useNow();
+  const facts: [string, string][] = [
+    ['Route', state.route ?? ''], ['Fixture', state.fixture ?? ''], ['Cohort', state.cohort ?? ''], ['Area', state.area ?? ''],
+    ['Feature flags', state.flags.join(', ')], ['Surfaces covered', state.covers.join(', ')], ['Producers', state.producers.join(', ')]
+  ];
+  return (
+    <Drawer opened onClose={onClose} position="right" size="xl" title={<Title order={2}>{state.title}</Title>} closeButtonProps={{ 'aria-label': 'Close the state' }}>
+      <Stack gap="md">
+        <Text c="dimmed" fz="sm">
+          {state.id}
+        </Text>
+        <Table aria-label="Declared facts" withRowBorders>
+          <Table.Tbody>
+            {facts.map(([name, value]) => (
+              <Table.Tr key={name}>
+                <Table.Th scope="row" w="40%">{name}</Table.Th>
+                <Table.Td>{value || <Text span c="dimmed">Not declared</Text>}</Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+        <Title order={3}>Profiles side by side</Title>
+        <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+          {state.cells.map((cell) => (
+            <CellColumn key={cell.profile.key} cell={cell} state={state} now={now} />
+          ))}
+        </SimpleGrid>
+      </Stack>
+    </Drawer>
+  );
+}
+
+function download(catalog: UiCatalog) {
+  const url = URL.createObjectURL(new Blob([JSON.stringify(catalog, null, 2)], { type: 'application/json' }));
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = 'ui-catalog.json';
+  link.click();
+  URL.revokeObjectURL(url);
+}
+
+function Summary({ catalog, narrowed }: { catalog: UiCatalog; narrowed: boolean }) {
+  const { summary } = catalog;
+  return (
+    <Stack gap="xs">
+      <Group gap="xs" role="status" aria-label="Catalog summary">
+        <Badge variant="light">{plural(summary.states, 'state', 'states')}</Badge>
+        <Badge variant="light">{plural(summary.profiles, 'profile', 'profiles')}</Badge>
+        {UI_COVERAGE.map((value) =>
+          summary.coverage[value] > 0 ? (
+            <Badge key={value} variant="light" color={value === 'captured' ? 'green' : value === 'failed' ? 'red' : value === 'capturing' ? 'blue' : 'gray'}>
+              {summary.coverage[value]} {coverageWord(value).toLowerCase()}
+            </Badge>
+          ) : null
+        )}
+        {summary.undeclared > 0 && <Badge variant="outline">{summary.undeclared} not in the expected set</Badge>}
+      </Group>
+      {narrowed && (
+        <Text c="dimmed" fz="sm">
+          Counts are for the states that match the filters.
+        </Text>
+      )}
+      {!summary.planned && summary.cells > 0 && (
+        <Text c="dimmed" fz="sm">
+          No expected set has been published, so states that should exist but were never captured cannot be listed. Publish a <Code>ui-plan</Code> layer to see them as not captured yet.
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+function Surfaces({ catalog }: { catalog: UiCatalog }) {
+  if (!catalog.surfaces.length) return null;
+  const open = catalog.summary.uncoveredSurfaces;
+  const inventoried = catalog.surfaces.some((surface) => surface.inventoried);
+  return (
+    <Accordion variant="contained" defaultValue={open ? 'surfaces' : null}>
+      <Accordion.Item value="surfaces">
+        <Accordion.Control>
+          Coverage of the product&rsquo;s surfaces: {plural(catalog.surfaces.length, 'surface', 'surfaces')}, {open === 0 ? 'all with a captured state' : `${open} without one`}
+        </Accordion.Control>
+        <Accordion.Panel>
+          <Table.ScrollContainer minWidth={420}>
+            <Table aria-label="Surfaces">
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th scope="col">Surface</Table.Th>
+                  <Table.Th scope="col">Coverage</Table.Th>
+                  <Table.Th scope="col">States</Table.Th>
+                  <Table.Th scope="col">Captured</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {catalog.surfaces.map((surface) => (
+                  <Table.Tr key={surface.id} data-surface={surface.id}>
+                    <Table.Td>
+                      <Anchor
+                        renderRoot={(props) => <Link {...props} to="/catalog" search={((prev: Record<string, unknown>) => ({ ...prev, surface: surface.id })) as never} resetScroll={false} />}
+                      >
+                        {surface.id}
+                      </Anchor>
+                      {inventoried && !surface.inventoried ? ' (not in the inventory)' : ''}
+                    </Table.Td>
+                    <Table.Td>{surface.status === 'covered' ? 'Covered' : surface.status === 'uncaptured' ? 'States cover it, none captured yet' : 'No state covers it'}</Table.Td>
+                    <Table.Td>{surface.states}</Table.Td>
+                    <Table.Td>{surface.captured}</Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Table.ScrollContainer>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+
+/** The `/catalog` route. */
+export function UiCatalogPage() {
+  const evidence = useEvidence();
+  const whole = useUiCatalog();
+  const { query, search } = useCatalogSearch();
+  const go = useCatalogNavigate();
+  const [shown, setShown] = useState(CARDS);
+  const catalog = useMemo(() => (whole ? filterUiCatalog(whole, query) : null), [whole, query]);
+  const narrowed = isUiCatalogFiltered(query);
+  const unavailable = evidence.backends.filter((backend) => !backend.available);
+  const open = catalog && search.state ? whole?.states.find((state) => state.id === search.state) ?? null : null;
+  return (
+    <Container size="xl" w="100%" py="xl" component="article" aria-label="UI catalog">
+      <Stack gap="md">
+        <Group justify="space-between" align="flex-start">
+          <Stack gap={4}>
+            <Title order={1}>UI catalog</Title>
+            <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>
+        {evidence.unavailable && (
+          <Alert role="alert" color="red" title="Recorded results cannot be read">
+            <Group gap="sm">
+              <Text span inherit>{evidence.unavailable}</Text>
+              <Button type="button" variant="subtle" onClick={evidence.retry}>Try again</Button>
+            </Group>
+          </Alert>
+        )}
+        {unavailable.length > 0 && (
+          <Alert role="status" color="orange" title={`${plural(unavailable.length, 'backend is', 'backends are')} not available`}>
+            {unavailable.map((backend) => backend.label).join(', ')}: captures held there are not shown, and nothing that depends on them is shown as captured. This catalog may be incomplete.
+          </Alert>
+        )}
+        {evidence.notices.length > 0 && (
+          <Alert role="status" color="orange" title="Some results could not be read">
+            {evidence.notices.join(' ')}
+          </Alert>
+        )}
+        <EvidenceIncomplete />
+        {!evidence.ready && !evidence.unavailable && <EvidenceWaiting label="Reading the recorded states…" />}
+        {evidence.ready && evidence.pending > 0 && (
+          <Text role="status" c="dimmed" component="div">
+            Reading {plural(evidence.pending, 'more layer', 'more layers')}; states appear here as they arrive.
+          </Text>
+        )}
+        {catalog && whole && (
+          <>
+            <Summary catalog={catalog} narrowed={narrowed} />
+            <Surfaces catalog={whole} />
+            {whole.states.length === 0 && evidence.ready && (
+              <Text c="dimmed" role="status" component="div" data-empty>
+                No UI states have been recorded yet. A collector publishes a layer with a part of kind <Code>ui-state</Code>; states appear here the moment it arrives.
+              </Text>
+            )}
+            {whole.states.length > 0 && catalog.states.length === 0 && (
+              <Stack gap="xs" align="flex-start" role="status" data-no-match>
+                <Text c="dimmed">Nothing matches these filters.</Text>
+                <Button type="button" variant="light" onClick={() => go({ q: undefined, coverage: undefined, profile: undefined, area: undefined, route: undefined, cohort: undefined, flag: undefined, surface: undefined, producer: undefined })}>
+                  Clear filters
+                </Button>
+              </Stack>
+            )}
+            {catalog.states.length > 0 && (
+              <>
+                <SimpleGrid role="list" cols={{ base: 1, sm: 2, lg: 3, xl: 4 }} spacing="md" aria-label="States">
+                  {catalog.states.slice(0, shown).map((state) => (
+                    <StateCard key={state.id} state={state} shown={state.cells.find((cell) => cell.coverage === 'captured') ?? state.cells[0]!} />
+                  ))}
+                </SimpleGrid>
+                {catalog.states.length > shown && (
+                  <Button type="button" variant="subtle" onClick={() => setShown(shown + CARDS)}>
+                    Show more ({catalog.states.length - shown} more)
+                  </Button>
+                )}
+              </>
+            )}
+          </>
+        )}
+        {search.state && catalog && !open && evidence.ready && evidence.pending === 0 && (
+          <Alert role="status" color="gray" title="That state is not in the catalog">
+            <Text span inherit>{search.state}</Text> has no recorded capture or plan yet. It appears here if a layer that holds it arrives.{' '}
+            <Anchor renderRoot={(props) => <Link {...props} to="/catalog" search={((prev: Record<string, unknown>) => ({ ...prev, state: undefined })) as never} />}>Back to the catalog</Anchor>
+          </Alert>
+        )}
+      </Stack>
+      {open && <StateDetail state={open} onClose={() => go({ state: undefined })} />}
+    </Container>
+  );
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @module UI catalog data
+ *
+ * The UI catalog of the report the viewer already holds. It is computed here, from the same layers the rest of the viewer
+ * shows (`uiCatalog` from `@crvouga/atlas/reports/ui-catalog`), so it fills in as layers arrive over the server's event stream
+ * and `?since=` deltas, and works unchanged when the viewer reads a store or a static export without a server.
+ */
+import { uiCatalog, type UiCatalog } from '@crvouga/atlas/reports/ui-catalog';
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+
+import { useEvidence } from '../evidence/evidence-context';
+
+const CatalogContext = createContext<UiCatalog | null>(null);
+
+/** Computes the catalog for its children, only while `enabled` (the catalog page is open): other pages pay nothing. */
+export function UiCatalogProvider({ enabled, children }: { enabled: boolean; children: ReactNode }) {
+  const { evidence, backends, notices, version } = useEvidence();
+  const catalog = useMemo(() => (enabled ? uiCatalog(evidence, { backends, notices, ...(version ? { version } : {}) }) : null), [enabled, evidence, backends, notices, version]);
+  return <CatalogContext.Provider value={catalog}>{children}</CatalogContext.Provider>;
+}
+
+/** The whole catalog (before the address's filters), or null when the catalog page is not open. */
+export function useUiCatalog(): UiCatalog | null {
+  return useContext(CatalogContext);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * @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 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';
+import { useNavigate, useSearch } from '@tanstack/react-router';
+import { useMemo } from 'react';
+import { z } from 'zod/v4';
+
+/** A search value as text: the router reads `123` as a number and `["a"]` as an array, both of which are meant as text here. */
+const text = z
+  .preprocess((value) => (typeof value === 'number' || typeof value === 'boolean' ? String(value) : value !== null && typeof value === 'object' ? JSON.stringify(value) : value), z.string().min(1))
+  .optional()
+  .catch(undefined);
+
+/** The `/catalog` route's search: the query of `GET /api/reports/ui-catalog` and the state opened. */
+export const CatalogSearchFields = {
+  q: text,
+  coverage: text,
+  profile: text,
+  area: text,
+  route: text,
+  cohort: text,
+  flag: text,
+  surface: text,
+  producer: text,
+  /** The open state: a state id. */
+  state: text
+};
+
+/** 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);
+  return parseUiCatalogQuery(params);
+}
+
+/** The address parts of a query, with the opened state kept as given. */
+export function catalogSearchOf(query: UiCatalogQuery, state?: string): CatalogSearch {
+  return { ...Object.fromEntries(uiCatalogParams(query)), ...(state ? { state } : {}) };
+}
+
+/** The catalog's search parameters, read from the address. */
+export function useCatalogSearch(): { readonly search: CatalogSearch; readonly query: UiCatalogQuery } {
+  const raw = useSearch({ strict: false }) as Record<string, unknown>;
+  return useMemo(() => {
+    const search: Record<string, string> = {};
+    for (const name of Object.keys(CatalogSearchFields)) {
+      const value = raw[name];
+      if (typeof value === 'string' && value) search[name] = value;
+      else if (typeof value === 'number') search[name] = String(value);
+    }
+    return { search, query: catalogQueryOf(search) };
+  }, [raw]);
+}
+
+/** Returns `go(patch)`, which moves the catalog to the address with `patch` applied (fields set to undefined are removed). */
+export function useCatalogNavigate() {
+  const navigate = useNavigate();
+  return (patch: CatalogSearch, options: { replace?: boolean } = {}) =>
+    void navigate({ to: '/catalog', search: ((prev: Record<string, unknown>) => ({ ...prev, ...patch })) as never, replace: options.replace ?? false, resetScroll: false });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @module UI catalog wording
+ *
+ * The words the catalog uses for a cell's coverage. Only `captured` is called captured; a state that is expected and not yet
+ * captured says so, and never looks like a picture exists.
+ */
+import type { UiCoverage } from '@crvouga/atlas/reports/ui-catalog';
+import type { SpecStatus } from '@crvouga/atlas/reports/evidence-view';
+
+const WORDS: Readonly<Record<UiCoverage, string>> = {
+  captured: 'Captured',
+  failed: 'Capture failed',
+  capturing: 'Capturing',
+  skipped: 'Skipped',
+  missing: 'Not captured yet'
+};
+
+/** The words for a coverage value; an unknown one is shown as it is. */
+export function coverageWord(value: string): string {
+  return WORDS[value as UiCoverage] ?? value;
+}
+
+/** The outcome mark that stands for a coverage value: every one but `captured` is a different mark, never a pass. */
+export function coverageStatus(value: UiCoverage): SpecStatus {
+  return value === 'captured' ? 'passed' : value === 'failed' ? 'failed' : value === 'capturing' ? 'running' : value === 'skipped' ? 'not-run' : 'none';
+}