videowright 0.1.0

package/skill/references/testing.md

@@ -0,0 +1,115 @@
+# Testing
+
+## When this is loaded
+
+You were routed here from the intent dispatch table because the user wants to write tests for their Videowright project.
+
+## What is worth testing
+
+Videowright projects are content-heavy. Not everything needs automated tests. Focus testing effort on things that break silently and are hard to catch by eye.
+
+The examples below are suggestions -- pick what fits the project. Do not prescribe a rigid test suite. For context on the tools these tests exercise, see [dev_server.md](dev_server.md) (interactive preview) and [export.md](export.md) (render export pipeline and advances validation).
+
+## Advances coherence
+
+The most common source of export failures is a mismatch between a segment's `advances` array and its actual `waitForNext()`/`hold()` calls.
+
+**What to test:** For each segment, verify that `advances.length` matches the expected number of triggerNext presses.
+
+```ts
+import { expect, test } from 'vitest';
+
+test('intro segment has correct advances count', async () => {
+  const mod = await import('../segments/intro/index.js');
+  const segment = mod.default;
+  // intro: hold(3000) -> 1 press to move past
+  expect(segment.advances).toHaveLength(1);
+});
+
+test('feature-list segment advances match beat count', async () => {
+  const mod = await import('../segments/feature-list/index.js');
+  const segment = mod.default;
+  // 3 waitForNext calls + 1 final press = 4 advances
+  expect(segment.advances).toHaveLength(4);
+});
+```
+
+This catches the case where someone adds a `waitForNext()` call but forgets to add an entry to `advances` (or vice versa). The export pipeline validates this at runtime, but catching it in tests is faster.
+
+## Typecheck
+
+Run the TypeScript compiler as part of CI to catch type errors in segments, timelines, and config:
+
+```bash
+npx tsc --noEmit
+```
+
+This verifies that:
+
+- All segment specs match the `SegmentSpec` type.
+- Timeline entries reference valid types.
+- Config uses correct field types.
+
+Type errors in segments are common after refactoring shared components or updating the lib version.
+
+## Playwright screenshot tests
+
+For visual-heavy segments, capture a screenshot at key beats and compare against a baseline:
+
+```ts
+import { expect, test } from '@playwright/test';
+
+test('intro segment renders correctly', async ({ page }) => {
+  await page.goto('http://localhost:5173/#/intro/0');
+  // Wait for segment to mount and settle
+  await page.waitForFunction('document.body.dataset.vwState === "playing"');
+  await expect(page).toHaveScreenshot('intro-beat-0.png');
+});
+
+test('feature-cards shows all cards after advances', async ({ page }) => {
+  await page.goto('http://localhost:5173/#/feature-cards/0');
+  await page.waitForFunction('document.body.dataset.vwState === "playing"');
+  // Advance twice to reveal cards, waiting for player to settle after each press
+  await page.keyboard.press('Space');
+  await page.waitForFunction('document.body.dataset.vwState === "playing"');
+  await page.keyboard.press('Space');
+  await page.waitForFunction('document.body.dataset.vwState === "playing"');
+  await expect(page).toHaveScreenshot('feature-cards-revealed.png');
+});
+```
+
+This requires a running dev server. In CI, start the dev server before tests:
+
+```bash
+npx videowright dev --port 5173 &
+npx playwright test
+```
+
+Screenshot tests are heavyweight — use them selectively for segments where visual correctness is important (branded content, data visualizations, precise layouts).
+
+## Timeline structure
+
+Verify that a timeline references valid segments and has expected properties:
+
+```ts
+import { expect, test } from 'vitest';
+
+test('demo timeline has expected segments', async () => {
+  const mod = await import('../videos/demo/timeline.js');
+  const timeline = mod.default;
+  
+  expect(timeline.meta.title).toBeTruthy();
+  expect(timeline.segments.length).toBeGreaterThan(0);
+  
+  const ids = timeline.segments.map(s => s.id);
+  expect(ids).toContain('intro');
+  expect(ids).toContain('outro');
+});
+```
+
+## What not to test
+
+- **Visual aesthetics.** Whether a segment "looks good" is a design judgment, not a test assertion.
+- **Voiceover text content.** VO copy changes frequently. Testing exact strings creates maintenance burden.
+- **Transition behavior.** Built-in transitions are tested in the lib's own test suite. Custom transitions may warrant tests if they have complex logic.
+- **The lib itself.** Videowright's internal tests cover the player, runner, CLI, and export pipeline. Consumer projects do not need to re-test lib behavior.

