@crvouga/atlas 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 1.1.0 (2026-10-28)
+
+### Features
+
+- make focused evidence navigation resilient to slow, missing or large catalogs ([db7932c](https://github.com/crvouga/atlas/commit/db7932cf7d912ebf8cba2ae1867e6eda2352f611))
+
 ## 1.0.0 (2026-10-28)
 
 ### ⚠️ Breaking changes

package/docs/ui.md

@@ -41,6 +41,13 @@ they preserve evidence semantics, provenance, URL selection, or playback behavio
   `Bounded`/show-more controls. Do not fetch unopened results' recordings eagerly.
 - Loading: named `Loader`/`Skeleton` or explicit text with `role="status"`. Error: `Alert color="red"` and
   a retry when possible. Empty: descriptive `Text` and a relevant action. Use built-in loading/disabled states.
+- Waiting is bounded. A focused page (a spec, a recording) loads what its link names on its own and never waits for
+  the whole catalog. `loadingPolicy.stallMs` in `evidence/load-state.tsx` is how long a read may take before the page
+  names what is affected, keeps the rest usable and offers `Try again` and a way back that keeps the selected scope.
+  A missing spec or layer is an explicit unavailable state with its path, never an endless `Loading…`. Layers that
+  fail to read are counted (`EvidenceIncomplete`) and the rest stays usable. Search disclosed as incomplete (still
+  reading, or specs it could not read) never reports "no match" as final. `tests/resilient-navigation.test.tsx`
+  holds the request budgets for a large catalog.
 - Spec overview links use a centered `Group`: status, flexible title/folder, then outcome and time. Keep gaps
   explicit with theme spacing; stack metadata on narrow screens instead of crowding the title.
 

package/llms-full.txt

@@ -3768,6 +3768,13 @@ they preserve evidence semantics, provenance, URL selection, or playback behavio
   `Bounded`/show-more controls. Do not fetch unopened results' recordings eagerly.
 - Loading: named `Loader`/`Skeleton` or explicit text with `role="status"`. Error: `Alert color="red"` and
   a retry when possible. Empty: descriptive `Text` and a relevant action. Use built-in loading/disabled states.
+- Waiting is bounded. A focused page (a spec, a recording) loads what its link names on its own and never waits for
+  the whole catalog. `loadingPolicy.stallMs` in `evidence/load-state.tsx` is how long a read may take before the page
+  names what is affected, keeps the rest usable and offers `Try again` and a way back that keeps the selected scope.
+  A missing spec or layer is an explicit unavailable state with its path, never an endless `Loading…`. Layers that
+  fail to read are counted (`EvidenceIncomplete`) and the rest stays usable. Search disclosed as incomplete (still
+  reading, or specs it could not read) never reports "no match" as final. `tests/resilient-navigation.test.tsx`
+  holds the request budgets for a large catalog.
 - Spec overview links use a centered `Group`: status, flexible title/folder, then outcome and time. Keep gaps
   explicit with theme spacing; stack metadata on narrow screens instead of crowding the title.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

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

@@ -303,7 +303,7 @@ export function CheckDetail(props: Props) {
   );
 }
 function RecordedCheckDetail({ slot, layerId, select, reads, written, pinned, pin }: Props) {
-  const { evidence, backends } = useEvidence();
+  const { evidence, backends, ready, pending } = useEvidence();
   const now = useNow();
   const [variant, setVariant] = useState(0);
   const history = useMemo(() => checkHistory(evidence, slot.specPath, slot.id), [evidence, slot.specPath, slot.id]);
@@ -350,6 +350,11 @@ function RecordedCheckDetail({ slot, layerId, select, reads, written, pinned, pi
           {note}
         </Alert>
       )}
+      {layerId && !earlier && ready && pending === 0 && (
+        <Alert role="status" color={'blue'} my="sm">
+          The layer this link names is not among the results held for this check. Showing the current result instead.
+        </Alert>
+      )}
       {failure && (
         <Code block c="red.7">
           {failure}

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

@@ -36,6 +36,8 @@ export type EvidenceState = {
   readonly retry: () => void;
   /** Layers whose checks are still arriving. */
   readonly pending: number;
+  /** Layers whose checks could not be read. The report shown leaves them out, so it may be incomplete. */
+  readonly failed: readonly LayerHeader[];
   /** Every distinct layer, whether or not it contributes. */
   readonly layers: readonly LayerHeader[];
   /** The layers that contribute, with their checks, once read. */
@@ -175,7 +177,7 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
       staleTime: Number.POSITIVE_INFINITY,
       retry: 1
     })),
-    combine: (results) => ({ data: results.map((result) => result.data), stamp: results.map((result) => result.dataUpdatedAt).join(',') })
+    combine: (results) => ({ data: results.map((result) => result.data), failed: results.map((result) => result.isError && result.data === undefined), stamp: results.map((result) => result.dataUpdatedAt).join(',') })
   });
 
   // A running suite's layer is re-read as tests finish. Its last read stays on screen meanwhile.
