@crvouga/atlas 1.3.0 → 1.5.0

package/llms-full.txt

@@ -1290,6 +1290,29 @@ or the command line, an attachment may name a `path` instead; `atlas report publ
 `atlas report publish --ctrf` keeps it ([native runner reporters](runners.md) cover CodeceptJS, Mocha, Jest and Node's
 test runner).
 
+## Run artifacts and direct links
+
+Files attached to a run as a whole (top-level `attachments`: a review movie, a ZIP, an HTML gallery, a summary) are
+shown under **Artifacts** when you open a run in the viewer's Runs tab, without opening any test. The movie plays
+inline, an archive is a download, and each file keeps its name, role, type, size, duration and tags. They are grouped
+by the layer that carries them, with who recorded it and when. A layer may hold no checks at all, only files: it is
+listed with `No checks in this layer`, and a run of only such layers shows `No checks recorded`, never `0 passed`.
+
+- **Direct link.** *Link to this file* gives an address that names the project, the run, one immutable layer and one
+  attachment: `#/?tab=runs&openRun=<run key>&layer=<layer id>&artifact=<id:… | key:… | name:…>`. Opened in a fresh tab
+  it selects that same file of that same layer, whatever runs arrived since. A link whose file is not in the layer says
+  so instead of showing another file.
+- **Shared recordings.** Tests that reference the same bytes (same SHA-256 or bundle key) are one recording. The run's
+  *Recordings in tests* lists each once, with every test that references it, and a run-level file that a test also
+  references says so.
+- **Unplayable files.** A file with no stored bytes, with an address that is not a web address, in a type the viewer
+  has no preview for, or that the browser cannot play, shows what is wrong and, when it can, a download.
+- **Safety is unchanged.** Files are served only through the attachment route (never sniffed, sandboxed), and an HTML
+  archive renders in an iframe with an empty `sandbox`: it cannot run script.
+- **API.** `GET /api/reports/runs/detail` lists the run's `layers` (backend, check count, file count) and
+  `GET /api/reports/evidence/detail/{backend}/{id}` returns what a layer carries as a whole (and, as `parts`, what its
+  parts carry). Both only gained optional fields.
+
 ## Recording completeness
 
 A green run does not say whether the videos you expected were kept and published. Atlas answers that separately from
@@ -3876,6 +3899,26 @@ and component defaults still live only in `ui/theme.tsx`. Quint/Alloy grammar so
 [`ui/grammars/README.md`](../packages/visualizer/src/ui/grammars/README.md). Unknown formats remain plain
 text, and parse failures must leave the source visible. Syntax highlighting never means a spec passed.
 
+## Behaviors: Read, Watch, Inspect
+
+A Gherkin page reads as behaviors: each scenario, or each example row of an outline (never the outline template as an
+extra), is one behavior in one coverage state (`evidence/behavior.ts`). Opening a behavior shows Mantine `Tabs`:
+**Read** (the steps with the example's values filled in), **Watch** (what is expected next to the matched recording,
+its status and provenance) and **Inspect** (the existing check detail: runs, environments, attempts, files). A behavior
+with a playable recording opens on Watch, one in a run in progress on Inspect, otherwise on Read. The video is read only
+when Watch is on screen.
+
+- States stay distinct and none but `demonstrated` is a pass with proof: recording missing, recording of an older spec
+  revision, no recording, API only, failed, running, skipped, parked (tagged `@parked`, `@wip`, `@pending`) and not executed.
+  Counts are in the Coverage section above the source; an empty state is left out except `demonstrated`.
+- The promise's revision (the spec's fingerprint now) and the evidence's revision (the fingerprint the layer recorded)
+  are shown separately. A known difference demotes a recording to "Recording is older" with an alert; a missing
+  fingerprint is "not recorded", never a match.
+- A recording is always labelled illustrative: it shows one run and does not approve a behavior for production.
+  `demo`/`representative` tags only add a "Representative demo" label.
+- The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
+  none are listed under "No domain declared"; the Tests view reports domain problems).
+
 ## Icons and notation marks
 
 Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
@@ -3934,9 +3977,9 @@ The narrowly scoped exceptions are:
 | Area | Screens/interactions | Mantine composition |
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
-| Project home | Tests/runs/artifacts tabs, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
+| Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion |
 | Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
-| Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
+| Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |
@@ -5230,7 +5273,7 @@ Responses: `200` The matching results and the facets.; `304` Unchanged since the
 
 `GET /api/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.
 
 - `key` (query, required): The run's `key` from `/api/reports/runs`, URL-encoded.
 - `format` (query): `markdown` for Markdown instead of JSON.
@@ -5242,7 +5285,7 @@ Responses: `200` The run and its results.; `304` Unchanged since the `If-None-Ma
 
 `GET /api/projects/{project}/reports/runs/detail` · role: read
 