package/skill/references/types.md

@@ -0,0 +1,240 @@
+# Types
+
+Quick reference for Videowright's public TypeScript types. All types are importable from `'videowright'`.
+
+## Segment types
+
+### `SegmentSpec`
+
+The spec object passed to `defineSegment()`.
+
+```ts
+interface SegmentSpec {
+  id: string;
+  advances: number[];
+  voiceover?: string;
+  notes?: string;
+  mount?(el: HTMLElement, ctx: PlayerContext): void | Promise<void>;
+  play(ctx: PlayerContext): Promise<void>;
+  unmount?(): void;
+  next?(): boolean;
+  prev?(): boolean;
+}
+```
+
+See [authoring_segment.md](authoring_segment.md) for field details.
+
+### `Segment`
+
+The branded object returned by `defineSegment()`. Extends `SegmentSpec` with an internal brand symbol. Frozen and immutable.
+
+```ts
+interface Segment extends SegmentSpec {
+  readonly [SEGMENT_BRAND]: true;
+}
+```
+
+### `PlayerContext`
+
+Runtime context passed to `mount` and `play` lifecycle methods.
+
+```ts
+interface PlayerContext {
+  waitForNext(): Promise<void>;
+  hold(ms: number): Promise<void>;
+  signal: AbortSignal;
+  mode: 'interactive' | 'render';
+  clock(): number;
+}
+```
+
+## Timeline types
+
+### `Timeline`
+
+A complete timeline definition. Default export of a video's `timeline.ts`.
+
+```ts
+interface Timeline {
+  meta: TimelineMeta;
+  segments: TimelineEntry[];
+  default_timing?: Timing;
+  default_audio_track?: AudioTrack;
+}
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `meta` | Yes | Timeline-level metadata. |
+| `segments` | Yes | Ordered array of segment entries. |
+| `default_timing` | No | Standalone timing overrides. Used when no audio track is active. |
+| `default_audio_track` | No | Default audio track for this video. See [audio.md](audio.md). |
+
+### `TimelineMeta`
+
+Timeline-level metadata.
+
+```ts
+interface TimelineMeta {
+  title: string;
+  style?: string;
+  aspectRatio?: string;
+  resolution?: [number, number];
+  fps?: number;
+}
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `title` | Yes | Video title. |
+| `style` | No | Style slug for this video. Overrides `config.defaultStyle`. Must match a folder in `styles/`. |
+| `aspectRatio` | No | Aspect ratio string (e.g., `'16:9'`). Falls back to config default, then `'16:9'`. |
+| `resolution` | No | `[width, height]` in pixels. Falls back to config default, then `[1920, 1080]`. |
+| `fps` | No | Frames per second. Falls back to config default, then `60`. |
+
+### `TimelineEntry`
+
+A single entry in a timeline's segments array.
+
+```ts
+interface TimelineEntry {
+  id: string;
+  transition?: string | { type: string; [k: string]: unknown };
+}
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `id` | Yes | Segment id. Maps to `segments/<id>/index.ts`. |
+| `transition` | No | Transition when entering this segment. String name (e.g., `'fade'`) or config object. |
+
+Built-in transitions: `cut`, `fade`, `slideLeft`, `slideRight`, `slideUp`, `slideDown`.
+
+## Timing and Voiceover types
+
+### `Timing`
+
+Per-segment advance schedule overrides. Used by voiceovers and as a standalone timing layer (`default_timing` on Timeline).
+
+```ts
+type Timing = {
+  perSegment: Partial<Record<string, number[]>>;
+};
+```
+
+Keys are segment ids; values are advance times in seconds (same units as `SegmentSpec.advances`). A Timing only needs to specify segments it wants to override -- unspecified segments fall back to their own `advances`.
+
+### `AudioTrack`
+
+A rendered audio track for a video. Stored at `videos/<video>/audio/tracks/<id>/track.ts`.
+
+```ts
+type AudioTrack = {
+  audio_file: string;
+  length_s: number;
+  timing: Timing;
+  audio_plan_path?: string;
+  plan_snapshot_path?: string;
+  created_at?: string;
+  notes?: string;
+};
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `audio_file` | Yes | Audio file path, relative to the **video folder** (directory containing `timeline.ts`). E.g., `"./audio/tracks/v1/track.mp3"`. Rewritten to absolute by `loadAudioTrack()`. |
+| `length_s` | Yes | Length of the rendered audio in seconds. |
+| `timing` | Yes | Per-segment advance timing synced to this audio track. |
+| `audio_plan_path` | No | Path to the audio plan that produced this track, relative to `track.ts`. |
+| `plan_snapshot_path` | No | Path to the point-in-time plan snapshot, relative to `track.ts`. |
+| `created_at` | No | ISO timestamp when this track was rendered. |
+| `notes` | No | Freeform notes about this track. |
+
+See [audio.md](audio.md) for the audio workflow.
+
+### `Voiceover`
+
+A single voiceover source file. Stored at `videos/<video>/audio/originals/voiceovers/<slug>/voiceover.ts`. Voiceovers are source data used to build audio tracks -- they are not directly referenced by `timeline.ts`.
+
+```ts
+type Voiceover = {
+  audio_file: string;
+  provider: "elevenlabs" | "manual";
+  provider_timing_file?: string;
+  timing: Timing;
+  notes?: string;
+  eleven_labs_voice_id?: string;
+};
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `audio_file` | Yes | Audio file path, relative to `voiceover.ts` directory. |
+| `provider` | Yes | Provider that produced the audio. |
+| `provider_timing_file` | No | Provider timing JSON path, relative to `voiceover.ts` directory. |
+| `timing` | Yes | Per-segment advance timing synced to this audio. |
+| `notes` | No | Freeform notes about this voiceover. |
+| `eleven_labs_voice_id` | No | ElevenLabs voice ID for TTS generation. Defaults to Asher (`tMvyQtpCVQ0DkixuYm6J`) when omitted. Ignored when provider is `"manual"`. |
+
+See [audio/voiceover.md](audio/voiceover.md) for the full voiceover flow and file conventions.
+
+## Transition types
+
+### `Transition`
+
+A transition function that animates between two slot elements.
+
+```ts
+type Transition = (
+  outgoing: HTMLElement,
+  incoming: HTMLElement,
+  ctx: TransitionContext,
+) => Promise<void>;
+```
+
+### `TransitionContext`
+
+Context passed to transition functions.
+
+```ts
+interface TransitionContext {
+  direction: 'forward' | 'backward';
+  duration?: number;
+}
+```
+
+## Config types
+
+### `Config`
+
+Repo-wide configuration from `videowright.config.ts`. Authored via `defineConfig()`.
+
+```ts
+interface Config {
+  projectStructure: 'v1';
+  defaultStyle?: string;
+  defaults?: {
+    resolution?: [number, number];
+    fps?: number;
+    aspectRatio?: string;
+  };
+  transitions?: Record<string, () => Promise<{ default: Transition }>>;
+}
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `projectStructure` | Yes | Layout version marker. Always `'v1'`. |
+| `defaultStyle` | After setup | Slug of the default style in `styles/<slug>/`. Required once setup completes. Empty or missing = setup gate open. |
+| `defaults` | No | Default values for timeline meta fields (resolution, fps, aspectRatio). |
+| `transitions` | No | Custom transition loaders keyed by name. Shadows built-ins if names collide. |
+
+## Functions
+
+### `defineSegment(spec: SegmentSpec): Segment`
+
+Validates and brands a segment spec. Throws `TypeError` if `id`, `play`, or `advances` is missing or invalid.
+
+### `defineConfig(config: Config): Config`
+
+Identity function for typed config authoring. Provides autocomplete and type checking for `videowright.config.ts`.

