jevway 0.1.2 → 0.2.0

package/dist/output/manifest.js

@@ -0,0 +1,80 @@
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const MANIFEST = 'manifest.json';
+/** Every file under `dir`, relative and sorted; dotfiles and dot-folders (`.frames` while encoding) are left out. */
+const filesUnder = (dir, base = dir) => readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => !entry.name.startsWith('.'))
+    .flatMap((entry) => (entry.isDirectory() ? filesUnder(join(dir, entry.name), base) : [relative(base, join(dir, entry.name))]))
+    .map((path) => path.split('\\').join('/'))
+    .sort();
+const readJson = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+/** What the folder's own records say about some of its files: step shots from `summary.json`, screens from `journey.json`. */
+const notesIn = (dir, kind) => {
+    const notes = new Map();
+    if (kind === 'run') {
+        const steps = readJson(join(dir, 'summary.json'))?.steps ?? [];
+        steps.forEach((step, i) => {
+            if (!step.file || !step.description)
+                return;
+            const finished = step.description.startsWith('Finished:');
+            notes.set(step.file, finished ? step.description : `Before step ${i + 1}, its target outlined: ${step.description}`);
+        });
+    }
+    else {
+        const screens = readJson(join(dir, 'journey.json'))?.screens ?? [];
+        for (const screen of screens)
+            if (screen.screenshot)
+                notes.set(screen.screenshot, `Screen ${screen.id} (${screen.type ?? 'unknown'}): ${screen.title ?? ''}`);
+    }
+    return notes;
+};
+/**
+ * One file as a manifest line: its kind from its name, and a description from the folder's records where they say more.
+ *
+ * @example
+ * describeFile('calls/02-needs-input.jpg', 'run', new Map()) // { path, kind: 'screenshot', description: 'The page as call 2 ended: needs_input' }
+ */
+export const describeFile = (path, kind, notes) => {
+    const line = (fileKind, description) => ({ path, kind: fileKind, description: oneLine(description) });
+    const call = /^calls\/(\d+)-(.+)\.jpg$/.exec(path);
+    if (path === MANIFEST)
+        return line('manifest', "This list of the folder's files");
+    if (path === 'index.html') {
+        return kind === 'run'
+            ? line('page', 'The run page for people: the video with every step on a timeline, and how each call ended')
+            : line('page', 'The journey map viewer: screens, flows and QA findings');
+    }
+    if (path === 'summary.json')
+        return line('summary', "Each call's summary (status, reason, steps, cost), plus the recorded steps when recorded");
+    if (path === 'journey.json')
+        return line('journey', 'The journey map as data: screens, steps, flows and QA findings');
+    if (path === 'run.mp4')
+        return line('video', 'Screencast of the whole session (idle stretches shortened)');
+    if (path === 'final.jpg')
+        return line('screenshot', 'The page as the latest call ended (viewport, JPEG)');
+    if (call)
+        return line('screenshot', `The page as call ${Number(call[1])} ended: ${call[2].replace(/-/g, '_')}`);
+    if (path.startsWith('steps/'))
+        return line('step', notes.get(path) ?? 'A recorded step, before its action');
+    if (path.startsWith('screens/'))
+        return line('screen', notes.get(path) ?? 'A journey screen');
+    return line('file', 'Not described');
+};
+/** Writes `manifest.json` for what `dir` holds now, itself included. */
+export const writeManifest = (dir, kind) => {
+    const notes = notesIn(dir, kind);
+    const paths = [...new Set([...filesUnder(dir), MANIFEST])].sort();
+    const manifest = { kind, files: paths.map((path) => describeFile(path, kind, notes)) };
+    writeFileSync(join(dir, MANIFEST), JSON.stringify(manifest, null, 1));
+    return join(dir, MANIFEST);
+};
+/** Reads a folder's `manifest.json`. */
+export const readManifest = (dir) => JSON.parse(readFileSync(join(dir, MANIFEST), 'utf8'));

package/dist/output/run-folder.js

