@mineo71/showtime 0.0.0-stage → 0.2.1

package/src/runner/steps.ts

@@ -0,0 +1,217 @@
+import type { Locator, Page } from 'playwright';
+import type { Step } from '../script/schema';
+import { clamp, easeInOutCubic } from '../timeline/math';
+import type { CursorKind, Pt, Rect } from '../timeline/types';
+import type { NetworkTracker } from './browser';
+import type { EventLog } from './events';
+import { rng, sleep } from './time';
+
+export type Mode = 'record' | 'check';
+
+export interface StepContext {
+  page: Page;
+  mode: Mode;
+  log: EventLog;
+  net: NetworkTracker;
+  cursor: Pt;
+}
+
+export interface StepWhere {
+  sceneId: string;
+  index: number;
+}
+
+export const STEP_TIMEOUT_MS = 10_000;
+export const WAIT_TIMEOUT_MS = 15_000;
+export const BEAT_MS = 450;
+const NET_QUIET_MS = 300;
+const NET_CAP_MS = 3000;
+const IDLE_GRACE_MS = 300;
+
+export class StepError extends Error {
+  constructor(
+    message: string,
+    readonly where: StepWhere,
+    readonly step: Step,
+  ) {
+    super(message);
+    this.name = 'StepError';
+  }
+}
+
+export function describeStep(step: Step): string {
+  if ('target' in step && step.target) return `${step.do} ${step.target}`;
+  if (step.do === 'wait') return step.for ? `wait ${step.for}` : `wait ${step.ms} ms`;
+  if (step.do === 'goto') return `goto ${step.url}`;
+  if (step.do === 'press') return `press ${step.key}`;
+  if (step.do === 'pause') return `pause ${step.ms} ms`;
+  if (step.do === 'scroll') return `scroll ${step.by}px`;
+  return step.do;
+}
+
+export async function runStep(ctx: StepContext, step: Step, where: StepWhere): Promise<void> {
+  try {
+    await perform(ctx, step, where);
+  } catch (err) {
+    if (err instanceof StepError) throw err;
+    const message = (err as Error).message.split('\n').filter(Boolean).slice(0, 4).join('\n');
+    throw new StepError(`Scene "${where.sceneId}" step ${where.index + 1} (${describeStep(step)}): ${message}`, where, step);
+  }
+}
+
+const centre = (r: Rect): Pt => ({ x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) });
+
+async function perform(ctx: StepContext, step: Step, where: StepWhere): Promise<void> {
+  const { page, log } = ctx;
+  const startMs = log.now();
+  let actionMs = startMs;
+  let target: Rect | undefined;
+
+  switch (step.do) {
+    case 'goto':
+      await page.goto(step.url, { waitUntil: 'load', timeout: WAIT_TIMEOUT_MS });
+      break;
+    case 'click':
+    case 'hover':
+    case 'select':
+    case 'type': {
+      const r = await resolve(ctx, step.target, false);
+      target = r.box;
+      let point = centre(r.box);
+      await travel(ctx, point, r.cursor);
+      // The page may have shifted during travel (late layout, animation): follow the element.
+      const now = await r.loc.boundingBox();
+      if (now && (Math.abs(now.x - target.x) > 2 || Math.abs(now.y - target.y) > 2)) {
+        target = now;
+        point = centre(now);
+        await travel(ctx, point, r.cursor);
+      }
+      actionMs = log.now();
+      if (step.do !== 'hover') log.clicks.push({ tMs: actionMs, ...point });
+      if (step.do === 'click') await r.loc.click({ timeout: STEP_TIMEOUT_MS });
+      if (step.do === 'select') await r.loc.selectOption(step.value, { timeout: STEP_TIMEOUT_MS });
+      if (step.do === 'type') {
+        await r.loc.click({ timeout: STEP_TIMEOUT_MS });
+        if (step.clear) await r.loc.fill('');
+        await typeText(ctx, step.text, step.pace);
+      }
+      break;
+    }
+    case 'press':
+      await page.keyboard.press(step.key);
+      break;
+    case 'scroll':
+      if (step.target) target = (await resolve(ctx, step.target, true)).box;
+      else await wheel(ctx, step.by ?? 0);
+      break;
+    case 'wait':
+      if (step.for) await page.locator(step.for).waitFor({ state: 'visible', timeout: WAIT_TIMEOUT_MS });
+      else await sleep(step.ms ?? 0);
+      break;
+    case 'pause':
+      if (ctx.mode === 'record') await sleep(step.ms);
+      break;
+  }
+
+  const endMs = log.now();
+  if (step.do === 'wait' || step.do === 'goto') log.idle.push({ startMs, endMs });
+  await settle(ctx, step);
+  log.steps.push({ ...where, do: step.do, startMs, actionMs, endMs, settledMs: log.now(), target });
+}
+
+async function resolve(ctx: StepContext, selector: string, forceScroll: boolean) {
+  const loc = ctx.page.locator(selector);
+  await loc.waitFor({ state: 'visible', timeout: STEP_TIMEOUT_MS });
+  // Visible fraction within the viewport, clipped by scrollable ancestors (a list or modal body too).
+  const visible = await loc.evaluate(
+    (el) =>
+      new Promise<number>((done) => {
+        const io = new IntersectionObserver((entries) => {
+          io.disconnect();
+          done(entries[0].intersectionRatio);
+        });
+        io.observe(el);
+      }),
+  );
+  if (forceScroll || visible < 0.99) {
+    const smooth = ctx.mode === 'record';
+    await loc.evaluate(
+      (el, s) => el.scrollIntoView({ behavior: (s ? 'smooth' : 'instant') as ScrollBehavior, block: 'center', inline: 'nearest' }),
+      smooth,
+    );
+  }
+  const box = await stableBox(loc);
+  const css = await loc.evaluate((el) => getComputedStyle(el).cursor);
+  const cursor: CursorKind = css === 'text' ? 'text' : css === 'pointer' ? 'pointer' : 'arrow';
+  return { loc, box, cursor };
+}
+
+/** Wait (max ~2 s) until the element stops moving, e.g. after smooth scrolling or an opening animation. */
+async function stableBox(loc: Locator): Promise<Rect> {
+  let prev = await loc.boundingBox();
+  for (let i = 0; i < 40; i++) {
+    await sleep(50);
+    const next = await loc.boundingBox();
+    if (prev && next && Math.abs(prev.x - next.x) < 0.5 && Math.abs(prev.y - next.y) < 0.5 && Math.abs(prev.width - next.width) < 0.5) {
+      return next;
+    }
+    prev = next;
+  }
+  if (!prev) throw new Error('element has no bounding box (hidden or detached)');
+  return prev;
+}
+
+async function travel(ctx: StepContext, to: Pt, cursor: CursorKind): Promise<void> {
+  const from = ctx.cursor;
+  if (ctx.mode === 'check') {
+    await ctx.page.mouse.move(to.x, to.y);
+    ctx.cursor = to;
+    return;
+  }
+  const dist = Math.hypot(to.x - from.x, to.y - from.y);
+  const duration = clamp(350 + dist * 0.35, 350, 900);
+  const startMs = ctx.log.now();
+  const t0 = Date.now();
+  const n = Math.max(2, Math.round(duration / 16));
+  for (let i = 1; i <= n; i++) {
+    const e = easeInOutCubic(i / n);
+    await ctx.page.mouse.move(from.x + (to.x - from.x) * e, from.y + (to.y - from.y) * e);
+    const wait = t0 + (duration * i) / n - Date.now();
+    if (wait > 0) await sleep(wait);
+  }
+  ctx.log.moves.push({ startMs, endMs: ctx.log.now(), from, to, cursor });
+  ctx.cursor = to;
+}
+
+async function typeText(ctx: StepContext, text: string, pace: 'human' | 'fast' | number): Promise<void> {
+  if (ctx.mode === 'check' || pace === 'fast') {
+    await ctx.page.keyboard.type(text);
+    return;
+  }
+  const rand = rng(text);
+  for (const ch of text) {
+    await ctx.page.keyboard.type(ch);
+    await sleep(typeof pace === 'number' ? pace : 45 + rand() * 65);
+  }
+}
+
+async function wheel(ctx: StepContext, by: number): Promise<void> {
+  if (ctx.mode === 'check') {
+    await ctx.page.mouse.wheel(0, by);
+    await sleep(100);
+    return;
+  }
+  const n = 14;
+  for (let i = 0; i < n; i++) {
+    await ctx.page.mouse.wheel(0, by / n);
+    await sleep(40);
+  }
+}
+
+async function settle(ctx: StepContext, step: Step): Promise<void> {
+  const s = ctx.log.now();
+  await ctx.net.idle(NET_QUIET_MS, NET_CAP_MS);
+  const waited = ctx.log.now() - s;
+  if (waited > IDLE_GRACE_MS) ctx.log.idle.push({ startMs: s + IDLE_GRACE_MS, endMs: s + waited });
+  if (ctx.mode === 'record') await sleep(BEAT_MS + (step.show?.hold ?? 0));
+}

