@crvouga/atlas 1.1.0 → 1.3.0

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

@@ -17,13 +17,25 @@ import type { EvidenceStatus } from '@crvouga/atlas/reports/explorer-types';
 import type { LayerEvidence, LayerRows, StatusCounts } from '@crvouga/atlas/reports/evidence-types';
 import type { CheckSlot, EvidenceView } from '@crvouga/atlas/reports/evidence-view';
 import {
+  facetsOf,
+  filterParams,
+  forRuns,
+  matchesFilter,
+  usedFilters,
+  type ArtifactFilter,
+  type FilterName,
+  type QueryFacets
+} from '@crvouga/atlas/reports/artifact-query';
+import {
+  artifactList,
   catalogModel,
+  fieldsOfRun,
   haystackOf,
-  hasVideo,
   runDetail,
   runList,
   testHistory,
   TestHistory,
+  type ArtifactList,
   type CatalogModel,
   type RunDetail,
   type RunList,
@@ -40,6 +52,8 @@ import { useEvidence } from '../evidence/evidence-context';
 
 /** How many runs the Runs tab lists. */
 export const RUNS_SHOWN = 500;
+/** How many recorded results the Artifacts tab lists. */
+export const ARTIFACTS_SHOWN = 200;
 /** The server's catalog is read again at most this often while results keep arriving. */
 const SERVER_REREAD_MS = 5_000;
 /** Layers read one after another are folded into the page's catalog at most this often. */
@@ -234,24 +248,95 @@ export function useTestHistory(key: string | undefined) {
   });
 }
 
+/** The runs a query matched, and what this server could not do about it. */
+export type RunsAnswer = RunList & {
+  /** What the viewer's query asks for that the answer does not reflect: filters an older server ignores and the viewer cannot apply itself (tags, types, labels need data it does not send). Say so; never present the list as narrowed by them. */
+  readonly notApplied: readonly FilterName[];
+  /** The values each dimension offers, from the server or worked out from the runs it sent. */
+  readonly facets: QueryFacets;
+};
+
+/** What an older server's run summary can answer by itself: the viewer filters its complete list for these. */
+const ANSWERABLE_HERE: ReadonlySet<FilterName> = new Set(['q', 'environment', 'producer', 'branch', 'sha', 'outcome', 'since', 'until', 'video']);
+
 /**
- * CI runs, newest first. With `video`, only the runs that have a playable video recording: the server filters every run
- * before it pages them, so the count is the whole dataset's. A server that does not know the parameter answers with
- * every run (and no video information), which is filtered here.
+ * Makes a server's answer honest about the filters it did not apply (an older server ignores parameters it does not know
+ * and answers with every run). Those the run summary can answer are applied here, to the complete list; the rest are
+ * reported in `notApplied` so the page can say the list is not narrowed by them.
  */
