@argo-video/cli 0.1.0 → 0.1.1

package/docs/superpowers/plans/2026-03-12-editorial-overlay-system.md

@@ -1,1560 +0,0 @@
-# Editorial Overlay System Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Evolve Argo's single-style caption system into a zone-based overlay renderer with four templates (lower-third, headline-card, callout, image-card), a local asset server for images, and manifest-driven auto-injection.
-
-**Architecture:** Refactor `src/captions.ts` into `src/overlays/` module with zone-based DOM management (one overlay per zone, independent coexistence). Templates are pure functions that return style+HTML specs. Asset server reuses the `tests/e2e/fake-server.ts` pattern. Overlay manifest (`<demo>.overlays.json`) is loaded by the fixture and auto-injected at matching scene marks.
-
-**Tech Stack:** TypeScript ESM, Playwright (`page.evaluate` for DOM injection), Node.js `http` module (asset server), Vitest for testing.
-
-**Spec:** `docs/enhancement-proposal.md`
-
-**Security note:** Overlay templates use `container.innerHTML` to render structured content (kicker/title/body/img elements). All text fields are escaped via `escapeHtml()` before injection. This is safe because overlay content comes from author-controlled manifest files, not from end-user input. The `escapeHtml` function handles `&`, `<`, `>`, and `"` characters.
-
----
-
-## File Structure
-
-```
-src/overlays/
-  types.ts          # OverlayCue, Zone, TemplateType, MotionPreset types
-  zones.ts          # Zone management: inject/remove overlays by zone ID
-  templates.ts      # Template renderers: lower-third, headline-card, callout, image-card
-  motion.ts         # CSS animation injection: fade-in, slide-in
-  manifest.ts       # Load and validate <demo>.overlays.json
-  index.ts          # Public API: showOverlay, hideOverlay, withOverlay + re-exports
-src/asset-server.ts   # Local HTTP file server for image assets
-src/captions.ts       # Kept as thin backward-compat wrappers over overlays/
-src/index.ts          # Updated exports
-src/fixtures.ts       # Extended to load overlay manifest + auto-inject
-src/record.ts         # Extended with asset server lifecycle
-
-tests/overlays/
-  types.test.ts     # Type guard tests
-  zones.test.ts     # Zone inject/remove/replace tests
-  templates.test.ts # Template rendering tests
-  motion.test.ts    # Animation CSS generation tests
-  manifest.test.ts  # Manifest loading/validation tests
-  index.test.ts     # Public API integration tests
-tests/asset-server.test.ts  # Asset server start/stop/serve tests
-tests/captions.test.ts      # Updated: verify backward compat wrappers
-```
-
----
-
-## Chunk 1: Core Types and Zone Management
-
-### Task 1: Define overlay types
-
-**Files:**
-- Create: `src/overlays/types.ts`
-- Test: `tests/overlays/types.test.ts`
-
-- [ ] **Step 1.1: Write failing tests for type guards**
-
-```ts
-// tests/overlays/types.test.ts
-import { describe, it, expect } from 'vitest';
-import { isValidZone, isValidTemplateType, isValidMotion } from '../src/overlays/types.js';
-
-describe('isValidZone', () => {
-  it('accepts all defined zones', () => {
-    for (const z of ['bottom-center', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center']) {
-      expect(isValidZone(z)).toBe(true);
-    }
-  });
-  it('rejects unknown zones', () => {
-    expect(isValidZone('middle')).toBe(false);
-    expect(isValidZone('')).toBe(false);
-  });
-});
-
-describe('isValidTemplateType', () => {
-  it('accepts all defined types', () => {
-    for (const t of ['lower-third', 'headline-card', 'callout', 'image-card']) {
-      expect(isValidTemplateType(t)).toBe(true);
-    }
-  });
-  it('rejects unknown types', () => {
-    expect(isValidTemplateType('banner')).toBe(false);
-  });
-});
-
-describe('isValidMotion', () => {
-  it('accepts defined motions and none', () => {
-    expect(isValidMotion('fade-in')).toBe(true);
-    expect(isValidMotion('slide-in')).toBe(true);
-    expect(isValidMotion('none')).toBe(true);
-  });
-  it('rejects unknown motions', () => {
-    expect(isValidMotion('bounce')).toBe(false);
-  });
-});
-```
-
-- [ ] **Step 1.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/types.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 1.3: Implement types and guards**
-
-```ts
-// src/overlays/types.ts
-
-export const ZONES = [
-  'bottom-center',
-  'top-left',
-  'top-right',
-  'bottom-left',
-  'bottom-right',
-  'center',
-] as const;
-
-export type Zone = (typeof ZONES)[number];
-
-export const TEMPLATE_TYPES = [
-  'lower-third',
-  'headline-card',
-  'callout',
-  'image-card',
-] as const;
-
-export type TemplateType = (typeof TEMPLATE_TYPES)[number];
-
-export const MOTIONS = ['none', 'fade-in', 'slide-in'] as const;
-
-export type MotionPreset = (typeof MOTIONS)[number];
-
-export interface LowerThirdCue {
-  type: 'lower-third';
-  text: string;
-  placement?: Zone;
-  motion?: MotionPreset;
-}
-
-export interface HeadlineCardCue {
-  type: 'headline-card';
-  title: string;
-  kicker?: string;
-  body?: string;
-  placement?: Zone;
-  motion?: MotionPreset;
-}
-
-export interface CalloutCue {
-  type: 'callout';
-  text: string;
-  placement?: Zone;
-  motion?: MotionPreset;
-}
-
-export interface ImageCardCue {
-  type: 'image-card';
-  src: string;
-  title?: string;
-  body?: string;
-  placement?: Zone;
-  motion?: MotionPreset;
-}
-
-export type OverlayCue = LowerThirdCue | HeadlineCardCue | CalloutCue | ImageCardCue;
-
-export interface OverlayManifestEntry extends OverlayCue {
-  scene: string;
-}
-
-export function isValidZone(value: string): value is Zone {
-  return (ZONES as readonly string[]).includes(value);
-}
-
-export function isValidTemplateType(value: string): value is TemplateType {
-  return (TEMPLATE_TYPES as readonly string[]).includes(value);
-}
-
-export function isValidMotion(value: string): value is MotionPreset {
-  return (MOTIONS as readonly string[]).includes(value);
-}
-```
-
-- [ ] **Step 1.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/types.test.ts`
-Expected: PASS (3 tests)
-
-- [ ] **Step 1.5: Commit**
-
-```bash
-git add src/overlays/types.ts tests/overlays/types.test.ts
-git commit -m "feat(overlays): define overlay types, zones, and type guards"
-```
-
----
-
-### Task 2: Zone management (inject/remove by zone)
-
-**Files:**
-- Create: `src/overlays/zones.ts`
-- Test: `tests/overlays/zones.test.ts`
-
-- [ ] **Step 2.1: Write failing tests for zone DOM management**
-
-```ts
-// tests/overlays/zones.test.ts
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { injectIntoZone, removeZone, ZONE_ID_PREFIX } from '../src/overlays/zones.js';
-import type { Page } from '@playwright/test';
-
-function createMockPage() {
-  return {
-    evaluate: vi.fn(),
-    waitForTimeout: vi.fn(),
-  } as unknown as Page;
-}
-
-describe('ZONE_ID_PREFIX', () => {
-  it('is argo-overlay-', () => {
-    expect(ZONE_ID_PREFIX).toBe('argo-overlay-');
-  });
-});
-
-describe('injectIntoZone', () => {
-  let page: Page;
-
-  beforeEach(() => {
-    page = createMockPage();
-  });
-
-  it('calls page.evaluate with zone ID', async () => {
-    await injectIntoZone(page, 'top-left', '<div>Hello</div>', { color: 'red' });
-    expect(page.evaluate).toHaveBeenCalledTimes(1);
-    const [fn, args] = (page.evaluate as any).mock.calls[0];
-    expect(typeof fn).toBe('function');
-    expect(args[0]).toBe('argo-overlay-top-left');
-  });
-
-  it('uses bottom-center zone ID correctly', async () => {
-    await injectIntoZone(page, 'bottom-center', '<span>text</span>', {});
-    const [, args] = (page.evaluate as any).mock.calls[0];
-    expect(args[0]).toBe('argo-overlay-bottom-center');
-  });
-});
-
-describe('removeZone', () => {
-  it('calls page.evaluate to remove element by zone ID', async () => {
-    const page = createMockPage();
-    await removeZone(page, 'top-left');
-    expect(page.evaluate).toHaveBeenCalledTimes(1);
-    const [fn, arg] = (page.evaluate as any).mock.calls[0];
-    expect(typeof fn).toBe('function');
-    expect(arg).toBe('argo-overlay-top-left');
-  });
-});
-```
-
-- [ ] **Step 2.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/zones.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 2.3: Implement zone management**
-
-Zone injection uses `page.evaluate` with a function that creates a container div, sets its ID to `argo-overlay-{zone}`, applies position styles for that zone, and appends it to the document body. If an overlay already exists in that zone, it is removed first. Animation CSS keyframes are injected via a `<style>` element scoped to the zone.
-
-```ts
-// src/overlays/zones.ts
-import type { Page } from '@playwright/test';
-import type { Zone } from './types.js';
-
-export const ZONE_ID_PREFIX = 'argo-overlay-';
-
-const ZONE_POSITIONS: Record<Zone, Record<string, string>> = {
-  'bottom-center': {
-    position: 'fixed', bottom: '60px', left: '50%', transform: 'translateX(-50%)',
-  },
-  'top-left': {
-    position: 'fixed', top: '40px', left: '40px',
-  },
-  'top-right': {
-    position: 'fixed', top: '40px', right: '40px',
-  },
-  'bottom-left': {
-    position: 'fixed', bottom: '60px', left: '40px',
-  },
-  'bottom-right': {
-    position: 'fixed', bottom: '60px', right: '40px',
-  },
-  'center': {
-    position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)',
-  },
-};
-
-/**
- * Inject content into a zone. Replaces any existing overlay in that zone.
- * Uses page.evaluate to manipulate the DOM inside the browser context.
- *
- * Security: contentHtml is generated by template renderers which escape all
- * text fields via escapeHtml(). Content originates from author-controlled
- * manifest files, not end-user input.
- */
-export async function injectIntoZone(
-  page: Page,
-  zone: Zone,
-  contentHtml: string,
-  containerStyles: Record<string, string>,
-  animationCSS?: string,
-): Promise<void> {
-  const zoneId = ZONE_ID_PREFIX + zone;
-  const positionStyles = ZONE_POSITIONS[zone];
-  const baseStyles: Record<string, string> = {
-    ...positionStyles,
-    zIndex: '999999',
-    pointerEvents: 'none',
-    fontFamily: 'system-ui, -apple-system, sans-serif',
-    ...containerStyles,
-  };
-
-  await page.evaluate(([id, html, styles, css]) => {
-    const existing = document.getElementById(id);
-    if (existing) existing.remove();
-
-    if (css) {
-      const styleId = id + '-style';
-      let styleEl = document.getElementById(styleId) as HTMLStyleElement | null;
-      if (!styleEl) {
-        styleEl = document.createElement('style');
-        styleEl.id = styleId;
-        document.head.appendChild(styleEl);
-      }
-      styleEl.textContent = css;
-    }
-
-    const container = document.createElement('div');
-    container.id = id;
-    // Content is pre-escaped by template renderers
-    container.innerHTML = html;
-    Object.assign(container.style, styles);
-    document.body.appendChild(container);
-  }, [zoneId, contentHtml, baseStyles, animationCSS ?? ''] as const);
-}
-
-/**
- * Remove the overlay in the specified zone, if any.
- */
-export async function removeZone(page: Page, zone: Zone): Promise<void> {
-  const zoneId = ZONE_ID_PREFIX + zone;
-  await page.evaluate((id) => {
-    document.getElementById(id)?.remove();
-    document.getElementById(id + '-style')?.remove();
-  }, zoneId);
-}
-```
-
-- [ ] **Step 2.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/zones.test.ts`
-Expected: PASS (4 tests)
-
-- [ ] **Step 2.5: Commit**
-
-```bash
-git add src/overlays/zones.ts tests/overlays/zones.test.ts
-git commit -m "feat(overlays): zone-based DOM management with position mapping"
-```
-
----
-
-### Task 3: Motion presets
-
-**Files:**
-- Create: `src/overlays/motion.ts`
-- Test: `tests/overlays/motion.test.ts`
-
-- [ ] **Step 3.1: Write failing tests for motion CSS generation**
-
-```ts
-// tests/overlays/motion.test.ts
-import { describe, it, expect } from 'vitest';
-import { getMotionCSS, getMotionStyles } from '../src/overlays/motion.js';
-
-describe('getMotionCSS', () => {
-  it('returns empty string for none', () => {
-    expect(getMotionCSS('none', 'argo-overlay-top-left')).toBe('');
-  });
-
-  it('returns fade-in keyframes', () => {
-    const css = getMotionCSS('fade-in', 'argo-overlay-top-left');
-    expect(css).toContain('@keyframes');
-    expect(css).toContain('opacity');
-    expect(css).toContain('argo-overlay-top-left');
-  });
-
-  it('returns slide-in keyframes', () => {
-    const css = getMotionCSS('slide-in', 'argo-overlay-top-left');
-    expect(css).toContain('@keyframes');
-    expect(css).toContain('translateX');
-    expect(css).toContain('argo-overlay-top-left');
-  });
-});
-
-describe('getMotionStyles', () => {
-  it('returns empty object for none', () => {
-    expect(getMotionStyles('none', 'test-id')).toEqual({});
-  });
-
-  it('returns animation property for fade-in', () => {
-    const styles = getMotionStyles('fade-in', 'test-id');
-    expect(styles.animation).toContain('300ms');
-  });
-
-  it('returns animation property for slide-in', () => {
-    const styles = getMotionStyles('slide-in', 'test-id');
-    expect(styles.animation).toContain('400ms');
-  });
-});
-```
-
-- [ ] **Step 3.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/motion.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 3.3: Implement motion presets**
-
-```ts
-// src/overlays/motion.ts
-import type { MotionPreset } from './types.js';
-
-/**
- * Generate CSS keyframes for a motion preset, scoped to a specific element ID.
- */
-export function getMotionCSS(motion: MotionPreset, elementId: string): string {
-  const animName = `argo-${motion}-${elementId}`;
-
-  switch (motion) {
-    case 'fade-in':
-      return `@keyframes ${animName} { from { opacity: 0; } to { opacity: 1; } }`;
-    case 'slide-in':
-      return `@keyframes ${animName} { from { opacity: 0; transform: translateX(-20px); } to { opacity: 1; transform: translateX(0); } }`;
-    case 'none':
-    default:
-      return '';
-  }
-}
-
-/**
- * Return inline styles that reference the generated animation.
- */
-export function getMotionStyles(motion: MotionPreset, elementId: string): Record<string, string> {
-  const animName = `argo-${motion}-${elementId}`;
-
-  switch (motion) {
-    case 'fade-in':
-      return { animation: `${animName} 300ms ease-out forwards` };
-    case 'slide-in':
-      return { animation: `${animName} 400ms ease-out forwards` };
-    case 'none':
-    default:
-      return {};
-  }
-}
-```
-
-- [ ] **Step 3.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/motion.test.ts`
-Expected: PASS (6 tests)
-
-- [ ] **Step 3.5: Commit**
-
-```bash
-git add src/overlays/motion.ts tests/overlays/motion.test.ts
-git commit -m "feat(overlays): fade-in and slide-in motion presets"
-```
-
----
-
-## Chunk 2: Templates and Public API
-
-### Task 4: Template renderers
-
-**Files:**
-- Create: `src/overlays/templates.ts`
-- Test: `tests/overlays/templates.test.ts`
-
-- [ ] **Step 4.1: Write failing tests for template renderers**
-
-Each renderer returns `{ contentHtml: string, styles: Record<string, string> }`. Tests verify the returned HTML contains expected elements and styles contain expected properties.
-
-```ts
-// tests/overlays/templates.test.ts
-import { describe, it, expect } from 'vitest';
-import { renderTemplate } from '../src/overlays/templates.js';
-
-describe('renderTemplate', () => {
-  describe('lower-third', () => {
-    it('renders text in a styled span', () => {
-      const result = renderTemplate({ type: 'lower-third', text: 'Hello world' });
-      expect(result.contentHtml).toContain('Hello world');
-      expect(result.styles.background).toBeDefined();
-      expect(result.styles.borderRadius).toBeDefined();
-    });
-
-    it('includes maxWidth for readability', () => {
-      const result = renderTemplate({ type: 'lower-third', text: 'Test' });
-      expect(result.styles.maxWidth).toBeDefined();
-    });
-
-    it('escapes HTML in text', () => {
-      const result = renderTemplate({ type: 'lower-third', text: '<script>alert("xss")</script>' });
-      expect(result.contentHtml).not.toContain('<script>');
-      expect(result.contentHtml).toContain('&lt;script&gt;');
-    });
-  });
-
-  describe('headline-card', () => {
-    it('renders title', () => {
-      const result = renderTemplate({ type: 'headline-card', title: 'Big Title' });
-      expect(result.contentHtml).toContain('Big Title');
-    });
-
-    it('renders kicker when provided', () => {
-      const result = renderTemplate({
-        type: 'headline-card', title: 'Title', kicker: 'LABEL',
-      });
-      expect(result.contentHtml).toContain('LABEL');
-    });
-
-    it('renders body when provided', () => {
-      const result = renderTemplate({
-        type: 'headline-card', title: 'Title', body: 'Details here',
-      });
-      expect(result.contentHtml).toContain('Details here');
-    });
-
-    it('omits kicker element when not provided', () => {
-      const result = renderTemplate({ type: 'headline-card', title: 'Title' });
-      expect(result.contentHtml).not.toContain('uppercase');
-    });
-
-    it('has backdrop blur style', () => {
-      const result = renderTemplate({ type: 'headline-card', title: 'T' });
-      expect(result.styles.backdropFilter).toContain('blur');
-    });
-  });
-
-  describe('callout', () => {
-    it('renders text in a compact bubble', () => {
-      const result = renderTemplate({ type: 'callout', text: 'Note this' });
-      expect(result.contentHtml).toContain('Note this');
-      expect(result.styles.borderRadius).toBeDefined();
-    });
-  });
-
-  describe('image-card', () => {
-    it('renders img tag with src', () => {
-      const result = renderTemplate({ type: 'image-card', src: 'http://localhost:9999/diagram.png' });
-      expect(result.contentHtml).toContain('<img');
-      expect(result.contentHtml).toContain('http://localhost:9999/diagram.png');
-    });
-
-    it('renders title when provided', () => {
-      const result = renderTemplate({
-        type: 'image-card', src: 'http://x/img.png', title: 'Architecture',
-      });
-      expect(result.contentHtml).toContain('Architecture');
-    });
-
-    it('renders body when provided', () => {
-      const result = renderTemplate({
-        type: 'image-card', src: 'http://x/img.png', body: 'Description',
-      });
-      expect(result.contentHtml).toContain('Description');
-    });
-  });
-});
-```
-
-- [ ] **Step 4.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/templates.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 4.3: Implement template renderers**
-
-Templates are pure functions: they take cue fields and return `{ contentHtml, styles }`. All user-provided text is escaped via `escapeHtml()` before being interpolated into HTML strings. This is safe because overlay content comes from author-controlled manifest files, not end-user input.
-
-```ts
-// src/overlays/templates.ts
-import type { OverlayCue } from './types.js';
-
-export interface TemplateResult {
-  contentHtml: string;
-  styles: Record<string, string>;
-}
-
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
-
-function lowerThird(text: string): TemplateResult {
-  return {
-    contentHtml: `<span>${escapeHtml(text)}</span>`,
-    styles: {
-      background: 'rgba(0, 0, 0, 0.85)',
-      color: '#fff',
-      padding: '16px 32px',
-      borderRadius: '12px',
-      fontSize: '28px',
-      fontWeight: '500',
-      textAlign: 'center',
-      maxWidth: '80vw',
-      letterSpacing: '0.01em',
-      lineHeight: '1.4',
-      boxShadow: '0 4px 24px rgba(0, 0, 0, 0.3)',
-    },
-  };
-}
-
-function headlineCard(title: string, kicker?: string, body?: string): TemplateResult {
-  const parts: string[] = [];
-  if (kicker) {
-    parts.push(
-      `<div style="font-size:12px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;color:rgba(255,255,255,0.7);margin-bottom:8px">${escapeHtml(kicker)}</div>`,
-    );
-  }
-  parts.push(
-    `<div style="font-size:26px;font-weight:700;line-height:1.25;color:#fff">${escapeHtml(title)}</div>`,
-  );
-  if (body) {
-    parts.push(
-      `<div style="font-size:16px;line-height:1.5;color:rgba(255,255,255,0.85);margin-top:8px">${escapeHtml(body)}</div>`,
-    );
-  }
-  return {
-    contentHtml: parts.join(''),
-    styles: {
-      background: 'rgba(0, 0, 0, 0.7)',
-      backdropFilter: 'blur(16px)',
-      WebkitBackdropFilter: 'blur(16px)',
-      padding: '24px 28px',
-      borderRadius: '16px',
-      maxWidth: '420px',
-      boxShadow: '0 8px 32px rgba(0, 0, 0, 0.4)',
-    },
-  };
-}
-
-function callout(text: string): TemplateResult {
-  return {
-    contentHtml: `<span>${escapeHtml(text)}</span>`,
-    styles: {
-      background: 'rgba(0, 0, 0, 0.8)',
-      color: '#fff',
-      padding: '10px 18px',
-      borderRadius: '20px',
-      fontSize: '16px',
-      fontWeight: '500',
-      lineHeight: '1.3',
-      maxWidth: '300px',
-      boxShadow: '0 2px 12px rgba(0, 0, 0, 0.3)',
-    },
-  };
-}
-
-function imageCard(src: string, title?: string, body?: string): TemplateResult {
-  const parts: string[] = [];
-  parts.push(
-    `<img src="${escapeHtml(src)}" style="max-width:100%;border-radius:8px;display:block" />`,
-  );
-  if (title) {
-    parts.push(
-      `<div style="font-size:18px;font-weight:600;color:#fff;margin-top:12px">${escapeHtml(title)}</div>`,
-    );
-  }
-  if (body) {
-    parts.push(
-      `<div style="font-size:14px;color:rgba(255,255,255,0.8);margin-top:4px;line-height:1.4">${escapeHtml(body)}</div>`,
-    );
-  }
-  return {
-    contentHtml: parts.join(''),
-    styles: {
-      background: 'rgba(0, 0, 0, 0.75)',
-      backdropFilter: 'blur(12px)',
-      WebkitBackdropFilter: 'blur(12px)',
-      padding: '16px',
-      borderRadius: '14px',
-      maxWidth: '360px',
-      boxShadow: '0 6px 24px rgba(0, 0, 0, 0.4)',
-    },
-  };
-}
-
-export function renderTemplate(cue: OverlayCue): TemplateResult {
-  switch (cue.type) {
-    case 'lower-third':
-      return lowerThird(cue.text);
-    case 'headline-card':
-      return headlineCard(cue.title, cue.kicker, cue.body);
-    case 'callout':
-      return callout(cue.text);
-    case 'image-card':
-      return imageCard(cue.src, cue.title, cue.body);
-  }
-}
-```
-
-- [ ] **Step 4.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/templates.test.ts`
-Expected: PASS (11 tests)
-
-- [ ] **Step 4.5: Commit**
-
-```bash
-git add src/overlays/templates.ts tests/overlays/templates.test.ts
-git commit -m "feat(overlays): template renderers for lower-third, headline-card, callout, image-card"
-```
-
----
-
-### Task 5: Public overlay API (showOverlay, hideOverlay, withOverlay)
-
-**Files:**
-- Create: `src/overlays/index.ts`
-- Test: `tests/overlays/index.test.ts`
-
-- [ ] **Step 5.1: Write failing tests for public API**
-
-```ts
-// tests/overlays/index.test.ts
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { showOverlay, hideOverlay, withOverlay } from '../src/overlays/index.js';
-import type { Page } from '@playwright/test';
-
-function createMockPage() {
-  return {
-    evaluate: vi.fn(),
-    waitForTimeout: vi.fn(),
-  } as unknown as Page;
-}
-
-describe('showOverlay', () => {
-  let page: Page;
-  beforeEach(() => { page = createMockPage(); });
-
-  it('injects overlay and removes after duration', async () => {
-    await showOverlay(page, 'intro', { type: 'lower-third', text: 'Hello' }, 2000);
-    // inject call + remove call = 2 evaluate calls
-    expect(page.evaluate).toHaveBeenCalledTimes(2);
-    expect(page.waitForTimeout).toHaveBeenCalledWith(2000);
-  });
-
-  it('defaults to bottom-center zone', async () => {
-    await showOverlay(page, 'intro', { type: 'lower-third', text: 'Hi' }, 1000);
-    const [, args] = (page.evaluate as any).mock.calls[0];
-    expect(args[0]).toContain('bottom-center');
-  });
-
-  it('uses specified zone', async () => {
-    await showOverlay(page, 'intro', {
-      type: 'headline-card', title: 'Title', placement: 'top-left',
-    }, 1000);
-    const [, args] = (page.evaluate as any).mock.calls[0];
-    expect(args[0]).toContain('top-left');
-  });
-});
-
-describe('hideOverlay', () => {
-  it('removes overlay from specified zone', async () => {
-    const page = createMockPage();
-    await hideOverlay(page, 'top-left');
-    expect(page.evaluate).toHaveBeenCalledTimes(1);
-  });
-
-  it('defaults to bottom-center', async () => {
-    const page = createMockPage();
-    await hideOverlay(page);
-    const [, arg] = (page.evaluate as any).mock.calls[0];
-    expect(arg).toContain('bottom-center');
-  });
-});
-
-describe('withOverlay', () => {
-  let page: Page;
-  beforeEach(() => { page = createMockPage(); });
-
-  it('shows overlay during action and removes after', async () => {
-    let actionRan = false;
-    await withOverlay(page, 'demo', { type: 'callout', text: 'Watch' }, async () => {
-      actionRan = true;
-    });
-    expect(actionRan).toBe(true);
-    // inject + remove = 2 evaluate calls
-    expect(page.evaluate).toHaveBeenCalledTimes(2);
-  });
-
-  it('removes overlay even if action throws', async () => {
-    await expect(
-      withOverlay(page, 'demo', { type: 'lower-third', text: 'Hi' }, async () => {
-        throw new Error('boom');
-      }),
-    ).rejects.toThrow('boom');
-    // inject + remove = 2 evaluate calls
-    expect(page.evaluate).toHaveBeenCalledTimes(2);
-  });
-});
-```
-
-- [ ] **Step 5.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/index.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 5.3: Implement public overlay API**
-
-```ts
-// src/overlays/index.ts
-import type { Page } from '@playwright/test';
-import type { OverlayCue, Zone } from './types.js';
-import { injectIntoZone, removeZone, ZONE_ID_PREFIX } from './zones.js';
-import { renderTemplate } from './templates.js';
-import { getMotionCSS, getMotionStyles } from './motion.js';
-
-export type { OverlayCue, OverlayManifestEntry, Zone, TemplateType, MotionPreset } from './types.js';
-export { renderTemplate } from './templates.js';
-
-/**
- * Show an overlay for a given duration, then remove it.
- */
-export async function showOverlay(
-  page: Page,
-  _scene: string,
-  cue: OverlayCue,
-  durationMs: number,
-): Promise<void> {
-  const zone: Zone = cue.placement ?? 'bottom-center';
-  const motion = cue.motion ?? 'none';
-  const { contentHtml, styles } = renderTemplate(cue);
-  const zoneId = ZONE_ID_PREFIX + zone;
-  const motionCSS = getMotionCSS(motion, zoneId);
-  const motionStyles = getMotionStyles(motion, zoneId);
-
-  await injectIntoZone(page, zone, contentHtml, { ...styles, ...motionStyles }, motionCSS);
-  await page.waitForTimeout(durationMs);
-  await removeZone(page, zone);
-}
-
-/**
- * Remove the overlay in the specified zone.
- */
-export async function hideOverlay(
-  page: Page,
-  zone: Zone = 'bottom-center',
-): Promise<void> {
-  await removeZone(page, zone);
-}
-
-/**
- * Show an overlay while running an action, then remove it (even on error).
- */
-export async function withOverlay(
-  page: Page,
-  _scene: string,
-  cue: OverlayCue,
-  action: () => Promise<void>,
-): Promise<void> {
-  const zone: Zone = cue.placement ?? 'bottom-center';
-  const motion = cue.motion ?? 'none';
-  const { contentHtml, styles } = renderTemplate(cue);
-  const zoneId = ZONE_ID_PREFIX + zone;
-  const motionCSS = getMotionCSS(motion, zoneId);
-  const motionStyles = getMotionStyles(motion, zoneId);
-
-  await injectIntoZone(page, zone, contentHtml, { ...styles, ...motionStyles }, motionCSS);
-  try {
-    await action();
-  } finally {
-    await removeZone(page, zone);
-  }
-}
-```
-
-- [ ] **Step 5.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/index.test.ts`
-Expected: PASS (7 tests)
-
-- [ ] **Step 5.5: Commit**
-
-```bash
-git add src/overlays/index.ts tests/overlays/index.test.ts
-git commit -m "feat(overlays): public API — showOverlay, hideOverlay, withOverlay"
-```
-
----
-
-### Task 6: Update captions.ts to thin wrappers + update exports
-
-**Files:**
-- Modify: `src/captions.ts`
-- Modify: `src/index.ts`
-- Modify: `tests/captions.test.ts` (if needed)
-
-- [ ] **Step 6.1: Run existing captions tests to establish baseline**
-
-Run: `npx vitest run tests/captions.test.ts`
-Expected: PASS (all current tests)
-
-- [ ] **Step 6.2: Rewrite captions.ts as wrappers over overlay API**
-
-Replace the entire contents of `src/captions.ts` with thin wrappers that delegate to the overlay system. The old `CAPTION_STYLES`, `OVERLAY_ID`, and `injectOverlay` are no longer needed — they've been superseded by the zone/template system.
-
-```ts
-// src/captions.ts
-import type { Page } from '@playwright/test';
-import { showOverlay, hideOverlay, withOverlay } from './overlays/index.js';
-
-/**
- * Show a lower-third caption for `durationMs`, then remove it.
- * @deprecated Use showOverlay() for new code.
- */
-export async function showCaption(
-  page: Page,
-  scene: string,
-  text: string,
-  durationMs: number,
-): Promise<void> {
-  await showOverlay(page, scene, { type: 'lower-third', text }, durationMs);
-}
-
-/**
- * Remove the caption overlay.
- * @deprecated Use hideOverlay() for new code.
- */
-export async function hideCaption(page: Page): Promise<void> {
-  await hideOverlay(page, 'bottom-center');
-}
-
-/**
- * Show a caption while running `action`, then hide it (even on error).
- * @deprecated Use withOverlay() for new code.
- */
-export async function withCaption(
-  page: Page,
-  scene: string,
-  text: string,
-  action: () => Promise<void>,
-): Promise<void> {
-  await withOverlay(page, scene, { type: 'lower-third', text }, action);
-}
-```
-
-- [ ] **Step 6.3: Update src/index.ts exports**
-
-Add new overlay exports alongside existing caption exports. Keep the caption exports for backward compatibility.
-
-Add after the `// Captions` section:
-
-```ts
-// Overlays
-export {
-  showOverlay,
-  hideOverlay,
-  withOverlay,
-  type OverlayCue,
-  type OverlayManifestEntry,
-  type Zone,
-  type TemplateType,
-  type MotionPreset,
-} from './overlays/index.js';
-```
-
-- [ ] **Step 6.4: Run captions tests to verify backward compatibility**
-
-Run: `npx vitest run tests/captions.test.ts`
-Expected: PASS (all existing tests still pass)
-
-- [ ] **Step 6.5: Run full test suite**
-
-Run: `npx vitest run`
-Expected: ALL PASS
-
-- [ ] **Step 6.6: Commit**
-
-```bash
-git add src/captions.ts src/index.ts
-git commit -m "refactor(captions): rewrite as thin wrappers over overlay API"
-```
-
----
-
-## Chunk 3: Asset Server and Manifest
-
-### Task 7: Asset server
-
-**Files:**
-- Create: `src/asset-server.ts`
-- Test: `tests/asset-server.test.ts`
-
-- [ ] **Step 7.1: Write failing tests for asset server**
-
-```ts
-// tests/asset-server.test.ts
-import { describe, it, expect, afterEach } from 'vitest';
-import { startAssetServer } from '../src/asset-server.js';
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-
-describe('startAssetServer', () => {
-  let tmpDir: string;
-  let close: (() => Promise<void>) | undefined;
-
-  function setup() {
-    tmpDir = mkdtempSync(join(tmpdir(), 'argo-asset-'));
-    mkdirSync(join(tmpDir, 'assets'), { recursive: true });
-  }
-
-  afterEach(async () => {
-    if (close) await close();
-    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('serves files from the asset directory', async () => {
-    setup();
-    writeFileSync(join(tmpDir, 'assets', 'test.txt'), 'hello');
-    const server = await startAssetServer(join(tmpDir, 'assets'));
-    close = server.close;
-
-    const res = await fetch(`${server.url}/test.txt`);
-    expect(res.status).toBe(200);
-    expect(await res.text()).toBe('hello');
-  });
-
-  it('returns 404 for missing files', async () => {
-    setup();
-    const server = await startAssetServer(join(tmpDir, 'assets'));
-    close = server.close;
-
-    const res = await fetch(`${server.url}/nope.png`);
-    expect(res.status).toBe(404);
-  });
-
-  it('prevents path traversal', async () => {
-    setup();
-    writeFileSync(join(tmpDir, 'secret.txt'), 'private');
-    const server = await startAssetServer(join(tmpDir, 'assets'));
-    close = server.close;
-
-    const res = await fetch(`${server.url}/../secret.txt`);
-    expect(res.status).toBe(403);
-  });
-
-  it('assigns a random available port', async () => {
-    setup();
-    const server = await startAssetServer(join(tmpDir, 'assets'));
-    close = server.close;
-    expect(server.port).toBeGreaterThan(0);
-  });
-
-  it('serves PNG with correct content type', async () => {
-    setup();
-    writeFileSync(join(tmpDir, 'assets', 'img.png'), Buffer.from([0x89, 0x50]));
-    const server = await startAssetServer(join(tmpDir, 'assets'));
-    close = server.close;
-
-    const res = await fetch(`${server.url}/img.png`);
-    expect(res.headers.get('content-type')).toBe('image/png');
-  });
-});
-```
-
-- [ ] **Step 7.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/asset-server.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 7.3: Implement asset server**
-
-The asset server serves static files from a directory over HTTP. It validates paths to prevent directory traversal and maps file extensions to MIME types. It binds to port 0 so the OS assigns a free port, avoiding conflicts.
-
-```ts
-// src/asset-server.ts
-import http from 'node:http';
-import { createReadStream, existsSync } from 'node:fs';
-import { resolve, relative, extname } from 'node:path';
-import type { AddressInfo } from 'node:net';
-
-export interface AssetServer {
-  url: string;
-  port: number;
-  close: () => Promise<void>;
-}
-
-const MIME_TYPES: Record<string, string> = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.webp': 'image/webp',
-  '.txt': 'text/plain',
-  '.json': 'application/json',
-};
-
-export function startAssetServer(assetDir: string): Promise<AssetServer> {
-  const resolvedDir = resolve(assetDir);
-
-  return new Promise((resolvePromise) => {
-    const server = http.createServer((req, res) => {
-      const urlPath = decodeURIComponent(req.url ?? '/');
-      const filePath = resolve(resolvedDir, '.' + urlPath);
-
-      // Path traversal check
-      const rel = relative(resolvedDir, filePath);
-      if (rel.startsWith('..') || resolve(filePath) !== filePath) {
-        res.writeHead(403);
-        res.end('Forbidden');
-        return;
-      }
-
-      if (!existsSync(filePath)) {
-        res.writeHead(404);
-        res.end('Not found');
-        return;
-      }
-
-      const ext = extname(filePath).toLowerCase();
-      const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
-      res.writeHead(200, { 'Content-Type': contentType });
-      createReadStream(filePath).pipe(res);
-    });
-
-    server.listen(0, '127.0.0.1', () => {
-      const { port } = server.address() as AddressInfo;
-      resolvePromise({
-        url: `http://127.0.0.1:${port}`,
-        port,
-        close: () => new Promise((res) => server.close(() => res())),
-      });
-    });
-  });
-}
-```
-
-- [ ] **Step 7.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/asset-server.test.ts`
-Expected: PASS (5 tests)
-
-- [ ] **Step 7.5: Commit**
-
-```bash
-git add src/asset-server.ts tests/asset-server.test.ts
-git commit -m "feat: local asset server for serving images during recording"
-```
-
----
-
-### Task 8: Overlay manifest loader
-
-**Files:**
-- Create: `src/overlays/manifest.ts`
-- Test: `tests/overlays/manifest.test.ts`
-
-- [ ] **Step 8.1: Write failing tests for manifest loading**
-
-```ts
-// tests/overlays/manifest.test.ts
-import { describe, it, expect, afterEach } from 'vitest';
-import { loadOverlayManifest, hasImageAssets, resolveAssetURLs } from '../src/overlays/manifest.js';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-
-describe('loadOverlayManifest', () => {
-  let tmpDir: string;
-
-  function setup() {
-    tmpDir = mkdtempSync(join(tmpdir(), 'argo-manifest-'));
-  }
-
-  afterEach(() => {
-    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('returns null when file does not exist', async () => {
-    setup();
-    const result = await loadOverlayManifest(join(tmpDir, 'missing.overlays.json'));
-    expect(result).toBeNull();
-  });
-
-  it('parses a valid manifest', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'demo.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify([
-      { scene: 'intro', type: 'lower-third', text: 'Hello' },
-      { scene: 'mid', type: 'headline-card', title: 'Title', placement: 'top-left' },
-    ]));
-    const result = await loadOverlayManifest(manifestPath);
-    expect(result).toHaveLength(2);
-    expect(result![0].scene).toBe('intro');
-    expect(result![1].type).toBe('headline-card');
-  });
-
-  it('throws on invalid JSON', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'bad.overlays.json');
-    writeFileSync(manifestPath, '{ nope }}}');
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('Failed to parse overlay manifest');
-  });
-
-  it('throws when manifest is not an array', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'obj.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify({ scene: 'x' }));
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('must contain a JSON array');
-  });
-
-  it('throws on entry missing scene', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'no-scene.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify([{ type: 'lower-third', text: 'Hi' }]));
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('missing required field "scene"');
-  });
-
-  it('throws on entry missing type', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'no-type.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify([{ scene: 'x', text: 'Hi' }]));
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('missing required field "type"');
-  });
-
-  it('throws on unknown template type', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'bad-type.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify([{ scene: 'x', type: 'banner', text: 'Hi' }]));
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('unknown overlay type "banner"');
-  });
-
-  it('throws on unknown zone', async () => {
-    setup();
-    const manifestPath = join(tmpDir, 'bad-zone.overlays.json');
-    writeFileSync(manifestPath, JSON.stringify([
-      { scene: 'x', type: 'lower-third', text: 'Hi', placement: 'middle' },
-    ]));
-    await expect(loadOverlayManifest(manifestPath)).rejects.toThrow('unknown placement "middle"');
-  });
-});
-
-describe('hasImageAssets', () => {
-  it('returns true when entries contain image-card', () => {
-    expect(hasImageAssets([
-      { scene: 'x', type: 'image-card', src: 'img.png' },
-    ])).toBe(true);
-  });
-
-  it('returns false when no image-card entries', () => {
-    expect(hasImageAssets([
-      { scene: 'x', type: 'lower-third', text: 'Hi' },
-    ])).toBe(false);
-  });
-});
-
-describe('resolveAssetURLs', () => {
-  it('prefixes relative image-card src with asset server URL', () => {
-    const entries = [
-      { scene: 'x', type: 'image-card' as const, src: 'assets/diagram.png' },
-    ];
-    const resolved = resolveAssetURLs(entries, 'http://127.0.0.1:9999');
-    expect(resolved[0]).toHaveProperty('src', 'http://127.0.0.1:9999/diagram.png');
-  });
-
-  it('leaves absolute URLs unchanged', () => {
-    const entries = [
-      { scene: 'x', type: 'image-card' as const, src: 'http://example.com/img.png' },
-    ];
-    const resolved = resolveAssetURLs(entries, 'http://127.0.0.1:9999');
-    expect(resolved[0]).toHaveProperty('src', 'http://example.com/img.png');
-  });
-
-  it('leaves non-image-card entries unchanged', () => {
-    const entries = [
-      { scene: 'x', type: 'lower-third' as const, text: 'Hello' },
-    ];
-    const resolved = resolveAssetURLs(entries, 'http://127.0.0.1:9999');
-    expect(resolved[0]).toEqual(entries[0]);
-  });
-});
-```
-
-- [ ] **Step 8.2: Run tests to verify they fail**
-
-Run: `npx vitest run tests/overlays/manifest.test.ts`
-Expected: FAIL with module not found
-
-- [ ] **Step 8.3: Implement manifest loader**
-
-```ts
-// src/overlays/manifest.ts
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import type { OverlayManifestEntry } from './types.js';
-import { isValidTemplateType, isValidZone, isValidMotion } from './types.js';
-
-/**
- * Load and validate an overlay manifest file.
- * Returns null if the file does not exist (overlays are optional).
- */
-export async function loadOverlayManifest(
-  manifestPath: string,
-): Promise<OverlayManifestEntry[] | null> {
-  if (!existsSync(manifestPath)) return null;
-
-  const raw = await readFile(manifestPath, 'utf-8');
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse overlay manifest ${manifestPath}: ${(err as Error).message}`,
-    );
-  }
-
-  if (!Array.isArray(parsed)) {
-    throw new Error(`Overlay manifest ${manifestPath} must contain a JSON array`);
-  }
-
-  const entries: OverlayManifestEntry[] = [];
-
-  for (let i = 0; i < parsed.length; i++) {
-    const entry = parsed[i];
-    const prefix = `Overlay manifest entry ${i}`;
-
-    if (!entry.scene || typeof entry.scene !== 'string') {
-      throw new Error(`${prefix}: missing required field "scene"`);
-    }
-    if (!entry.type || typeof entry.type !== 'string') {
-      throw new Error(`${prefix}: missing required field "type"`);
-    }
-    if (!isValidTemplateType(entry.type)) {
-      throw new Error(`${prefix}: unknown overlay type "${entry.type}"`);
-    }
-    if (entry.placement && !isValidZone(entry.placement)) {
-      throw new Error(`${prefix}: unknown placement "${entry.placement}"`);
-    }
-    if (entry.motion && !isValidMotion(entry.motion)) {
-      throw new Error(`${prefix}: unknown motion "${entry.motion}"`);
-    }
-
-    entries.push(entry as OverlayManifestEntry);
-  }
-
-  return entries;
-}
-
-/**
- * Check if any entries reference image assets (for deciding whether to start asset server).
- */
-export function hasImageAssets(entries: OverlayManifestEntry[]): boolean {
-  return entries.some((e) => e.type === 'image-card');
-}
-
-/**
- * Resolve image-card src fields to asset server URLs.
- * Entries with relative src paths get prefixed with the asset server URL.
- */
-export function resolveAssetURLs(
-  entries: OverlayManifestEntry[],
-  assetBaseURL: string,
-): OverlayManifestEntry[] {
-  return entries.map((e) => {
-    if (e.type === 'image-card' && e.src && !e.src.startsWith('http')) {
-      return { ...e, src: `${assetBaseURL}/${e.src.replace(/^assets\//, '')}` };
-    }
-    return e;
-  });
-}
-```
-
-- [ ] **Step 8.4: Run tests to verify they pass**
-
-Run: `npx vitest run tests/overlays/manifest.test.ts`
-Expected: PASS (12 tests)
-
-- [ ] **Step 8.5: Commit**
-
-```bash
-git add src/overlays/manifest.ts tests/overlays/manifest.test.ts
-git commit -m "feat(overlays): manifest loader with validation and asset URL resolution"
-```
-
----
-
-## Chunk 4: Integration (Record + Init)
-
-### Task 9: Wire asset server into record.ts
-
-**Files:**
-- Modify: `src/record.ts`
-
-The asset server needs to start before the Playwright subprocess if the overlay manifest contains image assets, and stop after recording completes.
-
-- [ ] **Step 9.1: Read current record.ts**
-
-Read `src/record.ts` to identify exact insertion points.
-
-- [ ] **Step 9.2: Add asset server lifecycle to record.ts**
-
-Add imports at the top of `src/record.ts`:
-
-```ts
-import { startAssetServer } from './asset-server.js';
-import { loadOverlayManifest, hasImageAssets } from './overlays/manifest.js';
-```
-
-Inside the `record()` function, before the `execFile` call:
-
-```ts
-// Start asset server if overlay manifest has image assets
-let assetServer: { url: string; close: () => Promise<void> } | undefined;
-const overlayManifestPath = join(options.demosDir, `${demoName}.overlays.json`);
-const overlayEntries = await loadOverlayManifest(overlayManifestPath);
-if (overlayEntries && hasImageAssets(overlayEntries)) {
-  const assetDir = join(options.demosDir, 'assets');
-  assetServer = await startAssetServer(assetDir);
-}
-```
-
-Add `ARGO_ASSET_URL: assetServer?.url ?? ''` to the `env` object passed to `execFile`.
-
-In the callback, add cleanup in both the resolve and reject paths:
-
-```ts
-if (assetServer) await assetServer.close();
-```
-
-Wrap the entire execFile callback body in a try/finally to ensure the asset server is always stopped:
-
-```ts
-// In the resolve path, before resolve():
-if (assetServer) await assetServer.close();
-
-// In the reject path, before reject():
-if (assetServer) await assetServer.close();
-```
-
-- [ ] **Step 9.3: Run existing tests to ensure nothing breaks**
-
-Run: `npx vitest run`
-Expected: ALL PASS
-
-- [ ] **Step 9.4: Commit**
-
-```bash
-git add src/record.ts
-git commit -m "feat: wire asset server lifecycle into record command"
-```
-
----
-
-### Task 10: Update init templates
-
-**Files:**
-- Modify: `src/init.ts`
-- Modify: `tests/init.test.ts`
-
-- [ ] **Step 10.1: Add example overlay manifest to init scaffolding**
-
-Add a new constant `EXAMPLE_OVERLAYS` in `src/init.ts`:
-
-```ts
-const EXAMPLE_OVERLAYS = JSON.stringify(
-  [
-    {
-      scene: 'welcome',
-      type: 'lower-third',
-      text: 'Welcome to our app',
-    },
-    {
-      scene: 'action',
-      type: 'headline-card',
-      placement: 'top-left',
-      title: 'One-click setup',
-      body: 'Just press the button to get started.',
-      motion: 'slide-in',
-    },
-  ],
-  null,
-  2,
-) + '\n';
-```
-
-Add this line in the `init()` function after the voiceover manifest write:
-
-```ts
-await writeIfMissing(join(demosDir, 'example.overlays.json'), EXAMPLE_OVERLAYS);
-```
-
-- [ ] **Step 10.2: Update init test to expect the new file**
-
-In `tests/init.test.ts`, add an assertion that `example.overlays.json` is created in the demos directory.
-
-- [ ] **Step 10.3: Run init tests**
-
-Run: `npx vitest run tests/init.test.ts`
-Expected: PASS
-
-- [ ] **Step 10.4: Commit**
-
-```bash
-git add src/init.ts tests/init.test.ts
-git commit -m "feat(init): scaffold example overlay manifest"
-```
-
----
-
-### Task 11: Full integration verification
-
-- [ ] **Step 11.1: Run full test suite**
-
-Run: `npx vitest run`
-Expected: ALL PASS
-
-- [ ] **Step 11.2: Type check the project**
-
-Run: `npx tsc --noEmit`
-Expected: No type errors
-
-- [ ] **Step 11.3: Commit any remaining fixes**
-
-```bash
-git add -A
-git commit -m "chore: integration fixes for editorial overlay system"
-```
-
----
-
-## Summary
-
-| Task | What | Files | Est. Tests |
-|------|------|-------|------------|
-| 1 | Overlay types and guards | `src/overlays/types.ts` | 3 |
-| 2 | Zone DOM management | `src/overlays/zones.ts` | 4 |
-| 3 | Motion presets | `src/overlays/motion.ts` | 6 |
-| 4 | Template renderers | `src/overlays/templates.ts` | 11 |
-| 5 | Public API | `src/overlays/index.ts` | 7 |
-| 6 | Captions backward compat | `src/captions.ts`, `src/index.ts` | existing |
-| 7 | Asset server | `src/asset-server.ts` | 5 |
-| 8 | Manifest loader | `src/overlays/manifest.ts` | 12 |
-| 9 | Record + asset server | `src/record.ts` | existing |
-| 10 | Init templates | `src/init.ts` | existing |
-| 11 | Integration verification | all | full suite |