package/src/runner/time.ts

@@ -0,0 +1,17 @@
+export const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+
+/** Deterministic PRNG (mulberry32) seeded from a string, so re-takes type with the same rhythm. */
+export function rng(seed: string): () => number {
+  let h = 1779033703 ^ seed.length;
+  for (let i = 0; i < seed.length; i++) {
+    h = Math.imul(h ^ seed.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  let a = h >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/src/script/hash.ts

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import type { Script, Step } from './schema';
+
+/** Everything that changes what gets recorded: the step minus `show`, plus `show.hold`. */
+function actionsOf(step: Step): Record<string, unknown> {
+  const { show, ...rest } = step;
+  return show?.hold ? { ...rest, hold: show.hold } : rest;
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj)
+      .filter((k) => obj[k] !== undefined)
+      .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function actionHash(script: Script): string {
+  const payload = {
+    app: script.app,
+    setup: script.setup.map(actionsOf),
+    scenes: script.scenes.map((s) => ({ id: s.id, steps: s.steps.map(actionsOf) })),
+  };
+  return createHash('sha256').update(canonical(payload)).digest('hex');
+}

package/src/script/load.ts

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseScript, ScriptError, type Script } from './schema';
+
+export interface LoadedScript {
+  script: Script;
+  scriptPath: string;
+  dir: string;
+  name: string;
+}
+
+export async function loadScript(file: string): Promise<LoadedScript> {
+  const scriptPath = path.resolve(file);
+  let text: string;
+  try {
+    text = await readFile(scriptPath, 'utf8');
+  } catch {
+    throw new ScriptError(`Cannot read script: ${scriptPath}`);
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new ScriptError(`Invalid JSON in ${scriptPath}: ${(err as Error).message}`);
+  }
+  const script = parseScript(raw, scriptPath);
+  const dir = path.dirname(scriptPath);
+  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, '') };
+}