@@ -0,0 +1,38 @@
+import { copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { callShotName } from './layout.js';
+import { writeManifest } from './manifest.js';
+/**
+ * Writes what one call leaves in its run folder: its end page as `calls/NN-<status>.jpg` and `final.jpg` (a failed
+ * capture removes an older `final.jpg`, so it never shows another call's page), `summary.json` unless the recording
+ * wrote its own, and the manifest. Returns the folder's files.
+ *
+ * @example
+ * writeCall({ dir, call: 2, status: 'done', shot, summaries, recorded: false }) // { run_dir, screenshot: '…/final.jpg', manifest }
+ */
+export const writeCall = ({ dir, call, status, shot, summaries, recorded, }) => {
+    const root = resolve(dir);
+    mkdirSync(root, { recursive: true });
+    const final = join(root, 'final.jpg');
+    if (shot) {
+        const callShot = join(root, callShotName(call, status));
+        mkdirSync(dirname(callShot), { recursive: true });
+        writeFileSync(callShot, shot);
+        copyFileSync(callShot, final);
+    }
+    else
+        rmSync(final, { force: true });
+    // A recording that failed before writing its own leaves the folder without one.
+    if (!recorded || !existsSync(join(root, 'summary.json')))
+        writeFileSync(join(root, 'summary.json'), JSON.stringify({ summaries }, null, 1));
+    const manifest = writeManifest(root, 'run');
+    const page = join(root, 'index.html');
+    const video = join(root, 'run.mp4');
+    return {
+        run_dir: root,
+        ...(shot && { screenshot: final }),
+        ...(recorded && existsSync(page) && { page }),
+        ...(recorded && existsSync(video) && { video }),
+        manifest,
+    };
+};

package/dist/recording/describe-step.js

@@ -0,0 +1,66 @@
+// The one wording of a step that people read: the recording's shots (what happens next) and a summary's story (what
+// happened). Kept apart from the recording so the pages and the story share it without importing the recorder.
+// Row labels carry a whole table row; a sentence needs its first words.
+const shorten = (label, max = 70) => {
+    const text = label.replace(/\s+/g, ' ').trim();
+    return text.length > max ? `${text.slice(0, max).replace(/\s+\S*$/, '')}…` : text;
+};
+// Each verb as Jev is about to do it (`next`, the recording's step shots) and as done (`done`, a summary's story).
+const VERBS = {
+    click: ['Click', 'Clicked'],
+    type: ['Type', 'Typed'],
+    choose: ['Choose', 'Chose'],
+    press: ['Press', 'Pressed'],
+    scroll: ['Scroll', 'Scrolled'],
+    wait: ['Wait', 'Waited'],
+    upload: ['Upload', 'Uploaded'],
+};
+/**
+ * A step as one plain sentence for people reading a recording (`next`, what happens on this screen) or a summary's
+ * story (`done`, what happened).
+ *
+ * @example
+ * describeStep({ operation: 'TYPE_TEXT', element: 'Search traces', valueKey: 'search_query' })
+ * // 'Type the "search_query" value into "Search traces"'
+ * describeStep({ operation: 'CLICK', element: 'Search' }, 'done') // 'Clicked "Search"'
+ */
+export const describeStep = ({ operation, element = '', valueKey, fileKey, option }, tense = 'next') => {
+    const target = `"${shorten(element)}"`;
+    const verb = (name) => VERBS[name][tense === 'next' ? 0 : 1];
+    switch (operation) {
+        case 'CLICK':
+            return `${verb('click')} ${target}`;
+        case 'CLICK_AT':
+            return `${verb('click')} the control at ${target} by its on-screen position`;
+        case 'TYPE_TEXT':
+            return `${verb('type')} the "${valueKey}" value into ${target}`;
+        case 'UPLOAD':
+            return fileKey ? `${verb('upload')} the "${fileKey}" file into ${target}` : `${verb('upload')} a file into ${target}`;
+        case 'SELECT':
+            return option ? `${verb('choose')} "${option}" in ${target}` : `${verb('choose')} an option in ${target}`;
+        case 'PRESS_ENTER':
+            return `${verb('press')} Enter in ${target} to submit it`;
+        case 'PRESS_ESCAPE':
+            return `${verb('press')} Escape to close the open menu or popup`;
+        case 'SCROLL_DOWN':
+            return `${verb('scroll')} down to reveal more of the page`;
+        case 'SCROLL_UP':
+            return `${verb('scroll')} back up`;
+        case 'WAIT':
+            return `${verb('wait')} for the page to finish updating`;
+        default:
+            return `${operation} ${target}`;
+    }
+};
+const PAST = new Map(Object.values(VERBS));
+/**
+ * A recorded step's description (the `next` tense) in the past tense, as a sentence.
+ *
+ * @example
+ * pastTense('Type the "email" value into "Email"') // 'Typed the "email" value into "Email".'
+ */
+export const pastTense = (description) => {
+    const [verb] = description.split(' ', 1);
+    const told = PAST.has(verb) ? `${PAST.get(verb)}${description.slice(verb.length)}` : description;
+    return /[.!?]$/.test(told) ? told : `${told}.`;
+};

package/dist/{task → recording}/recording-page.js

@@ -1,9 +1,42 @@
+// The design every recording page shares (Prima Persona: one 4-column grid, monochrome, hairline rows, Switzer):
+// a run's own index.html, the jobs report and the agent report. The player (the video, its timeline and the step strip,
+// kept on the same step) is here too, so a run looks the same wherever it is shown.
+import { readFileSync } from 'node:fs';
+import { storyLine } from '../task/present.js';
+import { pastTense } from './describe-step.js';
 export const escapeHtml = (text) => text.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 const escape = escapeHtml;
 /** Switzer from Fontshare; the system stack takes over when it can't load (offline, file://). */
 export const FONT_LINK = 'https://api.fontshare.com/v2/css?f[]=switzer@400,500&display=swap';
+// --- what every page's head carries
+/** The installed jevway's version (`package.json` sits two folders up from here in `src/` and in `dist/`). */
+export const JEVWAY_VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    }
+    catch {
+        return 'unknown';
+    }
+})();
+/** Names the page's maker for an agent that fetched it: `<meta name="generator" content="jevway 0.4.0">`. */
+export const GENERATOR_META = `<meta name="generator" content="jevway ${JEVWAY_VERSION}">`;
+/** The web font, optional: fetched without holding the first paint, so an offline page draws at once in the system stack. */
+export const FONT_STYLESHEET = `<link rel="stylesheet" href="${FONT_LINK}" media="print" onload="this.media='all'">`;
+/**
+ * Data an agent reads without scraping the markup: JSON in an inert script element, `<` escaped so no string in it can
+ * close the element.
+ *
+ * @example
+ * embeddedJson('jevway-summary', record) // '<script type="application/json" id="jevway-summary">{…}</script>'
+ */
+export const embeddedJson = (id, data) => `<script type="application/json" id="${escape(id)}">${JSON.stringify(data).replace(/</g, '\\u003c')}</script>`;
 // --- words and numbers a reader compares
 export const statusWord = (status) => status.replaceAll('_', ' ');
