Solidify Captioneer: translate, preview STT, CI, and professional UI

.eslintrc.cjs

@@ -0,0 +1,5 @@
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  ...require("@remotion/eslint-config"),
+  ignorePatterns: ["dist/**", "node_modules/**", "docs/**"],
+};

.github/workflows/ci.yml

@@ -33,6 +33,31 @@ jobs:
       - name: Build
         run: npm run build
 
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run validate:docs
+
+  studio-smoke:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npx remotion compositions
+
   lint:
     runs-on: ubuntu-latest
 
@@ -50,7 +75,8 @@ jobs:
         run: npm ci
 
       - name: Lint
-        run: npx eslint src --ext .ts,.tsx || true
+        continue-on-error: true
+        run: npm run lint
 
   pages:
     runs-on: ubuntu-latest

AGENTS.md

@@ -0,0 +1,56 @@
+# Cursor Cloud / agent instructions
+
+## Update script (VM startup)
+
+```bash
+npm install
+```
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Remotion Studio loads **14** demo compositions from `src/studio/`.
+
+## Preview server
+
+```bash
+npm run build
+npm run preview:web
+```
+
+Open http://localhost:3456 — upload **audio** (uses `POST /api/process` + STT env keys) or **caption JSON**.
+
+## Tests & checks
+
+```bash
+npm test
+npx tsc --noEmit
+npx remotion compositions
+npm run validate:docs
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `GROQ_API_KEY` | Groq Whisper STT |
+| `OPENAI_API_KEY` | OpenAI Whisper + `captioneer translate` |
+| `DEEPGRAM_API_KEY` | Deepgram STT |
+| `ASSEMBLYAI_API_KEY` | AssemblyAI STT |
+
+Local whisper: `captioneer process audio.mp4 --provider local` (requires whisper.cpp setup).
+
+## Design (docs & preview UI)
+
+Marketing and preview surfaces use a neutral zinc palette with a single blue accent (`#3b82f6`). Shared tokens live in `docs/theme.css`; the preview server inlines matching CSS variables. Avoid purple/gold gradients and emoji-heavy headings in new UI.
+
+## Architecture
+
+See [docs/PROJECT_PLAN.md](docs/PROJECT_PLAN.md).
+
+Node-only imports: `remotion-captioneer/node` (STT, export, translate).

CONTRIBUTING.md

@@ -23,15 +23,23 @@ npm start
 
 ## Project Structure
 
+See [docs/PROJECT_PLAN.md](docs/PROJECT_PLAN.md) for how surfaces connect.
+
 ```
 src/
-├── components/       # Caption style components
-├── types.ts          # TypeScript type definitions
-├── utils.ts          # Timing/frame utilities
-├── whisper.ts        # Whisper.cpp integration
-├── cli.ts            # CLI tool
-├── Root.tsx          # Remotion compositions
-└── index.ts          # Public exports
+├── components/       # 14 caption style components + AnimatedCaptions
+├── caption-styles.ts # CAPTION_STYLES (single list)
+├── demo/captions.ts  # Shared demo CaptionData
+├── providers/        # Cloud STT providers + registry
+├── sync/             # Audio analysis + hooks
+├── templates/        # Template builder + renderer
+├── layouts/          # Layout primitives
+├── presets/          # Style presets
+├── cli.ts            # CLI (captioneer)
+├── preview-server.ts # Browser preview (captioneer preview)
+├── remotion-entry.tsx# Remotion registerRoot entry
+├── Root.tsx          # Studio demo compositions (all styles)
+└── index.ts          # npm package exports
 ```
 
 ## Adding a New Caption Style
@@ -40,9 +48,10 @@ src/
 2. It receives `captions: CaptionData` and renders animated words
 3. Use `useCurrentFrame()` + `useVideoConfig()` to get timing
 4. Export it from `src/components/index.ts`