-One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.
 
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
 
@@ -5352,7 +5395,7 @@ Responses: `200` The rows.; `401` No token, or an unknown one. Send `Authorizati
 
 `GET /api/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 - `backend` (path, required): A backend id from `/api/server`.
 - `id` (path, required): A layer id: 64 lowercase hex digits.
@@ -5366,7 +5409,7 @@ Responses: `200` The detail.; `401` No token, or an unknown one. Send `Authoriza
 
 `GET /api/projects/{project}/reports/evidence/detail/{backend}/{id}` · role: read
 
-The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
+The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.
 
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.3.0",
+  "version": "1.5.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/schema/schemas/check-detail.schema.json

@@ -1645,6 +1645,30 @@
       "additionalProperties": {},
       "description": "What the run as a whole carries: its logs, links, labels, annotations, scope and extensions"
     },
+    "parts": {
+      "description": "Without `check` only: the parts of the layer that carry files or links of their own, each with what it carries. Absent when none",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind",
+          "id",
+          "title"
+        ],
+        "additionalProperties": {}
+      }
+    },
     "inheritedScope": {
       "description": "The scope the check inherits: its part's declaration, else its layer's. Absent when neither declared one: unknown, not live or physical",
       "type": "object",

package/packages/schema/schemas/report-run.schema.json

@@ -171,6 +171,12 @@
           ],
           "additionalProperties": {}
         },
+        "attachments": {
+          "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
         "artifactTags": {
           "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
           "type": "array",
@@ -431,6 +437,85 @@
         ],
         "additionalProperties": {}
       }
+    },
+    "layers": {
+      "description": "Every layer of the run, oldest first. Absent from an older server",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The layer id; read its files with `/api/reports/evidence/detail/{backend}/{id}`"
+          },
+          "backend": {
+            "type": "string"
+          },
+          "producer": {
+            "type": "string"
+          },
+          "environment": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "recordedAtMs": {
+            "type": "number"
+          },
+          "checks": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many checks the layer recorded. Zero means evidence only, not a pass"
+          },
+          "attachments": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Files the layer carries as a whole, not those of its checks"
+          },
+          "videos": {
+            "type": "object",
+            "properties": {
+              "references": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Every reference to a video; identical bytes referenced twice count twice"
+              },
+              "recordings": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Distinct playable recordings"
+              },
+              "unavailable": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "References that name no bytes"
+              }
+            },
+            "required": [
+              "references",
+              "recordings",
+              "unavailable"
+            ],
+            "additionalProperties": {}
+          }
+        },
+        "required": [
+          "id",
+          "backend",
+          "producer",
+          "environment",
+          "recordedAtMs",
+          "checks",
+          "attachments"
+        ],
+        "additionalProperties": {}
+      }
     }
   },
   "required": [

package/packages/schema/schemas/report-runs.schema.json

@@ -179,6 +179,12 @@
             ],
             "additionalProperties": {}
           },
+          "attachments": {
+            "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
           "artifactTags": {
             "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
             "type": "array",

package/packages/server/openapi.json

@@ -5299,7 +5299,7 @@
           "Report"
         ],
         "summary": "Every test one run recorded",
-        "description": "One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.\n\nRole needed: `read`.",
+        "description": "One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -5409,7 +5409,7 @@
           "Report"
         ],
         "summary": "Every test one run recorded",
-        "description": "One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
+        "description": "One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -6093,7 +6093,7 @@
           "Report"
         ],
         "summary": "Everything one result carries",
-        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nRole needed: `read`.",
+        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -6195,7 +6195,7 @@
           "Report"
         ],
         "summary": "Everything one result carries",
-        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
+        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -15767,6 +15767,30 @@
             "additionalProperties": {},
             "description": "What the run as a whole carries: its logs, links, labels, annotations, scope and extensions"
           },
+          "parts": {
+            "description": "Without `check` only: the parts of the layer that carry files or links of their own, each with what it carries. Absent when none",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "kind": {
+                  "type": "string"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "kind",
+                "id",
+                "title"
+              ],
+              "additionalProperties": {}
+            }
+          },
           "inheritedScope": {
             "description": "The scope the check inherits: its part's declaration, else its layer's. Absent when neither declared one: unknown, not live or physical",
             "type": "object",
@@ -18974,6 +18998,12 @@
                   ],
                   "additionalProperties": {}
                 },
+                "attachments": {
+                  "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991
+                },
                 "artifactTags": {
                   "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
                   "type": "array",
@@ -19928,6 +19958,12 @@
                 ],
                 "additionalProperties": {}
               },
+              "attachments": {
+                "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
               "artifactTags": {
                 "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
                 "type": "array",
@@ -20188,6 +20224,85 @@
               ],
               "additionalProperties": {}
             }
+          },
+          "layers": {
+            "description": "Every layer of the run, oldest first. Absent from an older server",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The layer id; read its files with `/api/reports/evidence/detail/{backend}/{id}`"
+                },
+                "backend": {
+                  "type": "string"
+                },
+                "producer": {
+                  "type": "string"
+                },
+                "environment": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "recordedAtMs": {
+                  "type": "number"
+                },
+                "checks": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "How many checks the layer recorded. Zero means evidence only, not a pass"
+                },
+                "attachments": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "Files the layer carries as a whole, not those of its checks"
+                },
+                "videos": {
+                  "type": "object",
+                  "properties": {
+                    "references": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "Every reference to a video; identical bytes referenced twice count twice"
+                    },
+                    "recordings": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "Distinct playable recordings"
+                    },
+                    "unavailable": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "References that name no bytes"
+                    }
+                  },
+                  "required": [
+                    "references",
+                    "recordings",
+                    "unavailable"
+                  ],
+                  "additionalProperties": {}
+                }
+              },
+              "required": [
+                "id",
+                "backend",
+                "producer",
+                "environment",
+                "recordedAtMs",
+                "checks",
+                "attachments"
+              ],
+              "additionalProperties": {}
+            }
           }
         },
         "required": [

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

@@ -4,9 +4,9 @@ import { effectiveScope } from '@crvouga/atlas/reports/evidence-scope';
 import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
 import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
 import type { Annotation, Attachment, Attempt, Step } from '@crvouga/atlas/schema';
-import { Accordion, Alert, Anchor, Box, Code, Flex, Image, List, Stack, Text, Title } from '@mantine/core';
+import { Accordion, Alert, Anchor, Badge, Box, Code, Flex, Image, List, Stack, Text, Title } from '@mantine/core';
 import { useQuery } from '@tanstack/react-query';
-import { useMemo, type ReactNode } from 'react';
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { ArtifactTagList, ArtifactTagsProvider, TagFilterBar, useFilteredAttachments } from './artifact-tags';
 import { reportAssetUrl, reportJson, reportText } from './api';
 import { ScopeNotice, ScopeProvider, useScope } from './evidence-scope';
@@ -35,6 +35,23 @@ export type ArtifactRenderer = {
 const mediaType = (attachment: Attachment) =>
   (attachment.contentType ?? contentTypeOf(attachment.name)).split(';')[0]!.trim().toLowerCase();
 const label = (attachment: Attachment) => attachment.description ?? attachment.name;
+/** A video that plays inline; when the file cannot be loaded or this browser cannot play it, it says so and offers the file, instead of an empty player. */
+function VideoPlayer({ attachment, url }: { attachment: Attachment; url: string }) {
+  const [failed, setFailed] = useState(false);
+  if (failed)
+    return (
+      <Alert role="alert" color="orange" title="This video cannot be played">
+        <Text component="div">
+          {label(attachment)} could not be loaded, or this browser cannot play its format. Nothing is wrong with the report: the file may be missing from the
+          store or in an unsupported codec.{' '}
+          <Anchor href={url} download={attachment.name} target="_blank" rel="noreferrer">
+            Download {attachment.name}
+          </Anchor>
+        </Text>
+      </Alert>
+    );
+  return <Box src={url} controls preload="metadata" aria-label={label(attachment)} component="video" maw="100%" w="100%" onError={() => setFailed(true)} />;
+}
 function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
   const stored = useQuery({
     queryKey: ['artifact-text', path ?? ''],
@@ -92,8 +109,7 @@ export const artifactRenderers: ArtifactRenderer[] = [
     id: 'video',
     wide: true,
     matches: (_, type) => type.startsWith('video/'),
-    render: (a, { url }) =>
-      url ? <Box src={url} controls preload="metadata" aria-label={label(a)} component="video" maw="100%" w="100%" /> : null
+    render: (a, { url }) => (url ? <VideoPlayer attachment={a} url={url} /> : null)
   },
   {
     id: 'audio',
@@ -130,25 +146,46 @@ function sizeOf(bytes: number | undefined) {
   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);
+/** Where an attachment's bytes are, if a browser can reach them: its stored file in the layer, else its safe `http(s)` address. */
+export function attachmentSource(attachment: Attachment, layer: string): { path: string | null; url: string | null } {
   const path = attachment.bundleKey
     ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}`
     : null;
