@mineo71/showtime 0.2.1 → 0.3.0

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,55 @@ 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,
+      };
+      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,
+  );
 }

package/src/runner/steps.ts

@@ -14,6 +14,8 @@ export interface StepContext {
   log: EventLog;
   net: NetworkTracker;
   cursor: Pt;
+  /** Relative `goto` URLs resolve against this (app.url); the current page when absent. */
+  baseUrl?: string;
 }
 
 export interface StepWhere {
@@ -69,7 +71,7 @@ async function perform(ctx: StepContext, step: Step, where: StepWhere): Promise<
 
   switch (step.do) {
     case 'goto':
-      await page.goto(step.url, { waitUntil: 'load', timeout: WAIT_TIMEOUT_MS });
+      await page.goto(new URL(step.url, ctx.baseUrl ?? page.url()).href, { waitUntil: 'load', timeout: WAIT_TIMEOUT_MS });
       break;
     case 'click':
     case 'hover':

package/src/script/config.ts

@@ -0,0 +1,58 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { formatIssues, MetaSchema, ScriptError, StyleSchema } from './schema';
+
+export const CONFIG_FILE = 'showtime.config.json';
+
+type Json = Record<string, unknown>;
+
+export interface BrandConfig {
+  style?: Json;
+  meta?: Json;
+}
+
+// Validated on its own so mistakes are blamed on this file; the raw values are what get merged.
+const ConfigSchema = z
+  .object({ $schema: z.string().optional(), style: StyleSchema.partial().optional(), meta: MetaSchema.partial().optional() })
+  .strict();
+
+/** The nearest showtime.config.json from `dir` upward, or null. */
+export function findConfig(dir: string): string | null {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    const file = path.join(d, CONFIG_FILE);
+    if (existsSync(file)) return file;
+    if (path.dirname(d) === d) return null;
+  }
+}
+
+/** Read a brand file; paths inside it (meta.logo) resolve against its folder. */
+export async function readConfig(file: string): Promise<BrandConfig> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(file, 'utf8'));
+  } catch (err) {
+    throw new ScriptError(`Invalid JSON in ${file}: ${(err as Error).message}`);
+  }
+  const parsed = ConfigSchema.safeParse(raw);
+  if (!parsed.success) throw new ScriptError(`Invalid ${file}:\n${formatIssues(parsed.error.issues)}`);
+  const { style, meta } = raw as BrandConfig;
+  return { style, meta: withLogoFrom(meta, path.dirname(file)) };
+}
+
+/** meta with `logo` made absolute against `dir` (when it is a string). */
+export function withLogoFrom(meta: Json | undefined, dir: string): Json | undefined {
+  if (!meta || typeof meta.logo !== 'string') return meta;
+  return { ...meta, logo: path.resolve(dir, meta.logo) };
+}
+
+const isObject = (v: unknown): v is Json => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Brand defaults under the raw script: the script wins key by key in `style` and `meta`. */
+export function applyConfig(config: BrandConfig, raw: Json): Json {
+  const merged: Json = { ...raw };
+  if (config.style) merged.style = isObject(raw.style) ? { ...config.style, ...raw.style } : (raw.style ?? config.style);
+  if (config.meta) merged.meta = isObject(raw.meta) ? { ...config.meta, ...raw.meta } : (raw.meta ?? config.meta);
+  return merged;
+}

package/src/script/hash.ts

@@ -19,9 +19,15 @@ function canonical(value: unknown): string {
   return JSON.stringify(value);
 }
 