+const STATUS_LABELS = { done: 'Done', needs_input: 'Needs input', needs_confirmation: 'Needs confirmation', uncertain: 'Uncertain', blocked: 'Blocked', step_budget: 'Out of budget' };
+/** A status as a person says it: "Needs input", "Out of budget". */
+export const statusLabel = (status) => STATUS_LABELS[status] ?? statusWord(status).replace(/^./, (c) => c.toUpperCase());
+/** How a status reads at a glance: done held, a hand-back is the caller's turn (reached), a stop missed. */
+export const statusTone = (status) => (status === 'done' ? 'held' : ['needs_input', 'needs_confirmation', 'uncertain'].includes(status) ? 'reached' : 'missed');
 export const clock = (s) => `${Math.floor(s / 60)}:${(s % 60).toFixed(1).padStart(4, '0')}`;
 export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 export const indexLabel = (i) => String(i + 1).padStart(2, '0');
@@ -22,6 +55,78 @@ export const pathOf = (url) => {
 };
 /** A run's Finished shots carry the status (lowercase) as their operation; actions are uppercase. */
 export const isFinished = (step) => step.operation === step.operation.toLowerCase();
+const lowerFirst = (text) => text.charAt(0).toLowerCase() + text.slice(1);
+const withoutStop = (text) => text.replace(/\.$/, '');
+// A recorded shot's own wording when no summary step tells it: past tense, or what kept it from running.
+const toldFromShot = (step) => step.unreachable
+    ? `Did not ${lowerFirst(step.description)}: something covered its target${(step.attempts ?? 1) > 1 ? ` (${step.attempts} tries)` : ''}.`
+    : pastTense(step.description);
+// A shot and a summary step are the same step when their operation and wording agree: the summary's sentence starts
+// with the shot's description in the past tense (or "Did not …" for a target that was never reached).
+const sameStep = (shot, step, sentence) => {
+    if (shot.operation !== step.operation)
+        return false;
+    if (shot.unreachable)
+        return sentence.startsWith(`Did not ${lowerFirst(shot.description)}`);
+    if (sentence.startsWith('Did not '))
+        return false;
+    return shot.operation === 'PRESS_ESCAPE' || sentence.startsWith(withoutStop(pastTense(shot.description)));
+};
+/**
+ * The recorded steps told the way a summary's `story` tells them (`storyLine`), one story per call: the recording's
+ * Finished shots split the calls, and each shot takes the sentence of the summary step it matches, in order. A summary
+ * step with no shot (a rejected done, a covered target fed back) keeps its place without one; a shot no summary step
+ * matches is told from its own description.
+ *
+ * @example
+ * storyOfRecording(steps, summaries)[0].entries[0] // { sentence: 'Clicked "New issue".', shot: 0 }
+ */
+export const storyOfRecording = (steps, summaries) => {
+    const calls = [{ shots: [] }];
+    steps.forEach((step, i) => {
+        const call = calls.at(-1);
+        if (isFinished(step)) {
+            call.end = i;
+            calls.push({ shots: [] });
+        }
+        else
+            call.shots.push(i);
+    });
+    if (!calls.at(-1).shots.length && calls.length > 1)
+        calls.pop();
+    return calls.map(({ shots, end }, n) => {
+        const told = summaries[n]?.steps ?? [];
+        // A summary saved by older code may lack a step's element.
+        const sentences = told.map((step) => storyLine({ ...step, element: step.element ?? '' }));
+        const entries = [];
+        let cursor = 0;
+        for (const shot of shots) {
+            const match = told.findIndex((step, j) => j >= cursor && sameStep(steps[shot], step, sentences[j]));
+            if (match < 0) {
+                entries.push({ sentence: toldFromShot(steps[shot]), shot });
+                continue;
+            }
+            entries.push(...sentences.slice(cursor, match).map((sentence) => ({ sentence })), { sentence: sentences[match], shot });
+            cursor = match + 1;
+        }
+        entries.push(...sentences.slice(cursor).map((sentence) => ({ sentence })));
+        if (end === undefined)
+            return { entries };
+        const status = steps[end].operation;
+        const reason = summaries[n]?.reason ?? steps[end].description.replace(/^Finished: [a-z_]+\.\s*/, '');
+        entries.push({ sentence: `${statusLabel(status)}: ${reason}`, shot: end });
+        return { status, entries };
+    });
+};
+/** Each recorded step's sentence, by its index: what its card and its alt text say. */
+export const sentencesOf = (stories) => {
+    const sentences = [];
+    for (const { entries } of stories)
+        for (const { sentence, shot } of entries)
+            if (shot !== undefined)
+                sentences[shot] = sentence;
+    return sentences;
+};
 /** One hairline row of a fact list: the label in column 1, the body across columns 2–4. */
 export const fact = (label, body) => `<div class="fact grid4"><dt>${label}</dt><dd class="c2s3">${body}</dd></div>`;
 /**
@@ -43,13 +148,14 @@ export const stripOpening = (label, viewport) => {
     return `<div class="strip${shape}" aria-label="Steps of ${label}">`;
 };
 /**
- * One step as a card: the shot, then its number, video time and confidence, what happened, and where. The run's
- * Finished shots (lowercase operation, the status) read "Finished: <status>", their reason in the alt text. With
- * `href` the whole card is a link (the overview); otherwise it seeks the player it sits in.
+ * One step as a card: the shot, then its number, video time and confidence, what happened (`sentence`, the story's
+ * wording, else the recorded description), and where. Finished shots (lowercase operation, the status) read
+ * "Finished: <status>" without a sentence. With `href` the whole card is a link (the overview); otherwise it seeks the
+ * player it sits in, and a link named after the shot's file opens it full size.
  */