-  const url = path ? reportAssetUrl(path) : safeUri(attachment.uri);
+  return { path, url: path ? reportAssetUrl(path) : safeUri(attachment.uri) };
+}
+/**
+ * One attachment as a card: it plays or shows itself when it can, and always says what it is (name, role, type, size,
+ * duration, tags) and how to get it. A file that has no address, has an address that is not a web address, or that
+ * nothing can preview says so in words. Pass `link` for a control that opens this one artifact, `note` for how it
+ * relates to the rest of the report, and `selected` to mark the one a link pointed at (it scrolls into view).
+ */
+export function ArtifactCard({ attachment, layer, link, note, selected }: { attachment: Attachment; layer: string; link?: ReactNode; note?: ReactNode; selected?: boolean }) {
+  const type = mediaType(attachment);
+  const { path, url } = attachmentSource(attachment, layer);
   const renderer = artifactRenderers.find((candidate) => candidate.matches(attachment, type));
   const body = renderer?.render(attachment, { url, path, type });
+  const item = useRef<HTMLLIElement>(null);
+  useEffect(() => {
+    if (selected) item.current?.scrollIntoView?.({ block: 'center' });
+  }, [selected]);
   const scope = effectiveScope(attachment.scope, useScope());
   // A recording says what it shows before it is played; evidence that declared a scope of its own says so too.
   const scoped = isVideoAttachment(attachment) || attachment.scope !== undefined;
   return (
-    <List.Item data-wide={renderer?.wide || undefined} data-role={attachment.role ?? roleOfType(type)}>
+    <List.Item
+      ref={item}
+      data-wide={renderer?.wide || undefined}
+      data-role={attachment.role ?? roleOfType(type)}
+      data-selected={selected || undefined}
+      {...(selected ? { bg: 'blue.0', p: 'sm', bd: '2px solid var(--mantine-color-blue-6)' } : {})}
+    >
       {scoped && <ScopeNotice scope={scope} name={attachment.name} />}
       {body}
       <Box component="figcaption">
         <Text span inherit fw={600}>
           {attachment.name}
         </Text>
+        {selected && <Badge variant="light">Selected</Badge>}
         {attachment.role && (
           <Text span inherit>
             {attachment.role}
@@ -162,12 +199,21 @@ function Artifact({ attachment, layer }: { attachment: Attachment; layer: string
             {body ? 'Download' : 'Open'}
           </Anchor>
         )}
-        {!url && attachment.text === undefined && (
-          <Text span inherit>
-            No file to show
-          </Text>
-        )}
+        {link}
       </Box>
+      {!url && attachment.text === undefined && (
+        <Alert role={selected ? 'alert' : undefined} color="orange" data-unavailable my="xs">
+          {attachment.uri
+            ? 'No file to show. This file is only given by an address that is not a web address, so Atlas will not follow it. Ask the producer for a web address or to upload the file.'
+            : 'No file to show. The report lists this file, but it was never stored, so it cannot be shown or downloaded. Publish it again with the file attached.'}
+        </Alert>
+      )}
+      {url && !renderer && (
+        <Text component="div" c="dimmed" data-no-preview>
+          Atlas has no preview for this kind of file. Open or download it to inspect it.
+        </Text>
+      )}
+      {note}
       <ArtifactTagList attachment={attachment} />
     </List.Item>
   );
@@ -182,7 +228,7 @@ export function Attachments({ attachments: all, layer }: { attachments: readonly
       </Title>
       <List spacing="xs" listStyleType="none">
         {attachments.map((attachment, index) => (
-          <Artifact key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />
+          <ArtifactCard key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />
         ))}
       </List>
     </Box>
@@ -379,20 +425,25 @@ function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: str
     </ScopeProvider>
   );
 }
-/** 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 }) {
+/** The full evidence of one result, read only when `enabled` and the result has some to read (an archived layer). Shared by every view of the result, so it is read once. */
+export function useCheckDetail(layer: LayerHeader, row: LayerRow, enabled = true) {
   const wanted = row.evidence !== undefined || layer.evidence !== undefined;
-  const detail = useQuery({
+  return 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),
+    enabled: enabled && wanted && /^[0-9a-f]{64}$/.test(layer.id),
     staleTime: Number.POSITIVE_INFINITY,
     retry: false
   });
+}
+/** 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 = useCheckDetail(layer, row);
   if (!wanted) return null;
   if (detail.isLoading)
     return (