@crvouga/atlas 0.4.0 → 0.5.0

package/packages/visualizer/src/evidence/artifacts.tsx

@@ -0,0 +1,272 @@
+import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
+import type { CheckDetail, EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
+import { roleOfType } from '@crvouga/atlas/reports/evidence-detail';
+import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
+import type { Annotation, Attachment, Attempt, Step } from '@crvouga/atlas/schema';
+import { useQuery } from '@tanstack/react-query';
+import { useMemo, type ReactNode } from 'react';
+
+import { reportAssetUrl, reportJson, reportText } from './api';
+import styles from './artifacts.module.css';
+import { duration, plural } from './format';
+import { StatusMark } from './marks';
+
+/**
+ * How one kind of attachment is shown. The first renderer that matches wins, so a new kind of artifact (a
+ * flame graph, a HAR, a coverage map) is one more entry, and an attachment nobody has a renderer for is still
+ * listed, with its name, what it is and a way to download it. Nothing here fails on what it does not know.
+ */
+export type ArtifactRenderer = {
+  readonly id: string;
+  readonly matches: (attachment: Attachment, type: string) => boolean;
+  /** `url` is where the bytes are, if they are anywhere a browser can reach; `path` is the report API path of a stored file. */
+  readonly render: (attachment: Attachment, context: { url: string | null; path: string | null; type: string }) => ReactNode;
+  /** Wide renderers take a whole row of the gallery. */
+  readonly wide?: boolean;
+};
+
+const mediaType = (attachment: Attachment) => (attachment.contentType ?? contentTypeOf(attachment.name)).split(';')[0]!.trim().toLowerCase();
+const label = (attachment: Attachment) => attachment.description ?? attachment.name;
+
+/** Only addresses a browser may follow: never `javascript:` or `data:` from a producer. */
+function safeUri(uri: string | undefined): string | null {
+  if (!uri) return null;
+  try {
+    const url = new URL(uri, 'https://atlas.invalid/');
+    return url.protocol === 'http:' || url.protocol === 'https:' ? uri : null;
+  } catch {
+    return null;
+  }
+}
+
+function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
+  const stored = useQuery({ queryKey: ['artifact-text', path ?? ''], queryFn: ({ signal }) => reportText(path!, signal), enabled: attachment.text === undefined && path !== null, staleTime: Number.POSITIVE_INFINITY, retry: false });
+  const raw = attachment.text ?? stored.data;
+  if (raw === undefined) return <p className={styles.where}>{stored.isError ? 'Could not be read.' : 'Loading…'}</p>;
+  const shown = raw.length > 200_000 ? raw.slice(0, 200_000) : raw;
+  const pretty = /json/.test(mediaType(attachment)) ? tryPretty(shown) : shown;
+  return (
+    <>
+      <pre className={styles.text}>{pretty}</pre>
+      {shown.length < raw.length && <p className={styles.where}>Showing the first 200 000 characters.</p>}
+    </>
+  );
+}
+
+function tryPretty(text: string) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+
+/** In order: the first that matches. Add to the front with {@link registerArtifactRenderer}. */
+export const artifactRenderers: ArtifactRenderer[] = [
+  { id: 'image', matches: (_, type) => type.startsWith('image/') && type !== 'image/svg+xml', render: (a, { url }) => (url ? <a href={url} target="_blank" rel="noreferrer"><img src={url} alt={label(a)} loading="lazy" width={a.width} height={a.height} /></a> : null) },
+  // SVG can carry script: shown as a picture only, never inlined.
+  { id: 'svg', matches: (_, type) => type === 'image/svg+xml', render: (a, { url }) => (url ? <img src={url} alt={label(a)} loading="lazy" /> : null) },
+  { id: 'video', wide: true, matches: (_, type) => type.startsWith('video/'), render: (a, { url }) => (url ? <video src={url} controls preload="metadata" aria-label={label(a)} /> : null) },
+  { id: 'audio', matches: (_, type) => type.startsWith('audio/'), render: (a, { url }) => (url ? <audio src={url} controls preload="none" aria-label={label(a)} /> : null) },
+  // A page snapshot runs nothing: the frame has no permissions and the file is served sandboxed.
+  { id: 'snapshot', wide: true, matches: (_, type) => type === 'text/html' || type === 'application/xhtml+xml', render: (a, { url }) => (url ? <iframe sandbox="" src={url} title={label(a)} loading="lazy" /> : null) },
+  { id: 'pdf', wide: true, matches: (_, type) => type === 'application/pdf', render: (a, { url }) => (url ? <iframe sandbox="" src={url} title={label(a)} loading="lazy" /> : null) },
+  { id: 'text', wide: true, matches: (a, type) => a.text !== undefined || type.startsWith('text/') || /(json|xml|yaml|x-ndjson|x-diff)/.test(type), render: (a, { path }) => <TextValue attachment={a} path={path} /> }
+];
+
+export function registerArtifactRenderer(renderer: ArtifactRenderer) {
+  artifactRenderers.unshift(renderer);
+}
+
+function sizeOf(bytes: number | undefined) {
+  if (bytes === undefined) return '';
+  if (bytes < 1024) return `${bytes} B`;
+  return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(0)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+
+function Artifact({ attachment, layer }: { attachment: Attachment; layer: string }) {
+  const type = mediaType(attachment);
+  const path = attachment.bundleKey ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}` : null;
+  const url = path ? reportAssetUrl(path) : safeUri(attachment.uri);
+  const renderer = artifactRenderers.find((candidate) => candidate.matches(attachment, type));
+  const body = renderer?.render(attachment, { url, path, type });
+  return (
+    <li className={styles.figure} data-wide={renderer?.wide || undefined} data-role={attachment.role ?? roleOfType(type)}>
+      {body}
+      <figcaption>
+        <strong>{attachment.name}</strong>
+        {attachment.role && <span className={styles.role}>{attachment.role}</span>}
+        <span>{[type, sizeOf(attachment.bytes), attachment.durationMs ? duration(attachment.durationMs) : ''].filter(Boolean).join(' · ')}</span>
+        {url && <a href={url} download={attachment.name} target="_blank" rel="noreferrer">{body ? 'Download' : 'Open'}</a>}
+        {!url && attachment.text === undefined && <span>No file to show</span>}
+      </figcaption>
+    </li>
+  );
+}
+
+export function Attachments({ attachments, layer }: { attachments: readonly Attachment[]; layer: string }) {
+  if (!attachments.length) return null;
+  return (
+    <section aria-label="Attachments">
+      <h4>{plural(attachments.length, 'attachment', 'attachments')}</h4>
+      <ul className={styles.gallery}>
+        {attachments.map((attachment, index) => <Artifact key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />)}
+      </ul>
+    </section>
+  );
+}
+
+const STEP_STATUS: Record<string, 'passed' | 'failed' | 'running' | 'not-run'> = { passed: 'passed', pass: 'passed', ok: 'passed', failed: 'failed', fail: 'failed', error: 'failed', running: 'running', skipped: 'not-run', 'not-run': 'not-run', 'not-reached': 'not-run', pending: 'not-run' };
+
+/** The timeline: ordered by when each step started, nested by `parentId`. A step whose parent is missing is shown at the top. */
+export function Timeline({ steps, layer }: { steps: readonly Step[]; layer: string }) {
+  const tree = useMemo(() => {
+    const ids = new Set(steps.flatMap((step) => (step.id ? [step.id] : [])));
+    const children = new Map<string | null, Step[]>();
+    for (const step of steps) {
+      const parent = step.parentId && ids.has(step.parentId) ? step.parentId : null;
+      children.set(parent, [...(children.get(parent) ?? []), step]);
+    }
+    for (const list of children.values()) list.sort((a, b) => (a.offsetMs ?? 0) - (b.offsetMs ?? 0));
+    return children;
+  }, [steps]);
+  const render = (parent: string | null): ReactNode => (
+    <ol>
+      {(tree.get(parent) ?? []).map((step, index) => {
+        const status = STEP_STATUS[(step.status ?? '').toLowerCase()];
+        return (
+          <li key={`${step.id ?? step.name}:${index}`} className={styles.step} data-status={status ?? step.status ?? 'none'}>
+            <div className={styles.stepRow}>
+              <StatusMark status={status ?? 'none'} size={14} />
+              <span className={styles.stepName}>{step.name}</span>
+              {step.kind && <span className={styles.stepKind}>{step.kind}</span>}
+              {step.status && !status && <span className={styles.stepKind}>{step.status}</span>}
+              <span className={styles.spacer} />
+              <span className={styles.stepTime}>{[step.offsetMs !== undefined ? `+${duration(step.offsetMs)}` : '', duration(step.durationMs)].filter(Boolean).join(' · ')}</span>
+            </div>
+            {step.detail && <p className={styles.stepDetail}>{step.detail}</p>}
+            {step.annotations && <Notes notes={step.annotations} />}
+            {step.attachments && <Attachments attachments={step.attachments} layer={layer} />}
+            {step.id && tree.has(step.id) && render(step.id)}
+          </li>
+        );
+      })}
+    </ol>
+  );
+  return (
+    <section aria-label="Timeline" className={styles.timeline}>
+      <h4>{plural(steps.length, 'step', 'steps')}</h4>
+      {render(null)}
+    </section>
+  );
+}
+
+export function Notes({ notes }: { notes: readonly Annotation[] }) {
+  if (!notes.length) return null;
+  return (
+    <ul className={styles.notes} aria-label="Annotations">
+      {notes.map((note, index) => (
+        <li key={index} className={styles.note}>
+          <span className={styles.level} data-level={note.level ?? 'info'}>{note.level && ['info', 'warning', 'error'].includes(note.level) ? note.level : note.type}</span>
+          <span>
+            {note.message}
+            {note.source?.file && <span className={styles.where}> {note.source.file}{note.source.line ? `:${note.source.line}` : ''}</span>}
+            {note.level && !['info', 'warning', 'error'].includes(note.level) && <span className={styles.where}> ({note.level})</span>}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: string }) {
+  if (!attempts.length) return null;
+  return (
+    <section aria-label="Tries">
+      <h4>{plural(attempts.length, 'try', 'tries')}</h4>
+      <ol className={styles.timeline}>
+        {attempts.map((attempt) => (
+          <li key={attempt.index} className={styles.step}>
+            <div className={styles.stepRow}>
+              <StatusMark status={attempt.status} size={14} />
+              <span className={styles.stepName}>Try {attempt.index + 1}</span>
+              <span className={styles.spacer} />
+              <span className={styles.stepTime}>{duration(attempt.durationMs)}</span>
+            </div>
+            {attempt.detail && <p className={styles.stepDetail}>{attempt.detail}</p>}
+            {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+          </li>
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+/** What is not known: kept, and shown as it is, so nothing a tool recorded is out of reach. */
+function Raw({ extensions }: { extensions: Readonly<Record<string, unknown>> }) {
+  const names = Object.keys(extensions);
+  if (!names.length) return null;
+  return (
+    <details className={styles.raw}>
+      <summary>{plural(names.length, 'extension', 'extensions')}: {names.join(', ')}</summary>
+      <pre className={styles.text}>{JSON.stringify(extensions, null, 2)}</pre>
+    </details>
+  );
+}
+
+function Facts({ holder }: { holder: EvidenceHolder }) {
+  const labels = Object.entries(holder.labels ?? {});
+  const tags = holder.tags ?? [];
+  const links = (holder.links ?? []).flatMap((link) => { const url = safeUri(link.url); return url ? [{ ...link, url }] : []; });
+  if (!labels.length && !tags.length && !links.length) return null;
+  return (
+    <div>
+      <ul className={styles.chips} aria-label="Facts">
+        {tags.map((tag) => <li key={`t:${tag}`} className={styles.chip}>{tag}</li>)}
+        {labels.map(([name, value]) => <li key={`l:${name}`} className={styles.chip}>{name}<b>{value}</b></li>)}
+        {links.map((link) => <li key={`k:${link.url}`} className={styles.chip}><a href={link.url} target="_blank" rel="noreferrer">{link.name ?? link.rel ?? link.url}</a></li>)}
+      </ul>
+    </div>
+  );
+}
+
+function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: string; steps?: boolean }) {
+  return (
+    <>
+      <Facts holder={holder} />
+      {holder.annotations && <Notes notes={holder.annotations} />}
+      {steps && holder.steps && holder.steps.length > 0 && <Timeline steps={holder.steps} layer={layer} />}
+      {holder.attempts && holder.attempts.length > 1 && <Tries attempts={holder.attempts} layer={layer} />}
+      {holder.attachments && <Attachments attachments={holder.attachments} layer={layer} />}
+      {holder.extensions && <Raw extensions={holder.extensions} />}
+    </>
+  );
+}
+
+/** Everything one result carries beyond its outcome, read when it is opened, and what the run around it carried. */
+export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerRow }) {
+  const wanted = row.evidence !== undefined || layer.evidence !== undefined;
+  const detail = useQuery({
+    queryKey: ['evidence-detail', layer.backend, layer.id, row.kind, row.id],
+    queryFn: ({ signal }) => reportJson<CheckDetail>(`/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}?check=${encodeURIComponent(row.id)}&kind=${encodeURIComponent(row.kind)}`, signal),
+    enabled: wanted && /^[0-9a-f]{64}$/.test(layer.id),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+  if (!wanted) return null;
+  if (detail.isLoading) return <p className={styles.where} role="status">Loading what this result carries…</p>;
+  if (detail.isError || !detail.data) return <p className={styles.where} role="alert">What this result carries could not be read.</p>;
+  const { check, run } = detail.data;
+  const hasRun = Object.values(run).some((value) => (Array.isArray(value) ? value.length > 0 : value && typeof value === 'object' ? Object.keys(value).length > 0 : false));
+  return (
+    <div className={styles.panel} aria-label="Evidence">
+      <Evidence holder={check} layer={layer.id} steps />
+      {hasRun && (
+        <section aria-label="From the run">
+          <h4>From the run</h4>
+          <Evidence holder={run} layer={layer.id} />
+        </section>
+      )}
+    </div>
+  );
+}

package/packages/visualizer/src/evidence/check-detail.tsx

@@ -8,6 +8,7 @@ import { useQuery } from '@tanstack/react-query';
 import { useMemo, useState, type ReactNode } from 'react';
 
 import { reportJson } from './api';
+import { ResultEvidence } from './artifacts';
 import { useEvidence } from './evidence-context';
 import styles from './evidence.module.css';
 import { ago, duration, plural, statusWord, useNow } from './format';
@@ -77,7 +78,7 @@ export function ResultRow({ label, slot, open, onToggle, children }: { label: st
         </span>
         {slot?.live && <span className={styles.liveTag}>Running now</span>}
         <span className={styles.resultAside}>
-          {newest ? [duration(newest.row.durationMs), slot.live ? '' : ago(slot.latestAtMs, now)].filter(Boolean).join(' · ') : 'No result'}
+          {newest ? [newest.row.evidence?.attachments ? plural(newest.row.evidence.attachments, 'attachment', 'attachments') : '', duration(newest.row.durationMs), slot.live ? '' : ago(slot.latestAtMs, now)].filter(Boolean).join(' · ') : 'No result'}
         </span>
         <span className={styles.chevron} aria-hidden="true" />
       </button>
@@ -253,6 +254,7 @@ export function CheckDetail({ slot, layerId, select, reads, written }: Props) {
           </p>
         );
       }))}
+      <ResultEvidence layer={chosen.layer} row={chosen.row} />
       {(moments > 0 || chosen.layer.runUrl) && (
         <p className={styles.actionsLine}>
           {moments > 0 && (

package/packages/visualizer/src/evidence/evidence-context.tsx

@@ -1,20 +1,29 @@
 import type { ActiveRun, BackendInfo, EvidencePage, LayerEvidence, LayerHeader, LayerRows } from '@crvouga/atlas/reports/evidence-types';
+import { applyEffectiveDelta, isEffectiveDelta, type EffectiveDelta } from '@crvouga/atlas/reports/effective-delta';
+import type { EffectiveEvidence } from '@crvouga/atlas/reports/report-index';
 import { contributes, evidenceView, type EvidenceView, type SourceSelection } from '@crvouga/atlas/reports/evidence-view';
 import type { SpecEntry } from '@crvouga/atlas/reports/explorer-types';
 import { combineEvidence, distinctHeaders } from '@crvouga/atlas/reports/layer-merge';
 import type { ReportOutline } from '@crvouga/atlas/reports/layer-types';
 import { SpecIndexSchema } from '@crvouga/atlas/schema';
-import { useInfiniteQuery, useQueries, useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQueries, useQuery, useQueryClient } from '@tanstack/react-query';
 import { createContext, useContext, useEffect, useMemo, useRef, type ReactNode } from 'react';
 
 import { keys, specKey, useAdapter } from '../data/queries';
+import { eventsAddress, listenLive, throttled, useLiveStatus } from '../live/live-stream';
 import { fileName, folderOf, kindOfFile, outlinePath } from '../spec-kind';
 import { useUiStore } from '../state/ui-store';
-import { reportJson, staticEvidence } from './api';
+import { effectiveEvidence, reportJson, staticEvidence } from './api';
 
 /** How often the layer list is asked for while a spec run is writing results, and while nothing is. */
 const LIVE_POLL_MS = 2_000;
 const IDLE_POLL_MS = 15_000;
+/** The effective report is revalidated with its ETag, so asking often costs one small answer. */
+const EFFECTIVE_POLL_MS = 5_000;
+/** While the server's stream is open it says when to read again; this is only the safety net behind it. */
+const LIVE_SAFETY_POLL_MS = 60_000;
+/** At most this often is the report read again because the server said it changed. */
+const LIVE_REREAD_MS = 250;
 
 export type EvidenceState = {
   /** The layer list has been read at least once. */
@@ -63,26 +72,76 @@ function outlineOf(files: readonly string[]): ReportOutline {
   return { specs, sha: null, changedFiles: [] };
 }
 
+const NONE: readonly LayerEvidence[] = [];
+
+function hasExclusions(excluded: SourceSelection): boolean {
+  return Object.values(excluded).some((list) => list.length > 0);
+}
+
 export function EvidenceProvider({ children }: { children: ReactNode }) {
   const adapter = useAdapter();
   const source = specKey(adapter);
   const excluded = useUiStore((s) => s.excluded);
   const setExcluded = useUiStore((s) => s.setExcluded);
 
+  const client = useQueryClient();
+  const stream = useLiveStatus();
+  const streaming = stream === 'live';
+  // The server says when results arrive: read the report again then, not on a timer.
+  useEffect(() => {
+    const url = eventsAddress();
+    if (!url) return;
+    // A burst of results (a CI run finishing, many shards at once) is read once, not once for each.
+    const reread = throttled(() => {
+      void client.invalidateQueries({ queryKey: ['evidence-effective'] });
+      void client.invalidateQueries({ queryKey: ['evidence-index'] });
+    }, LIVE_REREAD_MS);
+    const reoutline = throttled(() => {
+      void client.invalidateQueries({ queryKey: ['evidence-outline'] });
+      void client.invalidateQueries({ queryKey: ['evidence-effective'] });
+    }, LIVE_REREAD_MS);
+    const stop = listenLive(url, (event) => {
+      if (event.type === 'change' && event.change.scope === 'specs') return reoutline();
+      if (event.type !== 'report' && event.type !== 'open') return;
+      reread();
+      if (event.type === 'open') reoutline();
+    });
+    return () => { stop(); reread.cancel(); reoutline.cancel(); };
+  }, [client]);
+
   const specIndex = useQuery({ queryKey: keys.specIndex(source), queryFn: adapter.specIndex, retry: false });
   const files = useMemo(() => {
     const parsed = SpecIndexSchema.safeParse(specIndex.data);
     return parsed.success ? parsed.data.files : [];
   }, [specIndex.data]);
 
+  // The node answers with only what the report shows, in one request. Leaving a source out needs the
+  // history it hides, so that one case reads every layer, as a store without a node always does.
+  const effective = effectiveEvidence() && !staticEvidence && !hasExclusions(excluded);
+  const overview = useQuery({
+    queryKey: ['evidence-effective'],
+    // Holding a report, ask only for what changed since it; the server answers with all of it when it cannot.
+    queryFn: async ({ signal }) => {
+      const held = client.getQueryData<EffectiveEvidence>(['evidence-effective']);
+      const answer = await reportJson<EffectiveEvidence | EffectiveDelta>(held ? `/evidence/effective?since=${encodeURIComponent(held.version)}` : '/evidence/effective', signal);
+      if (!isEffectiveDelta(answer)) return answer;
+      return (held && applyEffectiveDelta(held, answer)) ?? reportJson<EffectiveEvidence>('/evidence/effective', signal);
+    },
+    enabled: effective,
+    staleTime: 0,
+    retry: false,
+    refetchInterval: streaming ? LIVE_SAFETY_POLL_MS : EFFECTIVE_POLL_MS
+  });
+
   const index = useInfiniteQuery({
     queryKey: ['evidence-index'],
+    enabled: !effective,
     initialPageParam: null as string | null,
     queryFn: ({ pageParam, signal }) => reportJson<EvidencePage>(`/evidence${pageParam ? `?cursor=${encodeURIComponent(pageParam)}` : ''}`, signal),
     getNextPageParam: (page) => page.cursor,
     staleTime: 0,
     retry: false,
-    refetchInterval: (query) => (staticEvidence ? false : query.state.data?.pages[0]?.active.length ? LIVE_POLL_MS : IDLE_POLL_MS)
+    refetchInterval: (query) => (staticEvidence ? false : streaming ? LIVE_SAFETY_POLL_MS : query.state.data?.pages[0]?.active.length ? LIVE_POLL_MS : IDLE_POLL_MS)
   });
   // Show the newest layers at once, then read the older pages behind them.
   const { hasNextPage, isFetching, isError, fetchNextPage } = index;
@@ -98,7 +157,7 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
   const serverOutline = useQuery({ queryKey: ['evidence-outline'], queryFn: ({ signal }) => reportJson<ReportOutline>('/outline', signal), staleTime: 30_000, retry: false });
   const outline = useMemo(() => serverOutline.data ?? outlineOf(files), [serverOutline.data, files]);
 
-  const wanted = useMemo(() => layers.filter((layer) => contributes(layer, excluded)), [layers, excluded]);
+  const wanted = useMemo(() => (effective ? [] : layers.filter((layer) => contributes(layer, excluded))), [layers, excluded, effective]);
   const rows = useQueries({
     queries: wanted.map((layer) => ({
       queryKey: rowsKey(layer),
@@ -126,23 +185,26 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
     // `stamp` changes exactly when a layer's rows do.
   }, [wanted, rows.stamp]);
 
-  const view = useMemo(() => evidenceView(combineEvidence(outline, evidence)), [outline, evidence]);
+  const shown = effective ? overview.data?.layers ?? NONE : evidence;
+  const view = useMemo(() => evidenceView(combineEvidence(outline, shown)), [outline, shown]);
   const titles = useMemo(() => new Map(outline.specs.map((spec) => [spec.path, spec.title])), [outline]);
+  const effectiveHeaders = useMemo(() => (overview.data?.layers ?? NONE).map((entry) => entry.layer), [overview.data]);
 
   const state: EvidenceState = {
-    ready: pages !== undefined,
-    unavailable: pages === undefined && index.error ? index.error.message : null,
+    ready: effective ? overview.data !== undefined : pages !== undefined,
+    unavailable: effective ? (overview.data === undefined && overview.error ? overview.error.message : null) : pages === undefined && index.error ? index.error.message : null,
     retry: () => {
+      if (effective) { void Promise.all([overview.refetch(), serverOutline.refetch()]); return; }
       void reportJson<EvidencePage>('/evidence?retry=1')
         .catch(() => null)
         .then(() => Promise.all([index.refetch(), serverOutline.refetch()]));
     },
     pending: wanted.length - evidence.length,
-    layers,
-    evidence,
-    backends: first?.backends ?? [],
-    active: first?.active ?? [],
-    notices,
+    layers: effective ? effectiveHeaders : layers,
+    evidence: shown,
+    backends: effective ? overview.data?.backends ?? [] : first?.backends ?? [],
+    active: effective ? [] : first?.active ?? [],
+    notices: effective ? overview.data?.notices ?? [] : notices,
     view,
     files,
     filesPending: specIndex.isPending,

package/packages/visualizer/src/evidence/spec-page.tsx

@@ -1,16 +1,23 @@
 import { useQuery } from '@tanstack/react-query';
 import { useNavigate, useParams, useSearch } from '@tanstack/react-router';
+import { lazy, Suspense } from 'react';
 
 import { keys, specKey, useAdapter } from '../data/queries';
 import { outlinePath, specFile, specKind } from '../spec-kind';
 import type { SelectCheck } from './check-detail';
-import { DocumentPage } from './document-page';
 import { useEvidence } from './evidence-context';
 import styles from './evidence.module.css';
-import { FeaturePage } from './feature-page';
-import { ModelPage } from './model-page';
 import { Overview } from './overview';
-import { RecordingPage } from './recording-page';
+
+// Each kind of spec has a page with a parser of its own (Gherkin, Quint, DMN); a page loads only the one it shows.
+const DocumentPage = lazy(() => import('./document-page').then((m) => ({ default: m.DocumentPage })));
+const FeaturePage = lazy(() => import('./feature-page').then((m) => ({ default: m.FeaturePage })));
+const ModelPage = lazy(() => import('./model-page').then((m) => ({ default: m.ModelPage })));
+const RecordingPage = lazy(() => import('./recording-page').then((m) => ({ default: m.RecordingPage })));
+
+function Loading({ children }: { children: React.ReactNode }) {
+  return <Suspense fallback={<article className={styles.page}><p className={styles.aside} role="status">Loading…</p></article>}>{children}</Suspense>;
+}
 
 /** One spec tab: its overview, one of its documents, or a recording opened from that document. */
 export function SpecPage() {
@@ -63,15 +70,17 @@ export function SpecPage() {
     const spec = `${evidence.titleOf(file)}: `;
     const label = slot ? (slot.title.startsWith(spec) ? slot.title.slice(spec.length) : slot.title) : 'Recorded test';
     return (
-      <RecordingPage
-        slot={slot}
-        layerId={search.layer}
-        label={label}
-        back={evidence.titleOf(file)}
-        moment={search.moment ?? null}
-        onMoment={(moment, replace) => void navigate({ search: (prev) => ({ ...prev, moment }), replace })}
-        onClose={() => select({ view: null })}
-      />
+      <Loading>
+        <RecordingPage
+          slot={slot}
+          layerId={search.layer}
+          label={label}
+          back={evidence.titleOf(file)}
+          moment={search.moment ?? null}
+          onMoment={(moment, replace) => void navigate({ search: (prev) => ({ ...prev, moment }), replace })}
+          onClose={() => select({ view: null })}
+        />
+      </Loading>
     );
   }
   if (text.isPending) return <article className={styles.page}><p className={styles.aside} role="status">Loading the {kind.one}…</p></article>;
@@ -86,7 +95,5 @@ export function SpecPage() {
     );
   }
   const page = { file, text: text.data, kind, entry, selection: { check: search.check, layer: search.layer }, select };
-  if (kind.id === 'gherkin') return <FeaturePage {...page} />;
-  if (kind.id === 'quint') return <ModelPage {...page} />;
-  return <DocumentPage {...page} />;
+  return <Loading>{kind.id === 'gherkin' ? <FeaturePage {...page} /> : kind.id === 'quint' ? <ModelPage {...page} /> : <DocumentPage {...page} />}</Loading>;
 }

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

@@ -9,7 +9,7 @@ import { StatusMark } from '../evidence/marks';
 import { useEvidence } from '../evidence/evidence-context';
 import { kindOfFile } from '../spec-kind';
 import { corpusFrom } from './corpus';
-import { setFinderOpen, setHelpOpen, toggleFinder, useFinderOpen, useHelpOpen, isHelpOpen } from './open';
+import { commandKey, setFinderOpen, setHelpOpen, toggleFinder, useFinderOpen, useHelpOpen, isHelpOpen } from './open';
 import { FIND_GROUPS, indexCorpus, notationOf, rankIndex, splitQuery, type FindDoc, type FindKind, type FindTarget, type Ranked } from './rank';
 import { applySemantic, createWorkerEmbedder, embeddingsAvailable, embedText, textHash, type Embedder } from './semantic';
 import styles from './Finder.module.css';
@@ -36,10 +36,6 @@ const SHORTCUTS: readonly { readonly keys: string; readonly does: string }[] = [
   { keys: 'Home  End', does: 'Start and end of a recording' }
 ];
 
-function commandKey() {
-  return typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent) ? '⌘K' : 'Ctrl+K';
-}
-
 function isTypingTarget(target: EventTarget | null) {
   if (!(target instanceof HTMLElement)) return false;
   const tag = target.tagName;
@@ -299,5 +295,3 @@ function Row({ hit }: { hit: Ranked }) {
     </>
   );
 }
-
-export { commandKey };

package/packages/visualizer/src/find/open.ts

@@ -49,3 +49,7 @@ export function useFinderOpen() {
 export function useHelpOpen() {
   return useSyncExternalStore(subscribeFinder, isHelpOpen, () => false);
 }
+
+export function commandKey() {
+  return typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent) ? '⌘K' : 'Ctrl+K';
+}