@mineo71/showtime 0.2.1 → 0.4.0

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':
@@ -191,6 +193,7 @@ async function typeText(ctx: StepContext, text: string, pace: 'human' | 'fast' |
   const rand = rng(text);
   for (const ch of text) {
     await ctx.page.keyboard.type(ch);
+    ctx.log.keys.push(ctx.log.now());
     await sleep(typeof pace === 'number' ? pace : 45 + rand() * 65);
   }
 }

package/src/script/config.ts

@@ -0,0 +1,74 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { AudioSchema, 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;
+  audio?: 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(),
+    audio: AudioSchema.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, audio.music.file) 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, audio } = raw as BrandConfig;
+  const dir = path.dirname(file);
+  return { style, meta: withLogoFrom(meta, dir), audio: withMusicFrom(audio, dir) };
+}
+
+/** 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) };
+}
+
+/** audio with `music.file` made absolute against `dir` (when it is a string). */
+export function withMusicFrom(audio: Json | undefined, dir: string): Json | undefined {
+  const music = audio?.music;
+  if (!isObject(music) || typeof music.file !== 'string') return audio;
+  return { ...audio, music: { ...music, file: path.resolve(dir, music.file) } };
+}
+
+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`, `meta` and `audio`. */
+export function applyConfig(config: BrandConfig, raw: Json): Json {
+  const merged: Json = { ...raw };
+  for (const key of ['style', 'meta', 'audio'] as const) {
+    const defaults = config[key];
+    if (defaults) merged[key] = isObject(raw[key]) ? { ...defaults, ...raw[key] } : (raw[key] ?? defaults);
+  }
+  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, withMusicFrom } 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,23 @@ 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 (own.audio && typeof own.audio === 'object') own.audio = withMusicFrom(own.audio 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}`);
+  const music = script.audio.music?.file;
+  if (music && !existsSync(music)) throw new ScriptError(`audio.music.file not found: ${music}`);
   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

@@ -15,6 +15,11 @@ export const ShowSchema = z
     spotlight: z.boolean().optional().describe('Dim everything except the target'),
     hold: z.number().int().min(0).max(30_000).optional().describe('Extra real-time ms after the step'),
     speed: z.number().min(0.25).max(16).optional().describe('Playback speed for this step'),
+    say: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('Narration spoken from the start of this step; the video waits for it before the next narrated step'),
   })
   .strict();
 
@@ -69,6 +74,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 +105,94 @@ 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();
+
+export const VoiceSchema = z
+  .object({
+    engine: z
+      .enum(['system', 'openai', 'elevenlabs', 'command'])
+      .default('system')
+      .describe('system: macOS say / Linux espeak-ng; openai and elevenlabs read OPENAI_API_KEY / ELEVENLABS_API_KEY'),
+    name: z.string().min(1).optional().describe('Voice name (system, openai) or voice id (elevenlabs)'),
+    speed: z.number().min(0.5).max(2).default(1),
+    model: z.string().min(1).optional().describe('openai: gpt-4o-mini-tts by default; elevenlabs: eleven_multilingual_v2'),
+    instructions: z.string().min(1).optional().describe('openai only: how to speak, e.g. "warm and confident"'),
+    command: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('command engine: shell command that reads the text on stdin and writes audio to {out}'),
+  })
+  .strict()
+  .superRefine((v, ctx) => {
+    if (v.engine === 'elevenlabs' && !v.name) {
+      ctx.addIssue({ code: 'custom', path: ['name'], message: 'elevenlabs needs a voice id in "name"' });
+    }
+    if (v.engine === 'command' && !v.command) {
+      ctx.addIssue({ code: 'custom', path: ['command'], message: 'the command engine needs "command"' });
+    }
+  });
+
+export const AudioSchema = z
+  .object({
+    voice: VoiceSchema.prefault({}).describe('Text-to-speech for show.say'),
+    music: z
+      .object({
+        file: z.string().min(1).describe('Audio file, relative to the file that names it'),
+        volume: z.number().min(0).max(1).default(0.25),
+      })
+      .strict()
+      .optional()
+      .describe('Music bed under the whole video; ducks while the voice speaks'),
+    sounds: z.boolean().default(false).describe('Click and keystroke sounds'),
+    subtitles: z
+      .enum(['off', 'file', 'burn'])
+      .default('file')
+      .describe('Narration subtitles: an .srt next to the video (file), also drawn on the video (burn), or none'),
   })
   .strict();
 
