@mineo71/showtime 0.2.1 → 0.4.0

package/src/render/remotion/Intro.tsx

@@ -2,6 +2,7 @@ import type { FC } from 'react';
 import { AbsoluteFill, Easing, interpolate } from 'remotion';
 import { introFrames } from '../../timeline/frames';
 import type { Timeline } from '../../timeline/types';
+import { Logo } from './Logo';
 
 export const Intro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t, frame }) => {
   const total = introFrames(t);
@@ -19,7 +20,8 @@ export const Intro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t,
         textAlign: 'center',
       }}
     >
-      <div style={{ opacity: Math.min(enter, exit), transform: `scale(${0.94 + 0.06 * enter})` }}>
+      <div style={{ maxWidth: '86%', opacity: Math.min(enter, exit), transform: `scale(${0.94 + 0.06 * enter})` }}>
+        <Logo src={t.logo} />
         <div style={{ fontSize: 88, fontWeight: 800, letterSpacing: -1.5 }}>{t.intro?.title}</div>
         {t.intro?.subtitle ? <div style={{ marginTop: 18, fontSize: 36, opacity: 0.75 }}>{t.intro.subtitle}</div> : null}
         <div style={{ margin: '28px auto 0', width: 72, height: 6, borderRadius: 3, background: t.style.accent }} />

package/src/render/remotion/Logo.tsx

@@ -0,0 +1,6 @@
+import type { FC } from 'react';
+import { Img } from 'remotion';
+
+/** The brand logo on the intro and outro cards; nothing when there is none. */
+export const Logo: FC<{ src: string | null; height?: number }> = ({ src, height = 120 }) =>
+  src ? <Img src={src} style={{ height, width: 'auto', display: 'block', margin: '0 auto 36px' }} /> : null;

package/src/render/remotion/Outro.tsx

@@ -0,0 +1,38 @@
+import type { FC } from 'react';
+import { AbsoluteFill, Easing, interpolate } from 'remotion';
+import type { Timeline } from '../../timeline/types';
+import { Logo } from './Logo';
+
+/** Closing card: logo, title, subtitle and the URL in an accent pill. `frame` counts from the outro start. */
+export const Outro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t, frame }) => {
+  const enter = interpolate(frame, [0, 18], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp', easing: Easing.out(Easing.cubic) });
+  const o = t.outro;
+  return (
+    <AbsoluteFill
+      style={{ background: t.style.background, fontFamily: t.style.font, alignItems: 'center', justifyContent: 'center', color: '#fff', textAlign: 'center' }}
+    >
+      <div style={{ maxWidth: '86%', opacity: enter, transform: `translateY(${(1 - enter) * 24}px)` }}>
+        <Logo src={t.logo} />
+        <div style={{ fontSize: 80, fontWeight: 800, letterSpacing: -1.5 }}>{o?.title}</div>
+        {o?.subtitle ? <div style={{ marginTop: 18, fontSize: 34, opacity: 0.75 }}>{o.subtitle}</div> : null}
+        {o?.url ? (
+          <div
+            style={{
+              display: 'inline-block',
+              marginTop: 40,
+              padding: '14px 34px',
+              borderRadius: 999,
+              border: `2px solid ${t.style.accent}`,
+              background: 'rgba(255, 255, 255, 0.08)',
+              fontSize: 30,
+              fontWeight: 600,
+              letterSpacing: 0.2,
+            }}
+          >
+            {o.url}
+          </div>
+        ) : null}
+      </div>
+    </AbsoluteFill>
+  );
+};

package/src/render/remotion/Overlays.tsx

@@ -1,5 +1,6 @@
-import type { FC } from 'react';
+import type { CSSProperties, FC } from 'react';
 import { ripplesAt } from '../../timeline/cursor';
+import { CAPTION_FADE_MS, SPOTLIGHT_FADE_MS } from '../../timeline/fades';
 import { clamp, easeOutCubic } from '../../timeline/math';
 import type { Timeline } from '../../timeline/types';
 
@@ -25,7 +26,7 @@ export const Spotlights: FC<LayerProps> = ({ timeline, srcMs }) => (
             boxShadow: '0 0 0 9999px rgba(2, 6, 23, 0.55)',
             outline: `3px solid ${timeline.style.accent}`,
             outlineOffset: 2,
-            opacity: envelope(srcMs, s.startMs, s.endMs, 250),
+            opacity: envelope(srcMs, s.startMs, s.endMs, SPOTLIGHT_FADE_MS),
           }}
         />
       ))}