+/** `app` without fields that sit at their defaults, so adding a field never invalidates older takes. */
+function appOf(app: Script['app']): Record<string, unknown> {
+  const { mock, dialogs, ...rest } = app;
+  return { ...rest, ...(mock.length ? { mock } : {}), ...(dialogs !== 'accept' ? { dialogs } : {}) };
+}
+
 export function actionHash(script: Script): string {
   const payload = {
-    app: script.app,
+    app: appOf(script.app),
     setup: script.setup.map(actionsOf),
     scenes: script.scenes.map((s) => ({ id: s.id, steps: s.steps.map(actionsOf) })),
   };

package/src/script/load.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { applyConfig, findConfig, readConfig, withLogoFrom } from './config';
 import { parseScript, ScriptError, type Script } from './schema';
 
 export interface LoadedScript {
@@ -8,6 +9,8 @@ export interface LoadedScript {
   scriptPath: string;
   dir: string;
   name: string;
+  /** The showtime.config.json whose defaults were applied, if any. */
+  config: string | null;
 }
 
 export async function loadScript(file: string): Promise<LoadedScript> {
@@ -24,13 +27,20 @@ export async function loadScript(file: string): Promise<LoadedScript> {
   } catch (err) {
     throw new ScriptError(`Invalid JSON in ${scriptPath}: ${(err as Error).message}`);
   }
-  const script = parseScript(raw, scriptPath);
   const dir = path.dirname(scriptPath);
+  const config = findConfig(dir);
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const own = raw as Record<string, unknown>;
+    if (own.meta && typeof own.meta === 'object') own.meta = withLogoFrom(own.meta as Record<string, unknown>, dir);
+    if (config) raw = applyConfig(await readConfig(config), own);
+  }
+  const script = parseScript(raw, scriptPath);
+  if (script.meta.logo && !existsSync(script.meta.logo)) throw new ScriptError(`meta.logo not found: ${script.meta.logo}`);
   if (script.app.storageState) {
     script.app.storageState = path.resolve(dir, script.app.storageState);
     if (!existsSync(script.app.storageState)) {
       throw new ScriptError(`app.storageState not found: ${script.app.storageState}`);
     }
   }
-  return { script, scriptPath, dir, name: path.basename(scriptPath).replace(/\.json$/i, '') };
+  return { script, scriptPath, dir, name: path.basename(scriptPath).replace(/\.json$/i, ''), config };
 }

package/src/script/schema.ts

@@ -69,6 +69,21 @@ export const StyleSchema = z
   })
   .strict();
 
+const headers = z.record(z.string(), z.string());
+
+export const MockSchema = z
+  .object({
+    url: z.string().min(1).describe('Playwright URL glob of the requests to answer, e.g. **/api/reports*'),
+    method: z.string().min(1).optional().describe('Only answer this HTTP method; others go to the network'),
+    status: z.number().int().min(100).max(599).default(200),
+    json: z.unknown().optional().describe('Response body, sent as application/json'),
+    body: z.string().optional().describe('Raw response body'),
+    headers: headers.optional(),
+    delayMs: z.number().int().min(0).max(30_000).optional().describe('Wait this long before answering'),
+  })
+  .strict()
+  .refine((m) => m.json === undefined || m.body === undefined, { message: 'a mock takes "json" or "body", not both' });
+
 export const AppSchema = z
   .object({
     url: z.string().min(1),
@@ -85,6 +100,49 @@ export const AppSchema = z
       .array(z.string().min(1))
       .default([])
       .describe('CSS selectors (not Playwright selectors) of elements to blur in the recording'),
+    mock: z.array(MockSchema).default([]).describe('Answer matching network requests with canned responses; the first match wins'),
+    clock: z
+      .string()
+      .refine((v) => !Number.isNaN(Date.parse(v)), { message: 'must be an ISO date-time, e.g. 2026-10-13T09:30:00Z' })
+      .optional()
+      .describe('Start the page clock at this ISO date-time; it then runs normally'),
+    dialogs: z.enum(['accept', 'dismiss']).default('accept').describe('How to answer alert/confirm/prompt dialogs'),
+  })
+  .strict();
+
+export const HookSchema = z.union([
+  z.object({ run: z.string().min(1).describe('Shell command, run in the script folder') }).strict(),
+  z
+    .object({
+      request: z
+        .object({
+          url: z.string().min(1),
+          method: z.string().min(1).default('POST'),
+          json: z.unknown().optional(),
+          headers: headers.optional(),
+        })
+        .strict(),
+    })
+    .strict(),
+]);
+
+export const HooksSchema = z
+  .object({
+    before: z.array(HookSchema).default([]).describe('Run before every check and record, e.g. to reset demo data'),
+    after: z.array(HookSchema).default([]).describe('Run after every check and record, even when it failed'),
+  })
+  .strict();
+
+export const MetaSchema = z
+  .object({
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    logo: z.string().min(1).optional().describe('SVG/PNG/JPEG/WebP shown on the intro and outro cards'),
+    outro: z
+      .object({ title: z.string().min(1), subtitle: z.string().optional(), url: z.string().optional() })
+      .strict()
+      .optional()
+      .describe('Closing card after the video'),
   })
   .strict();
 