@@ -195,6 +197,8 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
     // `stamp` changes exactly when a layer's rows do.
   }, [wanted, rows.stamp]);
 
+  const failed = useMemo(() => wanted.filter((_, i) => rows.failed[i]), [wanted, rows.failed]);
+
   const shown = effective ? overview.data?.layers ?? NONE : evidence;
   const { tests: liveTests } = useLiveTests();
   const view = useMemo(() => withLiveProgress(evidenceView(combineEvidence(outline, shown)), liveTests), [outline, shown, liveTests]);
@@ -206,11 +210,14 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
     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; }
+      // A layer whose rows could not be read is asked for again alone, so the layers already read stay on screen.
+      void client.refetchQueries({ queryKey: ['evidence-rows'], predicate: (query) => query.state.status === 'error' });
       void reportJson<EvidencePage>('/evidence?retry=1')
         .catch(() => null)
         .then(() => Promise.all([index.refetch(), serverOutline.refetch()]));
     },
-    pending: wanted.length - evidence.length,
+    pending: Math.max(0, wanted.length - evidence.length - failed.length),
+    failed,
     layers: effective ? effectiveHeaders : layers,
     evidence: shown,
     backends: effective ? overview.data?.backends ?? [] : first?.backends ?? [],

package/packages/visualizer/src/evidence/load-state.tsx

@@ -0,0 +1,65 @@
+import { Alert, Button, Group, Text } from '@mantine/core';
+import { useEffect, useState } from 'react';
+import { LoadError } from '../data/adapters';
+import { useEvidence } from './evidence-context';
+import { plural } from './format';
+import { ReportsError } from './api';
+
+/**
+ * How long a read may take before the page says so. Waiting is never silent past this: the page names what is
+ * affected, keeps whatever else is readable, and offers another attempt. A test shortens it.
+ */
+export const loadingPolicy = { stallMs: 10_000 };
+
+/** True once `active` has stayed true for the loading policy's bound. It starts over when `active` or `scope` changes. */
+export function useStalled(active: boolean, scope = ''): boolean {
+  const [stalled, setStalled] = useState(false);
+  useEffect(() => {
+    setStalled(false);
+    if (!active) return;
+    const timer = setTimeout(() => setStalled(true), loadingPolicy.stallMs);
+    return () => clearTimeout(timer);
+  }, [active, scope]);
+  return active && stalled;
+}
+
+/** Is this error the server saying the thing is not there, as opposed to it failing to answer? */
+export function isMissing(error: unknown): boolean {
+  return (error instanceof LoadError || error instanceof ReportsError) && error.status === 404;
+}
+
+/** Recorded results are still arriving. After the loading policy's bound it says so and offers another attempt. */
+export function EvidenceWaiting({ label = 'Loading recorded results…', usable }: { label?: string; usable?: string }) {
+  const { retry } = useEvidence();
+  const stalled = useStalled(true);
+  return stalled ? (
+    <Alert role="status" color="orange" my="sm" title="Recorded results are taking longer than expected">
+      <Group gap="sm">
+        <Text span inherit>
+          {usable ? `${usable} ` : ''}Results will appear here when they arrive.
+        </Text>
+        <Button type="button" onClick={retry} variant="subtle">
+          Try again
+        </Button>
+      </Group>
+    </Alert>
+  ) : (
+    <Text role="status" component="div" c="dimmed">
+      {label}
+    </Text>
+  );
+}
+
+/** Says when some layers could not be read, so counts and results are not taken for the whole report. */
+export function EvidenceIncomplete() {
+  const { failed, retry } = useEvidence();
+  if (failed.length === 0) return null;
+  return (
+    <Alert role="status" color="orange" my="sm">
+      {plural(failed.length, 'layer', 'layers')} could not be read, so the results shown here may be incomplete.{' '}
+      <Button type="button" onClick={retry} variant="subtle">
+        Try again
+      </Button>
+    </Alert>
+  );
+}

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