package/src/script/schema.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+
+const target = z
+  .string()
+  .min(1)
+  .describe("Playwright selector, e.g. role=button[name='Save'], text=Save, #id, [data-testid=x], CSS");
+
+export const ShowSchema = z
+  .object({
+    zoom: z
+      .union([z.number().min(1).max(4), z.literal(false)])
+      .optional()
+      .describe('Zoom depth for this step, or false to disable auto-zoom'),
+    caption: z.string().min(1).optional().describe('Caption shown while this step plays'),
+    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'),
+  })
+  .strict();
+
+const show = ShowSchema.optional();
+
+const exactlyOne = (a: string, b: string) => (s: Record<string, unknown>) =>
+  (s[a] === undefined) !== (s[b] === undefined);
+
+export const StepSchema = z.discriminatedUnion('do', [
+  z.object({ do: z.literal('goto'), url: z.string().min(1), show }).strict(),
+  z.object({ do: z.literal('click'), target, show }).strict(),
+  z
+    .object({
+      do: z.literal('type'),
+      target,
+      text: z.string(),
+      pace: z.union([z.enum(['human', 'fast']), z.number().int().min(0).max(1000)]).default('human'),
+      clear: z.boolean().default(false),
+      show,
+    })
+    .strict(),
+  z.object({ do: z.literal('press'), key: z.string().min(1), show }).strict(),
+  z.object({ do: z.literal('hover'), target, show }).strict(),
+  z.object({ do: z.literal('select'), target, value: z.string(), show }).strict(),
+  z
+    .object({ do: z.literal('scroll'), target: target.optional(), by: z.number().int().optional(), show })
+    .strict()
+    .refine(exactlyOne('target', 'by'), { message: 'scroll needs exactly one of "target" or "by"' }),
+  z
+    .object({ do: z.literal('wait'), for: target.optional(), ms: z.number().int().min(0).max(60_000).optional(), show })
+    .strict()
+    .refine(exactlyOne('for', 'ms'), { message: 'wait needs exactly one of "for" or "ms"' }),
+  z.object({ do: z.literal('pause'), ms: z.number().int().min(0).max(60_000), show }).strict(),
+]);
+
+export const StyleSchema = z
+  .object({
+    background: z.string().default('linear-gradient(135deg, #0f172a 0%, #312e81 100%)'),
+    padding: z.number().min(0).max(0.3).default(0.06),
+    radius: z.number().min(0).max(64).default(14),
+    shadow: z.boolean().default(true),
+    font: z.string().default('Inter, -apple-system, "Segoe UI", system-ui, sans-serif'),
+    accent: z.string().default('#6366f1'),
+    autoZoom: z.boolean().default(true),
+    autoSpeed: z.boolean().default(true),
+    maxZoom: z.number().min(1).max(4).default(1.8),
+    chrome: z
+      .enum(['browser', 'none'])
+      .default('browser')
+      .describe('Frame the recording in a browser window with an address bar, or show the bare viewport'),
+    address: z.string().optional().describe('Address-bar text; defaults to the app URL without its scheme'),
+  })
+  .strict();
+
+export const AppSchema = z
+  .object({
+    url: z.string().min(1),
+    viewport: z
+      .object({ width: z.number().int().min(320).max(3840), height: z.number().int().min(240).max(2160) })
+      .strict()
+      .default({ width: 1440, height: 900 }),
+    deviceScaleFactor: z.number().min(1).max(3).default(2),
+    storageState: z.string().optional(),
+    colorScheme: z.enum(['light', 'dark']).optional(),
+    locale: z.string().optional(),
+    timezoneId: z.string().optional(),
+    mask: z
+      .array(z.string().min(1))
+      .default([])
+      .describe('CSS selectors (not Playwright selectors) of elements to blur in the recording'),
+  })
+  .strict();
+
+export const SceneSchema = z
+  .object({
+    id: z.string().regex(/^[A-Za-z0-9_-]+$/, 'scene id may contain letters, digits, "-" and "_"'),
+    steps: z.array(StepSchema).min(1),
+  })
+  .strict();
+
+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({}),
+    app: AppSchema,
+    setup: z.array(StepSchema).default([]),
+    style: StyleSchema.prefault({}),
+    scenes: z.array(SceneSchema).min(1),
+  })
+  .strict()
+  .superRefine((s, ctx) => {
+    const seen = new Set<string>();
+    s.scenes.forEach((scene, i) => {
+      if (seen.has(scene.id)) {
+        ctx.addIssue({ code: 'custom', path: ['scenes', i, 'id'], message: `duplicate scene id "${scene.id}"` });
+      }
+      seen.add(scene.id);
+    });
+  });
+
+export type Script = z.output<typeof ScriptSchema>;
+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 class ScriptError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ScriptError';
+  }
+}
+
+export function formatIssues(issues: ReadonlyArray<{ path: PropertyKey[]; message: string }>): string {
+  return issues.map((i) => `  - ${i.path.length ? i.path.map(String).join('.') : '(root)'}: ${i.message}`).join('\n');
+}
+
+export function parseScript(raw: unknown, source = 'script'): Script {
+  const result = ScriptSchema.safeParse(raw);
+  if (!result.success) throw new ScriptError(`Invalid ${source}:\n${formatIssues(result.error.issues)}`);
+  return result.data;
+}
+
+export function scriptJsonSchema(): Record<string, unknown> {
+  return z.toJSONSchema(ScriptSchema, { io: 'input', unrepresentable: 'any' }) as Record<string, unknown>;
+}