@@ -99,8 +157,9 @@ export const ScriptSchema = z
   .object({
     $schema: z.string().optional(),
     version: z.literal(1),
-    meta: z.object({ title: z.string().optional(), subtitle: z.string().optional() }).strict().default({}),
+    meta: MetaSchema.default({}),
     app: AppSchema,
+    hooks: HooksSchema.prefault({}),
     setup: z.array(StepSchema).default([]),
     style: StyleSchema.prefault({}),
     scenes: z.array(SceneSchema).min(1),
@@ -121,6 +180,8 @@ export type ScriptInput = z.input<typeof ScriptSchema>;
 export type Step = z.output<typeof StepSchema>;
 export type Show = z.output<typeof ShowSchema>;
 export type Style = z.output<typeof StyleSchema>;
+export type Hook = z.output<typeof HookSchema>;
+export type Mock = z.output<typeof MockSchema>;
 
 export class ScriptError extends Error {
   constructor(message: string) {

package/src/setup.ts

@@ -26,16 +26,25 @@ export function linkSkill(agents: Agent[], home = homedir(), source = SKILL_DIR)
   });
 }
 
-/** Download the Chromium build this copy of Playwright drives, and Remotion's headless shell. */
-export async function installBrowsers(): Promise<void> {
+/**
+ * Download the Chromium build this copy of Playwright drives, and Remotion's headless shell.
+ * `quiet` sends their progress output to stderr, keeping stdout clean for --json.
+ */
+export async function installBrowsers(opts: { quiet?: boolean } = {}): Promise<void> {
   // Our own Playwright CLI: a bare `npx playwright` may resolve another version with another Chromium.
   const require = createRequire(import.meta.url);
   const cli = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
   await new Promise<void>((resolve, reject) => {
-    const child = spawn(process.execPath, [cli, 'install', 'chromium'], { stdio: 'inherit' });
+    const child = spawn(process.execPath, [cli, 'install', 'chromium'], { stdio: ['ignore', opts.quiet ? 2 : 'inherit', 'inherit'] });
     child.on('error', reject);
     child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`playwright install chromium exited with code ${code}`))));
   });
   const { ensureBrowser } = await import('@remotion/renderer');
-  await ensureBrowser();
+  const log = console.log;
+  if (opts.quiet) console.log = console.error;
+  try {
+    await ensureBrowser();
+  } finally {
+    console.log = log;
+  }
 }

package/src/sheet.ts