-export const shotCard = (step, i, dir, open) => {
+export const shotCard = (step, i, dir, open, sentence) => {
     const finished = isFinished(step);
-    const label = finished ? `Finished: ${statusWord(step.operation)}` : step.description;
+    const label = sentence ?? (finished ? `Finished: ${statusWord(step.operation)}` : step.description);
     const timed = 'video' in open && open.video && step.video_at !== undefined;
     const meta = [
         indexLabel(i),
@@ -57,15 +163,16 @@ export const shotCard = (step, i, dir, open) => {
         ...(step.unreachable ? [`<span class="missed">not reached${(step.attempts ?? 1) > 1 ? ` ×${step.attempts}` : ''}: covered</span>`] : step.confidence !== undefined && !finished ? [step.confidence.toFixed(2)] : []),
     ].join(' · ');
     const src = `${dir}${step.file}`;
-    const image = `<img src="${escape(src)}" alt="${escape(step.description)}" loading="lazy" decoding="async" width="1120" height="780">`;
+    const image = `<img src="${escape(src)}" alt="${escape(sentence ?? step.description)}" loading="lazy" decoding="async" width="1120" height="780">`;
     const text = `<span class="what">${escape(label)}</span><span class="where">${escape(pathOf(step.url))}</span>`;
     const className = `shot${finished ? ' finished' : ''}`;
     if ('href' in open)
         return `<a class="${className}" href="${escape(open.href)}">${image}<span class="caption"><span class="meta num">${meta}</span>${text}</span></a>`;
-    // In a player the whole card seeks (the button gives it a keyboard stop); the full-size link sits outside the button.
+    // In a player the whole card seeks (the button gives it a keyboard stop); the file's own link sits outside the button.
     const data = timed ? ` data-at="${step.video_at}"` : ` data-src="${escape(src)}"`;
+    const name = step.file.split('/').pop();
     return `<div class="${className}" data-index="${i}"${data}><button type="button" class="seek" aria-label="Show step ${i + 1}">${image}</button>
-<span class="caption"><span class="meta-line"><span class="meta num">${meta}</span><a class="full-size" href="${escape(src)}" target="_blank" rel="noopener">Full size</a></span>${text}</span></div>`;
+<span class="caption"><span class="meta-line"><span class="meta num">${meta}</span><a class="full-size" href="${escape(src)}" target="_blank" rel="noopener" title="Open the shot full size">${escape(name)}</a></span>${text}</span></div>`;
 };
 /**
  * The video (or the first shot when there is no video), its timeline with one tick per step, the `bar` (a run switcher
@@ -75,16 +182,16 @@ export const shotCard = (step, i, dir, open) => {
  * @example
  * playerMarkup({ dir: 'run-1/', video: 'run.mp4', steps, label: 'run 1', featured: true, viewport: { width: 1120, height: 780 }, bar })
  */
-export const playerMarkup = ({ dir, video, steps, label, featured, viewport, bar, preload = 'none', }) => {
+export const playerMarkup = ({ dir, video, steps, label, featured, viewport, bar, preload = 'none', sentences = [], }) => {
     const screen = screenFrame(viewport);
     const strip = stripOpening(label, viewport);
     const poster = `${dir}${steps[0].file}`;
     const timed = steps.filter((s) => s.video_at !== undefined);
     if (!video || !timed.length) {
-        return `${screen}<img data-frame src="${escape(poster)}" alt="${escape(steps[0].description)}"></div>
+        return `${screen}<img data-frame src="${escape(poster)}" alt="${escape(sentences[0] ?? steps[0].description)}"></div>
 <p class="small screen-note">No video for this run (it needs ffmpeg): pick a step to see its shot.</p>
 ${bar}
-${strip}${steps.map((s, i) => shotCard(s, i, dir, { video: false })).join('')}</div>`;
+${strip}${steps.map((s, i) => shotCard(s, i, dir, { video: false }, sentences[i])).join('')}</div>`;
     }
     // The last frame holds 1.5 s (recording.ts), so this is the video's length until its metadata says otherwise.
     const duration = Math.max(...timed.map((s) => s.video_at)) + 1.5;
@@ -99,7 +206,7 @@ ${strip}${steps.map((s, i) => shotCard(s, i, dir, { video: false })).join('')}</
     return `${screen}<video src="${escape(`${dir}${video}`)}" preload="${preload}"${posterAttribute} controls muted playsinline aria-label="Screencast of ${label}"></video></div>
 <div class="timeline-scroll"><div class="timeline" style="min-width:${width.toFixed(1)}rem"><div class="track"></div><div class="played"></div><div class="ticks">${ticks}</div></div></div>
 ${bar}
-${strip}${steps.map((s, i) => shotCard(s, i, dir, { video: true })).join('')}</div>`;
+${strip}${steps.map((s, i) => shotCard(s, i, dir, { video: true }, sentences[i])).join('')}</div>`;
 };
 // --- the stylesheet: tokens, the grid, type, the player and fact rows
 export const BASE_STYLE = `
@@ -108,9 +215,10 @@ export const BASE_STYLE = `
   --foreground: oklch(0.205 0 0);
   --muted: oklch(0.922 0 0);
   --muted-foreground: oklch(0.47 0 0);
-  --held: oklch(0.55 0.13 150);
-  --reached: oklch(0.64 0.14 70);
-  --missed: oklch(0.56 0.19 27);
+  /* Text-safe on the background: at least 4.5:1 */
+  --held: oklch(0.5 0.13 150);
+  --reached: oklch(0.52 0.12 65);
+  --missed: oklch(0.5 0.19 27);
   --font-sans: "Switzer", ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Helvetica Neue", Arial, sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --wrap: 85rem;
@@ -132,8 +240,8 @@ export const BASE_STYLE = `
 *, *::before, *::after { box-sizing: border-box; }
 html { -webkit-text-size-adjust: 100%; }
 body { margin: 0; background: var(--background); color: var(--foreground); font: 400 1rem/1.5 var(--font-sans); -webkit-font-smoothing: antialiased; }
-h1, h2, h3, p, dl, dd, ul, figure { margin: 0; }
-ul { padding: 0; list-style: none; }
+h1, h2, h3, p, dl, dd, ul, ol, figure { margin: 0; }
+ul, ol { padding: 0; list-style: none; }
 a { color: inherit; text-decoration: none; }
 a:hover { color: var(--muted-foreground); }
 button { font: inherit; color: inherit; background: none; border: 0; padding: 0; margin: 0; cursor: pointer; text-align: inherit; }
@@ -221,10 +329,27 @@ a.shot:hover img { opacity: 0.85; }
 .kv { color: var(--muted-foreground); margin-right: 0.375rem; }
 .address { color: var(--muted-foreground); font-family: var(--font-mono); font-size: 0.8125rem; overflow-wrap: anywhere; }
 
+/* The top bar: the page's name and its in-page links */
+nav.top { position: sticky; top: 0; z-index: 5; background: var(--background); }
+nav.top .wrapper { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem; padding-block: 0.75rem; font-size: 0.75rem; }
+nav.top .links { display: flex; gap: 1rem; color: var(--muted-foreground); }
+
 /* Footer */
 footer .wrapper { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 0.5rem 1rem; padding-block: 2rem; border-top: 1px solid var(--muted); font-size: 0.75rem; line-height: 1rem; color: var(--muted-foreground); }
 footer span { overflow-wrap: anywhere; }
 
+/* Print: the story and the shots on paper, no player */
+@media print {
+  :root { --background: #fff; --foreground: #000; --muted: #ccc; --muted-foreground: #444; color-scheme: light; }
+  video, .screen, .screen-note, .timeline-scroll, .player-bar, .full-size, nav.top, .needs-js { display: none !important; }
+  .strip { flex-wrap: wrap; overflow: visible; }
+  .shot { flex: 0 0 calc((100% - 3 * var(--gap)) / 4); break-inside: avoid; }
+  .player .shot img { opacity: 1; }
+  li, figure, article, .fact { break-inside: avoid; }
+  h1, h2, h3, .block-head { break-after: avoid; }
+  a { text-decoration: underline; }
+}
+
 @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition: none !important; scroll-behavior: auto !important; } }
 `;
 /**
@@ -244,6 +369,9 @@ export const PLAYER_SCRIPT = `<script>
     const ticks = [...panel.querySelectorAll('.tick')];
     const shots = [...panel.querySelectorAll('.strip .shot')];
     const played = panel.querySelector('.played');
+    // A run page's story list: one entry per shot, marked with the shot it tells (outside the strip).
+    const entries = [...panel.querySelectorAll('li[data-shot]')];
+    const screen = panel.querySelector('.screen');
     const clockText = panel.querySelector('.clock');
     let current = -1;
     const reveal = (shot) => {
@@ -255,6 +383,7 @@ export const PLAYER_SCRIPT = `<script>
       if (index === current) return;
       current = index;
       for (const list of [ticks, shots]) list.forEach((el, n) => (n === index ? el.setAttribute('aria-current', 'step') : el.removeAttribute('aria-current')));
+      entries.forEach((el) => (Number(el.dataset.shot) === index ? el.setAttribute('aria-current', 'step') : el.removeAttribute('aria-current')));
       reveal(shots[index]);
       const tick = ticks[index];
       if (tick && timeline && timeline.scrollWidth > timeline.clientWidth) {
@@ -279,17 +408,34 @@ export const PLAYER_SCRIPT = `<script>
         if (clockText) clockText.textContent = clock(Number(shot.dataset.at));
       }
     };
-    // A reader's seek: plays from there, and the address names the step so it can be shared (#<view>-r<run>-s<step>).
+    // A reader's seek: plays from there, and the address names the step so it can be shared (#<view>-r<run>-s<step>
+    // in a report, #s<step> on a run page).
     const choose = (index) => {
       seek(index, true);
       const view = panel.closest('.job-view');
       if (view && panel.dataset.run) history.replaceState(null, '', '#' + view.id + '-r' + panel.dataset.run + '-s' + (index + 1));
+      else if (panel.hasAttribute('data-step-links')) history.replaceState(null, '', '#s' + (index + 1));
     };
     ticks.forEach((tick) => tick.addEventListener('click', () => choose(Number(tick.dataset.index))));
     // A click anywhere on a card seeks, except on its full-size link.
     shots.forEach((shot, n) => shot.addEventListener('click', (event) => { if (!event.target.closest('a')) choose(n); }));
+    // A story entry's time: play from there, with the video in view.
+    panel.querySelectorAll('a.at[data-seek]').forEach((link) => link.addEventListener('click', (event) => {
+      event.preventDefault();
+      choose(Number(link.dataset.seek));
+      if (screen && screen.getBoundingClientRect().top < 0) screen.scrollIntoView({ block: 'start', behavior: reduceMotion ? 'auto' : 'smooth' });
+    }));
     // A link to a step (the router): go there without playing.
     panel.addEventListener('seek-step', (event) => seek(event.detail.index, false));
+    // A run page opened at #s<step> (a shared link): that step, without playing.
+    if (panel.hasAttribute('data-step-links')) {
+      const open = () => {
+        const step = /^s(\\d+)$/.exec(location.hash.slice(1));
+        if (step && shots[Number(step[1]) - 1]) seek(Number(step[1]) - 1, false);
+      };
+      addEventListener('hashchange', open);
+      open();
+    }
     if (!video) return;
     const place = () => {
       if (!video.duration || !isFinite(video.duration)) return;