package/src/setup.ts

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import { lstatSync, mkdirSync, symlinkSync, unlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const SKILL_DIR = fileURLToPath(new URL('../skill', import.meta.url));
+
+/** Where each agent looks for user skills (relative to the home folder). Codex reads the shared ~/.agents/skills. */
+export const SKILL_HOMES = { claude: '.claude/skills', codex: '.agents/skills' } as const;
+export type Agent = keyof typeof SKILL_HOMES;
+export const AGENTS = Object.keys(SKILL_HOMES) as Agent[];
+
+/** Symlink the skill into each agent's skills folder; returns the links. Re-linking our own link is fine. */
+export function linkSkill(agents: Agent[], home = homedir(), source = SKILL_DIR): string[] {
+  return agents.map((agent) => {
+    const dir = path.join(home, SKILL_HOMES[agent]);
+    const dest = path.join(dir, 'showtime');
+    mkdirSync(dir, { recursive: true });
+    const existing = lstatSync(dest, { throwIfNoEntry: false });
+    if (existing && !existing.isSymbolicLink()) throw new Error(`${dest} exists and is not a symlink — move it away first.`);
+    if (existing) unlinkSync(dest);
+    symlinkSync(source, dest, 'junction');
+    return dest;
+  });
+}
+
+/** Download the Chromium build this copy of Playwright drives, and Remotion's headless shell. */
+export async function installBrowsers(): 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' });
+    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();
+}