@@ -55,22 +56,19 @@ export const Ripples: FC<LayerProps> = ({ timeline, srcMs }) => (
   </>
 );
 
-export const Captions: FC<LayerProps> = ({ timeline, srcMs }) => {
+/** Where an overlay row sits: an inset from the top or bottom, or a band (top + height / top + bottom). */
+type Place = Pick<CSSProperties, 'top' | 'bottom' | 'height' | 'alignItems'>;
+
+const row = (place: Place): CSSProperties => ({ position: 'absolute', left: 0, right: 0, display: 'flex', justifyContent: 'center', ...place });
+
+/** The active caption, placed at `top` or `bottom` by its position. */
+export const Captions: FC<LayerProps & { top: Place; bottom: Place; fontSize: number }> = ({ timeline, srcMs, top, bottom, fontSize }) => {
   const active = timeline.captions.filter((c) => srcMs >= c.startMs && srcMs <= c.endMs);
   const c = active[active.length - 1];
   if (!c) return null;
-  const o = envelope(srcMs, c.startMs, c.endMs, 220);
+  const o = envelope(srcMs, c.startMs, c.endMs, CAPTION_FADE_MS);
   return (
-    <div
-      style={{
-        position: 'absolute',
-        left: 0,
-        right: 0,
-        bottom: Math.round(timeline.output.height * 0.075),
-        display: 'flex',
-        justifyContent: 'center',
-      }}
-    >
+    <div style={row(c.position === 'top' ? top : bottom)}>
       <div
         style={{
           maxWidth: '70%',
@@ -79,13 +77,40 @@ export const Captions: FC<LayerProps> = ({ timeline, srcMs }) => {
           background: 'rgba(15, 23, 42, 0.9)',
           color: '#fff',
           fontFamily: timeline.style.font,
-          fontSize: 36,
+          fontSize,
           fontWeight: 600,
           lineHeight: 1.25,
           textAlign: 'center',
           boxShadow: '0 12px 40px rgba(0, 0, 0, 0.35)',
           opacity: o,
-          transform: `translateY(${(1 - o) * 12}px)`,
+          transform: `translateY(${(1 - o) * (c.position === 'top' ? -12 : 12)}px)`,
+        }}
+      >
+        {c.text}
+      </div>
+    </div>
+  );
+};
+
+/** Burned-in narration subtitles. `videoMs` is output time from the start of the video. */
+export const Subtitles: FC<{ timeline: Timeline; videoMs: number; place: Place; fontSize: number }> = ({ timeline, videoMs, place, fontSize }) => {
+  if (!timeline.subtitlesBurned) return null;
+  const c = timeline.subtitles.find((s) => videoMs >= s.startMs && videoMs < s.endMs);
+  if (!c) return null;
+  return (
+    <div style={row(place)}>
+      <div
+        style={{
+          maxWidth: '80%',
+          padding: '10px 24px',
+          borderRadius: 12,
+          background: 'rgba(0, 0, 0, 0.72)',
+          color: '#fff',
+          fontFamily: timeline.style.font,
+          fontSize,
+          fontWeight: 500,
+          lineHeight: 1.35,
+          textAlign: 'center',
         }}
       >
         {c.text}

package/src/render/remotion/ShowtimeVideo.tsx

@@ -1,31 +1,50 @@
 import type { FC } from 'react';
-import { AbsoluteFill, Easing, interpolate, OffthreadVideo, Sequence, staticFile, useCurrentFrame } from 'remotion';
+import { AbsoluteFill, Easing, Freeze, Html5Audio, interpolate, OffthreadVideo, Sequence, staticFile, useCurrentFrame } from 'remotion';
 import { cameraAt, cameraTransform } from '../../timeline/camera';
-import { introFrames, segmentPlan, sourceMsAtFrame } from '../../timeline/frames';
-import { BROWSER_BAR, windowLayout } from '../../timeline/layout';
+import { introFrames, segmentPlan, sourceMsAtFrame, videoEndFrame } from '../../timeline/frames';
+import { BROWSER_BAR, viewLayout } from '../../timeline/layout';
 import type { Timeline } from '../../timeline/types';
 import { BrowserBar } from './BrowserBar';
 import { Cursor } from './Cursor';
 import { Intro } from './Intro';
-import { Captions, Ripples, Spotlights } from './Overlays';
+import { Outro } from './Outro';
+import { Captions, Ripples, Spotlights, Subtitles } from './Overlays';
 
 export type ShowtimeVideoProps = { timeline: Timeline };
 
 const SHADOW = '0 30px 80px rgba(0, 0, 0, 0.45), 0 8px 24px rgba(0, 0, 0, 0.25)';
 
-export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
+/** The soundtrack plays across every frame; the picture switches between cards and the take. */
+export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => (
+  <>
+    {t.audio ? <Html5Audio src={staticFile(t.audio.src)} /> : null}
+    <Picture timeline={t} />
+  </>
+);
+
+const Picture: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
   const frame = useCurrentFrame();
   const intro = introFrames(t);
   if (frame < intro) return <Intro timeline={t} frame={frame} />;
+  const end = videoEndFrame(t);
+  if (t.outro && frame >= end) return <Outro timeline={t} frame={frame - end} />;
 
   const src = sourceMsAtFrame(t, frame) ?? 0;
-  const win = windowLayout(t.output, t.stage, t.style.padding, t.chrome ? BROWSER_BAR : 0);
+  const win = viewLayout(t.output, t.stage, t.style.padding, t.chrome ? BROWSER_BAR : 0, t.aspect);
   const cam = cameraAt(t.camera, src);
-  const k = win.width / t.stage.width;
+  const { content } = win;
+  const k = content.width / t.stage.width;
+  const H = t.output.height;
+  // 9:16 puts captions and subtitles in the bands above and below the window; the others overlay it.
+  const bands = t.aspect === '9:16';
+  const above = { top: 0, height: win.y - win.bar, alignItems: 'center' } as const;
+  const below = { top: win.y + win.height, bottom: 0, alignItems: 'center' } as const;
   // After an intro card the window rises into place instead of cutting in.
   const enter = intro
     ? interpolate(frame - intro, [0, 16], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp', easing: Easing.out(Easing.cubic) })
     : 1;
+  // Before an outro card the window and its captions fade out over the last 12 frames.
+  const leave = t.outro ? interpolate(frame, [end - 12, end], [1, 0], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' }) : 1;
 
   return (
     <AbsoluteFill style={{ background: t.style.background, fontFamily: t.style.font }}>
@@ -40,7 +59,7 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
           overflow: 'hidden',
           background: '#fff',
           boxShadow: t.style.shadow ? SHADOW : undefined,
-          opacity: enter,
+          opacity: enter * leave,
           transform: `translateY(${(1 - enter) * 40}px) scale(${0.96 + 0.04 * enter})`,
         }}
       >
@@ -51,23 +70,28 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
               position: 'absolute',
               left: 0,
               top: 0,
-              width: win.width,
-              height: win.height,
+              width: content.width,
+              height: content.height,
               transformOrigin: '0 0',
-              transform: cameraTransform(cam, win.width, win.height),
+              transform: cameraTransform(cam, win.width, win.height, content),
             }}
           >
-            {segmentPlan(t).map((p) => (
-              <Sequence key={p.fromFrame} from={p.fromFrame} durationInFrames={p.durationInFrames} layout="none">
+            {segmentPlan(t).map((p) => {
+              const video = (
                 <OffthreadVideo
                   src={staticFile(t.video.src)}
                   trimBefore={p.trimBefore}
-                  playbackRate={p.speed}
+                  playbackRate={p.speed || 1}
                   muted
-                  style={{ position: 'absolute', left: 0, top: 0, width: win.width, height: win.height }}
+                  style={{ position: 'absolute', left: 0, top: 0, width: content.width, height: content.height }}
                 />
-              </Sequence>
-            ))}
+              );
+              return (
+                <Sequence key={p.fromFrame} from={p.fromFrame} durationInFrames={p.durationInFrames} layout="none">
+                  {p.speed === 0 ? <Freeze frame={0}>{video}</Freeze> : video}
+                </Sequence>
+              );
+            })}
             <div
               style={{
                 position: 'absolute',
@@ -86,7 +110,21 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
           </div>
         </div>
       </div>
-      <Captions timeline={t} srcMs={src} />
+      <div style={{ opacity: leave }}>
+        <Captions
+          timeline={t}
+          srcMs={src}
+          top={bands ? above : { top: win.y + Math.round(H * 0.03) }}
+          bottom={bands ? below : { bottom: Math.round(H * 0.075) }}
+          fontSize={bands ? 46 : 36}
+        />
+        <Subtitles
+          timeline={t}
+          videoMs={((frame - intro) * 1000) / t.fps}
+          place={bands ? below : { bottom: Math.round(H * 0.06) }}
+          fontSize={bands ? 40 : 34}
+        />
+      </div>
     </AbsoluteFill>
   );
 };

package/src/render/render.ts

@@ -8,7 +8,7 @@ import type { Timeline } from '../timeline/types';
 const ENTRY = fileURLToPath(new URL('./remotion/index.ts', import.meta.url));
 const COMPOSITION_ID = 'ShowtimeVideo';
 
-/** Bundle the composition with the take directory as public dir, so the raw video is staticFile('raw.mp4'). */
+/** Bundle the composition with `.showtime/<name>/` as public dir: the take is staticFile('take/raw.mp4'). */
 async function prepare(timeline: Timeline, publicDir: string) {
   const serveUrl = await bundle({ entryPoint: ENTRY, publicDir, symlinkPublicDir: true });
   const inputProps = { timeline };

package/src/runner/browser.ts

@@ -1,5 +1,5 @@
-import { chromium, type Browser, type BrowserContext, type Page } from 'playwright';
-import { ScriptError, type Script } from '../script/schema';
+import { chromium, type Browser, type BrowserContext, type Page, type Request, type Route } from 'playwright';
+import { ScriptError, type Mock, type Script } from '../script/schema';
 import type { Pt } from '../timeline/types';
 import { EventLog } from './events';
 import { runStep, STEP_TIMEOUT_MS, type StepContext } from './steps';
@@ -18,8 +18,12 @@ export interface Session {
   close(): Promise<void>;
 }
 
+/** Event streams never finish; counting them would hold every step for the full settle cap. */
+const isStream = (r: Request) => r.resourceType() === 'eventsource' || (r.headers().accept ?? '').includes('text/event-stream');
+
 export function trackNetwork(page: Page): NetworkTracker {
   let inflight = 0;
+  const counted = new Set<Request>();
   let lastChange = Date.now();
   const up = () => {
     inflight++;
@@ -29,9 +33,16 @@ export function trackNetwork(page: Page): NetworkTracker {
     inflight = Math.max(0, inflight - 1);
     lastChange = Date.now();
   };
-  page.on('request', up);
-  page.on('requestfinished', down);
-  page.on('requestfailed', down);
+  page.on('request', (r) => {
+    if (isStream(r)) return;
+    counted.add(r);
+    up();
+  });
+  const done = (r: Request) => {
+    if (counted.delete(r)) down();
+  };
+  page.on('requestfinished', done);
+  page.on('requestfailed', done);
   return {
     async idle(quietMs, capMs) {
       const start = Date.now();
@@ -79,8 +90,15 @@ export async function openSession(script: Script, opts: { headed?: boolean } = {
       timezoneId: app.timezoneId,
     });
     if (app.mask.length) await context.addInitScript({ content: maskScript(app.mask) });
+    // Starts the page clock at app.clock and lets it run: frozen time would stall Date-based debounce.
+    if (app.clock) await context.clock.install({ time: app.clock });
+    // Playwright tries the most recently added route first; reversed, the first matching mock wins.
+    for (const mock of [...app.mock].reverse()) await context.route(mock.url, (route) => answer(route, mock));
     const page = await context.newPage();
     page.setDefaultTimeout(STEP_TIMEOUT_MS);
+    page.on('dialog', (dialog) => {
+      (app.dialogs === 'accept' ? dialog.accept() : dialog.dismiss()).catch(() => undefined);
+    });
     const invalid = await page.evaluate(
       (selectors) =>
         selectors.map((s) => {
@@ -106,6 +124,29 @@ export async function openSession(script: Script, opts: { headed?: boolean } = {
   }
 }
 
+/**
+ * Fulfil a request from an `app.mock` entry. Cross-origin answers echo the page's origin and allow
+ * credentials (a wildcard is refused for cookie-authenticated calls); Playwright answers preflights.
+ */
+async function answer(route: Route, mock: Mock): Promise<void> {
+  const request = route.request();
+  if (mock.method && request.method().toUpperCase() !== mock.method.toUpperCase()) return route.fallback();
+  const origin = request.headers().origin;
+  const cors: Record<string, string> = origin
+    ? { 'access-control-allow-origin': origin, 'access-control-allow-credentials': 'true', vary: 'Origin' }
+    : {};
+  if (mock.delayMs) await sleep(mock.delayMs);
+  const json = mock.json !== undefined;
+  // The page may have navigated away while we waited: a closed route is not an error.
+  await route
+    .fulfill({
+      status: mock.status,
+      headers: { ...cors, ...(json ? { 'content-type': 'application/json' } : {}), ...mock.headers },
+      body: json ? JSON.stringify(mock.json) : (mock.body ?? ''),
+    })
+    .catch(() => undefined);
+}
+
 /** Open app.url, run setup steps (fast, unlogged), park the mouse at the centre. */
 export async function prepare(session: Session, script: Script): Promise<Pt> {
   const { page } = session;
@@ -115,7 +156,7 @@ export async function prepare(session: Session, script: Script): Promise<Pt> {
     throw new Error(`Cannot open app.url ${script.app.url}: ${(err as Error).message.split('\n')[0]}`);
   }
   const centre = { x: Math.round(script.app.viewport.width / 2), y: Math.round(script.app.viewport.height / 2) };
-  const ctx: StepContext = { page, mode: 'check', log: new EventLog(), net: session.net, cursor: centre };
+  const ctx: StepContext = { page, mode: 'check', log: new EventLog(), net: session.net, cursor: centre, baseUrl: script.app.url };
   for (const [index, step] of script.setup.entries()) await runStep(ctx, step, { sceneId: 'setup', index });
   await page.mouse.move(centre.x, centre.y);
   return centre;

package/src/runner/check.ts

@@ -4,11 +4,14 @@ import { workPaths } from '../paths';
 import type { LoadedScript } from '../script/load';
 import { openSession, prepare } from './browser';
 import { EventLog } from './events';
+import { withHooks } from './hooks';
 import { describeStep, runStep, StepError, type StepContext } from './steps';
 
 export interface RunOptions {
   headed?: boolean;
   log?: (line: string) => void;
+  /** Non-fatal problems, such as a failing after hook (default: stderr). */
+  warn?: (line: string) => void;
 }
 
 export interface CheckStep {
@@ -42,11 +45,17 @@ export async function check(loaded: LoadedScript, opts: RunOptions = {}): Promis
   await rm(paths.check, { recursive: true, force: true });
   await mkdir(paths.check, { recursive: true });
 
+  return withHooks(script.hooks, loaded.dir, () => rehearse(loaded, opts), opts.warn);
+}
+
+async function rehearse(loaded: LoadedScript, opts: RunOptions): Promise<CheckReport> {
+  const { script } = loaded;
+  const paths = workPaths(loaded);
   const report: CheckReport = { ok: true, steps: [], failure: null };
   const session = await openSession(script, opts);
   try {
     const cursor = await prepare(session, script);
-    const ctx: StepContext = { page: session.page, mode: 'check', log: new EventLog(), net: session.net, cursor };
+    const ctx: StepContext = { page: session.page, mode: 'check', log: new EventLog(), net: session.net, cursor, baseUrl: script.app.url };
     let n = 0;
     for (const scene of script.scenes) {
       for (const [index, step] of scene.steps.entries()) {

package/src/runner/events.ts

@@ -6,6 +6,8 @@ export class EventLog {
   readonly moves: Move[] = [];
   readonly clicks: Click[] = [];
   readonly idle: Interval[] = [];
+  /** keystroke times of human-paced typing */
+  readonly keys: number[] = [];
 
   constructor(private readonly t0: number = Date.now()) {}
 

package/src/runner/hooks.ts

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import type { Hook } from '../script/schema';
+
+export const RUN_TIMEOUT_MS = 120_000;
+export const REQUEST_TIMEOUT_MS = 30_000;
+const TAIL_LINES = 20;
+const KEEP_CHARS = 8000;
+
+export interface HookOptions {
+  /** Folder shell hooks run in (the script's folder). */
+  cwd: string;
+  /** Prefix for errors, e.g. "hooks.before". */
+  label: string;
+  timeoutMs?: number;
+}
+
+const describeHook = (h: Hook) => ('run' in h ? h.run : `${h.request.method} ${h.request.url}`);
+
+/** The last lines of a command's output, on their own lines after the message. */
+const tail = (out: string) => {
+  const lines = out.trim().split('\n').slice(-TAIL_LINES).join('\n');
+  return lines ? `\n${lines}` : '';
+};
+
+function runCommand(command: string, cwd: string, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Own process group, so a timeout kills whatever the shell started too.
+    const child = spawn(command, { cwd, shell: true, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    let settled = false;
+    const keep = (chunk: Buffer) => {
+      output = (output + chunk.toString()).slice(-KEEP_CHARS);
+    };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const finish = (err?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // A background process the hook started (a dev server, say) may hold the pipes open: let go.
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.unref();
+      if (err) reject(err);
+      else resolve();
+    };
+    const timer = setTimeout(() => {
+      try {
+        process.kill(-child.pid!, 'SIGKILL');
+      } catch {
+        child.kill('SIGKILL');
+      }
+      finish(new Error(`timed out after ${timeoutMs / 1000} s${tail(output)}`));
+    }, timeoutMs);
+    child.on('error', (err) => finish(err));
+    // Done when the shell exits, not when every process holding its output does.
+    child.on('exit', (code) => {
+      if (code === 0) return finish();
+      const fail = () => finish(new Error(`exit code ${code}${tail(output)}`));
+      child.on('close', fail); // the last output usually arrives right after exit
+      setTimeout(fail, 500);
+    });
+  });
+}
+
+async function runRequest(r: Extract<Hook, { request: unknown }>['request'], timeoutMs: number): Promise<void> {
+  const hasJson = r.json !== undefined;
+  const res = await fetch(r.url, {
+    method: r.method,
+    headers: { ...(hasJson ? { 'content-type': 'application/json' } : {}), ...r.headers },
+    body: hasJson ? JSON.stringify(r.json) : undefined,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}${tail(await res.text().catch(() => ''))}`);
+}
+
+/** Run hooks in order; the first failure stops the run and names the hook. */
+export async function runHooks(hooks: Hook[], opts: HookOptions): Promise<void> {
+  for (const [i, hook] of hooks.entries()) {
+    try {
+      if ('run' in hook) await runCommand(hook.run, opts.cwd, opts.timeoutMs ?? RUN_TIMEOUT_MS);
+      else await runRequest(hook.request, opts.timeoutMs ?? REQUEST_TIMEOUT_MS);
+    } catch (err) {
+      throw new Error(`${opts.label}[${i}] (${describeHook(hook)}) failed: ${(err as Error).message}`);
+    }
+  }
+}
+
+const toStderr = (line: string) => {
+  process.stderr.write(`${line}\n`);
+};
+
+/**
+ * `before` hooks, then the work, then `after` hooks, which run even when the work fails. A failing
+ * `before` hook aborts; a failing `after` hook is only a warning, so it never undoes the work's
+ * result (a saved take, a check report).
+ */
+export async function withHooks<T>(
+  hooks: { before: Hook[]; after: Hook[] },
+  cwd: string,
+  work: () => Promise<T>,
+  warn: (line: string) => void = toStderr,
+): Promise<T> {
+  await runHooks(hooks.before, { cwd, label: 'hooks.before' });
+  const after = () => runHooks(hooks.after, { cwd, label: 'hooks.after' }).catch((err: Error) => warn(`⚠ ${err.message}`));
+  try {
+    return await work();
+  } finally {
+    await after();
+  }
+}

package/src/runner/record.ts

@@ -1,4 +1,4 @@
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { assertFfmpeg, probeVideo } from '../ffmpeg';
 import { workPaths } from '../paths';
@@ -10,6 +10,7 @@ import { startCapture, type Frame } from './capture';
 import type { RunOptions } from './check';
 import { encodeFrames } from './encode';
 import { EventLog } from './events';
+import { withHooks } from './hooks';
 import { describeStep, runStep, StepError, type StepContext } from './steps';
 import { sleep } from './time';
 
@@ -36,7 +37,7 @@ async function shoot(session: Session, loaded: LoadedScript, framesDir: string,
     height: viewport.height * deviceScaleFactor,
   });
   const log = new EventLog(capture.t0);
-  const ctx: StepContext = { page: session.page, mode: 'record', log, net: session.net, cursor };
+  const ctx: StepContext = { page: session.page, mode: 'record', log, net: session.net, cursor, baseUrl: script.app.url };
   try {
     await sleep(ESTABLISH_MS);
     for (const scene of script.scenes) {
@@ -59,38 +60,56 @@ export async function record(loaded: LoadedScript, opts: RecordOptions = {}): Pr
   const { script } = loaded;
   await assertFfmpeg();
   const paths = workPaths(loaded);
-  await rm(paths.take, { recursive: true, force: true });
-  await mkdir(paths.rawFrames, { recursive: true });
+  // Record into take.tmp; the previous take is replaced only once this one is complete.
+  const tmp = paths.takeTmp;
+  const frames = path.join(tmp, 'frames');
+  await rm(tmp, { recursive: true, force: true });
+  await mkdir(frames, { recursive: true });
 
-  const session = await openSession(script, opts);
-  let shot: Shot;
-  try {
-    shot = await shoot(session, loaded, paths.rawFrames, opts);
-  } catch (err) {
-    if (err instanceof StepError) {
-      await session.page.screenshot({ path: path.join(paths.take, 'failure.png'), scale: 'css' }).catch(() => undefined);
-      throw new Error(`${err.message}\nRecording aborted. Run \`showtime check ${loaded.scriptPath}\` to debug.`);
-    }
-    throw err;
-  } finally {
-    await session.close();
-  }
+  // After hooks run once the take is saved, so a failing one cannot cost the take.
+  return withHooks(
+    script.hooks,
+    loaded.dir,
+    async () => {
+      const session = await openSession(script, opts);
+      let shot: Shot;
+      try {
+        shot = await shoot(session, loaded, frames, opts);
+      } catch (err) {
+        if (err instanceof StepError) {
+          const failure = path.join(tmp, 'failure.png');
+          await session.page.screenshot({ path: failure, scale: 'css' }).catch(() => undefined);
+          throw new Error(
+            `${err.message}\nRecording aborted; the previous take is untouched (failure screenshot: ${failure}). Run \`showtime check ${loaded.scriptPath}\` to debug.`,
+          );
+        }
+        throw err;
+      } finally {
+        await session.close();
+      }
 
-  opts.log?.('Encoding raw.mp4…');
-  await encodeFrames(shot.frames, paths.raw, { fps: TAKE_FPS, durationMs: shot.durationMs });
-  const probe = await probeVideo(paths.raw);
-  const events: TakeEvents = {
-    version: 1,
-    actionHash: actionHash(script),
-    viewport: script.app.viewport,
-    deviceScaleFactor: script.app.deviceScaleFactor,
-    video: { file: 'raw.mp4', width: probe.width, height: probe.height, fps: TAKE_FPS, durationMs: shot.durationMs },
-    steps: shot.log.steps,
-    moves: shot.log.moves,
-    clicks: shot.log.clicks,
-    idle: shot.log.idle,
-  };
-  await writeFile(paths.events, JSON.stringify(events, null, 2));
-  if (!opts.keepFrames) await rm(paths.rawFrames, { recursive: true, force: true });
-  return events;
+      opts.log?.('Encoding raw.mp4…');
+      const raw = path.join(tmp, 'raw.mp4');
+      await encodeFrames(shot.frames, raw, { fps: TAKE_FPS, durationMs: shot.durationMs });
+      const probe = await probeVideo(raw);
+      const events: TakeEvents = {
+        version: 1,
+        actionHash: actionHash(script),
+        viewport: script.app.viewport,
+        deviceScaleFactor: script.app.deviceScaleFactor,
+        video: { file: 'raw.mp4', width: probe.width, height: probe.height, fps: TAKE_FPS, durationMs: shot.durationMs },
+        steps: shot.log.steps,
+        moves: shot.log.moves,
+        clicks: shot.log.clicks,
+        idle: shot.log.idle,
+        keys: shot.log.keys,
+      };
+      await writeFile(path.join(tmp, 'events.json'), JSON.stringify(events, null, 2));
+      if (!opts.keepFrames) await rm(frames, { recursive: true, force: true });
+      await rm(paths.take, { recursive: true, force: true });
+      await rename(tmp, paths.take);
+      return events;
+    },
+    opts.warn,
+  );
 }