package/src/cli/entry/components/copy_button.ts

@@ -0,0 +1,42 @@
+/**
+ * Copy-to-clipboard icon button.
+ * Swaps to a check icon for 1.5s after a successful copy.
+ */
+
+import { iconCheck, iconCopy } from "./icons.js";
+
+export function renderCopyButton(text: string): HTMLButtonElement {
+	const btn = document.createElement("button");
+	btn.className = "vw-copy-btn";
+	btn.type = "button";
+	btn.setAttribute("aria-label", "Copy to clipboard");
+	btn.innerHTML = iconCopy();
+
+	let timeout: ReturnType<typeof setTimeout> | null = null;
+
+	btn.addEventListener("click", (e) => {
+		e.stopPropagation();
+		e.preventDefault();
+
+		navigator.clipboard.writeText(text).then(
+			() => {
+				btn.innerHTML = iconCheck();
+				btn.classList.add("vw-copy-btn--copied");
+				btn.setAttribute("aria-label", "Copied");
+
+				if (timeout) clearTimeout(timeout);
+				timeout = setTimeout(() => {
+					btn.innerHTML = iconCopy();
+					btn.classList.remove("vw-copy-btn--copied");
+					btn.setAttribute("aria-label", "Copy to clipboard");
+					timeout = null;
+				}, 1500);
+			},
+			() => {
+				// Clipboard API not available or denied -- silent fail for dev tool
+			},
+		);
+	});
+
+	return btn;
+}