package/src/take.ts

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { workPaths } from './paths';
+import { actionHash } from './script/hash';
+import type { LoadedScript } from './script/load';
+import type { TakeEvents } from './timeline/types';
+
+export async function loadTake(loaded: LoadedScript): Promise<TakeEvents> {
+  const paths = workPaths(loaded);
+  let text: string;
+  try {
+    text = await readFile(paths.events, 'utf8');
+  } catch {
+    throw new Error(`No take found for "${loaded.name}". Run: showtime record ${loaded.scriptPath}`);
+  }
+  const events = JSON.parse(text) as TakeEvents;
+  if (events.actionHash !== actionHash(loaded.script)) {
+    throw new Error(`Actions changed since the take (presentation-only edits are fine). Run: showtime record ${loaded.scriptPath}`);
+  }
+  const video = path.join(paths.take, events.video.file);
+  if (!existsSync(video)) throw new Error(`${video} is missing. Run: showtime record ${loaded.scriptPath}`);
+  return events;
+}

package/src/timeline/build.ts

@@ -0,0 +1,103 @@
+import type { Script, Step } from '../script/schema';
+import { buildCamera, MIN_ZOOM, zoomDepth, type ZoomRegion } from './camera';
+import { clamp } from './math';
+import { buildSegments, type SpeedSpan } from './timemap';
+import type { 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;
+
+const ZOOMABLE = new Set<Step['do']>(['click', 'type', 'select', 'hover']);
+
+export interface BuildOptions {
+  fps?: number;
+  output?: { width: number; height: number };
+}
+
+function stepOf(script: Script, e: StepEvent): Step {
+  const step = script.scenes.find((s) => s.id === e.sceneId)?.steps[e.index];
+  if (!step) throw new Error(`Take does not match the script: no step ${e.index + 1} in scene "${e.sceneId}"`);
+  return step;
+}
+
+/** "https://app.acme.com/reports/" → "app.acme.com/reports". */
+function displayAddress(url: string): string {
+  try {
+    const u = new URL(url);
+    return (u.host + u.pathname).replace(/\/$/, '');
+  } catch {
+    return url;
+  }
+}
+
+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 pairs = ev.steps.map((e) => ({ e, step: stepOf(script, e) }));
+
+  // Speed: auto idle first, explicit `show.speed` next, pauses last (later spans win).
+  const spans: SpeedSpan[] = [];
+  if (style.autoSpeed) {
+    for (const i of ev.idle) {
+      const len = i.endMs - i.startMs;
+      if (len > AUTO_SPEED_MIN_IDLE_MS) spans.push({ ...i, speed: clamp(len / AUTO_SPEED_TARGET_MS, 2, 8) });
+    }
+  }
+  for (const { e, step } of pairs) {
+    if (step.show?.speed !== undefined) spans.push({ startMs: e.startMs, endMs: e.settledMs, speed: step.show.speed });
+  }
+  for (const { e, step } of pairs) {
+    if (step.do === 'pause') spans.push({ startMs: e.startMs, endMs: e.endMs, speed: 1 });
+  }
+
+  const regions: ZoomRegion[] = [];
+  const captions: Caption[] = [];
+  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) {
+        regions.push({
+          startMs: e.actionMs,
+          endMs: e.settledMs,
+          scale,
+          cx: (e.target.x + e.target.width / 2) / stage.width,
+          cy: (e.target.y + e.target.height / 2) / stage.height,
+        });
+      }
+    }
+    if (step.show?.caption) {
+      captions.push({ startMs: e.startMs, endMs: Math.max(e.settledMs, e.startMs + CAPTION_MIN_MS), text: step.show.caption });
+    }
+    if (step.show?.spotlight && e.target) {
+      spotlights.push({ startMs: e.actionMs, endMs: e.settledMs, rect: pad(e.target, SPOTLIGHT_PAD) });
+    }
+  }
+
+  return {
+    version: 1,
+    fps: opts.fps ?? 30,
+    output: opts.output ?? { width: 1920, height: 1080 },
+    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,
+    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),
+    moves: ev.moves,
+    clicks: ev.clicks,
+    captions,
+    spotlights,
+    style,
+  };
+}