@@ -0,0 +1,47 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright';
+
+export const SHEET_COLUMNS = 4;
+export const SHEET_WIDTH = 1920;
+
+export interface SheetItem {
+  file: string;
+  label: string;
+}
+
+const ENTITIES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ENTITIES[c]);
+
+/** A page laying the stills out in a labelled grid; images load by file name from the page's own folder. */
+export function sheetHtml(items: SheetItem[]): string {
+  const figures = items
+    .map((i) => `<figure><img src="${encodeURIComponent(path.basename(i.file))}"><figcaption>${esc(i.label)}</figcaption></figure>`)
+    .join('\n');
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><style>
+  body { margin: 0; background: #0b0f17; color: #e2e8f0; font: 600 18px/1.3 -apple-system, "Segoe UI", system-ui, sans-serif; }
+  .grid { display: grid; grid-template-columns: repeat(${SHEET_COLUMNS}, 1fr); gap: 16px; padding: 24px; width: ${SHEET_WIDTH}px; box-sizing: border-box; }
+  figure { margin: 0; }
+  img { display: block; width: 100%; border-radius: 6px; }
+  figcaption { margin-top: 8px; }
+</style></head><body><div class="grid">
+${figures}
+</div></body></html>`;
+}
+
+/** Render the stills (all in one folder) into one labelled PNG at `out`, next to them. */
+export async function contactSheet(items: SheetItem[], out: string): Promise<string> {
+  const html = path.join(path.dirname(out), 'sheet.html');
+  await writeFile(html, sheetHtml(items));
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage({ viewport: { width: SHEET_WIDTH, height: 600 } });
+    await page.goto(pathToFileURL(html).href, { waitUntil: 'load' });
+    await page.screenshot({ path: out, fullPage: true });
+  } finally {
+    await browser.close();
+  }
+  return out;
+}

package/src/timeline/build.ts

@@ -1,20 +1,27 @@
 import type { Script, Step } from '../script/schema';
-import { buildCamera, MIN_ZOOM, zoomDepth, type ZoomRegion } from './camera';
+import { buildCamera, cameraAt, MIN_ZOOM, zoomDepth, type ZoomRegion } from './camera';
+import { BROWSER_BAR, projectRect, windowLayout, type Box } from './layout';
 import { clamp } from './math';
 import { buildSegments, type SpeedSpan } from './timemap';
-import type { Caption, Rect, Spotlight, StepEvent, TakeEvents, Timeline } from './types';
+import type { CameraKey, Caption, Rect, Spotlight, StepEvent, TakeEvents, Timeline } from './types';
 
 export const AUTO_SPEED_MIN_IDLE_MS = 800;
 export const AUTO_SPEED_TARGET_MS = 600;
 export const INTRO_MS = 2200;
 export const CAPTION_MIN_MS = 1500;
 export const SPOTLIGHT_PAD = 8;
+export const OUTRO_MS = 2600;
+/** Bottom captions own the output below this fraction of its height. */
+export const CAPTION_BAND = 0.78;
+const DEFAULT_OUTPUT = { width: 1920, height: 1080 };
 
 const ZOOMABLE = new Set<Step['do']>(['click', 'type', 'select', 'hover']);
 
 export interface BuildOptions {
   fps?: number;
   output?: { width: number; height: number };
+  /** Logo as a data URI. */
+  logo?: string;
 }
 
 function stepOf(script: Script, e: StepEvent): Step {
@@ -33,11 +40,30 @@ function displayAddress(url: string): string {
   }
 }
 
+/** Top when the target, at any of the caption's start/middle/end, reaches into the bottom caption band. */
+function captionPosition(
+  target: Rect | undefined,
+  c: { startMs: number; endMs: number },
+  camera: CameraKey[],
+  stage: { width: number; height: number },
+  win: Box,
+  output: { width: number; height: number },
+): Caption['position'] {
+  if (!target) return 'bottom';
+  const band = output.height * CAPTION_BAND;
+  const low = [c.startMs, (c.startMs + c.endMs) / 2, c.endMs].some((tMs) => {
+    const r = projectRect(target, cameraAt(camera, tMs), stage, win);
+    return r.y + r.height > band;
+  });
+  return low ? 'top' : 'bottom';
+}
+
 const pad = (r: Rect, p: number): Rect => ({ x: r.x - p, y: r.y - p, width: r.width + 2 * p, height: r.height + 2 * p });
 
 export function buildTimeline(script: Script, ev: TakeEvents, opts: BuildOptions = {}): Timeline {
   const { style } = script;
   const stage = ev.viewport;
+  const output = opts.output ?? DEFAULT_OUTPUT;
   const pairs = ev.steps.map((e) => ({ e, step: stepOf(script, e) }));
 
   // Speed: auto idle first, explicit `show.speed` next, pauses last (later spans win).
@@ -56,7 +82,7 @@ export function buildTimeline(script: Script, ev: TakeEvents, opts: BuildOptions
   }
 
   const regions: ZoomRegion[] = [];
-  const captions: Caption[] = [];
+  const drafts: { startMs: number; endMs: number; text: string; target?: Rect }[] = [];
   const spotlights: Spotlight[] = [];
   for (const { e, step } of pairs) {
     const zoom = step.show?.zoom;
@@ -74,17 +100,29 @@ export function buildTimeline(script: Script, ev: TakeEvents, opts: BuildOptions
       }
     }
     if (step.show?.caption) {
-      captions.push({ startMs: e.startMs, endMs: Math.max(e.settledMs, e.startMs + CAPTION_MIN_MS), text: step.show.caption });
+      drafts.push({ startMs: e.startMs, endMs: Math.max(e.settledMs, e.startMs + CAPTION_MIN_MS), text: step.show.caption, target: e.target });
     }
     if (step.show?.spotlight && e.target) {
       spotlights.push({ startMs: e.actionMs, endMs: e.settledMs, rect: pad(e.target, SPOTLIGHT_PAD) });
     }
   }
 
+  const camera = buildCamera(regions);
+  const win = windowLayout(output, stage, style.padding, style.chrome === 'browser' ? BROWSER_BAR : 0);
+  // A caption ends when the next one starts: no overlap, so captions dip instead of colliding.
+  drafts.sort((a, b) => a.startMs - b.startMs);
+  drafts.forEach((d, i) => {
+    const next = drafts[i + 1];
+    if (next) d.endMs = Math.min(d.endMs, next.startMs);
+  });
+  const captions: Caption[] = drafts
+    .filter((d) => d.endMs > d.startMs)
+    .map((d) => ({ startMs: d.startMs, endMs: d.endMs, text: d.text, position: captionPosition(d.target, d, camera, stage, win, output) }));
+
   return {
     version: 1,
     fps: opts.fps ?? 30,
-    output: opts.output ?? { width: 1920, height: 1080 },
+    output,
     stage,
     video: { src: ev.video.file, durationMs: ev.video.durationMs },
     intro: script.meta.title ? { title: script.meta.title, subtitle: script.meta.subtitle, durationMs: INTRO_MS } : null,
@@ -92,8 +130,10 @@ export function buildTimeline(script: Script, ev: TakeEvents, opts: BuildOptions
       style.chrome === 'browser'
         ? { address: style.address ?? displayAddress(script.app.url), dark: script.app.colorScheme === 'dark' }
         : null,
+    outro: script.meta.outro ? { ...script.meta.outro, durationMs: OUTRO_MS } : null,
+    logo: opts.logo ?? null,
     segments: buildSegments(ev.video.durationMs, spans),
-    camera: buildCamera(regions),
+    camera,
     moves: ev.moves,
     clicks: ev.clicks,
     captions,