-export function useRunList(enabled = true, video = false) {
+export function runsAnswer(list: RunList, filter: ArtifactFilter): RunsAnswer {
+  const asked = usedFilters(forRuns(filter)).filter((name) => name !== 'inherited');
+  // A server that predates `filters` but has `withVideo` already filtered by `video`.
+  const applied = new Set<FilterName>(list.filters ?? (list.withVideo !== undefined ? ['video'] : []));
+  const missing = asked.filter((name) => !applied.has(name));
+  if (!missing.length && list.facets) return { ...list, facets: list.facets, notApplied: [] };
+  const here = missing.filter((name) => ANSWERABLE_HERE.has(name));
+  const sub = Object.fromEntries(here.map((name) => [name, filter[name]])) as ArtifactFilter;
+  const runs = here.length ? list.runs.filter((run) => matchesFilter(fieldsOfRun(run), sub)) : list.runs;
+  return {
+    ...list,
+    total: here.length ? runs.length : list.total,
+    runs,
+    facets: list.facets ?? facetsOf(list.runs.map(fieldsOfRun), sub),
+    notApplied: missing.filter((name) => !ANSWERABLE_HERE.has(name))
+  };
+}
+
+/**
+ * CI runs, newest first, narrowed by a query (see `artifact-query.ts`). The server filters every run before it pages
+ * them, so counts are the whole dataset's; a server that does not know a filter is handled by {@link runsAnswer}.
+ */
+export function useRunList(enabled = true, filter: ArtifactFilter = {}) {
   const catalog = useTestCatalog();
+  const query = forRuns(filter);
+  const key = filterParams(query).toString();
   return useQuery({
-    queryKey: ['test-runs', catalog.version, video],
-    queryFn: async ({ signal }): Promise<RunList> => {
+    queryKey: ['test-runs', catalog.version, key],
+    queryFn: async ({ signal }): Promise<RunsAnswer> => {
       if (catalog.source === 'server') {
-        const list = await reportJson<RunList>(`/runs?limit=${RUNS_SHOWN}${video ? '&video=true' : ''}`, signal);
-        if (!video || list.withVideo !== undefined) return list;
-        const runs = list.runs.filter(hasVideo);
-        return { ...list, total: runs.length, runs };
+        const params = filterParams(query);
+        params.set('limit', String(RUNS_SHOWN));
+        return runsAnswer(await reportJson<RunList>(`/runs?${params}`, signal), query);
       }
       const history = catalog.model?.history;
-      return history ? runList(history, catalog.version, RUNS_SHOWN, { video }) : { schemaVersion: 1, version: catalog.version, total: 0, runs: [] };
+      const list = history ? runList(history, catalog.version, RUNS_SHOWN, query) : { schemaVersion: 1 as const, version: catalog.version, total: 0, runs: [] };
+      return runsAnswer(list, query);
+    },
+    enabled: enabled && catalog.model !== null,
+    placeholderData: keepPreviousData,
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+}
+
+/** The recorded results that carry evidence and match a query, or `unsupported` when the server has no artifact search. */
+export type ArtifactsAnswer = { readonly unsupported: false; readonly list: ArtifactList } | { readonly unsupported: true };
+
+/**
+ * Recorded results that carry evidence (recordings, screenshots, traces) across the whole history, newest first. A
+ * server without `/artifacts` (an older one) answers `unsupported`, and the page says so instead of showing an empty list.
+ */
+export function useArtifactList(filter: ArtifactFilter, enabled = true) {
+  const catalog = useTestCatalog();
+  const key = filterParams(filter).toString();
+  return useQuery({
+    queryKey: ['test-artifacts', catalog.version, key],
+    queryFn: async ({ signal }): Promise<ArtifactsAnswer> => {
+      if (catalog.source === 'server') {
+        const params = filterParams(filter);
+        params.set('limit', String(ARTIFACTS_SHOWN));
+        try {
+          return { unsupported: false, list: await reportJson<ArtifactList>(`/artifacts?${params}`, signal) };
+        } catch (error) {
+          if (notFound(error)) return { unsupported: true };
+          throw error;
+        }
+      }
+      const model = catalog.model!;
+      const domains = new Map(model.facets.specs.map((spec) => [spec.path, spec.domain]));
+      const history = model.history;
+      if (!history) return { unsupported: true };
+      return { unsupported: false, list: artifactList(history, catalog.version, filter, { limit: ARTIFACTS_SHOWN, domainOf: (path) => domains.get(path) }) };
     },
     enabled: enabled && catalog.model !== null,
     placeholderData: keepPreviousData,

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

@@ -0,0 +1,279 @@
+/**
+ * @module Run and artifact filters
+ *
+ * The filter bar of the Runs and Artifacts tabs: words, artifact tag, media type, label, environment, branch, outcome,
+ * feature domain and a time range, each offering the values the report has with counts in the scope of the list. What is
+ * chosen shows as removable chips and is the address, so copying it or reloading restores the same view; named views keep
+ * a query to open again. Choices combine with AND across the controls and OR within one.
+ */
+import { IconBookmark, IconLink, IconTrash, IconX } from '@tabler/icons-react';
+import { Anchor, Badge, Box, Button, Checkbox, CopyButton, Flex, Group, MultiSelect, Popover, SimpleGrid, Stack, Text, TextInput } from '@mantine/core';
+import type { QueryFacets, QueryFacetValue } from '@crvouga/atlas/reports/artifact-query';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import { Link } from '@tanstack/react-router';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import { currentProject } from '../runtime';
+import { patched, useExplorerNavigate } from './navigate';
+import { filtered, joined, NO_FILTERS, toggled, values, type ExplorerSearch } from './search';
+import { filtersOf, isView, readViews, writeViews, type SavedView } from './views';
+
+type Param = 'artifactTag' | 'type' | 'label' | 'env' | 'branch' | 'outcome' | 'domain' | 'producer';
+
+const NOUN: Record<Param, string> = {
+  artifactTag: 'Tag',
+  type: 'Type',
+  label: 'Label',
+  env: 'Environment',
+  branch: 'Branch',
+  outcome: 'Outcome',
+  domain: 'Domain',
+  producer: 'Producer'
+};
+
+/** How a chosen value reads: tags with their hash, environments by name. */
+function shown(param: Param, value: string): string {
+  if (param === 'artifactTag') return `#${value}`;
+  if (param === 'env') return environmentLabel(value);
+  if (param === 'domain' && value === '(no spec)') return 'No spec';
+  return value;
+}
+
+function Facet({ param, facets, search }: { param: Param; facets: readonly QueryFacetValue[]; search: ExplorerSearch }) {
+  const go = useExplorerNavigate();
+  const chosen = values(search[param]);
+  const data = useMemo(() => facets.map((facet) => ({ value: facet.value, label: `${shown(param, facet.value)} (${facet.count})` })), [facets, param]);
+  if (!data.length && !chosen.length) return null;
+  return (
+    <MultiSelect
+      label={NOUN[param]}
+      data={data}
+      value={chosen}
+      searchable
+      clearable
+      placeholder={chosen.length ? undefined : `Any ${NOUN[param].toLowerCase()}`}
+      nothingFoundMessage="Nothing found"
+      onChange={(next) => go({ [param]: joined(next) } as never)}
+    />
+  );
+}
+
+/** Saved views: name the current filters, open one again, delete it. They are live queries, said so beside the list. */
+function Views({
+  search,
+  tab,
+  views,
+  onChange,
+  failed
+}: {
+  search: ExplorerSearch;
+  tab: 'runs' | 'artifacts';
+  views: readonly SavedView[];
+  onChange: (next: SavedView[]) => void;
+  failed: boolean;
+}) {
+  const project = currentProject() ?? '';
+  const [name, setName] = useState('');
+  const mine = views.filter((view) => view.project === project && view.tab === tab);
+  const keep = onChange;
+  const narrowed = filtered(search);
+  return (
+    <Popover width={360} position="bottom-start" withArrow shadow="md" trapFocus>
+      <Popover.Target>
+        <Button type="button" variant="default" leftSection={<IconBookmark size={16} aria-hidden="true" />}>
+          Views{mine.length ? ` (${mine.length})` : ''}
+        </Button>
+      </Popover.Target>
+      <Popover.Dropdown>
+        <Stack gap="sm" aria-label="Saved views">
+          <Text size="sm" c="dimmed">
+            A saved view is a live query: opening it asks again, so it shows what matches the newest report now. It is not a snapshot of the results you see today.
+          </Text>
+          {mine.length === 0 && (
+            <Text size="sm" c="dimmed">
+              No saved views for this tab yet.
+            </Text>
+          )}
+          {mine.map((view) => (
+            <Group key={view.id} justify="space-between" wrap="nowrap">
+              <Anchor
+                aria-label={`Open view ${view.name}`}
+                renderRoot={(props) => (
+                  <Link
+                    {...props}
+                    to="/"
+                    search={patched({ ...NO_FILTERS, ...view.filters, tab: view.tab, openRun: undefined, test: undefined, layer: undefined } as never)}
+                    resetScroll={false}
+                    activeOptions={{ exact: true }}
+                  />
+                )}
+              >
+                {view.name}
+              </Anchor>
+              <Badge variant="outline" color="gray">
+                Live query
+              </Badge>
+              <Button
+                type="button"
+                variant="subtle"
+                color="red"
+                aria-label={`Delete view ${view.name}`}
+                onClick={() => keep(views.filter((entry) => entry.id !== view.id))}
+              >
+                <IconTrash size={16} aria-hidden="true" />
+              </Button>
+            </Group>
+          ))}
+          <TextInput label="View name" value={name} onChange={(event) => setName(event.target.value)} placeholder="Demo review" />
+          <Button
+            type="button"
+            disabled={!name.trim() || !narrowed}
+            onClick={() => {
+              const saved: SavedView = {
+                id: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+                name: name.trim(),
+                tab,
+                project,
+                filters: filtersOf(search),
+                savedAtMs: Date.now()
+              };
+              keep([...views.filter((view) => !(view.project === project && view.tab === tab && view.name === saved.name)), saved]);
+              setName('');
+            }}
+          >
+            Save the current filters
+          </Button>
+          {!narrowed && (
+            <Text size="sm" c="dimmed">
+              Choose at least one filter to save a view.
+            </Text>
+          )}
+          {failed && (
+            <Text size="sm" c="red.7" role="alert">
+              This browser would not keep the view, so it will be gone when the page closes.
+            </Text>
+          )}
+        </Stack>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+
+/**
+ * The filter bar for a tab. `facets` are the values on offer with their counts; `extra` is shown beside the controls (the
+ * Runs tab's Has video button); `domains` offers the feature domain (artifacts only).
+ */
+export function FilterBar({
+  facets,
+  search,
+  tab,
+  extra
+}: {
+  facets: QueryFacets;
+  search: ExplorerSearch;
+  tab: 'runs' | 'artifacts';
+  extra?: ReactNode;
+}) {
+  const go = useExplorerNavigate();
+  const [draft, setDraft] = useState(search.q ?? '');
+  // The address may change from elsewhere (a link, a saved view, back): follow it.
+  useEffect(() => setDraft((current) => (current.trim() === (search.q ?? '').trim() ? current : (search.q ?? ''))), [search.q]);
+  const params: Param[] = ['artifactTag', 'type', 'label', 'env', 'branch', 'outcome', ...(tab === 'artifacts' ? (['domain'] as const) : []), 'producer'];
+  const chips = [
+    ...params.flatMap((param) =>
+      values(search[param]).map((value) => ({ label: `${NOUN[param]}: ${shown(param, value)}`, clear: { [param]: toggled(search[param], value) } as never }))
+    ),
+    ...(search.since ? [{ label: `From ${search.since}`, clear: { since: undefined } as never }] : []),
+    ...(search.until ? [{ label: `Until ${search.until}`, clear: { until: undefined } as never }] : []),
+    ...(search.q ? [{ label: `Words: ${search.q}`, clear: { q: undefined } as never }] : []),
+    ...(search.video ? [{ label: 'Has video', clear: { video: undefined } as never }] : [])
+  ];
+  const [views, setViews] = useState<SavedView[]>(() => readViews());
+  const [failed, setFailed] = useState(false);
+  const saved = views.find((view) => view.project === (currentProject() ?? '') && isView(view, search));
+  return (
+    <Box aria-label="Filters" component="section" mb="md">
+      <Stack gap="sm">
+        <Flex gap="sm" align="flex-end" wrap="wrap">
+          <TextInput
+            flex={1}
+            miw={{ base: '100%', sm: '15rem' }}
+            type="search"
+            aria-label={`Search ${tab}`}
+            placeholder={tab === 'runs' ? 'Search runs by title, branch, commit, tag…' : 'Search by test, spec, tag, label…'}
+            value={draft}
+            onChange={(event) => {
+              setDraft(event.target.value);
+              go({ q: event.target.value.trim() || undefined }, { replace: true });
+            }}
+          />
+          <Views
+            search={search}
+            tab={tab}
+            views={views}
+            failed={failed}
+            onChange={(next) => {
+              setViews(next);
+              setFailed(!writeViews(next));
+            }}
+          />
+          <CopyButton value={typeof window === 'undefined' ? '' : window.location.href}>
+            {({ copied, copy }) => (
+              <Button type="button" variant="default" onClick={copy} leftSection={<IconLink size={16} aria-hidden="true" />}>
+                {copied ? 'Link copied' : 'Copy link'}
+              </Button>
+            )}
+          </CopyButton>
+          {extra}
+        </Flex>
+        <SimpleGrid cols={{ base: 1, sm: 2, md: 4 }}>
+          <Facet param="artifactTag" facets={facets.artifactTags} search={search} />
+          <Facet param="type" facets={facets.types} search={search} />
+          <Facet param="label" facets={facets.labels} search={search} />
+          <Facet param="env" facets={facets.environments} search={search} />
+          <Facet param="branch" facets={facets.branches} search={search} />
+          <Facet param="outcome" facets={facets.outcomes} search={search} />
+          {tab === 'artifacts' && facets.domains && <Facet param="domain" facets={facets.domains} search={search} />}
+          {facets.producers.length > 1 && <Facet param="producer" facets={facets.producers} search={search} />}
+          <TextInput type="date" label="From" value={search.since ?? ''} onChange={(event) => go({ since: event.target.value || undefined })} />
+          <TextInput type="date" label="Until" value={search.until ?? ''} onChange={(event) => go({ until: event.target.value || undefined })} />
+        </SimpleGrid>
+        {values(search.artifactTag).length > 0 && (
+          <Checkbox
+            label="Also match tags inherited from the check and run"
+            description="Off: only tags written on the recording itself."
+            checked={search.inherited === true}
+            onChange={(event) => go({ inherited: event.currentTarget.checked ? true : undefined })}
+          />
+        )}
+        {(chips.length > 0 || saved) && (
+          <Flex gap="xs" align="center" wrap="wrap" aria-label="Active filters">
+            {saved && (
+              <Badge variant="light" aria-label={`Live query ${saved.name}`}>
+                Live query: {saved.name}
+              </Badge>
+            )}
+            {chips.map((chip) => (
+              <Button key={chip.label} type="button" onClick={() => go(chip.clear)} aria-label={`Remove ${chip.label}`} variant="light">
+                {chip.label}{' '}
+                <Text aria-hidden="true" span inherit>
+                  <IconX size={16} aria-hidden="true" />
+                </Text>
+              </Button>
+            ))}
+            {filtered(search) && (
+              <Button type="button" variant="subtle" onClick={() => go(NO_FILTERS)}>
+                Clear filters
+              </Button>
+            )}
+            {saved && (
+              <Text size="sm" c="dimmed">
+                A live query, not a snapshot: it follows the newest report.
+              </Text>
+            )}
+          </Flex>
+        )}
+      </Stack>
+    </Box>
+  );
+}

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

@@ -3,8 +3,13 @@
  *
  * 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, and the exact layer a test's detail is pinned to. Filters that
- * take several values are comma-separated (`status=failed,flaky`). Anything unreadable is dropped, never an error.
+ * 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.
+ *
+ * The Runs and Artifacts tabs share the tests' `q`, `env`, `producer`, `domain` and `spec` and add `artifactTag`,
+ * `type`, `label`, `branch`, `outcome`, `since` and `until`, so a link to one tab's filters opens the same query on another.
  */
+import { joinList, splitList, type ArtifactFilter } from '@crvouga/atlas/reports/artifact-query';
 import { TEST_SORTS, type TestQuery, type TestSort } from '@crvouga/atlas/reports/test-catalog';
 import { z } from 'zod/v4';
 
@@ -30,11 +35,29 @@ export const ExplorerSearchFields = {
   domain: text,
   spec: text,
   tag: text,
+  /** Only tests with one recording that declares every one of these scope tokens (`device:physical,audio:recorded`). */
+  scope: text,
+  /** Artifact tags (`demo`, shown `#demo`): tests with an attachment carrying one; runs and artifacts likewise. */
+  artifactTag: text,
+  /** With `artifactTag`: also the tags attachments inherit from their check and run. */
+  inherited: z.preprocess((value) => (value === 'true' ? true : value), z.literal(true)).optional().catch(undefined),
+  /** Media types of attachments (`video`, `image`…): runs and artifacts. */
+  type: text,
+  /** `key=value` labels: runs and artifacts. */
+  label: text,
+  /** Branches: runs and artifacts. */
+  branch: text,
+  /** Outcomes of a run or recorded result (`passed`, `failed`…). */
+  outcome: text,
+  /** Only records from this day (`YYYY-MM-DD`, the viewer's local time). */
+  since: text,
+  /** Only records until the end of this day (`YYYY-MM-DD`, local time). */
+  until: text,
   /** Only the tests a CI run recorded (a `RunSummary.key`). Not `run`, which already names a recorded statechart run. */
   inRun: text,
   group: z.enum(TEST_GROUPS).optional().catch(undefined),
   sort: z.enum(TEST_SORTS).optional().catch(undefined),
-  tab: z.enum(['runs']).optional().catch(undefined),
+  tab: z.enum(['runs', 'artifacts']).optional().catch(undefined),
   /** The run opened in the Runs tab. */
   openRun: text,
   /** Pins the open test's detail to one exact layer (a run's record of it), instead of the latest combined evidence. */
@@ -53,10 +76,19 @@ export type ExplorerSearch = {
   readonly domain?: string;
   readonly spec?: string;
   readonly tag?: string;
+  readonly scope?: string;
+  readonly artifactTag?: string;
+  readonly inherited?: true;
+  readonly type?: string;
+  readonly label?: string;
+  readonly branch?: string;
+  readonly outcome?: string;
+  readonly since?: string;
+  readonly until?: string;
   readonly inRun?: string;
   readonly group?: TestGroup;
   readonly sort?: TestSort;
-  readonly tab?: 'runs';
+  readonly tab?: 'runs' | 'artifacts';
   readonly openRun?: string;
   readonly layer?: string;
   readonly video?: true;
@@ -64,12 +96,12 @@ export type ExplorerSearch = {
 
 /** The values of a comma-separated filter, empty when it is not set. */
 export function values(value: string | undefined): string[] {
-  return value ? value.split(',').map((item) => item.trim()).filter(Boolean) : [];
+  return value ? splitList(value) : [];
 }
 
 /** A list of values as one comma-separated parameter, or undefined (left out of the address) when empty. */
 export function joined(list: readonly string[]): string | undefined {
-  return list.length ? list.join(',') : undefined;
+  return joinList(list);
 }
 
 /** Adds a value to a comma-separated filter, or removes it when it is there. */
@@ -88,6 +120,9 @@ export function queryOf(search: ExplorerSearch): TestQuery {
     domain: values(search.domain),
     spec: values(search.spec),
     tag: values(search.tag),
+    ...(values(search.scope).length ? { scope: values(search.scope) } : {}),
+    artifactTag: values(search.artifactTag),
+    ...(search.inherited ? { inherited: true } : {}),
     sort: search.sort ?? 'spec'
   };
 }
@@ -99,5 +134,49 @@ export function explorerSearch(search: Record<string, unknown>): ExplorerSearch
 
 /** True when any filter or search narrows the list. */
 export function narrowed(search: ExplorerSearch): boolean {
-  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.inRun);
+  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.scope || search.artifactTag || search.inRun);
+}
+
+/** The filters of the Runs and Artifacts tabs, in the address. */
+export const FILTER_FIELDS = ['q', 'artifactTag', 'inherited', 'type', 'label', 'env', 'producer', 'branch', 'outcome', 'domain', 'spec', 'since', 'until', 'video'] as const;
+
+/** A patch that removes every filter of the Runs and Artifacts tabs. */
+export const NO_FILTERS = Object.fromEntries(FILTER_FIELDS.map((field) => [field, undefined])) as { [K in (typeof FILTER_FIELDS)[number]]?: undefined };
+
+/** True when an address narrows the Runs and Artifacts tabs. */
+export function filtered(search: ExplorerSearch): boolean {
+  return FILTER_FIELDS.some((field) => field !== 'inherited' && search[field] !== undefined);
+}
+
+/** Midnight at the start (or the last millisecond) of a `YYYY-MM-DD` day in the viewer's local time, or undefined. */
+function dayMs(day: string | undefined, end: boolean): number | undefined {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day ?? '');
+  if (!match) return undefined;
+  const [year, month, date] = [Number(match[1]), Number(match[2]) - 1, Number(match[3])];
+  const value = new Date(year, month, date + (end ? 1 : 0)).getTime() - (end ? 1 : 0);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/** The query the Runs and Artifacts tabs ask for: the address's filters in the shape the report API and `matchesFilter` read. */
+export function filterOf(search: ExplorerSearch): ArtifactFilter {
+  const list = (value: string | undefined) => (values(value).length ? values(value) : undefined);
+  const since = dayMs(search.since, false);
+  const until = dayMs(search.until, true);
+  const parts = {
+    q: search.q,
+    artifactTag: list(search.artifactTag),
+    inherited: search.inherited,
+    type: list(search.type),
+    label: list(search.label),
+    environment: list(search.env),
+    producer: list(search.producer),
+    branch: list(search.branch),
+    outcome: list(search.outcome),
+    domain: list(search.domain),
+    spec: list(search.spec),
+    since,
+    until,
+    video: search.video
+  };
+  return Object.fromEntries(Object.entries(parts).filter(([, value]) => value !== undefined)) as ArtifactFilter;
 }

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

@@ -0,0 +1,75 @@
+/**
+ * @module Saved views
+ *
+ * A saved view is a name for a set of filters on the Runs or Artifacts tab of one project, kept in this browser. It is a
+ * live query, not a snapshot: opening it asks again and shows what matches the newest report, so its results change as
+ * runs arrive. (An immutable collection of reviewed results is a different thing, and is not what this stores.) Unreadable
+ * storage is treated as no saved views, never as an error.
+ */
+import { FILTER_FIELDS, type ExplorerSearch } from './search';
+
+/** The storage key of the saved views of this browser, all projects. */
+export const VIEWS_KEY = 'atlas.savedViews.v1';
+
+/** A saved live query. `filters` holds only the filter fields of the address, as the address writes them. */
+export type SavedView = {
+  readonly id: string;
+  readonly name: string;
+  /** The tab it opens on. */
+  readonly tab: 'runs' | 'artifacts';
+  /** The project it belongs to (the page's `?project=`), or an empty string. */
+  readonly project: string;
+  readonly filters: Readonly<Record<string, string | true>>;
+  readonly savedAtMs: number;
+};
+
+/** The filters of an address, ready to save: only the fields that narrow, with their values. */
+export function filtersOf(search: ExplorerSearch): Record<string, string | true> {
+  const filters: Record<string, string | true> = {};
+  for (const field of FILTER_FIELDS) {
+    const value = search[field];
+    if (value !== undefined) filters[field] = value;
+  }
+  return filters;
+}
+
+/** Whether an address is exactly a saved view's query on its tab (ignoring anything that is not a filter). */
+export function isView(view: SavedView, search: ExplorerSearch): boolean {
+  if ((search.tab ?? 'tests') !== view.tab) return false;
+  const now = filtersOf(search);
+  const keys = Object.keys(now);
+  return keys.length === Object.keys(view.filters).length && keys.every((key) => now[key] === view.filters[key]);
+}
+
+/** The saved views of this browser, oldest first; empty when none or when storage cannot be read. */
+export function readViews(storage: Pick<Storage, 'getItem'> | undefined = safeStorage()): SavedView[] {
+  try {
+    const parsed: unknown = JSON.parse(storage?.getItem(VIEWS_KEY) ?? '[]');
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item): item is SavedView =>
+        !!item && typeof item.id === 'string' && typeof item.name === 'string' && (item.tab === 'runs' || item.tab === 'artifacts') && typeof item.project === 'string' && !!item.filters && typeof item.filters === 'object'
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Keeps the saved views. Returns false when storage refused them (full, private or unavailable), so the page can say so. */
+export function writeViews(views: readonly SavedView[], storage: Pick<Storage, 'setItem'> | undefined = safeStorage()): boolean {
+  try {
+    if (!storage) return false;
+    storage.setItem(VIEWS_KEY, JSON.stringify(views));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}