@@ -99,10 +207,12 @@ 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({}),
+    audio: AudioSchema.prefault({}),
     scenes: z.array(SceneSchema).min(1),
   })
   .strict()
@@ -121,6 +231,10 @@ 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 type Audio = z.output<typeof AudioSchema>;
+export type Voice = z.output<typeof VoiceSchema>;
 
 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,32 @@
 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, OUTPUT_SIZES, projectRect, viewLayout, visibleFraction, type View } from './layout';
 import { clamp } from './math';
-import { buildSegments, type SpeedSpan } from './timemap';
-import type { Caption, Rect, Spotlight, StepEvent, TakeEvents, Timeline } from './types';
+import { RIPPLE_MS } from './cursor';
+import { CAPTION_FADE_MS, SPOTLIGHT_FADE_MS } from './fades';
+import { soundEvents, stepKey, subtitleCues, withNarration, type Span, type Typing } from './narration';
+import { buildSegments, sourceToOutput, type SpeedSpan } from './timemap';
+import type { Aspect, CameraKey, Caption, NarrationLine, 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 ZOOMABLE = new Set<Step['do']>(['click', 'type', 'select', 'hover']);
 
 export interface BuildOptions {
   fps?: number;
-  output?: { width: number; height: number };
+  /** 16:9 by default; 9:16 and 1:1 crop the viewport and follow the action. */
+  aspect?: Aspect;
+  /** Logo as a data URI. */
+  logo?: string;
+  /** Length of each synthesized `show.say` line, by step (`scene#n`); lines without one are left out. */
+  voices?: Record<string, number>;
 }
 
 function stepOf(script: Script, e: StepEvent): Step {
@@ -33,11 +45,36 @@ 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: View,
+  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 aspect = opts.aspect ?? '16:9';
+  const output = OUTPUT_SIZES[aspect];
+  const win = viewLayout(output, stage, style.padding, style.chrome === 'browser' ? BROWSER_BAR : 0, aspect);
+  const visible = visibleFraction(win);
+  // Cropped formats follow every target; a zoom only adds what the crop doesn't already magnify.
+  const crop = aspect !== '16:9';
+  const cropDepth = Math.min(visible.x, visible.y);
   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,14 +93,15 @@ 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;
     const wantsZoom = typeof zoom === 'number' || (zoom === undefined && style.autoZoom && ZOOMABLE.has(step.do));
-    if (e.target && wantsZoom) {
-      const scale = typeof zoom === 'number' ? zoom : zoomDepth(e.target, stage, style.maxZoom);
-      if (scale >= MIN_ZOOM) {
+    if (e.target && (wantsZoom || crop)) {
+      const depth = wantsZoom ? (typeof zoom === 'number' ? zoom : zoomDepth(e.target, stage, style.maxZoom)) : 1;
+      const scale = crop ? Math.max(1, depth * cropDepth) : depth;
+      if (scale >= MIN_ZOOM || crop) {
         regions.push({
           startMs: e.actionMs,
           endMs: e.settledMs,
@@ -74,30 +112,92 @@ 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 lines = pairs.flatMap(({ e, step }) => {
+    const where = stepKey(e.sceneId, e.index);
+    const durationMs = opts.voices?.[where];
+    return step.show?.say && durationMs !== undefined ? [{ where, text: step.show.say, startMs: e.startMs, durationMs }] : [];
+  });
+  const subtitlesBurned = script.audio.subtitles === 'burn' && lines.length > 0;
+
+  const camera = buildCamera(regions, { visible, hold: crop });
+  // 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,
+      // 9:16 captions sit in the band under the window, clear of the action.
+      position: subtitlesBurned ? 'top' : aspect === '9:16' ? 'bottom' : captionPosition(d.target, d, camera, stage, win, output),
+    }));
+
+  // Narration holds freeze the frame, so they go where nothing is moving: not during an action,
+  // a cursor move, a ripple, a camera move or a fade.
+  const fades = (x: { startMs: number; endMs: number }, ms: number) => [
+    { startMs: x.startMs, endMs: x.startMs + ms },
+    { startMs: x.endMs - ms, endMs: x.endMs },
+  ];
+  const busy: Span[] = [
+    ...pairs.filter(({ step }) => step.do !== 'pause').map(({ e }) => ({ startMs: e.startMs, endMs: e.endMs })),
+    ...ev.moves,
+    ...ev.clicks.map((c) => ({ startMs: c.tMs, endMs: c.tMs + RIPPLE_MS })),
+    ...camera.slice(1).flatMap((b, i) => {
+      const a = camera[i];
+      return a.scale !== b.scale || a.cx !== b.cx || a.cy !== b.cy ? [{ startMs: a.tMs, endMs: b.tMs }] : [];
+    }),
+    ...captions.flatMap((c) => fades(c, CAPTION_FADE_MS)),
+    ...spotlights.flatMap((s) => fades(s, SPOTLIGHT_FADE_MS)),
+  ];
+  const segments = withNarration(buildSegments(ev.video.durationMs, spans), lines, ev.video.durationMs, busy);
+  const narration: NarrationLine[] = lines.map((l) => ({
+    where: l.where,
+    text: l.text,
+    atMs: Math.round(sourceToOutput(segments, l.startMs)),
+    durationMs: l.durationMs,
+  }));
+  const subtitles = script.audio.subtitles === 'off' ? [] : narration.flatMap((n) => subtitleCues(n.text, n.atMs, n.durationMs));
+  const typing: Typing[] = pairs.flatMap(({ e, step }) =>
+    step.do === 'type' && step.pace !== 'fast' ? [{ startMs: e.actionMs, endMs: e.endMs, chars: [...step.text].length }] : [],
+  );
+
   return {
     version: 1,
     fps: opts.fps ?? 30,
-    output: opts.output ?? { width: 1920, height: 1080 },
+    aspect,
+    output,
     stage,
-    video: { src: ev.video.file, durationMs: ev.video.durationMs },
+    video: { src: `take/${ev.video.file}`, durationMs: ev.video.durationMs },
     intro: script.meta.title ? { title: script.meta.title, subtitle: script.meta.subtitle, durationMs: INTRO_MS } : null,
     chrome:
       style.chrome === 'browser'
         ? { address: style.address ?? displayAddress(script.app.url), dark: script.app.colorScheme === 'dark' }
         : null,
-    segments: buildSegments(ev.video.durationMs, spans),
-    camera: buildCamera(regions),
+    outro: script.meta.outro ? { ...script.meta.outro, durationMs: OUTRO_MS } : null,
+    logo: opts.logo ?? null,
+    segments,
+    camera,
     moves: ev.moves,
     clicks: ev.clicks,
     captions,
     spotlights,
+    narration,
+    subtitles,
+    subtitlesBurned,
+    sounds: script.audio.sounds ? soundEvents(ev, typing, segments) : [],
+    music: script.audio.music ? { volume: script.audio.music.volume } : null,
+    audio: null,
     style,
   };
 }

package/src/timeline/camera.ts

@@ -19,14 +19,33 @@ export function zoomDepth(target: Rect, stage: { width: number; height: number }
   return clamp(fit, 1, maxZoom);
 }
 
-export function clampFocus(scale: number, cx: number, cy: number): { cx: number; cy: number } {
-  const half = 0.5 / scale;
-  return { cx: clamp(cx, half, 1 - half), cy: clamp(cy, half, 1 - half) };
+/** Share of the content visible at scale 1, per axis: 1 unless the format crops the viewport. */
+export interface Visible {
+  x: number;
+  y: number;
+}
+
+const FULL: Visible = { x: 1, y: 1 };
+
+/** Keep the focus where the visible part stays inside the content. */
+export function clampFocus(scale: number, cx: number, cy: number, visible: Visible = FULL): { cx: number; cy: number } {
+  const hx = Math.min(0.5, visible.x / (2 * scale));
+  const hy = Math.min(0.5, visible.y / (2 * scale));
+  return { cx: clamp(cx, hx, 1 - hx), cy: clamp(cy, hy, 1 - hy) };
 }
 
 const rest = (tMs: number): CameraKey => ({ tMs, scale: 1, cx: 0.5, cy: 0.5 });
 
-export function buildCamera(regions: ZoomRegion[]): CameraKey[] {
+export interface CameraOptions {
+  visible?: Visible;
+  /** Between regions keep the last focus (at scale 1) instead of returning to the centre: the follow camera of cropped formats. */
+  hold?: boolean;
+}
+
+export function buildCamera(regions: ZoomRegion[], opts: CameraOptions = {}): CameraKey[] {
+  const visible = opts.visible ?? FULL;
+  let last = { cx: 0.5, cy: 0.5 };
+  const restAt = (tMs: number): CameraKey => (opts.hold ? { tMs, scale: 1, ...clampFocus(1, last.cx, last.cy, visible) } : rest(tMs));
   const rs = [...regions].sort((a, b) => a.startMs - b.startMs);
   const keys: CameraKey[] = [];
   rs.forEach((r, i) => {
@@ -34,14 +53,15 @@ export function buildCamera(regions: ZoomRegion[]): CameraKey[] {
     const next = rs[i + 1];
     const start = prev ? Math.max(r.startMs, prev.endMs) : r.startMs;
     const end = Math.max(start, r.endMs);
-    const focus = clampFocus(r.scale, r.cx, r.cy);
+    const focus = clampFocus(r.scale, r.cx, r.cy, visible);
     if (!prev || start - prev.endMs > CONNECT_GAP_MS) {
       const lastT = keys.length ? keys[keys.length - 1].tMs : 0;
-      keys.push(rest(Math.max(lastT, start - ZOOM_LEAD_MS)));
+      keys.push(restAt(Math.max(lastT, start - ZOOM_LEAD_MS)));
     }
     keys.push({ tMs: start, scale: r.scale, ...focus });
     keys.push({ tMs: end, scale: r.scale, ...focus });
-    if (!next || next.startMs - end > CONNECT_GAP_MS) keys.push(rest(end + ZOOM_LEAD_MS));
+    last = focus;
+    if (!next || next.startMs - end > CONNECT_GAP_MS) keys.push(restAt(end + ZOOM_LEAD_MS));
   });
   return keys;
 }
@@ -60,10 +80,13 @@ export function cameraAt(keys: CameraKey[], tMs: number): CameraKey {
   return { ...keys[keys.length - 1], tMs };
 }
 
-/** CSS transform (transform-origin 0 0) that puts the focus point at the centre of a width×height box. */
-export function cameraTransform(cam: CameraKey, width: number, height: number): string {
-  const tx = width / 2 - cam.cx * width * cam.scale;
-  const ty = height / 2 - cam.cy * height * cam.scale;
+/**
+ * CSS transform (transform-origin 0 0) for content of `content` size that puts the focus point at
+ * the centre of a width×height window (content defaults to the window's size).
+ */
+export function cameraTransform(cam: CameraKey, width: number, height: number, content = { width, height }): string {
+  const tx = width / 2 - cam.cx * content.width * cam.scale;
+  const ty = height / 2 - cam.cy * content.height * cam.scale;
   const r = (v: number) => Math.round(v * 100) / 100 + 0;
   return `translate(${r(tx)}px, ${r(ty)}px) scale(${r(cam.scale * 1000) / 1000})`;
 }

package/src/timeline/fades.ts

@@ -0,0 +1,3 @@
+/** Fade lengths shared by the renderer and the timeline (holds must not freeze a fade). */
+export const CAPTION_FADE_MS = 220;
+export const SPOTLIGHT_FADE_MS = 250;