@argo-video/cli 0.1.0 → 0.1.1

package/docs/enhancement-proposal.md

@@ -1,262 +0,0 @@
-# Enhancement Proposal: Editorial Overlay System
-
-## Summary
-
-Argo's current caption system renders a single bottom-centered text pill. That's enough for narration subtitles but not for editorial demo videos where text feels composed into the frame — headline cards with kicker/title/body hierarchy, callout annotations, image-backed panels at different screen positions.
-
-This proposal evolves `src/captions.ts` from a single-style caption helper into a zone-based overlay system with pluggable templates.
-
-## Goals
-
-- Make captions feel designed, not appended.
-- Support editorial overlays: headline cards, callouts, image-backed panels.
-- Keep narration timing and overlay visuals separate so demos stay easy to author.
-- Preserve the simple default path — `showCaption` and `withCaption` continue to work unchanged.
-
-## Current System
-
-```
-captions.ts
-├── OVERLAY_ID = 'argo-caption-overlay'     ← single element, replaced on each call
-├── CAPTION_STYLES = { ... }                ← one hardcoded style object
-├── injectOverlay(page, text)               ← creates div, sets textContent + styles
-├── showCaption(page, scene, text, dur)     ← inject → wait → remove
-├── withCaption(page, scene, text, action)  ← inject → action → remove (try/finally)
-└── hideCaption(page)                       ← remove by ID
-```
-
-Limitations:
-- One overlay type, one placement, one visual treatment.
-- Single DOM element — showing a new caption removes the previous one globally.
-- No support for images, rich cards, or animation.
-- No way to have two overlays visible simultaneously (e.g., subtitle + headline card).
-
-## Design Decisions
-
-### Zone-based coexistence
-
-Overlays are placed into **zones**. Each zone is a screen region that holds at most one overlay at a time. Showing an overlay in a zone automatically replaces any existing overlay in that zone, but overlays in different zones coexist independently.
-
-Zones:
-- `bottom-center` (default — current caption position)
-- `top-left`
-- `top-right`
-- `bottom-left`
-- `bottom-right`
-- `center`
-
-DOM IDs become `argo-overlay-{zone}` instead of the current single `argo-caption-overlay`.
-
-This gives editorial power (subtitle + headline card visible simultaneously) without requiring manual dismissal of every overlay.
-
-### Asset injection via local server
-
-Image overlays (`image-card`) reference local files like `assets/diagram.png`. These need to be accessible inside the Playwright browser context.
-
-**Approach: local asset server.** A tiny HTTP server (same pattern as the E2E fake server) serves files from the project's asset directory during recording. It starts automatically before `record` and stops after.
-
-Why not base64 data URIs: a 2MB screenshot becomes ~2.7MB of serialized DOM, slowing `page.evaluate`. Asset server keeps the DOM clean and scales to many images.
-
-### Templates, not a theme system
-
-v1 ships with hardcoded visual presets per template — no theme tokens. Each template has one opinionated look that works well on dark and light backgrounds. Theme customization (typography, colors, spacing tokens) is a future enhancement once real usage patterns emerge.
-
-### Motion: two presets only
-
-CSS animations during Playwright recording are frame-rate dependent. v1 supports two safe presets:
-- `fade-in` — opacity 0→1 over 300ms
-- `slide-in` — translateX + opacity over 400ms
-
-Staggered multi-element reveals (kicker, then title, then body) are deferred to v2 — they require careful timing coordination that's hard to get right at variable recording FPS.
-
-## Overlay Templates
-
-### `lower-third` (default)
-
-The current caption style, refined. Bottom-center translucent pill with text.
-
-```
-┌─────────────────────────────────────────┐
-│                                         │
-│                                         │
-│                                         │
-│    ┌─────────────────────────────┐      │
-│    │  Caption text here          │      │
-│    └─────────────────────────────┘      │
-└─────────────────────────────────────────┘
-```
-
-Fields: `text`
-
-### `headline-card`
-
-A card with optional kicker (small caps label), title (large), and body (smaller). Backdrop blur + translucent background.
-
-```
-┌─────────────────────────────────────────┐
-│  ┌──────────────────────┐               │
-│  │  KICKER LABEL        │               │
-│  │  Title text here     │               │
-│  │  Body text here      │               │
-│  └──────────────────────┘               │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-Fields: `kicker?`, `title`, `body?`
-
-### `callout`
-
-A compact annotation bubble for pointing out UI elements. Meant for short text.
-
-Fields: `text`
-
-### `image-card`
-
-An image with optional title and body caption below it. Image loaded from the asset server.
-
-```
-┌─────────────────────────────────────────┐
-│               ┌─────────────────┐       │
-│               │  ┌───────────┐  │       │
-│               │  │   image   │  │       │
-│               │  └───────────┘  │       │
-│               │  Title          │       │
-│               │  Body text      │       │
-│               └─────────────────┘       │
-└─────────────────────────────────────────┘
-```
-
-Fields: `src`, `title?`, `body?`
-
-## Authoring Model
-
-### Overlay manifest (`demos/example.overlays.json`)
-
-A new file, separate from the voiceover manifest. Maps scenes to overlay cues.
-
-```json
-[
-  {
-    "scene": "intro",
-    "type": "lower-third",
-    "text": "Hacker News — the front page of the internet"
-  },
-  {
-    "scene": "browse",
-    "type": "headline-card",
-    "placement": "top-left",
-    "kicker": "LOCAL EXECUTION",
-    "title": "WebGPU + Transformers.js",
-    "body": "Models cache after first load.",
-    "motion": "slide-in"
-  },
-  {
-    "scene": "rerank",
-    "type": "image-card",
-    "placement": "top-right",
-    "src": "assets/rerank-diagram.png",
-    "title": "Cross-encoder reranking"
-  }
-]
-```
-
-Rules:
-- `scene` links to `narration.mark()` calls in the demo script.
-- `type` selects the template. Default: `lower-third`.
-- `placement` selects the zone. Default: `bottom-center`.
-- `motion` selects the entrance animation. Default: none (instant appear).
-- Template-specific fields (`kicker`, `title`, `body`, `src`, `text`) vary by type.
-
-### Programmatic API
-
-The existing `showCaption`/`withCaption` API stays unchanged as sugar for `lower-third` overlays. New overlays are shown via a new function:
-
-```ts
-import { showOverlay, hideOverlay, withOverlay } from 'argo';
-
-// Show a headline card in the top-left zone
-await showOverlay(page, 'browse', {
-  type: 'headline-card',
-  placement: 'top-left',
-  kicker: 'LOCAL EXECUTION',
-  title: 'WebGPU + Transformers.js',
-  motion: 'slide-in',
-}, 4000);
-
-// Hide a specific zone
-await hideOverlay(page, 'top-left');
-
-// Overlay around an action
-await withOverlay(page, 'rerank', {
-  type: 'image-card',
-  placement: 'top-right',
-  src: 'assets/diagram.png',
-  title: 'Reranking pipeline',
-}, async () => {
-  await page.click('.rerank-button');
-});
-```
-
-Backward compatibility: `showCaption(page, scene, text, dur)` becomes equivalent to `showOverlay(page, scene, { type: 'lower-third', text }, dur)`.
-
-### Auto-overlay from manifest
-
-When a `<demo>.overlays.json` file exists alongside the voiceover manifest, the recording fixture automatically injects overlays at their matching `narration.mark()` timestamps. This means users can define overlays purely in JSON without touching the demo script — the programmatic API is for advanced use only.
-
-## Implementation Plan
-
-### Phase 1: Zone-based overlay renderer
-
-1. Refactor `src/captions.ts` → `src/overlays.ts`
-   - Replace single `OVERLAY_ID` with `argo-overlay-{zone}` scheme
-   - Extract template rendering into a `renderTemplate(type, fields)` → HTML+styles function
-   - Implement `lower-third` template (current caption style, now zone-aware)
-   - Implement `showOverlay`, `hideOverlay`, `withOverlay`
-   - Re-export `showCaption`, `withCaption`, `hideCaption` as thin wrappers
-
-2. Add CSS animation injection for `fade-in` and `slide-in` presets
-
-3. Update `src/index.ts` exports
-
-### Phase 2: Editorial templates
-
-4. Implement `headline-card` template (kicker + title + body, backdrop blur)
-5. Implement `callout` template
-6. Implement `image-card` template
-
-### Phase 3: Asset server + image support
-
-7. Extract `tests/e2e/fake-server.ts` pattern into `src/asset-server.ts`
-   - Serves files from a configurable asset directory
-   - Auto-starts before recording, auto-stops after
-   - Only starts if an overlay manifest references image assets
-
-8. Wire asset server URL into `image-card` template `src` resolution
-
-### Phase 4: Manifest-driven overlays
-
-9. Define overlay manifest schema and loader in `src/overlays/manifest.ts`
-10. Wire manifest loading into the recording fixture
-    - If `<demo>.overlays.json` exists, auto-inject overlays at matching scene marks
-
-### Phase 5: Polish
-
-11. Update `argo init` templates with overlay examples
-12. Update README with overlay documentation
-13. Add tests for each template, zone management, and manifest loading
-
-## Migration
-
-- `showCaption`, `withCaption`, `hideCaption` remain exported and unchanged.
-- Existing demos work without modification.
-- The overlay manifest is optional — demos without one behave exactly as before.
-- `src/captions.ts` is replaced by `src/overlays.ts` but all original exports are preserved.
-
-## Out of Scope (v1)
-
-- Theme tokens / custom styling
-- Staggered multi-element animation
-- Overlay transitions (exit animations)
-- Overlay positioning relative to DOM elements (e.g., "anchor to this button")
-- Video-time overlays via ffmpeg (all overlays render in-browser during recording)

package/docs/superpowers/plans/2026-03-12-argo.md

@@ -1,208 +0,0 @@
-# Argo 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:** Build Argo — a CLI + library that turns Playwright demo scripts into polished product demo videos with AI-generated voiceover.
-
-**Architecture:** Four-stage pipeline (TTS → Record → Align → Export) orchestrated by a CLI. Library exports Playwright fixtures and helpers for authoring demos. Kokoro TTS via Transformers.js for local voiceover generation, ffmpeg for final video export.
-
-**Tech Stack:** TypeScript, Playwright, @huggingface/transformers (Kokoro TTS), ffmpeg (system dep), commander (CLI), vitest (testing)
-
----
-
-## File Structure
-
-```
-argo/
-├── src/
-│   ├── index.ts          # Public library exports
-│   ├── cli.ts            # CLI entry point — commander program
-│   ├── fixtures.ts       # Playwright test fixture (injects narration)
-│   ├── narration.ts      # NarrationTimeline class
-│   ├── captions.ts       # DOM caption overlay helpers
-│   ├── tts/
-│   │   ├── engine.ts     # TTSEngine interface + WAV utilities + MockTTSEngine
-│   │   ├── kokoro.ts     # Kokoro TTS via @huggingface/transformers
-│   │   ├── cache.ts      # ClipCache — SHA-256 content-addressed caching
-│   │   ├── generate.ts   # generateClips — reads manifest, checks cache, calls engine
-│   │   └── align.ts      # Clip alignment with overlap prevention
-│   ├── record.ts         # Playwright recording wrapper
-│   ├── export.ts         # ffmpeg video+audio merge
-│   ├── pipeline.ts       # Orchestrates TTS→record→align→export
-│   ├── config.ts         # ArgoConfig type, defineConfig(), loadConfig(), demosProject()
-│   └── init.ts           # Scaffolding: creates demos/, example files, config
-├── tests/
-│   ├── config.test.ts
-│   ├── narration.test.ts
-│   ├── captions.test.ts
-│   ├── fixtures.test.ts
-│   ├── export.test.ts
-│   ├── pipeline.test.ts
-│   ├── cli.test.ts
-│   ├── init.test.ts
-│   └── tts/
-│       ├── engine.test.ts
-│       ├── kokoro.test.ts
-│       ├── cache.test.ts
-│       ├── generate.test.ts
-│       └── align.test.ts
-├── bin/
-│   └── argo.js           # CLI bin shim
-├── package.json
-├── tsconfig.json
-└── .gitignore
-```
-
----
-
-## Chunk 1: Foundation (Tasks 1-4)
-
-### Task 1: Project Setup
-
-**Files:** Create: `package.json`, `tsconfig.json`, `bin/argo.js`, `.gitignore`, `src/index.ts`, `src/cli.ts`
-
-- [ ] **Step 1.1:** Create package.json with type: module, ESM config, dependencies (commander, @huggingface/transformers), peer deps (playwright, @playwright/test), dev deps (typescript, vitest)
-- [ ] **Step 1.2:** Create tsconfig.json (target ES2022, module NodeNext, outDir dist, strict)
-- [ ] **Step 1.3:** Create bin/argo.js shim: `#!/usr/bin/env node` + `import('../dist/cli.js')`
-- [ ] **Step 1.4:** Create .gitignore (node_modules, dist, .argo, videos, *.tsbuildinfo)
-- [ ] **Step 1.5:** Create placeholder src/index.ts and src/cli.ts
-- [ ] **Step 1.6:** npm install and verify tsc --noEmit passes
-- [ ] **Step 1.7:** Commit: "chore: project setup with deps, tsconfig, and bin shim"
-
-### Task 2: Config System
-
-**Files:** Create: `src/config.ts`, Test: `tests/config.test.ts`
-
-- [ ] **Step 2.1:** Write failing tests for defineConfig (defaults, merging, custom engine), demosProject (returns Playwright project), loadConfig (defaults, .js, .mjs, explicit path)
-- [ ] **Step 2.2:** Run tests — verify they fail
-- [ ] **Step 2.3:** Implement ArgoConfig types, defineConfig (deep merge with defaults), demosProject helper, loadConfig (searches for argo.config.ts/.js/.mjs, dynamic import)
-- [ ] **Step 2.4:** Run tests — verify they pass
-- [ ] **Step 2.5:** Commit: "feat: config system with defineConfig, loadConfig, and demosProject"
-
-### Task 3: NarrationTimeline
-
-**Files:** Create: `src/narration.ts`, Test: `tests/narration.test.ts`
-
-- [ ] **Step 3.1:** Write failing tests: start sets t=0, mark records elapsed ms, mark throws before start, mark throws on duplicate, getTimings returns copy, flush writes JSON and creates dirs
-- [ ] **Step 3.2:** Run tests — verify they fail
-- [ ] **Step 3.3:** Implement NarrationTimeline with Map-based timings, Date.now() tracking
-- [ ] **Step 3.4:** Run tests — verify they pass
-- [ ] **Step 3.5:** Commit: "feat: NarrationTimeline with start, mark, getTimings, and flush"
-
-### Task 4: Caption Helpers
-
-**Files:** Create: `src/captions.ts`, Test: `tests/captions.test.ts`
-
-- [ ] **Step 4.1:** Write failing tests: showCaption injects+waits+removes, hideCaption removes, withCaption wraps action, withCaption cleans up on throw
-- [ ] **Step 4.2:** Run tests — verify they fail
-- [ ] **Step 4.3:** Implement showCaption/hideCaption/withCaption using page.evaluate with styled overlay div
-- [ ] **Step 4.4:** Run tests — verify they pass
-- [ ] **Step 4.5:** Commit: "feat: caption helpers (showCaption, hideCaption, withCaption)"
-
----
-
-## Chunk 2: TTS System (Tasks 5-8)
-
-### Task 5: TTS Engine Interface + WAV Utilities
-
-**Files:** Create: `src/tts/engine.ts`, Test: `tests/tts/engine.test.ts`
-
-- [ ] **Step 5.1:** Write failing tests: createWavBuffer (valid header, correct data size, preserves samples), parseWavHeader (round-trip, rejects small/invalid), MockTTSEngine (interface compliance, valid WAV, records calls)
-- [ ] **Step 5.2:** Run tests — verify they fail
-- [ ] **Step 5.3:** Implement TTSEngine interface, createWavBuffer (mono 24kHz 32-bit float), parseWavHeader (find data chunk), createMockTTSEngine
-- [ ] **Step 5.4:** Run tests — verify they pass
-- [ ] **Step 5.5:** Commit: "feat(tts): TTSEngine interface, WAV utilities, and MockTTSEngine"
-
-### Task 6: Kokoro TTS Engine
-
-**Files:** Create: `src/tts/kokoro.ts`, Test: `tests/tts/kokoro.test.ts`
-
-- [ ] **Step 6.1:** Implement KokoroEngine: lazy-loads pipeline from @huggingface/transformers, generates WAV via createWavBuffer
-- [ ] **Step 6.2:** Write integration test (skipped in CI): generates valid WAV, throws on empty text
-- [ ] **Step 6.3:** Commit: "feat(tts): KokoroEngine with lazy model loading"
-
-### Task 7: Clip Caching
-
-**Files:** Create: `src/tts/cache.ts`, Test: `tests/tts/cache.test.ts`
-
-- [ ] **Step 7.1:** Write failing tests: isCached false/true, getCachedClip null/buffer, invalidation on text/voice/speed change, independent per demo
-- [ ] **Step 7.2:** Run tests — verify they fail
-- [ ] **Step 7.3:** Implement ClipCache: SHA-256 hash of {scene,text,voice,speed}, stores in .argo/<demo>/clips/<hash>.wav
-- [ ] **Step 7.4:** Run tests — verify they pass
-- [ ] **Step 7.5:** Commit: "feat(tts): ClipCache with SHA-256 content-addressed caching"
-
-### Task 8: TTS Generate Command
-
-**Files:** Create: `src/tts/generate.ts`, Test: `tests/tts/generate.test.ts`
-
-- [ ] **Step 8.1:** Write failing tests: generates all entries, uses cache on rerun, regenerates only changed, applies defaults, throws on missing file/invalid JSON/missing fields
-- [ ] **Step 8.2:** Run tests — verify they fail
-- [ ] **Step 8.3:** Implement generateClips: read manifest, validate entries, check cache, call engine, cache results
-- [ ] **Step 8.4:** Run tests — verify they pass
-- [ ] **Step 8.5:** Commit: "feat(tts): generateClips with manifest parsing and cache integration"
-
----
-
-## Chunk 3: Recording & Alignment (Tasks 9-10)
-
-### Task 9: Playwright Fixtures
-
-**Files:** Create: `src/fixtures.ts`, Test: `tests/fixtures.test.ts`
-
-- [ ] **Step 9.1:** Write failing tests: createNarrationFixture (creates timeline, starts, provides, flushes; flushes on throw), demoType (types with delay, custom delay)
-- [ ] **Step 9.2:** Run tests — verify they fail
-- [ ] **Step 9.3:** Implement createNarrationFixture factory, demoType helper (pressSequentially), test.extend with narration fixture
-- [ ] **Step 9.4:** Run tests — verify they pass
-- [ ] **Step 9.5:** Commit: "feat: Playwright fixtures with narration injection and demoType"
-
-### Task 10: Alignment
-
-**Files:** Create: `src/tts/align.ts`, Test: `tests/tts/align.test.ts`
-
-- [ ] **Step 10.1:** Write failing tests: places clips at timestamps, prevents overlap with 100ms gap, correct output buffer duration, mixes samples at correct positions, handles empty, orders by timestamp, skips unknown scenes
-- [ ] **Step 10.2:** Run tests — verify they fail
-- [ ] **Step 10.3:** Implement alignClips: filter/sort by timing, overlap prevention, create silence buffer, mix samples
-- [ ] **Step 10.4:** Run tests — verify they pass
-- [ ] **Step 10.5:** Commit: "feat(tts): clip alignment with overlap prevention and sample mixing"
-
----
-
-## Chunk 4: Export, Pipeline, CLI & Init (Tasks 11-14)
-
-### Task 11: Export (ffmpeg)
-
-**Files:** Create: `src/export.ts`, Test: `tests/export.test.ts`
-
-- [ ] **Step 11.1:** Write failing tests: checkFfmpeg (available/missing), exportVideo (correct args, custom config, missing files, non-zero exit)
-- [ ] **Step 11.2:** Run tests — verify they fail
-- [ ] **Step 11.3:** Implement checkFfmpeg (execSync ffmpeg -version), exportVideo (spawnSync with -c:v libx264 -preset -crf -c:a aac -shortest)
-- [ ] **Step 11.4:** Run tests — verify they pass
-- [ ] **Step 11.5:** Commit: "feat: ffmpeg export with configurable encoding options"
-
-### Task 12: Pipeline Orchestration
-
-**Files:** Create: `src/pipeline.ts`, Test: `tests/pipeline.test.ts`
-
-- [ ] **Step 12.1:** Write failing tests: calls all steps in order (tts → record → export), checks ffmpeg first
-- [ ] **Step 12.2:** Implement runPipeline: checkFfmpeg, then generateClips → record → alignClips → exportVideo with console progress
-- [ ] **Step 12.3:** Run tests — verify they pass
-- [ ] **Step 12.4:** Commit: "feat: pipeline orchestration for end-to-end demo generation"
-
-### Task 13: CLI
-
-**Files:** Create: `src/cli.ts`, Test: `tests/cli.test.ts`
-
-- [ ] **Step 13.1:** Write failing tests: record/tts generate/tts align/export/pipeline/init commands call correct functions, --config passes to loadConfig
-- [ ] **Step 13.2:** Implement createProgram with commander: all commands as thin wrappers that load config and delegate
-- [ ] **Step 13.3:** Run tests — verify they pass
-- [ ] **Step 13.4:** Commit: "feat: CLI with commander for all pipeline commands"
-
-### Task 14: Init + Library Exports
-
-**Files:** Create: `src/init.ts`, Modify: `src/index.ts`, Test: `tests/init.test.ts`
-
-- [ ] **Step 14.1:** Write failing tests: creates demos/, example.demo.ts, example.voiceover.json, argo.config.ts; does not overwrite existing
-- [ ] **Step 14.2:** Implement init: writeIfMissing for each scaffold file with template content
-- [ ] **Step 14.3:** Update src/index.ts: export test, expect, demoType, NarrationTimeline, showCaption, hideCaption, withCaption, defineConfig, demosProject, TTSEngine type
-- [ ] **Step 14.4:** Run all tests: `npx vitest run`
-- [ ] **Step 14.5:** Commit: "feat: init scaffolding and complete library exports"