@mineo71/showtime 0.2.1 → 0.3.0

package/src/cli/main.ts

@@ -1,17 +1,38 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { workPaths } from '../paths';
-import { loadScript } from '../script/load';
+import { loadScript, type LoadedScript } from '../script/load';
 import { scriptJsonSchema } from '../script/schema';
-import { formatCheck } from './format';
+import type { TakeEvents } from '../timeline/types';
+import { formatCheck, formatLint } from './format';
 
-const say = (line: string) => process.stdout.write(`${line}\n`);
-const progress = (p: number) => {
-  if (process.stdout.isTTY) process.stdout.write(`\rRendering ${Math.round(p * 100)}%`);
+const say = (line: string): void => {
+  process.stdout.write(`${line}\n`);
 };
+/** With --json, stdout carries exactly one JSON document. */
+const emit = (data: unknown): void => say(JSON.stringify(data, null, 2));
+const progressFor = (json?: boolean) =>
+  json
+    ? undefined
+    : (p: number) => {
+        if (process.stdout.isTTY) process.stdout.write(`\rRendering ${Math.round(p * 100)}%`);
+      };
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
 
+const takeSummary = (loaded: LoadedScript, ev: TakeEvents) => ({
+  take: workPaths(loaded).take,
+  durationMs: ev.video.durationMs,
+  steps: ev.steps.length,
+});
+
+async function render(loaded: LoadedScript, o: { out?: string; json?: boolean }) {
+  const { renderDemo } = await import('../pipeline');
+  const { probeVideo } = await import('../ffmpeg');
+  const video = await renderDemo(loaded, { out: o.out, onProgress: progressFor(o.json) });
+  return { video, durationMs: (await probeVideo(video)).durationMs };
+}
+
 const program = new Command('showtime')
   .description('AI-directed product demo videos: JSON script in, polished MP4 out')
   .version(version);
@@ -21,23 +42,27 @@ program
   .description('download the browsers showTime records with and link the skill into Claude Code and Codex')
   .option('--agent <agent>', 'claude, codex or all', 'all')
   .option('--no-browsers', 'only link the skill')
-  .action(async (o: { agent: string; browsers: boolean }) => {
+  .option('--json', 'print the result as JSON')
+  .action(async (o: { agent: string; browsers: boolean; json?: boolean }) => {
     const { AGENTS, installBrowsers, linkSkill } = await import('../setup');
     const agents = o.agent === 'all' ? AGENTS : AGENTS.filter((a) => a === o.agent);
     if (!agents.length) throw new Error(`--agent must be ${AGENTS.join(', ')} or all`);
     if (o.browsers) {
-      say('Downloading Chromium and the Remotion renderer browser…');
-      await installBrowsers();
+      if (!o.json) say('Downloading Chromium and the Remotion renderer browser…');
+      await installBrowsers({ quiet: o.json });
     }
-    for (const dest of linkSkill(agents)) say(`✓ skill linked: ${dest}`);
+    const links = linkSkill(agents);
+    if (o.json) return emit({ links, browsers: o.browsers });
+    for (const dest of links) say(`✓ skill linked: ${dest}`);
     say('Ready. Ask your agent for a demo, or run `showtime make <script>`.');
   });
 
 program
   .command('schema')
   .description('print the JSON Schema of demo scripts')
+  .option('--json', 'accepted for symmetry; the output is always JSON')
   .action(() => {
-    say(JSON.stringify(scriptJsonSchema(), null, 2));
+    emit(scriptJsonSchema());
   });
 
 program
@@ -49,41 +74,66 @@ program
     const loaded = await loadScript(file);
     const { check } = await import('../runner/check');
     const report = await check(loaded, { headed: o.headed, log: o.json ? undefined : say });
-    say(o.json ? JSON.stringify(report, null, 2) : formatCheck(report));
+    if (o.json) emit(report);
+    else say(formatCheck(report));
     if (!report.ok) process.exitCode = 1;
   });
 
+program
+  .command('lint <script>')
+  .description('flag script problems, and timing problems when a fresh take exists')
+  .option('--json', 'print { issues, timing } as JSON')
+  .action(async (file: string, o: { json?: boolean }) => {
+    const loaded = await loadScript(file);
+    const { lintScript, lintTiming } = await import('../lint');
+    const issues = lintScript(loaded.script);
+    const { loadTake } = await import('../take');
+    const events = await loadTake(loaded).catch(() => null);
+    if (events) {
+      const { buildTimeline } = await import('../timeline/build');
+      issues.push(...lintTiming(buildTimeline(loaded.script, events), events.steps));
+    }
+    if (o.json) emit({ issues, timing: events !== null });
+    else say(formatLint(issues, events !== null));
+    if (issues.some((i) => i.level === 'warn')) process.exitCode = 1;
+  });
+
 program
   .command('record <script>')
   .description('record a take (raw video + event log) into .showtime/<name>/take')
   .option('--headed', 'show the browser')
   .option('--keep-frames', 'keep the captured JPEG frames')
-  .action(async (file: string, o: { headed?: boolean; keepFrames?: boolean }) => {
+  .option('--json', 'print { take, durationMs, steps } as JSON')
+  .action(async (file: string, o: { headed?: boolean; keepFrames?: boolean; json?: boolean }) => {
     const loaded = await loadScript(file);
     const { record } = await import('../runner/record');
-    const ev = await record(loaded, { headed: o.headed, keepFrames: o.keepFrames, log: say });
-    say(`✓ take: ${(ev.video.durationMs / 1000).toFixed(1)} s, ${ev.steps.length} steps → ${workPaths(loaded).take}`);
+    const ev = await record(loaded, { headed: o.headed, keepFrames: o.keepFrames, log: o.json ? undefined : say });
+    const take = takeSummary(loaded, ev);
+    if (o.json) emit(take);
+    else say(`✓ take: ${(take.durationMs / 1000).toFixed(1)} s, ${take.steps} steps → ${take.take}`);
   });
 
 program
   .command('render <script>')
   .description('render the polished video from the last take (no re-recording)')
   .option('-o, --out <file>', 'output MP4 (default: <script-name>.mp4 next to the script)')
-  .action(async (file: string, o: { out?: string }) => {
-    const loaded = await loadScript(file);
-    const { renderDemo } = await import('../pipeline');
-    const out = await renderDemo(loaded, { out: o.out, onProgress: progress });
-    say(`\n✓ ${out}`);
+  .option('--json', 'print { video, durationMs } as JSON')
+  .action(async (file: string, o: { out?: string; json?: boolean }) => {
+    const result = await render(await loadScript(file), o);
+    if (o.json) emit(result);
+    else say(`\n✓ ${result.video}`);
   });
 
 program
   .command('frames <script>')
-  .description('render QA stills (intro + one per step) for visual review')
-  .action(async (file: string) => {
-    const loaded = await loadScript(file);
+  .description('render QA stills (intro, one per step, outro) and a contact sheet of them')
+  .option('--json', 'print { sheet, frames } as JSON')
+  .action(async (file: string, o: { json?: boolean }) => {
     const { renderQaFrames } = await import('../pipeline');
-    const files = await renderQaFrames(loaded);
-    say(files.join('\n'));
+    const { sheet, frames } = await renderQaFrames(await loadScript(file));
+    if (o.json) return emit({ sheet, frames });
+    say(`sheet: ${sheet}`);
+    say(frames.join('\n'));
   });
 
 program
@@ -91,22 +141,25 @@ program
   .description('check → record → render')
   .option('-o, --out <file>', 'output MP4 (default: <script-name>.mp4 next to the script)')
   .option('--headed', 'show the browser')
-  .action(async (file: string, o: { out?: string; headed?: boolean }) => {
+  .option('--json', 'print { check, take, video } as JSON')
+  .action(async (file: string, o: { out?: string; headed?: boolean; json?: boolean }) => {
     const loaded = await loadScript(file);
+    const log = o.json ? undefined : say;
     const { check } = await import('../runner/check');
     const report = await check(loaded, { headed: o.headed });
     if (!report.ok) {
-      say(formatCheck(report));
+      if (o.json) emit({ check: report });
+      else say(formatCheck(report));
       process.exitCode = 1;
       return;
     }
-    say(`✓ check passed (${report.steps.length} steps)`);
+    log?.(`✓ check passed (${report.steps.length} steps)`);
     const { record } = await import('../runner/record');
-    const ev = await record(loaded, { headed: o.headed, log: say });
-    say(`✓ take: ${(ev.video.durationMs / 1000).toFixed(1)} s`);
-    const { renderDemo } = await import('../pipeline');
-    const out = await renderDemo(loaded, { out: o.out, onProgress: progress });
-    say(`\n✓ ${out}`);
+    const take = takeSummary(loaded, await record(loaded, { headed: o.headed, log }));
+    log?.(`✓ take: ${(take.durationMs / 1000).toFixed(1)} s`);
+    const video = await render(loaded, o);
+    if (o.json) emit({ check: report, take, video });
+    else say(`\n✓ ${video.video}`);
   });
 
 program.parseAsync().catch((err: Error) => {

package/src/lint.ts

@@ -0,0 +1,101 @@
+import type { Script, Step } from './script/schema';
+import { outputDurationMs, sourceToOutput } from './timeline/timemap';
+import type { StepEvent, Timeline } from './timeline/types';
+
+export interface Issue {
+  rule: 'caption-length' | 'pause-for-loading' | 'show-ignored' | 'no-intro' | 'caption-too-short' | 'video-length';
+  level: 'warn' | 'info';
+  /** `scene#step` (1-based), `setup#n`, or `script` */
+  where: string;
+  message: string;
+}
+
+const MAX_CAPTION_WORDS = 6;
+const LOADING_PAUSE_MS = 1500;
+const ACTIONS = new Set<Step['do']>(['click', 'press', 'type', 'select']);
+const TARGETED = new Set<Step['do']>(['click', 'type', 'hover', 'select']);
+
+const words = (text: string) => text.trim().split(/\s+/).filter(Boolean).length;
+const hasTarget = (s: Step) => TARGETED.has(s.do) || (s.do === 'scroll' && s.target !== undefined);
+/** Reading time for a caption: half a second to notice it, a quarter per word, never under 1.2 s. */
+export const readingMs = (text: string) => Math.max(1200, 500 + 250 * words(text));
+
+/** Checks that need only the script. */
+export function lintScript(script: Script): Issue[] {
+  const issues: Issue[] = [];
+  if (!script.meta.title) {
+    issues.push({ rule: 'no-intro', level: 'info', where: 'script', message: 'No meta.title, so the video starts without an intro card.' });
+  }
+  script.setup.forEach((step, i) => {
+    if (step.show) {
+      issues.push({
+        rule: 'show-ignored',
+        level: 'warn',
+        where: `setup#${i + 1}`,
+        message: 'Setup steps run before the camera starts, so their `show` does nothing.',
+      });
+    }
+  });
+  for (const scene of script.scenes) {
+    scene.steps.forEach((step, i) => {
+      const where = `${scene.id}#${i + 1}`;
+      const caption = step.show?.caption;
+      if (caption && words(caption) > MAX_CAPTION_WORDS) {
+        issues.push({
+          rule: 'caption-length',
+          level: 'warn',
+          where,
+          message: `Caption has ${words(caption)} words; keep it to ${MAX_CAPTION_WORDS} or fewer: "${caption}"`,
+        });
+      }
+      const zooms = typeof step.show?.zoom === 'number';
+      if ((zooms || step.show?.spotlight) && !hasTarget(step)) {
+        issues.push({
+          rule: 'show-ignored',
+          level: 'warn',
+          where,
+          message: `\`${step.do}\` has no target, so ${zooms ? 'zoom' : 'spotlight'} does nothing here.`,
+        });
+      }
+      const prev = scene.steps[i - 1];
+      if (step.do === 'pause' && step.ms >= LOADING_PAUSE_MS && prev && ACTIONS.has(prev.do)) {
+        issues.push({
+          rule: 'pause-for-loading',
+          level: 'warn',
+          where,
+          message: 'A long pause right after an action usually waits for loading. Use { "do": "wait", "for": "<what appears>" } so it is sped up.',
+        });
+      }
+    });
+  }
+  return issues;
+}
+
+/** Checks on the edited result: caption reading time and overall length (output time). */
+export function lintTiming(timeline: Timeline, steps: StepEvent[]): Issue[] {
+  const issues: Issue[] = [];
+  for (const c of timeline.captions) {
+    const shown = sourceToOutput(timeline.segments, c.endMs) - sourceToOutput(timeline.segments, c.startMs);
+    const need = readingMs(c.text);
+    if (shown < need) {
+      const step = steps.find((s) => s.startMs === c.startMs);
+      issues.push({
+        rule: 'caption-too-short',
+        level: 'warn',
+        where: step ? `${step.sceneId}#${step.index + 1}` : 'script',
+        // Round shown down and needed up, so the numbers never read as equal.
+        message: `"${c.text}" is on screen for ${(Math.floor(shown / 100) / 10).toFixed(1)} s but needs about ${(Math.ceil(need / 100) / 10).toFixed(1)} s to read. Add show.hold or slow the step down.`,
+      });
+    }
+  }
+  const totalMs = (timeline.intro?.durationMs ?? 0) + outputDurationMs(timeline.segments) + (timeline.outro?.durationMs ?? 0);
+  if (totalMs > 60_000) {
+    issues.push({
+      rule: 'video-length',
+      level: totalMs > 120_000 ? 'warn' : 'info',
+      where: 'script',
+      message: `The video runs ${Math.round(totalMs / 1000)} s; pitch demos land best under a minute.`,
+    });
+  }
+  return issues;
+}

package/src/logo.ts

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const TYPES: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+};
+const MAX_BYTES = 2_000_000;
+
+/** The logo file as a data URI, so timeline.json carries it to the renderer without extra files. */
+export async function logoDataUri(file: string): Promise<string> {
+  const type = TYPES[path.extname(file).toLowerCase()];
+  if (!type) throw new Error(`meta.logo must be an SVG, PNG, JPEG or WebP file: ${file}`);
+  const data = await readFile(file);
+  if (data.length > MAX_BYTES) throw new Error(`meta.logo is larger than 2 MB: ${file}`);
+  return `data:${type};base64,${data.toString('base64')}`;
+}

package/src/paths.ts

@@ -5,11 +5,15 @@ export interface WorkPaths {
   root: string;
   check: string;
   take: string;
+  /** a take being recorded; swapped in for `take` only when it succeeds */
+  takeTmp: string;
   rawFrames: string;
   raw: string;
   events: string;
   timeline: string;
   stills: string;
+  /** contact sheet of the stills */
+  sheet: string;
   video: string;
 }
 
@@ -20,11 +24,13 @@ export function workPaths(loaded: LoadedScript): WorkPaths {
     root,
     check: path.join(root, 'check'),
     take,
+    takeTmp: path.join(root, 'take.tmp'),
     rawFrames: path.join(take, 'frames'),
     raw: path.join(take, 'raw.mp4'),
     events: path.join(take, 'events.json'),
     timeline: path.join(root, 'timeline.json'),
     stills: path.join(root, 'frames'),
+    sheet: path.join(root, 'frames', 'sheet.png'),
     video: path.join(loaded.dir, `${loaded.name}.mp4`),
   };
 }

package/src/pipeline.ts

@@ -1,7 +1,9 @@
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { logoDataUri } from './logo';
 import { workPaths } from './paths';
 import { renderStills, renderVideo } from './render/render';
+import { contactSheet } from './sheet';
 import type { LoadedScript } from './script/load';
 import { loadTake } from './take';
 import { buildTimeline } from './timeline/build';
@@ -10,7 +12,8 @@ import type { TakeEvents, Timeline } from './timeline/types';
 
 export async function timelineFor(loaded: LoadedScript): Promise<{ timeline: Timeline; events: TakeEvents }> {
   const events = await loadTake(loaded);
-  const timeline = buildTimeline(loaded.script, events);
+  const { logo } = loaded.script.meta;
+  const timeline = buildTimeline(loaded.script, events, { logo: logo ? await logoDataUri(logo) : undefined });
   const paths = workPaths(loaded);
   await mkdir(paths.root, { recursive: true });
   await writeFile(paths.timeline, JSON.stringify(timeline, null, 2));
@@ -29,10 +32,16 @@ export async function renderDemo(
   return out;
 }
 
-export async function renderQaFrames(loaded: LoadedScript): Promise<string[]> {
+/** QA stills (intro, one per step, outro) and a contact sheet of all of them. */
+export async function renderQaFrames(loaded: LoadedScript): Promise<{ sheet: string; frames: string[] }> {
   const { timeline, events } = await timelineFor(loaded);
   const paths = workPaths(loaded);
   await rm(paths.stills, { recursive: true, force: true });
   await mkdir(paths.stills, { recursive: true });
-  return renderStills(timeline, paths.take, paths.stills, qaShots(timeline, events.steps));
+  const frames = await renderStills(timeline, paths.take, paths.stills, qaShots(timeline, events.steps));
+  const sheet = await contactSheet(
+    frames.map((file) => ({ file, label: path.basename(file, '.png') })),
+    paths.sheet,
+  );
+  return { sheet, frames };
 }

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);
@@ -20,6 +21,7 @@ export const Intro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t,
       }}
     >
       <div style={{ 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={{ 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

@@ -55,7 +55,8 @@ export const Ripples: FC<LayerProps> = ({ timeline, srcMs }) => (
   </>
 );
 
-export const Captions: FC<LayerProps> = ({ timeline, srcMs }) => {
+/** `top` is where a top caption's box starts (output px); bottom captions sit at a fixed inset. */
+export const Captions: FC<LayerProps & { top: number }> = ({ timeline, srcMs, top }) => {
   const active = timeline.captions.filter((c) => srcMs >= c.startMs && srcMs <= c.endMs);
   const c = active[active.length - 1];
   if (!c) return null;
@@ -66,7 +67,7 @@ export const Captions: FC<LayerProps> = ({ timeline, srcMs }) => {
         position: 'absolute',
         left: 0,
         right: 0,
-        bottom: Math.round(timeline.output.height * 0.075),
+        ...(c.position === 'top' ? { top } : { bottom: Math.round(timeline.output.height * 0.075) }),
         display: 'flex',
         justifyContent: 'center',
       }}
@@ -85,7 +86,7 @@ export const Captions: FC<LayerProps> = ({ timeline, srcMs }) => {
           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}

package/src/render/remotion/ShowtimeVideo.tsx

@@ -1,12 +1,13 @@
 import type { FC } from 'react';
 import { AbsoluteFill, Easing, interpolate, OffthreadVideo, Sequence, staticFile, useCurrentFrame } from 'remotion';
 import { cameraAt, cameraTransform } from '../../timeline/camera';
-import { introFrames, segmentPlan, sourceMsAtFrame } from '../../timeline/frames';
+import { introFrames, segmentPlan, sourceMsAtFrame, videoEndFrame } from '../../timeline/frames';
 import { BROWSER_BAR, windowLayout } from '../../timeline/layout';
 import type { Timeline } from '../../timeline/types';
 import { BrowserBar } from './BrowserBar';
 import { Cursor } from './Cursor';
 import { Intro } from './Intro';
+import { Outro } from './Outro';
 import { Captions, Ripples, Spotlights } from './Overlays';
 
 export type ShowtimeVideoProps = { timeline: Timeline };
@@ -17,6 +18,8 @@ export const ShowtimeVideo: 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);
@@ -26,6 +29,8 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
   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 +45,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})`,
         }}
       >
@@ -86,7 +91,9 @@ 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={win.y + Math.round(t.output.height * 0.03)} />
+      </div>
     </AbsoluteFill>
   );
 };

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()) {