@@ -7,6 +7,7 @@ import { folderOf, outlinePath, type SpecKind } from '../spec-kind';
 import { useUiStore } from '../state/ui-store';
 import { useEvidence } from './evidence-context';
 import { ago, plural, useNow } from './format';
+import { EvidenceIncomplete, EvidenceWaiting } from './load-state';
 import { backendLabel, Bounded, CountLine, Meter, StatusMark, Tally } from './marks';
 /** A kind's specs at a glance: how many have results, which are failing, and what just ran. */
 export function Overview({ kind }: { kind: SpecKind }) {
@@ -104,11 +105,8 @@ export function Overview({ kind }: { kind: SpecKind }) {
           </Button>
         </Alert>
       ))}
-      {!evidence.ready && !evidence.unavailable && (
-        <Text role="status" component="div" c="dimmed">
-          Loading recorded results…
-        </Text>
-      )}
+      {!evidence.ready && !evidence.unavailable && <EvidenceWaiting usable={`The list of ${kind.many} is readable.`} />}
+      {evidence.ready && <EvidenceIncomplete />}
       {evidence.ready && evidence.pending > 0 && (
         <Text role="status" component="div" c="dimmed">
           Reading {plural(evidence.pending, 'more layer', 'more layers')}…
@@ -168,7 +166,7 @@ export function Overview({ kind }: { kind: SpecKind }) {
         </Box>
       )}
 
-      {evidence.ready && evidence.pending === 0 && withResults.length === 0 && !evidence.unavailable && (
+      {evidence.ready && evidence.pending === 0 && evidence.failed.length === 0 && withResults.length === 0 && !evidence.unavailable && (
         <Text component="div" c="dimmed">
           {evidence.layers.length === 0
             ? `Nothing has been recorded yet. Results appear here as a spec run finishes each test.`

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

@@ -10,6 +10,7 @@ import { useRecordedReport } from './check-detail';
 import { useEvidence } from './evidence-context';
 import { duration, statusWord, useNow } from './format';
 import { Origin, StatusMark } from './marks';
+import { EvidenceIncomplete, EvidenceWaiting } from './load-state';
 import { Timeline } from './recording';
 type Props = {
   /** The check whose recording is open, once the combined report holds it. */
@@ -40,7 +41,7 @@ function needsStylesheet(report: RunReport | undefined): boolean {
 /** One recorded test, opened in place of its spec. */
 export function RecordingPage({ slot, layerId, entry, label, back, moment, onMoment, onClose }: Props) {
   const progress = useTestProgress(slot ?? null);
-  const { evidence, backends, pending, ready, unavailable } = useEvidence();
+  const { evidence, backends, pending, ready, unavailable, failed, retry } = useEvidence();
   const now = useNow();
   const history = useMemo(() => (slot ? checkHistory(evidence, slot.specPath, slot.id) : []), [evidence, slot]);
   const winner = slot?.outcomes[0];
@@ -86,17 +87,26 @@ export function RecordingPage({ slot, layerId, entry, label, back, moment, onMom
         )}
       </Box>
       <TestProgress {...progress} />
-      {waiting && (
-        <Text role="status" component="div" c="dimmed">
-          Loading the recording…
-        </Text>
-      )}
+      {waiting && <EvidenceWaiting label="Loading the recording…" usable="The way back to the spec is available." />}
       {!chosen && !waiting && !progress.tests.length && (
         <Alert color={'blue'} my="sm">
           {unavailable ??
-            'This result is not in the combined report any more. A newer run may have replaced it, or its source is switched off.'}
+            (failed.length > 0
+              ? 'This result was not found in the layers that could be read, and some layers could not be read.'
+              : 'This result is not in the combined report any more. A newer run may have replaced it, or its source is switched off.')}{' '}
+          {(unavailable || failed.length > 0) && (
+            <Button type="button" onClick={retry} variant="subtle">
+              Try again
+            </Button>
+          )}
+        </Alert>
+      )}
+      {chosen && layerId && !entry && chosen.layer.id !== layerId && ready && pending === 0 && (
+        <Alert role="status" color={'blue'} my="sm">
+          The layer this link names is not among the results held for this test. Showing the current result instead.
         </Alert>
       )}
+      {ready && !chosen && <EvidenceIncomplete />}
       {chosen && !paths && (
         <Alert color={'blue'} my="sm">
           This result has an outcome and no recorded timeline.

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

@@ -6,6 +6,7 @@ import type { ReactNode } from 'react';
 import type { SpecKind } from '../spec-kind';
 import { useEvidence } from './evidence-context';
 import { useNow } from './format';
+import { EvidenceIncomplete, EvidenceWaiting } from './load-state';
 import { CountLine, Meter, Origin } from './marks';
 /** A spec's name, where it lives, and what the combined report holds for it. */
 export function SpecHeader({
@@ -23,7 +24,7 @@ export function SpecHeader({
   planned?: number;
   children?: ReactNode;
 }) {
-  const { backends, ready, unavailable, pending } = useEvidence();
+  const { backends, ready, unavailable, pending, failed } = useEvidence();
   const now = useNow();
   const summary = entry?.summary ?? NO_EVIDENCE;
   const newest = entry?.slots
@@ -50,13 +51,13 @@ export function SpecHeader({
             <Text span inherit>
               Recorded results are unavailable.
             </Text>
-          ) : !ready ? (
-            <Text role="status" span inherit>
-              Loading recorded results…
-            </Text>
+          ) : !ready || (summary.status === 'none' && pending > 0) ? (
+            <EvidenceWaiting usable={`The ${kind.one} below is readable.`} />
           ) : summary.status === 'none' ? (
             <Text span inherit>
-              {pending > 0 ? 'Loading recorded results…' : `No completed test report for this ${kind.one} yet.`}
+              {failed.length > 0
+                ? `No completed test report for this ${kind.one} in the layers that could be read.`
+                : `No completed test report for this ${kind.one} yet.`}
             </Text>
           ) : (
             <>
@@ -69,6 +70,7 @@ export function SpecHeader({
             </>
           )}
         </Flex>
+        {ready && <EvidenceIncomplete />}
         {newest && (
           <Flex gap="xs" align="center" wrap="wrap" c="dimmed">
             Latest from <Origin layer={newest.layer} backends={backends} now={now} />

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

@@ -1,11 +1,13 @@
-import { Alert, Button, Container, Text, Title } from '@mantine/core';
-import { useQuery } from '@tanstack/react-query';
-import { useNavigate, useParams, useSearch } from '@tanstack/react-router';
+import { Alert, Anchor, Button, Container, Group, List, Stack, Text, Title } from '@mantine/core';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { Link, 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 { outlinePath, resolveSpec, similarSpecs, specFile, specKind, type SpecKind } from '../spec-kind';
 import type { SelectCheck } from './check-detail';
 import { useEvidence } from './evidence-context';
+import { isMissing, useStalled } from './load-state';
+import { SpecHeader } from './spec-header';
 import { Overview } from './overview';
 // 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 })));
@@ -27,6 +29,63 @@ function Loading({ children }: { children: React.ReactNode }) {
     </Suspense>
   );
 }
+/** What a spec that cannot be shown still says: where it was looked for, what is recorded for it, and the ways on. */
+function SpecUnavailable({
+  kind,
+  file,
+  missing,
+  detail,
+  retry,
+  run
+}: {
+  kind: SpecKind;
+  file: string;
+  missing: boolean;
+  detail: string;
+  retry: () => void;
+  run: string | undefined;
+}) {
+  const evidence = useEvidence();
+  const listed = evidence.files.filter(kind.accepts);
+  const similar = similarSpecs(file, listed);
+  const entry = evidence.view.specs.get(outlinePath(file));
+  return (
+    <Container component="article" size="xl" w="100%" py="xl">
+      <SpecHeader title={file.split('/').at(-1)!} file={file} kind={kind} entry={entry}>
+        <Alert role={missing ? 'status' : 'alert'} color={missing ? 'orange' : 'red'} my="sm" title={missing ? `This ${kind.one} is not available` : `The ${kind.one} could not be read`}>
+          <Stack gap="sm">
+            <Text component="div">
+              {missing ? `specs/${file} is not in this spec set. ` : ''}
+              {detail}
+              {evidence.filesPending || evidence.filesError ? '' : ` ${listed.length} ${listed.length === 1 ? kind.one : kind.many} are listed.`}
+              {entry && entry.slots.length > 0 ? ' Results recorded against it are shown above.' : ''}
+            </Text>
+            {similar.length > 0 && (
+              <>
+                <Text component="div">Did you mean:</Text>
+                <List listStyleType="none">
+                  {similar.map((candidate) => (
+                    <List.Item key={candidate}>
+                      <Anchor renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run, spec: candidate }} />}>{candidate}</Anchor>
+                    </List.Item>
+                  ))}
+                </List>
+              </>
+            )}
+            <Group gap="sm">
+              <Button type="button" onClick={retry} variant="light">
+                Try again
+              </Button>
+              <Button variant="subtle" renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run }} />}>
+                Back to {kind.label}
+              </Button>
+            </Group>
+          </Stack>
+        </Alert>
+      </SpecHeader>
+    </Container>
+  );
+}
 /** One spec tab: its overview, one of its documents, or a recording opened from that document. */
 export function SpecPage() {
   const params = useParams({ from: '/specs/$kind' });
@@ -35,7 +94,8 @@ export function SpecPage() {
   const adapter = useAdapter();
   const evidence = useEvidence();
   const kind = specKind(params.kind);
-  const file = search.spec ? specFile(search.spec) : '';
+  // A link may name a spec by another form of its path (with the folder, in other letter case): the listed one is shown.
+  const file = search.spec ? resolveSpec(specFile(search.spec), evidence.files) : '';
   const readable = kind !== null && file.length > 0 && kind.accepts(file);
   const text = useQuery({
     queryKey: keys.specFile(specKey(adapter), file),
@@ -43,6 +103,12 @@ export function SpecPage() {
     enabled: readable,
     retry: false
   });
+  const stalled = useStalled(text.isLoading, file);
+  const client = useQueryClient();
+  // A read that has not answered is dropped before asking again; asking again beside it would only wait for the same answer.
+  const retryText = () => {
+    void client.cancelQueries({ queryKey: keys.specFile(specKey(adapter), file) }).then(() => text.refetch());
+  };
   if (!kind) {
     return (
       <Container component="article" size="xl" w="100%" py="xl">
@@ -101,24 +167,41 @@ export function SpecPage() {
       </Loading>
     );
   }
-  if (text.isPending)
+  if (text.isPending || (text.isError && evidence.filesPending))
     return (
       <Container component="article" size="xl" w="100%" py="xl">
         <Text role="status" component="div" c="dimmed">
-          Loading the {kind.one}…
+          Loading specs/{file}…
         </Text>
+        {stalled && (
+          <Alert role="status" color="orange" my="sm" title={`Reading the ${kind.one} is taking longer than expected`}>
+            <Group gap="sm">
+              <Text span inherit>
+                specs/{file} has not arrived yet. Recorded results for other specs are not affected.
+              </Text>
+              <Button type="button" onClick={retryText} variant="light">
+                Try again
+              </Button>
+              <Button variant="subtle" renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run: search.run }} />}>
+                Back to {kind.label}
+              </Button>
+            </Group>
+          </Alert>
+        )}
       </Container>
     );
   if (text.isError) {
+    const listedElsewhere = !evidence.filesPending && !evidence.filesError && !evidence.files.includes(file);
+    const missing = isMissing(text.error) || listedElsewhere;
     return (
-      <Container component="article" size="xl" w="100%" py="xl">
-        <Alert role="alert" color={'red'} my="sm">
-          The {kind.one} could not be read.{' '}
-          <Button type="button" onClick={() => void text.refetch()} variant="subtle">
-            Try again
-          </Button>
-        </Alert>
-      </Container>
+      <SpecUnavailable
+        kind={kind}
+        file={file}
+        missing={missing}
+        detail={text.error instanceof Error ? text.error.message : ''}
+        retry={retryText}
+        run={search.run}
+      />
     );
   }
   const page = { file, text: text.data, kind, entry, selection: { check: search.check, layer: search.layer }, select };

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

@@ -6,6 +6,7 @@ import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboa
 import { useAtlas } from '../app/atlas-context';
 import { keys, specKey, useAdapter } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
+import { plural } from '../evidence/format';
 import { StatusMark } from '../evidence/marks';
 import { kindOfFile } from '../spec-kind';
 import { corpusFrom } from './corpus';
@@ -41,15 +42,29 @@ function isTypingTarget(target: EventTarget | null) {
   const tag = target.tagName;
   return target.isContentEditable || tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A';
 }
-function useSpecTexts(files: readonly string[]) {
+/**
+ * Reads the text of every spec for search, a few at a time, once `enabled`. Each file lands as it arrives, so a search
+ * can use what is read so far; `read` of `total` say how far it is, and `failed` how many could not be read at all.
+ */
+function useSpecTexts(files: readonly string[], enabled: boolean, open: boolean) {
   const adapter = useAdapter();
   const client = useQueryClient();
   const source = specKey(adapter);
   const cache = useRef(new Map<string, string>());
+  const unreadable = useRef(new Set<string>());
   const [texts, setTexts] = useState<ReadonlyMap<string, string>>(() => new Map());
   const [pending, setPending] = useState(false);
+  const [failedFiles, setFailedFiles] = useState<ReadonlySet<string>>(() => new Set());
   const key = files.join('\n');
+  // Opening the finder is another chance for the files that could not be read.
   useEffect(() => {
+    if (!open || unreadable.current.size === 0) return;
+    for (const file of unreadable.current) cache.current.delete(file);
+    unreadable.current.clear();
+    setFailedFiles(new Set());
+  }, [open]);
+  useEffect(() => {
+    if (!enabled) return;
     const wanted = key.length === 0 ? [] : key.split('\n');
     let cancelled = false;
     const missing = wanted.filter((file) => !cache.current.has(file));
@@ -65,13 +80,15 @@ function useSpecTexts(files: readonly string[]) {
         if (file === undefined || cancelled) return;
         let text = '';
         try {
-          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file) });
+          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file), retry: false });
         } catch {
           text = '';
+          unreadable.current.add(file);
         }
         if (cancelled) return;
         cache.current.set(file, text);
         setTexts(new Map(cache.current));
+        if (unreadable.current.has(file)) setFailedFiles(new Set(unreadable.current));
       }
     };
     void Promise.all([pull(), pull(), pull(), pull()]).then(() => {
@@ -80,8 +97,10 @@ function useSpecTexts(files: readonly string[]) {
     return () => {
       cancelled = true;
     };
-  }, [adapter, client, key, source]);
-  return { texts, pending };
+  }, [adapter, client, enabled, key, source]);
+  const read = useMemo(() => files.filter((file) => texts.has(file)).length, [files, texts]);
+  const failed = useMemo(() => files.filter((file) => failedFiles.has(file)).length, [files, failedFiles]);
+  return { texts, pending, total: files.length, read, failed };
 }
 /** The vector cache outlives a keystroke, so a live run does not embed the suite again. */
 const vectorCache = new Map<string, Float32Array>();
@@ -101,12 +120,25 @@ export function Finder() {
   const navigate = useNavigate();
   const routeSearch = useSearch({ strict: false });
   const readable = useMemo(() => evidence.files.filter((file) => kindOfFile(file)), [evidence.files]);
-  const { texts, pending } = useSpecTexts(readable);
+  // Reading every spec's text is for search, and a focused page needs its own spec first: start only once search is wanted.
+  const [wanted, setWanted] = useState(false);
+  useEffect(() => {
+    if (open) setWanted(true);
+  }, [open]);
+  const { texts, pending, total, read, failed } = useSpecTexts(readable, wanted, open);
   const docs = useMemo(
     () => corpusFrom(view, evidence.files, evidence.titleOf, evidence.view, texts),
     [view, evidence.files, evidence.titleOf, evidence.view, texts]
   );
   const index = useMemo(() => indexCorpus(docs), [docs]);
+  // What search has not covered yet, so an empty answer is not read as "no such behavior".
+  const unindexed = evidence.filesPending
+    ? 'The spec list is still loading'
+    : pending
+      ? `${total - read} of ${total} specs are still being read`
+      : !evidence.ready && !evidence.unavailable
+        ? 'Recorded results are still loading'
+        : '';
   const [query, setQuery] = useState('');
   const store = finderStore;
   const spotlightState = useSpotlight(store);
@@ -254,7 +286,13 @@ export function Finder() {
         <Spotlight.ActionsList id="atlas-finder-actions" role="listbox" aria-label="Flows, specs and runs">
           {shown.length === 0 && (
             <Spotlight.Empty>
-              {query.trim() ? 'Nothing close to that.' : 'Type what someone does. For example, add a todo.'}
+              {!query.trim()
+                ? 'Type what someone does. For example, add a todo.'
+                : unindexed
+                  ? `No match yet. ${unindexed}, so this is not the final answer.`
+                  : failed > 0
+                    ? `Nothing close to that. ${plural(failed, 'spec', 'specs')} could not be read, so search may miss ${failed === 1 ? 'it' : 'them'}.`
+                    : 'Nothing close to that.'}
             </Spotlight.Empty>
           )}
           {FIND_GROUPS.map((group) => {
@@ -285,7 +323,7 @@ export function Finder() {
         <Spotlight.Footer>
           <Group gap="md" justify="space-between">
             <Text size="xs" c="dimmed">
-              {pending ? 'Reading specs…' : '↑↓ move'}
+              {unindexed ? `Searching what is read so far: ${unindexed}` : failed > 0 ? `${plural(failed, 'spec', 'specs')} could not be read and ${failed === 1 ? 'is' : 'are'} not searched` : '↑↓ move'}
             </Text>
             <Text size="xs" c="dimmed">
               ↵ open · esc close

package/packages/visualizer/src/spec-kind.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 
-import { fileName, folderOf, kindOfFile, outlinePath, specFile, specKind } from './spec-kind';
+import { fileName, folderOf, kindOfFile, outlinePath, resolveSpec, similarSpecs, specFile, specKind } from './spec-kind';
 
 describe('spec kinds', () => {
   it('gives each notation its own tab and leaves statecharts and notes to the map', () => {
@@ -24,4 +24,17 @@ describe('spec kinds', () => {
     expect(folderOf('auth/sign-in.feature')).toBe('auth');
     expect(folderOf('atlas.yaml')).toBe('');
   });
+
+  it('reads a link to a spec by any form of its path and finds the listed spec it means', () => {
+    expect(specFile('./auth/sign-in.feature')).toBe('auth/sign-in.feature');
+    expect(specFile('/specs/auth\\sign-in.feature')).toBe('auth/sign-in.feature');
+    const listed = ['auth/sign-in.feature', 'billing/Pay.feature', 'billing/pay-later.feature', 'a/x.feature', 'b/x.feature'];
+    expect(resolveSpec('auth/sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('Auth/Sign-In.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    // Two candidates, or none, leave the link as written.
+    expect(resolveSpec('x.feature', listed)).toBe('x.feature');
+    expect(resolveSpec('nothing.feature', listed)).toBe('nothing.feature');
+    expect(similarSpecs('other/pay.feature', listed)).toEqual(['billing/Pay.feature']);
+  });
 });

package/packages/visualizer/src/spec-kind.ts

@@ -42,9 +42,35 @@ export function outlinePath(file: string) {
   return normal.startsWith('specs/') ? normal : `specs/${normal}`;
 }
 
-/** A file path relative to the specs folder, from either form. */
+/**
+ * A file path relative to the specs folder, from any form a link may name it by: with or without the `specs/` folder,
+ * with a leading `./` or `/`, with backslashes. Nothing here can leave the folder; `..` parts are kept for the reader to refuse.
+ */
 export function specFile(path: string) {
-  return path.replaceAll('\\', '/').replace(/^specs\//, '');
+  return path
+    .replaceAll('\\', '/')
+    .replace(/^(\.?\/)+/, '')
+    .replace(/^specs\//, '')
+    .replace(/\/{2,}/g, '/');
+}
+
+/**
+ * The listed spec a link means. An exact entry wins; otherwise the one listed spec that differs only in letter case, or that
+ * the link names by a trailing part of its path. More than one candidate, or none, leaves the link as written.
+ */
+export function resolveSpec(file: string, listed: readonly string[]): string {
+  if (listed.includes(file)) return file;
+  const lower = file.toLowerCase();
+  const sameCase = listed.filter((candidate) => candidate.toLowerCase() === lower);
+  if (sameCase.length === 1) return sameCase[0]!;
+  const tail = listed.filter((candidate) => candidate.toLowerCase().endsWith(`/${lower}`));
+  return tail.length === 1 ? tail[0]! : file;
+}
+
+/** The listed specs with the same file name as `file`, to offer when a link names one that is not there. */
+export function similarSpecs(file: string, listed: readonly string[], limit = 5): string[] {
+  const name = fileName(file).toLowerCase();
+  return listed.filter((candidate) => fileName(candidate).toLowerCase() === name).slice(0, limit);
 }
 
 export function fileName(path: string) {