@crvouga/atlas 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.11.0 (2026-10-29)
+## 1.12.0 (2026-10-29)
+
+### Features
+
+- seek recordings from scenario steps and share a moment ([6071cd9](https://github.com/crvouga/atlas/commit/6071cd90e8ece66deb384b037a25ee51381283ed))
+
+## 1.11.0 (2026-10-28)
 
 ### Features
 

package/docs/extending.md

@@ -121,6 +121,13 @@ when you do not know, and the viewer says the cause is unknown. It is never infe
 failed before the behavior started comes from the failed step's `kind`: `hook`, `setup`, `fixture`, `before`,
 `beforeAll`, `beforeEach` or `given` mean preparation; `when`, `then`, `assertion` or `expect` mean the behavior.
 
+### Placing steps in a recording
+
+A video may declare how its clock relates to the check's under the `atlas.media` extension (`checkStartMs`, `pauses`,
+`marks`), so the viewer can seek it from a step and mark the step playing. Without it the video plays as ever and no step
+is placed. The fields, the rules and the link to a moment are in
+[Place steps in a recording](rich-evidence.md#place-steps-in-a-recording).
+
 ## Attach evidence
 
 ### From the command line

package/docs/rich-evidence.md

@@ -27,6 +27,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
 | `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
+| `extensions['atlas.media']` | attachment (video) | Where the check's steps are in the recording, so a click on a step seeks the video. See [Place steps in a recording](#place-steps-in-a-recording). |
 | `scope` | attachment, attempt, check, part, layer | What a recording does and does not show: where it ran, whether data and dependencies were real, whether audio was captured. See [Evidence scope](#evidence-scope). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
@@ -109,6 +110,44 @@ Every field is optional, and every value except the booleans is an open string.
 - **It decides nothing.** A scope never changes a status, a slot or a winner. A scope an older Atlas cannot read is
   dropped, and the attachment, check and layer stay.
 
+## Place steps in a recording
+
+A step says when it started on the check's clock (`offsetMs`, after the check started). A video has its own clock, which
+began when the recorder did, and the two are not assumed to agree: a recorder usually starts before the first step, and a
+paced demo may have delays put into the video that the check never waited for. To let a reviewer click a step and land on
+its moment in the video, say how the clocks relate in the `atlas.media` extension of the video attachment:
+
+```ts
+{
+  name: 'checkout.webm', role: 'video', durationMs: 9000,
+  extensions: {
+    'atlas.media': {
+      checkStartMs: 1200,                                           // the check started 1.2 s into the video
+      pauses: [{ atMs: 900, durationMs: 2000, reason: 'title card' }], // 2 s put into the video before the step at +900 ms
+      marks: [{ step: 'pay', mediaMs: 4100 }]                        // a step whose moment in the video you know exactly
+    }
+  }
+}
+```
+
+Every field is optional and none of it decides a status, a slot or a winner. A step is placed at `checkStartMs` + its
+`offsetMs` + the `durationMs` of every pause whose `atMs` is at or before the step; a mark names the moment outright and
+wins. Anything else is unavailable and said so, never guessed.
+
+- **Without timing, nothing is placed.** A video with no `atlas.media`, no `checkStartMs`, or a step with no `offsetMs` and
+  no mark, is never assumed to start with the check, and a step is never placed from the wording of its name. Selecting
+  such a step says why it cannot be shown, and moves nothing.
+- **Outside the video is not clamped.** A moment before the start, or after `durationMs` (or the length the player reports),
+  is unavailable. A declaration with a field Atlas cannot read (a pause without a duration) is reported and places nothing.
+- **Pacing is not latency.** A video with `pauses`, or with a `scope` of `pacing: 'paced'`, is labelled as paced: the time
+  between its steps includes deliberate pauses and is not application latency, and no measurement is changed by it.
+- **Each try has its own clock.** Put the video and the `atlas.media` of a retry on its `attempts[]` entry, with that
+  try's `steps`. A try is aligned only by its own video, never by the check's or an earlier try's.
+- **Link to a moment.** The viewer copies a link that names the run (`layer`), the exact recording (`clip`, its digest or
+  stored key) and the position (`clipAt`, milliseconds into the video). Opening it selects that recording of that run, even
+  when a newer run exists, and goes to the position; a recording the run does not hold is reported, never replaced.
+- **Older layers.** A layer without `atlas.media` reads exactly as before; the video plays and its steps list as ever.
+
 ## Product latency
 
 A test's `durationMs` includes fixture setup, deliberate waits, demo pacing, retries and cleanup, so it says how long the

package/docs/ui.md

@@ -150,6 +150,28 @@ over the same filtered set the page lists, in the same order (`explorer/playlist
   (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. Developer
   details opens the test pinned to that run's record and closes the playlist.
 
+## Steps and moments in a recording
+
+Wherever a result's steps sit beside its recording (a result's Timeline under Inspect, the Watch tab of a behavior, an
+opened watch playlist), `evidence/moments.tsx` joins them. Placement is from the recording's own declared timing
+(`evidence/media-timing.ts`, the `atlas.media` extension; see [Place steps in a recording](rich-evidence.md#place-steps-in-a-recording)),
+never from an assumption that the recording starts with the check.
+
+- A step has a "Recording m:ss.s" button that seeks the selected recording; the step's test-clock offset stays visible beside it.
+  A step that cannot be placed (no timing, no origin, no offset, outside the recording, unreadable declaration) is "Not aligned"
+  and selecting it states the reason in a status alert. Nothing is guessed and the video is not moved.
+- While playing, the step under the playhead gets `aria-current="step"` and "Playing now". It never moves focus, scrolls
+  the page or announces itself. Seeking only scrolls the player into view.
+- A paced recording (pauses declared, or a `pacing: paced` scope) says that gaps between steps include deliberate pauses and are
+  not application latency.
+- A failed step has "Jump to the failing moment" in the bar above the timeline, and the failure summary has the same action
+  (`requestFailureMoment`). If the recording is not on screen, or the step cannot be placed, it says so.
+- "Copy link to this moment" names the run (`layer`), the exact recording (`clip`) and the position (`clipAt`, ms), as the
+  explorer address `/?test=…&layer=…&clip=…&clipAt=…` (the playlist links to the result it is playing). Opening it selects that
+  recording of that exact run and seeks once the player knows its length; a position past the end or a recording that the run
+  does not hold is reported and nothing else is played in its place. If the browser refuses to copy, the link is shown to copy.
+- One provider serves one holder: the check, or one try. A try's steps are placed by that try's recording and timing only.
+
 ## Review collections
 
 The **Collections** tab (`explorer/collections.tsx`, `?tab=collections&collection=<id>&rev=<n>`) lists and opens review

package/llms-full.txt

@@ -1014,6 +1014,7 @@ decided exactly as before ([the report contract](report-contract.md)). Evidence
 | `attempts` | check | Every try of a retried check, with its own status, detail, steps and attachments. A check that passed after failing is flaky. |
 | `tags`, `labels` | check, layer | Filters and groups (`smoke`, `flaky`, an owner, a browser). |
 | `tags` | attachment | Marks one recording or screenshot, for example `demo`: shown as a `#demo` chip, and searchable. See [Tagging artifacts and demos](#tagging-artifacts-and-demos). |
+| `extensions['atlas.media']` | attachment (video) | Where the check's steps are in the recording, so a click on a step seeks the video. See [Place steps in a recording](#place-steps-in-a-recording). |
 | `scope` | attachment, attempt, check, part, layer | What a recording does and does not show: where it ran, whether data and dependencies were real, whether audio was captured. See [Evidence scope](#evidence-scope). |
 | `annotations`, `links` | check, step, attempt, layer | Notes, warnings and issue links next to the result. |
 | `specPath` | check | The spec a check belongs to (a `.feature`, a test file), relative to the repository. Checks are grouped by it. |
@@ -1096,6 +1097,44 @@ Every field is optional, and every value except the booleans is an open string.
 - **It decides nothing.** A scope never changes a status, a slot or a winner. A scope an older Atlas cannot read is
   dropped, and the attachment, check and layer stay.
 
+## Place steps in a recording
+
+A step says when it started on the check's clock (`offsetMs`, after the check started). A video has its own clock, which
+began when the recorder did, and the two are not assumed to agree: a recorder usually starts before the first step, and a
+paced demo may have delays put into the video that the check never waited for. To let a reviewer click a step and land on
+its moment in the video, say how the clocks relate in the `atlas.media` extension of the video attachment:
+
+```ts
+{
+  name: 'checkout.webm', role: 'video', durationMs: 9000,
+  extensions: {
+    'atlas.media': {
+      checkStartMs: 1200,                                           // the check started 1.2 s into the video
+      pauses: [{ atMs: 900, durationMs: 2000, reason: 'title card' }], // 2 s put into the video before the step at +900 ms
+      marks: [{ step: 'pay', mediaMs: 4100 }]                        // a step whose moment in the video you know exactly
+    }
+  }
+}
+```
+
+Every field is optional and none of it decides a status, a slot or a winner. A step is placed at `checkStartMs` + its
+`offsetMs` + the `durationMs` of every pause whose `atMs` is at or before the step; a mark names the moment outright and
+wins. Anything else is unavailable and said so, never guessed.
+
+- **Without timing, nothing is placed.** A video with no `atlas.media`, no `checkStartMs`, or a step with no `offsetMs` and
+  no mark, is never assumed to start with the check, and a step is never placed from the wording of its name. Selecting
+  such a step says why it cannot be shown, and moves nothing.
+- **Outside the video is not clamped.** A moment before the start, or after `durationMs` (or the length the player reports),
+  is unavailable. A declaration with a field Atlas cannot read (a pause without a duration) is reported and places nothing.
+- **Pacing is not latency.** A video with `pauses`, or with a `scope` of `pacing: 'paced'`, is labelled as paced: the time
+  between its steps includes deliberate pauses and is not application latency, and no measurement is changed by it.
+- **Each try has its own clock.** Put the video and the `atlas.media` of a retry on its `attempts[]` entry, with that
+  try's `steps`. A try is aligned only by its own video, never by the check's or an earlier try's.
+- **Link to a moment.** The viewer copies a link that names the run (`layer`), the exact recording (`clip`, its digest or
+  stored key) and the position (`clipAt`, milliseconds into the video). Opening it selects that recording of that run, even
+  when a newer run exists, and goes to the position; a recording the run does not hold is reported, never replaced.
+- **Older layers.** A layer without `atlas.media` reads exactly as before; the video plays and its steps list as ever.
+
 ## Product latency
 
 A test's `durationMs` includes fixture setup, deliberate waits, demo pacing, retries and cleanup, so it says how long the
@@ -3057,6 +3096,13 @@ when you do not know, and the viewer says the cause is unknown. It is never infe
 failed before the behavior started comes from the failed step's `kind`: `hook`, `setup`, `fixture`, `before`,
 `beforeAll`, `beforeEach` or `given` mean preparation; `when`, `then`, `assertion` or `expect` mean the behavior.
 
+### Placing steps in a recording
+
+A video may declare how its clock relates to the check's under the `atlas.media` extension (`checkStartMs`, `pauses`,
+`marks`), so the viewer can seek it from a step and mark the step playing. Without it the video plays as ever and no step
+is placed. The fields, the rules and the link to a moment are in
+[Place steps in a recording](rich-evidence.md#place-steps-in-a-recording).
+
 ## Attach evidence
 
 ### From the command line
@@ -4139,6 +4185,28 @@ over the same filtered set the page lists, in the same order (`explorer/playlist
   (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. Developer
   details opens the test pinned to that run's record and closes the playlist.
 
+## Steps and moments in a recording
+
+Wherever a result's steps sit beside its recording (a result's Timeline under Inspect, the Watch tab of a behavior, an
+opened watch playlist), `evidence/moments.tsx` joins them. Placement is from the recording's own declared timing
+(`evidence/media-timing.ts`, the `atlas.media` extension; see [Place steps in a recording](rich-evidence.md#place-steps-in-a-recording)),
+never from an assumption that the recording starts with the check.
+
+- A step has a "Recording m:ss.s" button that seeks the selected recording; the step's test-clock offset stays visible beside it.
+  A step that cannot be placed (no timing, no origin, no offset, outside the recording, unreadable declaration) is "Not aligned"
+  and selecting it states the reason in a status alert. Nothing is guessed and the video is not moved.
+- While playing, the step under the playhead gets `aria-current="step"` and "Playing now". It never moves focus, scrolls
+  the page or announces itself. Seeking only scrolls the player into view.
+- A paced recording (pauses declared, or a `pacing: paced` scope) says that gaps between steps include deliberate pauses and are
+  not application latency.
+- A failed step has "Jump to the failing moment" in the bar above the timeline, and the failure summary has the same action
+  (`requestFailureMoment`). If the recording is not on screen, or the step cannot be placed, it says so.
+- "Copy link to this moment" names the run (`layer`), the exact recording (`clip`) and the position (`clipAt`, ms), as the
+  explorer address `/?test=…&layer=…&clip=…&clipAt=…` (the playlist links to the result it is playing). Opening it selects that
+  recording of that exact run and seeks once the player knows its length; a position past the end or a recording that the run
+  does not hold is reported and nothing else is played in its place. If the browser refuses to copy, the link is shown to copy.
+- One provider serves one holder: the check, or one try. A try's steps are placed by that try's recording and timing only.
+
 ## Review collections
 
 The **Collections** tab (`explorer/collections.tsx`, `?tab=collections&collection=<id>&rev=<n>`) lists and opens review

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.11.0",
+  "version": "1.12.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/app/router.tsx

@@ -30,6 +30,9 @@ const SpecSearch = RootSearch.extend({
   spec: z.string().min(1).optional().catch(undefined),
   check: z.string().min(1).optional().catch(undefined),
   layer: z.string().min(1).optional().catch(undefined),
+  /** A shared moment: the exact recording (an `attachmentIdentity`) of that layer, and the position in it in milliseconds. */
+  clip: z.coerce.string().min(1).optional().catch(undefined),
+  clipAt: z.coerce.number().nonnegative().optional().catch(undefined),
   view: z.enum(['recording']).optional().catch(undefined),
   moment: z.coerce.number().int().positive().optional().catch(undefined),
   /** The release evidence is read against: its build, commit and platform, and the evidence filter (see `evidence/applicability.ts`). A build such as `90` is read from a typed link as a number: coerced back to its text. */

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

@@ -1,5 +1,5 @@
 import type { CheckDetail, EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
-import { isVideoAttachment, roleOfType } from '@crvouga/atlas/reports/evidence-detail';
+import { attachmentIdentity, isVideoAttachment, roleOfType } from '@crvouga/atlas/reports/evidence-detail';
 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';
@@ -12,6 +12,8 @@ import { reportAssetUrl, reportJson, reportText } from './api';
 import { ScopeNotice, ScopeProvider, useScope } from './evidence-scope';
 import { duration, plural, safeUri } from './format';
 import { StatusMark } from './marks';
+import { MomentBar, MomentPlayback, momentOwner, SeekStep, useIsPlaying, useMomentVideo, useRequestedMoment } from './moments';
+import { videosIn } from './outcome';
 /**
  * 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
@@ -38,6 +40,8 @@ const label = (attachment: Attachment) => attachment.description ?? attachment.n
 /** 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);
+  // Inside a result's playback the player is the one its steps seek and that marks the step playing.
+  const moments = useMomentVideo(attachment);
   if (failed)
     return (
       <Alert role="alert" color="orange" title="This video cannot be played">
@@ -50,7 +54,19 @@ function VideoPlayer({ attachment, url }: { attachment: Attachment; url: string
         </Text>
       </Alert>
     );
-  return <Box src={url} controls preload="metadata" aria-label={label(attachment)} component="video" maw="100%" w="100%" onError={() => setFailed(true)} />;
+  return (
+    <Box
+      src={url}
+      controls
+      preload="metadata"
+      aria-label={label(attachment)}
+      component="video"
+      maw="100%"
+      w="100%"
+      onError={() => setFailed(true)}
+      {...moments}
+    />
+  );
 }
 function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
   const stored = useQuery({
@@ -261,37 +277,11 @@ export function Timeline({ steps, layer }: { steps: readonly Step[]; layer: stri
   }, [steps]);
   const render = (parent: string | null): ReactNode => (
     <List spacing="xs" listStyleType="none" type="ordered">
-      {(tree.get(parent) ?? []).map((step, index) => {
-        const status = STEP_STATUS[(step.status ?? '').toLowerCase()];
-        return (
-          <List.Item data-evidence-step key={`${step.id ?? step.name}:${index}`} data-status={status ?? step.status ?? 'none'}>
-            <Flex gap="xs" align="center" wrap="wrap">
-              <StatusMark status={status ?? 'none'} size={14} />
-              <Text span inherit>
-                {step.name}
-              </Text>
-              {step.kind && (
-                <Text span inherit>
-                  {step.kind}
-                </Text>
-              )}
-              {step.status && !status && (
-                <Text span inherit>
-                  {step.status}
-                </Text>
-              )}
-              <Box flex={1} />
-              <Text span inherit c="dimmed">
-                {[step.offsetMs !== undefined ? `+${duration(step.offsetMs)}` : '', duration(step.durationMs)].filter(Boolean).join(' · ')}
-              </Text>
-            </Flex>
-            {step.detail && <Text component="div">{step.detail}</Text>}
-            {step.annotations && <Notes notes={step.annotations} />}
-            {step.attachments && <Attachments attachments={step.attachments} layer={layer} />}
-            {step.id && tree.has(step.id) && render(step.id)}
-          </List.Item>
-        );
-      })}
+      {(tree.get(parent) ?? []).map((step, index) => (
+        <TimelineStep key={`${step.id ?? step.name}:${index}`} step={step} layer={layer}>
+          {step.id && tree.has(step.id) && render(step.id)}
+        </TimelineStep>
+      ))}
     </List>
   );
   return (
@@ -299,10 +289,52 @@ export function Timeline({ steps, layer }: { steps: readonly Step[]; layer: stri
       <Title order={4} mb="sm">
         {plural(steps.length, 'step', 'steps')}
       </Title>
+      <MomentBar />
       {render(null)}
     </Box>
   );
 }
+/** One step of the timeline: its outcome and times, a control to show it in the recording when there is one, and what it carries. */
+function TimelineStep({ step, layer, children }: { step: Step; layer: string; children: ReactNode }) {
+  const status = STEP_STATUS[(step.status ?? '').toLowerCase()];
+  const playing = useIsPlaying(step);
+  return (
+    <List.Item
+      data-evidence-step
+      data-status={status ?? step.status ?? 'none'}
+      data-playing={playing || undefined}
+      aria-current={playing ? 'step' : undefined}
+      {...(playing ? { bg: 'blue.0' } : {})}
+    >
+      <Flex gap="xs" align="center" wrap="wrap">
+        <StatusMark status={status ?? 'none'} size={14} />
+        <Text span inherit>
+          {step.name}
+        </Text>
+        {step.kind && (
+          <Text span inherit>
+            {step.kind}
+          </Text>
+        )}
+        {step.status && !status && (
+          <Text span inherit>
+            {step.status}
+          </Text>
+        )}
+        {playing && <Badge variant="light">Playing now</Badge>}
+        <Box flex={1} />
+        <SeekStep step={step} />
+        <Text span inherit c="dimmed">
+          {[step.offsetMs !== undefined ? `+${duration(step.offsetMs)}` : '', duration(step.durationMs)].filter(Boolean).join(' · ')}
+        </Text>
+      </Flex>
+      {step.detail && <Text component="div">{step.detail}</Text>}
+      {step.annotations && <Notes notes={step.annotations} />}
+      {step.attachments && <Attachments attachments={step.attachments} layer={layer} />}
+      {children}
+    </List.Item>
+  );
+}
 export function Notes({ notes }: { notes: readonly Annotation[] }) {
   if (!notes.length) return null;
   return (
@@ -333,6 +365,7 @@ export function Notes({ notes }: { notes: readonly Annotation[] }) {
     </List>
   );
 }
+const NO_FILES: readonly Attachment[] = [];
 function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: string }) {
   if (!attempts.length) return null;
   return (
@@ -355,7 +388,11 @@ function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: strin
             </Flex>
             {attempt.detail && <Text component="div">{attempt.detail}</Text>}
             <ScopeProvider scope={attempt.scope}>
-              {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+              {/* A try is placed in its own recording with that recording's own timing, never in another try's. */}
+              <MomentPlayback steps={attempt.steps} attachments={attempt.attachments ?? NO_FILES} layer={layer}>
+                {attempt.steps && attempt.steps.length > 0 ? <Timeline steps={attempt.steps} layer={layer} /> : <MomentBar />}
+                {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+              </MomentPlayback>
             </ScopeProvider>
           </List.Item>
         ))}
@@ -413,15 +450,17 @@ function Facts({ holder }: { holder: EvidenceHolder }) {
     </Stack>
   );
 }
-function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: string; steps?: boolean }) {
+function Evidence({ holder, layer, steps = false, owner }: { holder: EvidenceHolder; layer: string; steps?: boolean; owner?: string }) {
   return (
     <ScopeProvider scope={holder.scope}>
-      <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} />}
+      <MomentPlayback steps={steps ? holder.steps : undefined} attachments={holder.attachments ?? NO_FILES} layer={layer} primary={steps} owner={owner}>
+        <Facts holder={holder} />
+        {holder.annotations && <Notes notes={holder.annotations} />}
+        {steps && holder.steps && holder.steps.length > 0 ? <Timeline steps={holder.steps} layer={layer} /> : <MomentBar />}
+        {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} />}
+      </MomentPlayback>
     </ScopeProvider>
   );
 }
@@ -444,6 +483,7 @@ export function useCheckDetail(layer: LayerHeader, row: LayerRow, enabled = true
 export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerRow }) {
   const wanted = row.evidence !== undefined || layer.evidence !== undefined;
   const detail = useCheckDetail(layer, row);
+  const requested = useRequestedMoment();
   if (!wanted) return null;
   if (detail.isLoading)
     return (
@@ -466,13 +506,19 @@ export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerR
     <ArtifactTagsProvider layer={layer.id} kind={row.kind} check={row.id} holders={[check, run]}>
       <Stack aria-label="Evidence" gap="sm" miw={0}>
         <TagFilterBar holders={[check, run]} />
+        {requested.clip !== undefined && requested.layer === layer.id && ![...videosIn(check), ...videosIn(run)].some((video) => attachmentIdentity(video) === requested.clip) && (
+          <Alert role="status" color="orange" title="The recording this link names is not in this result" data-moment-missing>
+            The link names a recording that this run did not record for this check. Nothing is played in its place, and no other run is
+            substituted.
+          </Alert>
+        )}
         {declared && (
           <Box aria-label="Scope of this result" component="section">
             <ScopeNotice scope={declared} name={row.title} />
           </Box>
         )}
         <ScopeProvider scope={inheritedScope}>
-          <Evidence holder={check} layer={layer.id} steps />
+          <Evidence holder={check} layer={layer.id} steps owner={momentOwner(layer.id, row.kind, row.id)} />
         </ScopeProvider>
         {hasRun && (
           <Box aria-label="From the run" component="section" mb="lg">

package/packages/visualizer/src/evidence/behavior-panel.tsx

@@ -6,22 +6,25 @@
  * record: run, environment, source, attempts). Also the coverage summary of the whole feature. A recording is always
  * labelled as illustrative evidence with its own status, provenance and revision; it never stands for approval.
  */
+import { attachmentIdentity } from '@crvouga/atlas/reports/evidence-detail';
 import { effectiveScope } from '@crvouga/atlas/reports/evidence-scope';
 import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
 import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
 import { Alert, Badge, Box, Group, List, Paper, Stack, Tabs, Text, Title } from '@mantine/core';
 import { useMemo, type ReactNode } from 'react';
+import type { Attachment } from '@crvouga/atlas/schema';
 
 import type { Assessment, ReleaseIdentity } from './applicability';
 import { ApplicabilitySummary } from './applicability-view';
-import { attachmentSource, useCheckDetail } from './artifacts';
+import { attachmentSource, Timeline, useCheckDetail } from './artifacts';
 import { COVERAGE, COVERAGE_ORDER, type Behavior, type CoverageCounts, type CoverageState, type Revision } from './behavior';
 import { PlainSteps } from './check-detail';
 import { useEvidence } from './evidence-context';
-import { ScopeNotice } from './evidence-scope';
+import { ScopeNotice, ScopeProvider } from './evidence-scope';
 import { plural, statusWord, useNow } from './format';
 import { exampleIndexFor, exampleRows, fillExample, type FeatureStep } from './gherkin';
 import { Origin, StatusMark } from './marks';
+import { MomentPlayback, stepsOfRecording, useMomentVideo, useRequestedMoment } from './moments';
 import { outcomeHeadline, videosIn } from './outcome';
 
 /** The short, readable form of a spec fingerprint (`<length>:<hash>:<hash>`): its length and the start of its hash. */
@@ -80,14 +83,37 @@ function expectedSteps(steps: readonly FeatureStep[]): FeatureStep[] {
   return at < 0 ? [] : steps.slice(at);
 }
 
+/** The recording itself: the one player the steps beside it seek, which marks the step playing. */
+function WatchVideo({ attachment, url }: { attachment: Attachment; url: string }) {
+  const moments = useMomentVideo(attachment);
+  return (
+    <Box
+      component="video"
+      src={url}
+      controls
+      preload="metadata"
+      aria-label={`Recording: ${attachment.description ?? attachment.name}`}
+      maw="100%"
+      w="100%"
+      mah="70vh"
+      {...moments}
+    />
+  );
+}
+
 /** The recording of one result, read only when this is on screen. */
 function Player({ result }: { result: EvidenceResult }) {
   const detail = useCheckDetail(result.layer, result.row);
   const videos = useMemo(() => videosIn(detail.data?.check), [detail.data]);
-  const sources = videos.flatMap((attachment) => {
-    const { url } = attachmentSource(attachment, result.layer.id);
-    return url ? [{ attachment, url }] : [];
-  });
+  const requested = useRequestedMoment();
+  const sources = useMemo(
+    () =>
+      videos.flatMap((attachment) => {
+        const { url } = attachmentSource(attachment, result.layer.id);
+        return url ? [{ attachment, url, list: [attachment] }] : [];
+      }),
+    [videos, result.layer.id]
+  );
   if (detail.isLoading) {
     return (
       <Text role="status" component="div" c="dimmed">
@@ -109,27 +135,20 @@ function Player({ result }: { result: EvidenceResult }) {
       </Text>
     );
   }
+  const shown = sources.find(({ attachment }) => attachmentIdentity(attachment) === requested.clip) ?? sources[0]!;
+  const { attachment, url } = shown;
+  const check = detail.data!.check;
+  const steps = stepsOfRecording(check, attachmentIdentity(attachment));
   return (
     <Stack gap="sm">
-      {sources.slice(0, 1).map(({ attachment, url }) => (
-        <Stack key={url} gap="xs">
-          {/* What the recording does and does not show, as its producer declared it; undeclared says unknown. */}
-          <ScopeNotice
-            scope={effectiveScope(attachment.scope, detail.data?.check.scope, detail.data?.inheritedScope)}
-            name={attachment.name}
-          />
-          <Box
-            component="video"
-            src={url}
-            controls
-            preload="metadata"
-            aria-label={`Recording: ${attachment.description ?? attachment.name}`}
-            maw="100%"
-            w="100%"
-            mah="70vh"
-          />
-        </Stack>
-      ))}
+      {/* What the recording does and does not show, as its producer declared it; undeclared says unknown. */}
+      <ScopeProvider scope={effectiveScope(check.scope, detail.data?.inheritedScope)}>
+        <MomentPlayback steps={steps} attachments={shown.list} layer={result.layer.id}>
+          <ScopeNotice scope={effectiveScope(attachment.scope, check.scope, detail.data?.inheritedScope)} name={attachment.name} />
+          <WatchVideo attachment={attachment} url={url} />
+          {steps.length > 0 && <Timeline steps={steps} layer={result.layer.id} />}
+        </MomentPlayback>
+      </ScopeProvider>
       {sources.length > 1 && (
         <Text component="div" c="dimmed">
           {plural(sources.length - 1, 'more recording', 'more recordings')} in Inspect.

package/packages/visualizer/src/evidence/media-timing.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+
+import { activeIndex, alignStep, clock, mediaTimingOf, pausedMs, UNALIGNED } from './media-timing';
+
+const video = (media: unknown) => ({ extensions: { 'atlas.media': media } });
+
+describe('what a recording declares about its clock', () => {
+  test('no declaration is no timing, never a timing that starts with the check', () => {
+    expect(mediaTimingOf({})).toBeUndefined();
+    expect(mediaTimingOf({ extensions: { 'com.example': {} } })).toBeUndefined();
+    expect(alignStep({ id: 'a', offsetMs: 0 }, undefined, 5000)).toEqual({ state: 'unavailable', reason: UNALIGNED.noTiming });
+  });
+
+  test('a declaration that cannot be read as a whole places nothing', () => {
+    for (const bad of [
+      'text',
+      [],
+      { checkStartMs: '1000' },
+      { checkStartMs: 0, pauses: [{ atMs: 10 }] },
+      { checkStartMs: 0, pauses: 'long' },
+      { checkStartMs: 0, marks: [{ step: 'a' }] }
+    ]) {
+      const timing = mediaTimingOf(video(bad));
+      expect(timing?.problem).toBeDefined();
+      const aligned = alignStep({ id: 'a', offsetMs: 1 }, timing, undefined);
+      expect(aligned.state).toBe('unavailable');
+    }
+  });
+
+  test('a declaration without an origin places only the steps it marks', () => {
+    const timing = mediaTimingOf(video({ marks: [{ step: 'a', mediaMs: 700 }] }));
+    expect(alignStep({ id: 'a', offsetMs: 5 }, timing, undefined)).toEqual({ state: 'aligned', mediaMs: 700, source: 'mark', pausedMs: 0 });
+    expect(alignStep({ id: 'b', offsetMs: 5 }, timing, undefined)).toEqual({ state: 'unavailable', reason: UNALIGNED.noOrigin });
+  });
+});
+
+describe('placing a step in a recording', () => {
+  const timing = mediaTimingOf(video({ checkStartMs: 1200, pauses: [{ atMs: 2000, durationMs: 500 }, { atMs: 500, durationMs: 300, reason: 'title' }] }));
+
+  test('the recording starts before the check: the step is the origin plus its offset', () => {
+    expect(alignStep({ offsetMs: 0 }, timing, 20_000)).toMatchObject({ state: 'aligned', mediaMs: 1200, source: 'offset' });
+    expect(alignStep({ offsetMs: 100 }, timing, 20_000)).toMatchObject({ mediaMs: 1300 });
+  });
+
+  test('delays put into the recording move the steps after them and not the ones before', () => {
+    expect(alignStep({ offsetMs: 499 }, timing, undefined)).toMatchObject({ mediaMs: 1699, pausedMs: 0 });
+    expect(alignStep({ offsetMs: 500 }, timing, undefined)).toMatchObject({ mediaMs: 2000, pausedMs: 300 });
+    expect(alignStep({ offsetMs: 2000 }, timing, undefined)).toMatchObject({ mediaMs: 4000, pausedMs: 800 });
+    expect(pausedMs(timing)).toBe(800);
+    expect(timing!.pauses.map((pause) => pause.reason)).toEqual(['title', undefined]);
+  });
+
+  test('a mark states the moment outright and wins over the offset', () => {
+    const marked = mediaTimingOf(video({ checkStartMs: 0, marks: [{ step: 'a', mediaMs: 9 }] }));
+    expect(alignStep({ id: 'a', offsetMs: 5000 }, marked, undefined)).toMatchObject({ mediaMs: 9, source: 'mark' });
+  });
+
+  test('a step with no offset, before the start, or after the end is unavailable and is never clamped', () => {
+    expect(alignStep({ id: 'a' }, timing, undefined)).toEqual({ state: 'unavailable', reason: UNALIGNED.noOffset });
+    const early = mediaTimingOf(video({ checkStartMs: -500 }));
+    expect(alignStep({ offsetMs: 100 }, early, undefined)).toMatchObject({ state: 'unavailable', reason: expect.stringContaining('before the recording starts') });
+    expect(alignStep({ offsetMs: 100 }, early, undefined)).not.toHaveProperty('mediaMs');
+    expect(alignStep({ offsetMs: 9000 }, timing, 5000)).toMatchObject({ state: 'unavailable', reason: expect.stringContaining('after the recording ends') });
+    // A length that is not known never excludes a moment.
+    expect(alignStep({ offsetMs: 9000 }, timing, undefined).state).toBe('aligned');
+  });
+});
+
+describe('the step playing', () => {
+  const placed = [[0, 1000], [1, 3000], [2, 3000], [3, 6000]] as const;
+  test('is the latest step started, the innermost of several that started together, and none before the first', () => {
+    expect(activeIndex(placed, 500)).toBeNull();
+    expect(activeIndex(placed, 1000)).toBe(0);
+    expect(activeIndex(placed, 2999)).toBe(0);
+    expect(activeIndex(placed, 3000)).toBe(2);
+    expect(activeIndex(placed, 99_000)).toBe(3);
+    expect(activeIndex([], 10)).toBeNull();
+  });
+
+  test('a position reads as minutes, seconds and tenths', () => {
+    expect(clock(0)).toBe('0:00.0');
+    expect(clock(4250)).toBe('0:04.3');
+    expect(clock(61_000)).toBe('1:01.0');
+  });
+});