-5. Add it to the `styleMap` in `AnimatedCaptions.tsx`
-6. Add a demo composition in `Root.tsx`
-7. Update the README
+5. Add it to `CaptionStyle` in `types.ts` and `CAPTION_STYLES` in `caption-styles.ts`
+6. Add it to the `styleMap` in `AnimatedCaptions.tsx`
+7. Studio picks it up automatically via `Root.tsx` (no manual composition per style)
+8. Update preview-server `<select>`, README, and `docs/index.html` if user-facing
 
 ## Code Style
 

README.md

@@ -136,14 +136,6 @@ This creates a ready-to-use Remotion project with captions.
 npm install remotion-captioneer
 ```
 
-### Option 2: Add to Existing Project
-
-#### 1. Install
-
-```bash
-npm install remotion-captioneer
-```
-
 #### 2. Generate Captions from Audio
 
 ```bash
@@ -805,7 +797,7 @@ See the [`examples/`](https://github.com/neutral-Stage/remotion-captioneer/tree/
 - [x] Export formats (SRT, VTT, ASS, TXT, word-level SRT & VTT)
 - [x] Project scaffolder (`npx captioneer init`)
 - [x] 7 working examples covering all features
-- [x] 10 CLI commands (init, process, batch, export, preview, presets, providers, styles, demo)
+- [x] 11 CLI commands (init, process, batch, export, translate, preview, presets, providers, styles, demo)
 - [x] GitHub Pages demo with all 14 styles animated
 - [x] GitHub Actions CI/CD (build, test, release to npm, CodeQL)
 - [x] 0 vulnerabilities in npm audit
@@ -818,7 +810,7 @@ See the [`examples/`](https://github.com/neutral-Stage/remotion-captioneer/tree/
 - [x] ~~Caption editor with visual timeline~~ (Preview server with playback controls, progress bar, beat markers, style selector)
 - [ ] Integration with video hosting APIs (YouTube, Vimeo)
 - [x] ~~Real-time caption rendering in browser~~ (`npx captioneer preview` — live browser-based caption rendering with audio sync)
-- [ ] Caption translation utilities
+- [x] Caption translation utilities (`translateCaptionData`, `captioneer translate`)
 - [ ] Speaker diarization (multi-speaker support)
 
 ---

docs/PROJECT_PLAN.md

@@ -0,0 +1,40 @@
+# remotion-captioneer — Project plan
+
+## Product surfaces
+
+| Surface | Path | Status |
+|---------|------|--------|
+| Library API | `src/index.ts`, `src/node.ts` | ✅ |
+| Remotion Studio | `src/studio/` + `remotion.config.ts` | ✅ 14 compositions |
+| Preview server | `src/preview-server.ts` | ✅ JSON + `POST /api/process` STT |
+| GitHub Pages | `docs/index.html` | ✅ API snippets aligned |
+| Scaffold | `src/scaffold.ts` | ✅ `registerRoot` + config |
+| Examples | `examples/` + `captions.json` | ✅ README |
+
+## Implemented (maintenance backlog → done)
+
+- [x] `transcribeMediaFile()` shared by CLI + preview
+- [x] `LocalWhisperProvider` + `createProvider('local')`
+- [x] `translateCaptionData` sets `language`; batch progress logging
+- [x] `AnimatedCaptions`: `backgroundColor`, `maxWidth`, `wordsPerLine`, `useSmartWrap`
+- [x] `remotion-captioneer/node` export subpath
+- [x] Vitest + CI test + `remotion compositions` smoke
+- [x] `AGENTS.md`, `validate:docs`, examples README
+- [x] Studio under `src/studio/`
+
+## Next (optional)
+
+- [ ] Extract preview HTML to `src/preview/` bundle
+- [ ] Full ESLint cleanup (lint job is `continue-on-error` until legacy rules fixed)
+- [ ] Preview pixel parity with Remotion (or embed rendered clips on Pages)
+- [ ] Speaker diarization / hosting APIs (roadmap)
+
+## Commands
+
+| Goal | Command |
+|------|---------|
+| Studio | `npm start` |
+| Web preview | `npm run preview:web` |
+| Test | `npm test` |
+| Transcribe | `npx captioneer process audio.mp4` |
+| Node API | `import { transcribeMediaFile } from "remotion-captioneer/node"` |