package/src/timeline/camera.ts

@@ -0,0 +1,69 @@
+import { clamp, easeInOutCubic, lerp } from './math';
+import type { CameraKey, Rect } from './types';
+
+export const ZOOM_LEAD_MS = 700;
+export const CONNECT_GAP_MS = 1500;
+export const MIN_ZOOM = 1.15;
+const ZOOM_MARGIN_PX = 160;
+
+export interface ZoomRegion {
+  startMs: number;
+  endMs: number;
+  scale: number;
+  cx: number;
+  cy: number;
+}
+
+export function zoomDepth(target: Rect, stage: { width: number; height: number }, maxZoom: number): number {
+  const fit = Math.min(stage.width / (target.width + ZOOM_MARGIN_PX), stage.height / (target.height + ZOOM_MARGIN_PX));
+  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) };
+}
+
+const rest = (tMs: number): CameraKey => ({ tMs, scale: 1, cx: 0.5, cy: 0.5 });
+
+export function buildCamera(regions: ZoomRegion[]): CameraKey[] {
+  const rs = [...regions].sort((a, b) => a.startMs - b.startMs);
+  const keys: CameraKey[] = [];
+  rs.forEach((r, i) => {
+    const prev = rs[i - 1];
+    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);
+    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({ 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));
+  });
+  return keys;
+}
+
+export function cameraAt(keys: CameraKey[], tMs: number): CameraKey {
+  if (!keys.length) return { ...rest(tMs) };
+  if (tMs <= keys[0].tMs) return { ...keys[0], tMs };
+  for (let i = 1; i < keys.length; i++) {
+    const b = keys[i];
+    if (tMs > b.tMs) continue;
+    const a = keys[i - 1];
+    if (b.tMs === a.tMs) return { ...b, tMs };
+    const e = easeInOutCubic((tMs - a.tMs) / (b.tMs - a.tMs));
+    return { tMs, scale: lerp(a.scale, b.scale, e), cx: lerp(a.cx, b.cx, e), cy: lerp(a.cy, b.cy, e) };
+  }
+  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;
+  const r = (v: number) => Math.round(v * 100) / 100 + 0;
+  return `translate(${r(tx)}px, ${r(ty)}px) scale(${r(cam.scale * 1000) / 1000})`;
+}