videowright 0.1.0

package/skill/install/INSTALL.md

@@ -0,0 +1,400 @@
+# Install Videowright
+
+*This file is an install script for coding agents (Claude Code, Codex, opencode). Read it top-to-bottom and execute each step.*
+
+You are installing Videowright -- a library for composing animated explainer videos in HTML/CSS/JS. Follow these steps in order. Do not skip steps. Do not reorder.
+
+Each step includes exact prompts to show the user. Use them verbatim -- do not rephrase.
+
+---
+
+## Step 1: Folder check
+
+Videowright expects to own its folder. It can live in a sub-folder of a larger repo, but it should not share a folder with another project.
+
+Inspect the current working directory. Apply these rules in order:
+
+1. **Empty folder, or only innocent files** (`README.md`, `LICENSE`, `.gitignore`, `.git/`, an empty or near-empty `package.json` with no meaningful dependencies): proceed without asking. This is the happy path.
+
+2. **Already a Videowright project** (`videowright.config.ts` exists, or `package.json` has `videowright` in `dependencies` or `devDependencies`): proceed without asking. This is a re-install or repair.
+
+3. **Has other project content** (source code, populated `package.json` with unrelated dependencies, framework config files, etc.): stop and ask the user exactly:
+
+   > This folder already contains another project. Videowright should own its own folder. Options:
+   > 1. Cancel and `cd` into a clean folder.
+   > 2. Install into a sub-folder of this project (recommended sub-folder name: `videos/`).
+   >
+   > Which would you like?
+
+   - If they pick **1**: stop the install. Tell the user to `cd` into a clean folder and re-run.
+   - If they pick **2**: confirm or adjust the sub-folder name (default `videos/`). Create the directory if it does not exist. `cd` into it for the remainder of the install. Remember: the instruction file (Step 6) is written to the **root** of the larger project, not the sub-folder.
+
+---
+
+## Step 2: Agent detection
+
+Detect which supported coding agents are installed. Run these commands separately (since `&&` short-circuits on failure). On macOS/Linux use `which`; on Windows use `where`:
+
+```bash
+# macOS / Linux
+which claude
+which codex
+which opencode
+
+# Windows (if not using WSL)
+where claude
+where codex
+where opencode
+```
+
+The agent you are running in is implicitly installed -- include it in the detected set even if `which` fails (e.g., it may not be on `PATH` inside the sandbox).
+
+**Decision:**
+
+- **Only one supported agent installed** (the current one): proceed without asking. You will install the skill and instruction file for this agent only.
+
+- **Multiple supported agents installed**: ask the user exactly:
+
+  > I see you have [list of detected agents] installed. Should I set up Videowright for all of them, or just [current agent]?
+  > 1. Just [current agent].
+  > 2. All installed agents.
+  >
+  > Which?
+
+  Default suggestion is **1** (just the current agent). The user can re-run install in another agent later.
+
+Record the chosen set of agents for Step 6.
+
+---
+
+## Step 3: Package manager detection
+
+Detect the package manager. Apply these rules in order:
+
+1. **Lockfile exists**: `package-lock.json` -> use `npm`. `pnpm-lock.yaml` -> use `pnpm`. If `yarn.lock` or `bun.lockb` exists (but no npm/pnpm lockfile), warn the user:
+   > This project uses yarn/bun, which Videowright does not support. Would you like to proceed with npm or pnpm instead?
+   If they agree, continue to step 2 to pick npm or pnpm. If not, stop.
+
+2. **No lockfile -- check availability** (use `which` on macOS/Linux, `where` on Windows):
+   ```bash
+   # macOS / Linux
+   which npm
+   which pnpm
+
+   # Windows (if not using WSL)
+   where npm
+   where pnpm
+   ```
+   - Only one installed: use it without asking.
+   - Both installed: ask the user exactly:
+     > Which package manager do you want to use? [npm] or [pnpm]?
+     >
+     > Default: npm.
+   - Neither installed: stop with this exact message:
+     > Videowright requires npm or pnpm. Install one and try again.
+
+Record the chosen package manager as `<pm>` for the remaining steps.
+
+---
+
+## Step 4: Package install
+
+### 4a: Ensure package.json exists
+
+If `package.json` does **not** exist in the current directory, write one with these fields:
+
+```json
+{
+  "name": "my-videowright-project",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx videowright dev",
+    "render": "npx videowright render"
+  }
+}
+```
+
+Optionally rename the `"name"` field to match the current directory name (kebab-case).
+
+The canonical source for this shape is `node_modules/videowright/skill/assets/install/package.json` (available after step 4b).
+
+If `package.json` **does** exist:
+
+1. Read the file and check for the `"type"` field.
+2. If `"type"` is missing: add `"type": "module"` to the existing package.json. Do not overwrite other fields.
+3. If `"type"` exists and equals `"module"`: no action needed.
+4. If `"type"` exists with a value other than `"module"`: stop and tell the user exactly:
+   > Your package.json has `"type": "<current-value>"`. Videowright requires `"type": "module"` for ESM imports. Should I change it?
+   If the user agrees, update the field. If not, stop the install -- Videowright will not work without ESM.
+5. Check for `"scripts"` and add `"dev"` and `"render"` entries if they do not already exist. Do not overwrite existing script entries.
+
+### 4b: Install Videowright
+
+```bash
+<pm> install videowright
+```
+
+### 4c: Install dev toolchain
+
+Install the dev tools that Videowright projects use. These mirror the core Videowright repo's own toolchain.
+
+**Pin versions from the core package:** after step 4b, read `node_modules/videowright/package.json` and note the version ranges in its `devDependencies` for `vitest` and `@playwright/test`. Use those same version ranges when installing:
+
+```bash
+<pm> install --save-dev vitest@<version-from-core> @playwright/test@<version-from-core>
+```
+
+**Install latest for tools not in core:** `typescript` and `@biomejs/biome` are not listed in the core `videowright` package's `package.json`. Install the latest version of each:
+
+```bash
+<pm> install --save-dev typescript @biomejs/biome
+```
+
+| Tool | Version source | Purpose |
+|---|---|---|
+| `vitest` | Pin from core package.json | Unit tests for segment helpers |
+| `@playwright/test` | Pin from core package.json | E2e/browser tests for video output |
+| `typescript` | Latest | Type-checking for segments and config |
+| `@biomejs/biome` | Latest | Lint + format (single tool) |
+
+If a dev dependency is already present at a compatible version, skip it. If present at an incompatible version, warn the user and let them decide whether to upgrade.
+
+### 4d: Ensure tsconfig.json exists
+
+If `tsconfig.json` does **not** exist in the current directory, copy the template:
+
+```bash
+cp node_modules/videowright/skill/assets/install/tsconfig.json tsconfig.json
+```
+
+If `tsconfig.json` **does** exist, leave it alone. Do not attempt to merge tsconfig files — the user's existing configuration takes precedence.
+
+### 4e: Install Playwright browsers
+
+```bash
+npx playwright install
+```
+
+This downloads the browser binaries Playwright needs for e2e testing and video export.
+
+### 4f: Check and install ffmpeg
+
+ffmpeg is required for video rendering (combining frames into the final video file). Check whether it is available on PATH:
+
+```bash
+# macOS / Linux
+which ffmpeg
+
+# Windows (if not using WSL)
+where ffmpeg
+```
+
+**If ffmpeg is found:** proceed to the next step without prompting.
+
+**If ffmpeg is not found:** detect the platform, then check for a supported package manager to attempt auto-install.
+
+**Platform detection:** on macOS/Linux, run `uname -s` — a result of `Darwin` means macOS, `Linux` means Linux. On Windows, skip this step (you already know). Then check for a package manager from the matching platform row(s) in the table below (first match wins):
+
+| Platform | Package manager detection | Install command |
+|---|---|---|
+| macOS | `which brew` | `brew install ffmpeg` |
+| Linux (Debian/Ubuntu) | `which apt` | `sudo apt update && sudo apt install -y ffmpeg` |
+| Linux (Fedora/RHEL) | `which dnf` | `sudo dnf install -y ffmpeg-free` |
+| Linux (Arch) | `which pacman` | `sudo pacman -S --noconfirm ffmpeg` |
+| Windows | `where choco` | `choco install ffmpeg -y` |
+| Windows | `where scoop` | `scoop install ffmpeg` |
+| Windows | `where winget` | `winget install --id Gyan.FFmpeg -e --accept-source-agreements` |
+
+Apply these rules in order:
+
+1. **Recognized package manager found:** ask the user exactly:
+
+   > ffmpeg is required for video rendering but was not found on your PATH. I can install it for you using `<install-command>`. Proceed?
+   > 1. Yes, install ffmpeg.
+   > 2. No, I'll install it manually.
+
+   - If **yes**: run the install command. Then re-verify that `ffmpeg` is on PATH (re-run `which`/`where`). If it still cannot be found, tell the user the install may have failed and show the same manual install message as the "no" case below.
+   - If **no**: tell the user exactly:
+
+     > OK — please install ffmpeg manually and make sure it is on your PATH, then say "done" to continue.
+     >
+     > - macOS: `brew install ffmpeg` (install Homebrew from https://brew.sh if needed)
+     > - Linux: use your distribution's package manager (e.g., `sudo apt install ffmpeg`)
+     > - Windows: download from https://ffmpeg.org/download.html, or use `choco install ffmpeg` / `winget install ffmpeg`
+
+     Wait for the user to confirm, then re-verify that `ffmpeg` is on PATH. If still not found, repeat the message. Do not proceed until ffmpeg is confirmed available.
+
+2. **No recognized package manager found:** tell the user exactly:
+
+   > ffmpeg is required for video rendering but was not found on your PATH, and I could not detect a supported package manager to install it automatically.
+   >
+   > Please install ffmpeg manually:
+   > - macOS: `brew install ffmpeg` (install Homebrew from https://brew.sh if needed)
+   > - Linux: use your distribution's package manager (e.g., `sudo apt install ffmpeg`)
+   > - Windows: download from https://ffmpeg.org/download.html, or use `choco install ffmpeg` / `winget install ffmpeg`
+   >
+   > After installing, make sure `ffmpeg` is on your PATH, then say "done" to continue.
+
+   Wait for the user to confirm, then re-verify that `ffmpeg` is on PATH. If still not found, repeat the message. Do not proceed until ffmpeg is confirmed available.
+
+### 4g: Verify install
+
+1. Confirm that `node_modules/videowright/` exists after installation. If it does not, surface the error to the user and stop.
+2. Read `package.json` and verify that `"type"` is set to `"module"`. If it is not, the dev server will fail with `Cannot use import statement outside a module`. Fix it before proceeding.
+3. Confirm that `tsconfig.json` exists.
+
+---
+
+## Step 5: Skill installation (symlinks)
+
+Create **both** of these symlinks at the install root (the Videowright project folder), regardless of which agent(s) the user chose in Step 2. This keeps the install idempotent and future-proof.
+
+**Symlinks to create:**
+
+| Symlink path | Target |
+|---|---|
+| `.claude/skills/videowright` | `node_modules/videowright/skill/` |
+| `.agents/skills/videowright` | `node_modules/videowright/skill/` |
+
+**Coverage:**
+
+| Agent | Reads from |
+|---|---|
+| Claude Code | `.claude/skills/` |
+| Codex | `.agents/skills/` |
+| opencode | both `.claude/skills/` and `.agents/skills/` |
+
+**How to create each symlink:**
+
+Follow the symlink creation algorithm in Appendix B. In summary:
+
+1. Create intermediate directories if they do not exist (e.g., `.claude/skills/`).
+2. Compute the target as a **relative path** from the symlink's parent directory to `node_modules/videowright/skill/`. See Appendix B for examples.
+3. If the symlink already exists and points to the correct target: leave it alone.
+4. If the symlink exists but points elsewhere: ask the user before replacing.
+5. If a real file or directory exists at the symlink path: ask the user before replacing.
+6. Create the symlink:
+   - macOS/Linux: `ln -s <relative-target> <symlink-path>`
+   - Windows: `mklink /D <symlink-path> <relative-target>`
+
+**Windows note:** If symlink creation fails on Windows, tell the user exactly:
+
+> Symlink creation failed. On Windows, this usually means Developer Mode is off. Either enable Developer Mode (Settings > Privacy & security > For developers > Developer Mode) and re-run, or create the link manually with `mklink /D .claude\skills\videowright node_modules\videowright\skill` (run from an admin terminal). Then verify by running setup again.
+
+---
+
+## Step 6: Instruction file
+
+Write or update the instruction file for each agent the user opted to install for in Step 2.
+
+**File mapping:**
+
+| Agent | Instruction file |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Codex | `AGENTS.md` |
+| opencode | `AGENTS.md` |
+
+If installing for multiple agents that need different files (e.g., Claude Code + Codex), write the **same content** into each file. Do not symlink between them.
+
+**File location:** the instruction file is written at the **root** of the project. If Step 1 chose sub-folder mode, the instruction file goes in the parent (the larger repo's root), not in the sub-folder.
+
+**Content:** use a marked region so re-installs are idempotent. Follow the marked-region writer algorithm in Appendix A.
+
+The content to place inside the marked region depends on whether this is a root install or sub-folder install:
+
+### Root install content:
+
+```
+<!-- videowright:start -->
+*Auto-managed by Videowright installer. Edits inside this block will be overwritten on re-install. Add your own context outside the markers.*
+
+This project is a [Videowright](https://github.com/scosman/videowright) project -- a library for composing animated explainer videos in HTML/CSS/JS.
+
+For any video-related work, use the `videowright` skill (loaded automatically from `.claude/skills/videowright` or `.agents/skills/videowright`). It has full guidance on segments, voiceovers, styles, and the dev server.
+
+Key paths:
+- `videowright.config.ts` -- project config and default style.
+- `videos/` -- one folder per video.
+- `styles/` -- design tokens and shared styling.
+- `segments/`, `components/`, `transitions/` -- shared building blocks.
+<!-- videowright:end -->
+```
+
+### Sub-folder install content:
+
+When Step 1 chose sub-folder mode (e.g., sub-folder `videos/`), use this complete block instead:
+
+```
+<!-- videowright:start -->
+*Auto-managed by Videowright installer. Edits inside this block will be overwritten on re-install. Add your own context outside the markers.*
+
+The folder `<subfolder>/` in this project is a [Videowright](https://github.com/scosman/videowright) project -- a library for composing animated explainer videos in HTML/CSS/JS.
+
+For any video-related work, use the `videowright` skill (loaded automatically from `.claude/skills/videowright` or `.agents/skills/videowright`). It has full guidance on segments, voiceovers, styles, and the dev server.
+
+Key paths:
+- `<subfolder>/videowright.config.ts` -- project config and default style.
+- `<subfolder>/videos/` -- one folder per video.
+- `<subfolder>/styles/` -- design tokens and shared styling.
+- `<subfolder>/segments/`, `<subfolder>/components/`, `<subfolder>/transitions/` -- shared building blocks.
+<!-- videowright:end -->
+```
+
+Replace `<subfolder>` with the actual sub-folder name chosen in Step 1.
+
+---
+
+## Step 7: Continue to setup
+
+Tell the user exactly:
+
+> Videowright installed. Now configuring the project.
+
+Then immediately load [references/setup.md](../references/setup.md) and follow it. Do **not** wait for user input between install and setup — proceed directly.
+
+---
+
+## Appendix A: Marked-region writer algorithm
+
+Given a target file path and the content string to place inside the markers:
+
+1. **File does not exist**: create a new file containing exactly the full marked region as shown in Step 6 (including the start/end markers, the auto-managed note, and the content). For example:
+   ```
+   <!-- videowright:start -->
+   *Auto-managed by Videowright installer. Edits inside this block will be overwritten on re-install. Add your own context outside the markers.*
+
+   ... rest of content ...
+   <!-- videowright:end -->
+   ```
+
+2. **File exists**: read its contents and search for the pattern `<!-- videowright:start -->` ... `<!-- videowright:end -->`:
+   - **Match found**: replace everything from `<!-- videowright:start -->` through `<!-- videowright:end -->` (inclusive) with the new marked region. This is an idempotent re-install.
+   - **No match**: append the full marked region (start marker, auto-managed note, content, end marker -- exactly as shown in point 1) at the end of the file. If the file does not end with a newline, add two blank lines before the region; otherwise add one blank line.
+
+3. **Never modify content outside the markers.**
+
+## Appendix B: Symlink creation algorithm
+
+Given a symlink path (e.g., `.claude/skills/videowright`) and a target directory (`node_modules/videowright/skill/`):
+
+1. **Create intermediate directories**: ensure the parent directory of the symlink exists (e.g., `.claude/skills/`). Create with `mkdir -p` if needed.
+
+2. **Compute relative target**: the symlink target must be a relative path from the symlink's parent directory to the target. Compute this dynamically based on the actual directory depth. Examples:
+   - **Root install**: symlink at `.claude/skills/videowright`, target at `node_modules/videowright/skill/` -- relative target is `../../node_modules/videowright/skill/`
+   - **Sub-folder install** (e.g., project in `videos/`): symlink at `videos/.claude/skills/videowright`, target at `videos/node_modules/videowright/skill/` -- relative target is `../../node_modules/videowright/skill/` (same, because both are relative to the sub-folder root)
+
+3. **Check existing state**:
+   - If the path is a symlink pointing to the correct relative target: do nothing (idempotent).
+   - If the path is a symlink pointing to a different target: ask the user before replacing:
+     > `.claude/skills/videowright` currently points to `<old-target>`. Replace it with a link to `node_modules/videowright/skill/`?
+   - If the path is a real file or directory (not a symlink): ask the user before replacing.
+   - If the path does not exist: proceed to create.
+
+4. **Create the symlink**:
+   - macOS/Linux: `ln -s <relative-target> <symlink-path>`
+   - Windows: `mklink /D <symlink-path> <relative-target>`
+
+Apply this algorithm identically for both `.claude/skills/videowright` and `.agents/skills/videowright`.

package/skill/references/audio/audio_plan.md

@@ -0,0 +1,199 @@
+# Audio Plan Format
+
+## When this is loaded
+
+You are authoring or editing an `audio_plan.md` file for a video. This reference specifies the format, the two-section structure, and the conventions the build and sync stages depend on.
+
+## Overview
+
+Every video with audio gets one `audio_plan.md` at `videos/<video-slug>/audio/audio_plan.md`. It describes the complete audio composition: which source assets are used, how they are sliced and placed in time, their volume curves and fades, and the ffmpeg command that renders the final mix.
+
+The file has two sections:
+
+1. **Plan** (top) -- the current intended audio composition. Overwritten as the mix evolves.
+2. **Log** (bottom) -- append-only history of edits and renders. Never delete entries.
+
+The build stage reads the Plan section to produce a rendered track. The sync stage reads the rendered track's snapshot to compute per-segment timing. The Log section is for human and agent reference only.
+
+## Plan section
+
+### Structure
+
+```markdown
+# Audio Plan
+
+## Plan
+
+<prose summary>
+
+### Cue 1 -- <short name>
+<labeled fields + ffmpeg snippet>
+
+### Cue 2 -- <short name>
+<labeled fields + ffmpeg snippet>
+
+...
+
+### Final mix command
+
+<single ffmpeg invocation>
+
+## Log
+
+<append-only entries>
+```
+
+### Prose summary
+
+A 1-3 sentence description of the audio composition. It anchors what the mix is trying to achieve and helps when reviewing cue-level detail.
+
+Examples:
+
+> Music bed throughout. VO carries the demo (4.5-22s). Keyboard SFX over the terminal segment, brief whoosh on transitions.
+
+> VO-only track. Single full-file voiceover placed at 0s.
+
+### Cues
+
+Cues are listed in playback order. Each cue uses the labeled-field template defined in [cue_template.md](cue_template.md). Every cue ends with an ffmpeg snippet that produces a labeled audio stream.
+
+Number cues sequentially starting at 1. When cues are added or removed, renumber.
+
+### Final mix command
+
+After all cues, the plan includes a single complete ffmpeg invocation that:
+
+1. Takes every input file referenced by the cues
+2. Applies the per-cue filter fragments
+3. Mixes them with `amix` (or equivalent)
+4. Writes output to `{TRACK_OUT}`
+
+The `{TRACK_OUT}` placeholder is replaced at build time with the actual output path (e.g., `audio/tracks/v3/track.mp3`).
+
+The final mix command must be a **self-contained, runnable ffmpeg command** -- not a fragment. It should include all inputs, the complete filter graph, and the output path placeholder.
+
+Example (VO-only, simplest case):
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -c:a libmp3lame -q:a 2 \
+  {TRACK_OUT}
+```
+
+Example (VO + music with ducking):
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -i audio/originals/music/uplift_piano/audio.mp3 \
+  -filter_complex "
+    [0:a] atrim=0:22.5, asetpts=PTS-STARTPTS [vo];
+    [1:a] atrim=0:30, asetpts=PTS-STARTPTS,
+          volume='if(between(t,4.5,22),0.15,1)':eval=frame,
+          afade=t=in:st=0:d=0.5, afade=t=out:st=28:d=2 [music];
+    [vo][music] amix=inputs=2:duration=longest:normalize=0 [mix];
+    [mix] loudnorm=I=-14:TP=-1:LRA=11 [out]
+  " -map "[out]" -c:a libmp3lame -q:a 2 {TRACK_OUT}
+```
+
+### Paths in the plan
+
+All paths in the plan are **relative to the video folder** (the parent of `audio/`). This matches the working directory when the agent runs ffmpeg from the video folder.
+
+Example: `audio/originals/voiceovers/v1/audio.mp3`, not an absolute path.
+
+## Log section
+
+The Log section is below the Plan section, separated by `## Log`. Entries are newest-first (most recent at the top, matching PLAN.md convention). Each entry records one discrete event.
+
+### Render entry
+
+```markdown
+## YYYY-MM-DD HH:MM -- <summary of what changed>
+**Change:** <what was modified in the plan>
+**Why:** <user feedback or reason>
+**Render:** ffmpeg ... -> audio/tracks/vN/track.mp3
+```
+
+### Activation entry
+
+Written when the user approves a track and it becomes the default:
+
+```markdown
+## YYYY-MM-DD HH:MM -- Adopted vN as active track
+```
+
+### Discard entry
+
+Written when the user discards a rendered track:
+
+```markdown
+## YYYY-MM-DD HH:MM -- Discarded vN
+**Why:** <user feedback>
+```
+
+### Edit entry
+
+For plan-only changes (no render):
+
+```markdown
+## YYYY-MM-DD HH:MM -- <what changed>
+**Change:** <description>
+**Why:** <reason>
+```
+
+Free-text body below the structured fields is welcome for longer notes.
+
+## VO-only shortcut
+
+For videos with only a voiceover and no SFX or music, the audio plan is minimal:
+
+```markdown
+# Audio Plan
+
+## Plan
+
+VO-only track. Single full-file voiceover placed at 0s.
+
+### Cue 1 -- VO (full file)
+Source: audio/originals/voiceovers/v1/
+Slice: full file
+Place at: 0s
+Volume: 100%
+Fades: none
+Notes: Full voiceover, see timing.json for word timings.
+
+ffmpeg snippet:
+[0:a] acopy [vo1]
+
+### Final mix command
+
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -c:a libmp3lame -q:a 2 \
+  {TRACK_OUT}
+
+## Log
+
+(No entries yet.)
+```
+
+For VO-only videos, the plan is auto-emitted by the skill. The user does not need to understand the plan format -- it is created as part of the voiceover flow and consumed transparently by build and sync.
+
+## Editing the plan
+
+When the user requests changes to the audio mix:
+
+1. Update the relevant cues in the Plan section (add, remove, or modify cues).
+2. Update the final mix command to match the new cue set.
+3. Renumber cues if needed.
+4. Do **not** modify the Log section when editing the plan. Log entries are appended only at build time or when significant plan changes are recorded.
+
+## Relationship to other files
+
+- **`cue_template.md`** -- defines the per-cue field format
+- **`build.md`** -- reads the plan to produce a rendered track
+- **`sync.md`** -- reads the track's plan snapshot to compute timing
+- **`ffmpeg_cookbook.md`** -- recipes for common ffmpeg operations used in cue snippets
+- **`styles.md`** -- guidance on volume levels, ducking, and mix aesthetics