package/src/cli/entry/components/download_modal.ts

@@ -0,0 +1,204 @@
+/**
+ * Download modal: two-column layout offering "Export Video" (CLI command)
+ * and "Screen Record" (instructions). Accessible from both homepage card
+ * and video view top bar.
+ */
+
+import { renderCopyButton } from "./copy_button.js";
+import { iconX } from "./icons.js";
+
+export interface DownloadModalProps {
+	slug: string;
+	title: string;
+	onClose: () => void;
+}
+
+/**
+ * Mount the download modal onto document.body.
+ * Returns a cleanup function that removes it.
+ */
+export function renderDownloadModal(props: DownloadModalProps): () => void {
+	// Dismiss any existing modal before opening a new one
+	const existing = document.querySelector(".vw-modal-backdrop");
+	if (existing) {
+		existing.remove();
+	}
+
+	const { slug, title, onClose } = props;
+
+	// Backdrop
+	const backdrop = document.createElement("div");
+	backdrop.className = "vw-modal-backdrop";
+	backdrop.setAttribute("role", "presentation");
+
+	// Modal dialog
+	const dialog = document.createElement("div");
+	dialog.className = "vw-modal";
+	dialog.setAttribute("role", "dialog");
+	dialog.setAttribute("aria-modal", "true");
+	dialog.setAttribute("aria-labelledby", "vw-modal-title");
+
+	// Header
+	const header = document.createElement("div");
+	header.className = "vw-modal__header";
+
+	const headerText = document.createElement("div");
+	headerText.className = "vw-modal__header-text";
+
+	const headerTitle = document.createElement("h2");
+	headerTitle.className = "vw-modal__title";
+	headerTitle.id = "vw-modal-title";
+	headerTitle.textContent = `Export ${title}`;
+	headerText.appendChild(headerTitle);
+
+	const headerSlug = document.createElement("div");
+	headerSlug.className = "vw-modal__slug";
+	headerSlug.textContent = slug;
+	headerText.appendChild(headerSlug);
+
+	header.appendChild(headerText);
+
+	const closeBtn = document.createElement("button");
+	closeBtn.className = "vw-modal__close";
+	closeBtn.type = "button";
+	closeBtn.setAttribute("aria-label", "Close");
+	closeBtn.innerHTML = iconX();
+	closeBtn.addEventListener("click", dismiss);
+	header.appendChild(closeBtn);
+
+	dialog.appendChild(header);
+
+	// Columns container
+	const columns = document.createElement("div");
+	columns.className = "vw-modal__columns";
+
+	// --- Export Video column ---
+	const exportCol = document.createElement("div");
+	exportCol.className = "vw-modal__column";
+
+	const exportLabel = document.createElement("div");
+	exportLabel.className = "vw-modal__column-label";
+
+	const exportLabelText = document.createElement("span");
+	exportLabelText.textContent = "EXPORT VIDEO";
+	exportLabel.appendChild(exportLabelText);
+
+	const badge = document.createElement("span");
+	badge.className = "vw-modal__badge";
+	badge.textContent = "Recommended";
+	exportLabel.appendChild(badge);
+
+	exportCol.appendChild(exportLabel);
+
+	const exportDesc = document.createElement("p");
+	exportDesc.className = "vw-modal__desc";
+	exportDesc.textContent = "Pixel-perfect MP4 export. Best quality.";
+	exportCol.appendChild(exportDesc);
+
+	// CLI command code block
+	const cliCommand = `npx videowright render ${slug}`;
+	const codeBlock = document.createElement("div");
+	codeBlock.className = "vw-modal__code";
+
+	const code = document.createElement("code");
+	code.textContent = cliCommand;
+	codeBlock.appendChild(code);
+
+	const copyBtn = renderCopyButton(cliCommand);
+	codeBlock.appendChild(copyBtn);
+
+	exportCol.appendChild(codeBlock);
+
+	const exportNote = document.createElement("p");
+	exportNote.className = "vw-modal__note";
+	exportNote.textContent = "Export is CLI-only — runs ffmpeg + Playwright on your machine.";
+	exportCol.appendChild(exportNote);
+
+	columns.appendChild(exportCol);
+
+	// --- Screen Record column ---
+	const recordCol = document.createElement("div");
+	recordCol.className = "vw-modal__column";
+
+	const recordLabel = document.createElement("div");
+	recordLabel.className = "vw-modal__column-label";
+	recordLabel.textContent = "SCREEN RECORD";
+	recordCol.appendChild(recordLabel);
+
+	const recordDesc = document.createElement("p");
+	recordDesc.className = "vw-modal__desc";
+	recordDesc.textContent =
+		"Capture in a live browser with your screen recorder. Manual pace, great for live VO.";
+	recordCol.appendChild(recordDesc);
+
+	const tips = document.createElement("ul");
+	tips.className = "vw-modal__tips";
+
+	const tipItems = ["Press H to hide HUD", "→ next | ← prev", "Space to play/pause"];
+	for (const tipText of tipItems) {
+		const li = document.createElement("li");
+		li.textContent = tipText;
+		tips.appendChild(li);
+	}
+
+	recordCol.appendChild(tips);
+	columns.appendChild(recordCol);
+
+	dialog.appendChild(columns);
+	backdrop.appendChild(dialog);
+
+	// Event handlers
+	backdrop.addEventListener("click", (e) => {
+		if (e.target === backdrop) dismiss();
+	});
+
+	function getFocusableElements(): HTMLElement[] {
+		const selectors = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+		return Array.from(dialog.querySelectorAll<HTMLElement>(selectors)).filter(
+			(el) => !el.hasAttribute("disabled"),
+		);
+	}
+
+	function onKeyDown(e: KeyboardEvent): void {
+		if (e.key === "Escape") {
+			e.preventDefault();
+			dismiss();
+			return;
+		}
+
+		// Focus trap: cycle Tab among focusable elements inside the dialog
+		if (e.key === "Tab") {
+			const focusable = getFocusableElements();
+			if (focusable.length === 0) return;
+
+			const first = focusable[0];
+			const last = focusable[focusable.length - 1];
+
+			if (e.shiftKey) {
+				if (document.activeElement === first) {
+					e.preventDefault();
+					last.focus();
+				}
+			} else {
+				if (document.activeElement === last) {
+					e.preventDefault();
+					first.focus();
+				}
+			}
+		}
+	}
+
+	function dismiss(): void {
+		document.removeEventListener("keydown", onKeyDown);
+		backdrop.remove();
+		onClose();
+	}
+
+	document.addEventListener("keydown", onKeyDown);
+	document.body.appendChild(backdrop);
+
+	// Focus the close button for keyboard accessibility
+	closeBtn.focus();
+
+	return dismiss;
+}

