jevway 0.0.0-stage → 0.1.2

package/dist/task/recording-page.js

@@ -0,0 +1,310 @@
+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';
+// --- words and numbers a reader compares
+export const statusWord = (status) => status.replaceAll('_', ' ');
+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');
+export const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+export const thousands = (n) => `${(n / 1000).toFixed(1)}k`;
+// Two significant digits: a run costs fractions of a cent.
+export const dollars = (usd) => (usd === 0 ? '$0' : usd < 1 ? `$${usd.toPrecision(2)}` : `$${usd.toFixed(2)}`);
+export const pathOf = (url) => {
+    try {
+        const { pathname, search } = new URL(url);
+        return pathname + search;
+    }
+    catch {
+        return 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();
+/** 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>`;
+/**
+ * The video frame's opening tag, shaped like the recording: its own aspect, a portrait (phone) one capped in height and
+ * centred so it never fills a whole screen or sits in a wide empty band. Unknown (an old recording): the video takes
+ * its own size.
+ *
+ * @example
+ * screenFrame({ width: 393, height: 852 }) // '<div class="screen portrait" style="aspect-ratio:393 / 852">'
+ */
+export const screenFrame = (viewport) => {
+    if (!viewport)
+        return '<div class="screen intrinsic">';
+    return `<div class="screen${viewport.height > viewport.width ? ' portrait' : ''}" style="aspect-ratio:${viewport.width} / ${viewport.height}">`;
+};
+/** A step strip's opening tag: its shots take the recording's aspect, a portrait strip fits twice as many. */
+export const stripOpening = (label, viewport) => {
+    const shape = viewport ? `${viewport.height > viewport.width ? ' portrait' : ''}" style="--shot-aspect:${viewport.width} / ${viewport.height}` : '';
+    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.
+ */
+export const shotCard = (step, i, dir, open) => {
+    const finished = isFinished(step);
+    const label = finished ? `Finished: ${statusWord(step.operation)}` : step.description;
+    const timed = 'video' in open && open.video && step.video_at !== undefined;
+    const meta = [
+        indexLabel(i),
+        ...(step.video_at !== undefined && ('href' in open || timed) ? [clock(step.video_at)] : []),
+        ...(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 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.
+    const data = timed ? ` data-at="${step.video_at}"` : ` data-src="${escape(src)}"`;
+    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>`;
+};
+/**
+ * The video (or the first shot when there is no video), its timeline with one tick per step, the `bar` (a run switcher
+ * and the clock), then the step strip, all shaped like the recording's `viewport`. Only a `featured` player fetches its poster;
+ * the others hold it in `data-poster` until shown.
+ *
+ * @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', }) => {
+    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>
+<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>`;
+    }
+    // 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;
+    // Wide enough that the two closest ticks don't overlap (about 1.75rem apart); a long one scrolls inside its own box.
+    const times = timed.map((s) => s.video_at).sort((a, b) => a - b);
+    const closest = Math.min(...times.slice(1).map((t, i) => t - times[i]).filter((gap) => gap > 0), duration);
+    const width = Math.min(200, Math.max(steps.length * 2, (1.75 * duration) / closest));
+    const ticks = steps
+        .map((s, i) => (s.video_at === undefined ? '' : `<button type="button" class="tick" aria-label="Play from step ${i + 1}" data-at="${s.video_at}" data-index="${i}" style="left:${((s.video_at / duration) * 100).toFixed(2)}%">${i + 1}</button>`))
+        .join('');
+    const posterAttribute = featured ? ` poster="${escape(poster)}"` : ` data-poster="${escape(poster)}"`;
+    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>`;
+};
+// --- the stylesheet: tokens, the grid, type, the player and fact rows
+export const BASE_STYLE = `
+:root {
+  --background: oklch(1 0 0);
+  --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);
+  --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;
+  --gap: 1rem;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0); --held: oklch(0.72 0.14 150); --reached: oklch(0.8 0.14 80);
+    --missed: oklch(0.7 0.17 27); color-scheme: dark;
+  }
+}
+:root[data-theme="dark"] {
+  --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0); --held: oklch(0.72 0.14 150); --reached: oklch(0.8 0.14 80);
+  --missed: oklch(0.7 0.17 27); color-scheme: dark;
+}
+*, *::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; }
+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; }
+img, video { display: block; max-width: 100%; }
+code { font-family: var(--font-mono); font-size: 0.8125rem; }
+:focus-visible { outline: 2px solid var(--foreground); outline-offset: 3px; border-radius: 0.25rem; }
+[hidden] { display: none !important; }
+
+/* Frame and the one grid */
+.wrapper { max-width: var(--wrap); margin-inline: auto; padding-left: max(1rem, env(safe-area-inset-left)); padding-right: max(1rem, env(safe-area-inset-right)); }
+.grid4 { display: grid; grid-template-columns: minmax(0, 1fr); gap: 0.5rem var(--gap); }
+.grid4 > * { min-width: 0; }
+@media (min-width: 64rem) {
+  .wrapper { padding-left: max(2rem, env(safe-area-inset-left)); padding-right: max(2rem, env(safe-area-inset-right)); }
+  .grid4 { grid-template-columns: repeat(4, minmax(0, 1fr)); align-items: baseline; }
+  .c1 { grid-column: 1; } .c2 { grid-column: 2; } .c3 { grid-column: 3; } .c4 { grid-column: 4; }
+  .c2s2 { grid-column: 2 / span 2; } .c3s2 { grid-column: 3 / span 2; } .c2s3 { grid-column: 2 / span 3; } .c1s3 { grid-column: 1 / span 3; }
+  .end { justify-self: end; text-align: right; }
+}
+
+/* Type: the theme's low end, one display size */
+.meta { font-size: 0.75rem; line-height: 1rem; color: var(--muted-foreground); text-transform: uppercase; letter-spacing: 0.02em; }
+.small { font-size: 0.875rem; line-height: 1.375rem; color: var(--muted-foreground); overflow-wrap: anywhere; }
+.job-title { font-size: clamp(1.75rem, 1.3rem + 1.6vw, 2.5rem); font-weight: 500; line-height: 1.15; letter-spacing: -0.025em; text-wrap: balance; }
+.section-title { font-size: clamp(1.125rem, 1rem + 0.6vw, 1.5rem); font-weight: 500; line-height: 1.375; letter-spacing: -0.02em; }
+.num, .figure, .clock { font-variant-numeric: tabular-nums; }
+.held { color: var(--held); } .reached { color: var(--reached); } .missed { color: var(--missed); } .unrun { color: var(--muted-foreground); }
+.marks { letter-spacing: 0.15em; text-transform: none; }
+.textlinks { display: flex; flex-wrap: wrap; gap: 0.25rem 1.25rem; font-size: 0.75rem; line-height: 1rem; color: var(--muted-foreground); }
+.textlinks button:hover, .textlinks [aria-pressed="true"] { color: var(--foreground); }
+.textlinks [aria-pressed="true"] { text-decoration: underline; text-underline-offset: 4px; }
+
+/* Step strip: real shots, one per grid column on wide screens */
+.strip { position: relative; display: flex; gap: var(--gap); overflow-x: auto; overscroll-behavior-x: contain; scroll-snap-type: x proximity; padding-bottom: 0.75rem; scrollbar-width: thin; }
+.shot { flex: 0 0 72%; display: flex; flex-direction: column; gap: 0.625rem; scroll-snap-align: start; min-width: 0; color: var(--foreground); }
+@media (min-width: 40rem) { .shot { flex-basis: calc((100% - 2 * var(--gap)) / 3); } }
+@media (min-width: 64rem) { .shot { flex-basis: calc((100% - 3 * var(--gap)) / 4); } }
+.strip.portrait .shot { flex-basis: calc((100% - var(--gap)) / 2.6); }
+@media (min-width: 40rem) { .strip.portrait .shot { flex-basis: calc((100% - 4 * var(--gap)) / 5); } }
+@media (min-width: 64rem) { .strip.portrait .shot { flex-basis: calc((100% - 7 * var(--gap)) / 8); } }
+.shot img { width: 100%; height: auto; aspect-ratio: var(--shot-aspect, 1120 / 780); object-fit: cover; object-position: top; border-radius: 0.75rem; background: var(--muted); transition: opacity 160ms ease; }
+.caption { display: flex; flex-direction: column; gap: 0.125rem; min-width: 0; }
+.caption .meta, .caption .where { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.meta-line { display: flex; align-items: baseline; justify-content: space-between; gap: 0.75rem; min-width: 0; }
+.full-size { flex: none; font-size: 0.75rem; line-height: 1rem; color: var(--muted-foreground); }
+.full-size:hover { color: var(--foreground); }
+.seek { display: block; width: 100%; border-radius: 0.75rem; }
+.player .shot { cursor: pointer; }
+.caption .where { font-size: 0.75rem; line-height: 1rem; color: var(--muted-foreground); }
+.what { font-size: 0.875rem; line-height: 1.25rem; height: 2.5rem; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
+.shot.finished .what { color: var(--muted-foreground); }
+a.shot:hover img { opacity: 0.85; }
+.player .shot img { opacity: 0.55; }
+.player .shot[aria-current="step"] img, .player .shot:hover img { opacity: 1; }
+.player .shot[aria-current="step"] .meta { color: var(--foreground); }
+
+/* A view: its head, the player, the facts */
+.job-head { padding-block: 2rem 0; }
+.job-head .story { margin-top: 0.75rem; }
+.back { display: inline-flex; align-items: center; gap: 0.375rem; color: var(--foreground); }
+.screen { margin-top: 2rem; width: 100%; aspect-ratio: 16 / 10; border-radius: 2rem; overflow: hidden; background: var(--muted); }
+.screen video, .screen img { width: 100%; height: 100%; object-fit: contain; background: var(--muted); }
+/* A phone recording: as wide as its own aspect needs at a capped height, centred in the grid */
+.screen.portrait { width: auto; max-width: 100%; height: min(72svh, 48rem); margin-inline: auto; }
+.screen.intrinsic { aspect-ratio: auto; width: fit-content; max-width: 100%; margin-inline: auto; }
+.screen.intrinsic video, .screen.intrinsic img { width: auto; height: auto; max-height: min(72svh, 48rem); }
+.screen.quiet { aspect-ratio: auto; max-height: none; display: grid; align-content: center; gap: 0.5rem; min-height: 14rem; padding: 2rem; }
+.screen.quiet p { max-width: 40rem; }
+.screen-note { margin-top: 0.75rem; }
+.timeline-scroll { overflow-x: auto; margin-top: 1rem; scrollbar-width: none; }
+.timeline { position: relative; height: 1.75rem; }
+.timeline .track, .timeline .played { position: absolute; left: 0; top: 50%; height: 1px; }
+.timeline .track { right: 0; background: var(--muted); }
+.timeline .played { width: 0; background: var(--foreground); }
+.timeline .ticks { position: absolute; inset: 0 0.875rem; }
+.tick { position: absolute; top: 50%; transform: translate(-50%, -50%); min-width: 1.5rem; padding: 0.25rem 0.3rem; border-radius: 99px; border: 1px solid var(--muted); background: var(--background); color: var(--muted-foreground); font-size: 0.625rem; line-height: 1; text-align: center; font-variant-numeric: tabular-nums; }
+.tick:hover { color: var(--foreground); border-color: var(--foreground); }
+.tick[aria-current="step"] { color: var(--background); background: var(--foreground); border-color: var(--foreground); }
+.player-bar { margin-top: 0.75rem; }
+.player .strip { margin-top: 2rem; }
+.run-head { margin-top: 4rem; margin-bottom: 2rem; }
+.fact { border-top: 1px solid var(--muted); padding-block: 1.25rem; }
+.fact dt { font-size: 0.75rem; line-height: 1.375rem; color: var(--muted-foreground); text-transform: uppercase; letter-spacing: 0.02em; }
+.fact dd, .fact p { font-size: 0.9375rem; line-height: 1.5rem; overflow-wrap: anywhere; }
+.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; }
+
+/* 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; }
+
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition: none !important; scroll-behavior: auto !important; } }
+`;
+/**
+ * Keeps each player (`.run`) on one step: its video, its timeline ticks and its step shots. Clicking a tick or a shot
+ * seeks (and plays, muted); playing marks the current step's tick and shot and scrolls the strip, never the page.
+ * Without a video, a shot shows in the frame. A `seek-step` event (`detail.index`) goes to a step without playing.
+ */
+export const PLAYER_SCRIPT = `<script>
+(() => {
+  const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const clock = (s) => Math.floor(s / 60) + ':' + (s % 60).toFixed(1).padStart(4, '0');
+  const wire = (panel) => {
+    const video = panel.querySelector('video');
+    const frame = panel.querySelector('.screen img[data-frame]');
+    const strip = panel.querySelector('.strip');
+    const timeline = panel.querySelector('.timeline-scroll');
+    const ticks = [...panel.querySelectorAll('.tick')];
+    const shots = [...panel.querySelectorAll('.strip .shot')];
+    const played = panel.querySelector('.played');
+    const clockText = panel.querySelector('.clock');
+    let current = -1;
+    const reveal = (shot) => {
+      if (!shot || !strip) return;
+      const left = shot.offsetLeft - (strip.clientWidth - shot.offsetWidth) / 2;
+      strip.scrollTo({ left: Math.max(0, left), behavior: reduceMotion ? 'auto' : 'smooth' });
+    };
+    const mark = (index) => {
+      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')));
+      reveal(shots[index]);
+      const tick = ticks[index];
+      if (tick && timeline && timeline.scrollWidth > timeline.clientWidth) {
+        timeline.scrollTo({ left: Math.max(0, tick.offsetLeft - timeline.clientWidth / 2), behavior: reduceMotion ? 'auto' : 'smooth' });
+      }
+    };
+    const stepAt = (time) => {
+      let index = 0;
+      shots.forEach((shot, n) => { if (shot.dataset.at !== undefined && time + 0.05 >= Number(shot.dataset.at)) index = n; });
+      return index;
+    };
+    const seek = (index, play) => {
+      mark(index);
+      const shot = shots[index];
+      if (frame && shot && shot.dataset.src) frame.src = shot.dataset.src;
+      if (!video || !shot || shot.dataset.at === undefined) return;
+      video.currentTime = Number(shot.dataset.at);
+      if (play) video.play().catch(() => {});
+      // A paused video shows its poster until it has data: show the linked step's own shot meanwhile.
+      else {
+        if (video.readyState < 2) video.poster = shot.querySelector('img').getAttribute('src');
+        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>).
+    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));
+    };
+    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 link to a step (the router): go there without playing.
+    panel.addEventListener('seek-step', (event) => seek(event.detail.index, false));
+    if (!video) return;
+    const place = () => {
+      if (!video.duration || !isFinite(video.duration)) return;
+      for (const tick of ticks) tick.style.left = Math.min(100, (Number(tick.dataset.at) / video.duration) * 100) + '%';
+    };
+    video.addEventListener('loadedmetadata', place);
+    const follow = () => {
+      const time = video.currentTime;
+      mark(stepAt(time));
+      if (clockText) clockText.textContent = clock(time) + (video.duration && isFinite(video.duration) ? ' / ' + clock(video.duration) : '');
+      if (played && video.duration) played.style.width = Math.min(100, (time / video.duration) * 100) + '%';
+    };
+    video.addEventListener('timeupdate', follow);
+    video.addEventListener('seeked', follow);
+  };
+  document.querySelectorAll('.run').forEach(wire);
+})();
+</script>`;

package/dist/task/recording.js

@@ -0,0 +1,232 @@
+import { execFile } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { BASE_STYLE, clock, dollars, escapeHtml, fact, FONT_LINK, playerMarkup, plural, PLAYER_SCRIPT, seconds, statusWord, thousands, } from './recording-page.js';
+const VIDEO = 'run.mp4';
+// The video shows what changed, not how long anyone waited: no frame holds longer than this.
+const LONGEST_FRAME_S = 1.5;
+const SHORTEST_FRAME_S = 1 / 30;
+/**
+ * How long each screencast frame stays on screen: until the next one, clamped so idle stretches
+ * (a slow request, the agent between calls) don't freeze the video. The last frame holds the longest.
+ *
+ * @example
+ * frameDurations([10, 10.2, 19]) // [0.2, 1.5, 1.5]
+ */
+export const frameDurations = (times) => times.map((at, i) => i === times.length - 1 ? LONGEST_FRAME_S : Math.min(LONGEST_FRAME_S, Math.max(SHORTEST_FRAME_S, times[i + 1] - at)));
+/** Seconds into the encoded video at which the wall-clock moment `at` appears. */
+export const videoOffset = (times, durations, at) => times.reduce((offset, time, i) => (time < at ? offset + durations[i] : offset), 0);
+// 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;
+};
+/**
+ * A step as one plain sentence for people reading a recording.
+ *
+ * @example
+ * describeStep({ operation: 'TYPE_TEXT', element: 'Search traces', valueKey: 'search_query' })
+ * // 'Type the "search_query" value into "Search traces"'
+ */
+export const describeStep = ({ operation, element = '', valueKey, option }) => {
+    const target = `"${shorten(element)}"`;
+    switch (operation) {
+        case 'CLICK':
+            return `Click ${target}`;
+        case 'CLICK_AT':
+            return `Click the control at ${target} by its on-screen position`;
+        case 'TYPE_TEXT':
+            return `Type the "${valueKey}" value into ${target}`;
+        case 'SELECT':
+            return option ? `Choose "${option}" in ${target}` : `Choose an option in ${target}`;
+        case 'PRESS_ENTER':
+            return `Press Enter in ${target} to submit it`;
+        case 'PRESS_ESCAPE':
+            return 'Press Escape to close the open menu or popup';
+        case 'SCROLL_DOWN':
+            return 'Scroll down to reveal more of the page';
+        case 'SCROLL_UP':
+            return 'Scroll back up';
+        case 'WAIT':
+            return 'Wait for the page to finish updating';
+        default:
+            return `${operation} ${target}`;
+    }
+};
+/**
+ * A human-facing record of a run: a screencast video (`run.mp4`, needs ffmpeg), a sharp screenshot before every
+ * executed action with its target outlined and a one-sentence description, the final page, `summary.json`
+ * and an `index.html` viewer. Separate from what the model sees.
+ *
+ * @example
+ * const task = new BrowserTask(tab, ask, { goal, recordDir: 'runs/langfuse' });
+ * await task.run(); // runs/langfuse/run.mp4, 01.jpg … index.html
+ */
+export class Recording {
+    steps = [];
+    summaries = [];
+    #dir;
+    #frames = [];
+    /** The page size the screencast reports (CSS pixels): the run page and the reports shape the video's frame by it. */
+    #viewport;
+    #stopListening;
+    /** Takes the caller's secret values out of what is written (labels and addresses can echo them); screenshots are pixels and show what the page shows. */
+    #scrub;
+    constructor(dir, scrub = (text) => text) {
+        this.#dir = dir;
+        this.#scrub = scrub;
+        mkdirSync(dir, { recursive: true });
+    }
+    /** Starts the screencast; each frame is acknowledged at once, or Chrome stops sending them. */
+    async start(tab) {
+        if (this.#stopListening)
+            return;
+        this.#stopListening = tab.onEvent((method, params) => {
+            if (method !== 'Page.screencastFrame')
+                return;
+            this.#frames.push({ jpeg: params.data, at: params.metadata.timestamp });
+            const { deviceWidth, deviceHeight } = params.metadata;
+            if (!this.#viewport && deviceWidth > 0 && deviceHeight > 0)
+                this.#viewport = { width: Math.round(deviceWidth), height: Math.round(deviceHeight) };
+            tab.send('Page.screencastFrameAck', { sessionId: params.sessionId }).catch(() => undefined);
+        });
+        await tab.send('Page.enable');
+        await tab.send('Page.startScreencast', { format: 'jpeg', quality: 85, maxWidth: 2560, maxHeight: 1600 });
+    }
+    async step(tab, page, intent, target) {
+        const marks = target ? [{ label: intent.operation, rect: target }] : [];
+        const file = `${String(this.steps.length + 1).padStart(2, '0')}.jpg`;
+        writeFileSync(join(this.#dir, file), Buffer.from(await tab.markedScreenshot(marks, page, { sharp: true }), 'base64'));
+        this.steps.push({
+            file,
+            operation: intent.operation,
+            description: this.#scrub(describeStep(intent)),
+            ...(intent.confidence !== undefined && { confidence: intent.confidence }),
+            url: this.#scrub(page.url),
+            at: Date.now() / 1000,
+        });
+    }
+    /** The action shot just taken never ran (the page moved first); the retry takes its place. */
+    discardLast() {
+        this.steps.pop();
+    }
+    /** The action shot just taken never ran: its target couldn't be reached. Repeats of the same miss fold into one. */
+    markUnreachable() {
+        const [previous, last] = this.steps.slice(-2);
+        if (!last)
+            return;
+        if (previous?.unreachable && previous.description === last.description) {
+            previous.attempts = (previous.attempts ?? 1) + 1;
+            this.steps.pop();
+            return;
+        }
+        last.unreachable = true;
+        last.attempts = 1;
+    }
+    // A session can run several times (missing value, confirmation); each run ends with its own final shot,
+    // and the video is re-encoded to cover every run so far.
+    async finish(tab, summary) {
+        const page = await tab.observe();
+        await this.step(tab, page, { operation: summary.status });
+        this.steps.at(-1).description = `Finished: ${summary.status}. ${summary.reason}`;
+        this.summaries.push(summary);
+        await tab.send('Page.stopScreencast').catch(() => undefined);
+        this.#stopListening?.();
+        this.#stopListening = undefined;
+        const video = (await this.#encode()) ?? null;
+        const viewport = this.#viewport;
+        writeFileSync(join(this.#dir, 'summary.json'), JSON.stringify({ summaries: this.summaries, video, steps: this.steps, ...(viewport && { viewport }) }, null, 1));
+        writeFileSync(join(this.#dir, 'index.html'), renderSteps(this.steps, this.summaries, video, viewport));
+    }
+    // Frames → H.264 through ffmpeg's concat list, each frame held for its duration. Without ffmpeg: no video.
+    async #encode() {
+        if (!this.#frames.length)
+            return undefined;
+        const framesDir = join(this.#dir, '.frames');
+        mkdirSync(framesDir, { recursive: true });
+        try {
+            const times = this.#frames.map((f) => f.at);
+            const durations = frameDurations(times);
+            const list = this.#frames.map((frame, i) => {
+                const file = join(framesDir, `${String(i).padStart(5, '0')}.jpg`);
+                writeFileSync(file, Buffer.from(frame.jpeg, 'base64'));
+                return `file '${file}'\nduration ${durations[i].toFixed(3)}`;
+            });
+            // The concat demuxer ignores the last entry's duration unless that file is listed once more.
+            writeFileSync(join(framesDir, 'list.txt'), `${list.join('\n')}\n${list.at(-1).split('\n')[0]}\n`);
+            await promisify(execFile)('ffmpeg', [
+                '-y', '-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', join(framesDir, 'list.txt'),
+                '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p', '-r', '30',
+                '-c:v', 'libx264', '-crf', '20', '-movflags', '+faststart', join(this.#dir, VIDEO),
+            ]);
+            for (const step of this.steps)
+                step.video_at = Number(videoOffset(times, durations, step.at).toFixed(2));
+            return VIDEO;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            rmSync(framesDir, { recursive: true, force: true });
+        }
+    }
+}
+export { escapeHtml };
+// What a run's calls cost, summed: requests, input tokens, time, and the estimate unless a call has none.
+const costLine = (summaries) => {
+    const sum = (pick) => summaries.reduce((total, s) => total + pick(s), 0);
+    const cost = summaries.reduce((total, s) => (total === null || s.jev.est_cost_usd == null ? null : total + s.jev.est_cost_usd), 0);
+    return `${plural(sum((s) => s.jev.requests), 'Jev request')} · ${thousands(sum((s) => s.jev.input_tokens))} input tokens · ${seconds(sum((s) => s.elapsed_ms))} · ${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}`;
+};
+// epoch seconds → "2026-11-01 18:39 UTC"
+const recordedAt = (at) => `${new Date(at * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+/**
+ * A run's own page (`index.html` in its record folder), in the reports' layout: how it ended, then the screencast with
+ * its steps on a timeline and a strip kept in sync, then the facts. One self-contained file next to its shots and
+ * video; it reads without JS (the script only syncs the player).
+ *
+ * @example
+ * writeFileSync('runs/a/index.html', renderSteps(steps, summaries, 'run.mp4', { width: 1120, height: 780 }));
+ */
+export const renderSteps = (steps, summaries, video = null, viewport) => {
+    const last = summaries.at(-1);
+    const ending = last ? `Finished: ${statusWord(last.status)}` : 'jevway run';
+    const actions = summaries.reduce((total, s) => total + s.steps.length, 0);
+    const bar = `<div class="player-bar grid4"><p class="meta c1s3">${plural(steps.length, 'step')}${video ? ' · pick one to play from there' : ''}</p><span class="meta clock c4 end">${video ? clock(0) : ''}</span></div>`;
+    const player = steps.length
+        ? playerMarkup({ dir: '', video, steps, label: 'this run', featured: true, viewport, bar, preload: 'metadata' })
+        : '<div class="screen quiet"><p class="small">No step was recorded.</p></div>';
+    const facts = [
+        ...(summaries.length ? [fact('Calls', `${escapeHtml(summaries.map((s) => statusWord(s.status)).join(' → '))} · ${plural(actions, 'action')}`)] : []),
+        ...(last ? [fact('Final reason', escapeHtml(last.reason)), fact('Final address', `<span class="address">${escapeHtml(last.url)}</span>`), fact('Page title', escapeHtml(last.title))] : []),
+        ...(summaries.length ? [fact('Cost', `<span class="num">${costLine(summaries)}</span>`)] : []),
+        fact('Files', `<a href="summary.json">summary.json</a>${video ? ` · <a href="${escapeHtml(video)}">${escapeHtml(video)}</a>` : ''}`),
+    ];
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${escapeHtml(`jevway run: ${last ? statusWord(last.status) : 'recorded'}`)}</title>
+<link rel="preconnect" href="https://api.fontshare.com" crossorigin>
+<link rel="stylesheet" href="${FONT_LINK}">
+<style>${BASE_STYLE}
+.run-page { padding-bottom: 4rem; }
+.run-page .facts { margin-top: 4rem; }
+</style>
+</head><body>
+<main class="wrapper run-page">
+<header class="job-head grid4">
+<p class="meta">jevway run<br>${steps.length ? recordedAt(steps[0].at) : ''}</p>
+<h1 class="job-title c2s2">${escapeHtml(ending)}</h1>
+<p class="meta c4 end">${plural(summaries.length, 'call')} · ${plural(actions, 'action')}</p>
+${last ? `<p class="small story c2s2">${escapeHtml(last.reason)}</p>` : ''}
+</header>
+<div class="run player current">
+${player}
+</div>
+<dl class="facts">${facts.join('\n')}</dl>
+</main>
+<footer><div class="wrapper"><span>Recorded by jevway for people to read; the model never sees these shots.</span><span>${plural(steps.length, 'step')}${video ? ` · ${escapeHtml(video)}` : ' · no video (needs ffmpeg)'}</span></div></footer>
+${PLAYER_SCRIPT}
+</body></html>
+`;
+};

package/dist/task/run-limit.js

@@ -0,0 +1,66 @@
+/** Why a call must end now: the caller cancelled it, or its time budget passed. */
+export class RunStopped extends Error {
+    status;
+    reason;
+    constructor(status, reason) {
+        super(reason);
+        this.status = status;
+        this.reason = reason;
+    }
+}
+/**
+ * One call's stop signal: it aborts when the caller's signal does (`blocked`, "Cancelled by the caller") or when
+ * `maxSeconds` pass (`step_budget`). Waits and model requests take `signal`; inputs never do, so an input in flight
+ * always finishes and the loop stops at its next check. `dispose()` clears the timer when the call ends.
+ *
+ * @example
+ * const limit = startRunLimit({ signal: extra.signal, maxSeconds: 300, actions: () => executed });
+ * await limit.pause(300); // returns early on a stop
+ * const halt = limit.stopped(); // RunStopped | undefined
+ */
+export const startRunLimit = ({ signal, maxSeconds, actions }) => {
+    const controller = new AbortController();
+    const stopWith = (status, reason) => {
+        if (!controller.signal.aborted)
+            controller.abort(new RunStopped(status, reason));
+    };
+    const cancel = () => stopWith('blocked', 'Cancelled by the caller');
+    const timer = setTimeout(() => stopWith('step_budget', `Reached the time budget of ${maxSeconds} s (max_seconds) after ${actions()} actions without finishing`), maxSeconds * 1000);
+    // Unref'd: a CLI run must not stay alive just for its budget timer.
+    timer.unref?.();
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener('abort', cancel, { once: true });
+    const stopped = () => (controller.signal.aborted ? controller.signal.reason : undefined);
+    return {
+        signal: controller.signal,
+        stopped,
+        /** Sleeps `ms`, or less when the run is stopped meanwhile; never throws. */
+        pause: (ms) => new Promise((resolve) => {
+            if (controller.signal.aborted)
+                return resolve();
+            const done = () => {
+                clearTimeout(wait);
+                controller.signal.removeEventListener('abort', done);
+                resolve();
+            };
+            const wait = setTimeout(done, ms);
+            controller.signal.addEventListener('abort', done, { once: true });
+        }),
+        /** Settles like `work`, or rejects with the stop as soon as the run is stopped, whether or not `work` heeds the signal. */
+        within: (work) => new Promise((resolve, reject) => {
+            // `work` is always handled, even when the stop wins: a request rejected after the stop must not go unhandled.
+            const onStop = () => reject(stopped());
+            work.then(resolve, reject).finally(() => controller.signal.removeEventListener('abort', onStop));
+            if (controller.signal.aborted)
+                onStop();
+            else
+                controller.signal.addEventListener('abort', onStop, { once: true });
+        }),
+        dispose: () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', cancel);
+        },
+    };
+};