package/src/cli/entry/components/empty_state.ts

@@ -0,0 +1,55 @@
+/**
+ * Cold-start empty state panel.
+ * Shown on the homepage when no videos exist.
+ */
+
+import { renderCopyButton } from "./copy_button.js";
+
+export function renderEmptyState(): HTMLElement {
+	const panel = document.createElement("div");
+	panel.className = "vw-empty";
+
+	// Hero text
+	const hero = document.createElement("h2");
+	hero.className = "vw-empty__hero";
+	hero.textContent = "No videos yet";
+	panel.appendChild(hero);
+
+	// Instruction
+	const desc = document.createElement("p");
+	desc.className = "vw-empty__desc";
+	desc.textContent = "Ask your coding agent to create one for you:";
+	panel.appendChild(desc);
+
+	// Code block with copy button
+	const codeBlock = document.createElement("div");
+	codeBlock.className = "vw-empty__code";
+
+	const code = document.createElement("code");
+	code.textContent = "/videowright new video";
+	codeBlock.appendChild(code);
+
+	const copyBtn = renderCopyButton("/videowright new video");
+	codeBlock.appendChild(copyBtn);
+
+	panel.appendChild(codeBlock);
+
+	// Docs link
+	const docsLine = document.createElement("p");
+	docsLine.className = "vw-empty__docs";
+
+	const docsText = document.createTextNode("New to Videowright? ");
+	docsLine.appendChild(docsText);
+
+	const docsLink = document.createElement("a");
+	docsLink.className = "vw-empty__docs-link";
+	docsLink.href = "https://github.com/scosman/videowright";
+	docsLink.target = "_blank";
+	docsLink.rel = "noopener noreferrer";
+	docsLink.textContent = "Read the docs →";
+	docsLine.appendChild(docsLink);
+
+	panel.appendChild(docsLine);
+
+	return panel;
+}

package/src/cli/entry/components/hide_hud_tab.ts

@@ -0,0 +1,37 @@
+/**
+ * Hide-HUD tab: a small clickable tab anchored to the top edge of the HUD
+ * strip. Click toggles HUD visibility; chevron icon indicates direction.
+ */
+
+import { iconChevronDown, iconChevronUp } from "./icons.js";
+
+export interface HideHudTabProps {
+	onToggle: () => boolean; // returns new visibility state
+}
+
+/**
+ * Create the hide-HUD tab element.
+ * The tab starts in the "HUD visible" state (chevron down = collapse).
+ */
+export function renderHideHudTab(props: HideHudTabProps): HTMLElement {
+	const tab = document.createElement("button");
+	tab.className = "vw-hide-hud-tab";
+	tab.type = "button";
+	tab.setAttribute("aria-label", "Toggle HUD");
+
+	let hudVisible = true;
+
+	function updateIcon(): void {
+		tab.innerHTML = hudVisible ? iconChevronDown() : iconChevronUp();
+	}
+
+	updateIcon();
+
+	tab.addEventListener("click", (e) => {
+		e.stopPropagation();
+		hudVisible = props.onToggle();
+		updateIcon();
+	});
+
+	return tab;
+}