@lalalic/markcut 1.0.0

package/.env.example

@@ -0,0 +1,27 @@
+# ── Google Maps ──────────────────────────────────────────────────────────────
+# API key for map stream type rendering.
+# Get one at https://console.cloud.google.com/apis/credentials
+GOOGLE_MAPS_API_KEY=your_key_here
+
+# ── CLI templates (config.mjs) ──────────────────────────────────────────────
+# All use MARKCUT_*_CLI env vars. Supported placeholders vary per CLI:
+#
+#   {input}  → media file path (image, video, audio)
+#   {prompt} → text prompt / instruction
+#   {output} → output file or directory path
+#
+# Shared by vision and render pipelines:
+# MARKCUT_ITT_CLI=    # Image-to-text — placeholders: {input} {prompt}
+# MARKCUT_VTT_CLI=    # Video-to-text — placeholders: {input} {prompt}
+# MARKCUT_STT_CLI=    # Speech-to-text — placeholders: {input} {output}
+# MARKCUT_TTS_CLI=    # Text-to-speech — placeholders: {input} {output}
+# MARKCUT_AGENT_CLI=  # General-purpose agent — placeholders: {prompt}
+# Render-only:
+# MARKCUT_TTI_CLI=    # Text-to-image — placeholders: {input} {output}
+# MARKCUT_TTV_CLI=    # Text-to-video — placeholders: {input} {output}
+#                     # (empty default → TTI + ffmpeg fallback)
+# Other:
+# MARKCUT_MAX_IMAGE_DIMENSION=384
+# MARKCUT_MAX_VIDEO_DURATION=60
+# MARKCUT_MAX_VIDEO_DIMENSION=360
+# MARKCUT_VTT_SAMPLE_INTERVAL=5

package/.github/user-steer.md

@@ -0,0 +1,9 @@
+
+[Discord 2026-07-04T21:03:40.038Z]
+Discord has been disabled.
+
+[Discord 2026-07-04T21:03:42.727Z]
+Discord has been enabled.
+
+[Discord 2026-07-11T16:22:32.656Z]
+Discord has been disabled.

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "copilot-infinite.discord.enabled": false
+}

package/AGENTS.md

@@ -0,0 +1,271 @@
+# markcut — AGENT.md
+
+> Markdown-to-video engine. Describe scenes in markdown, get a rendered video with TTS narration.
+
+## Quick Start
+
+```bash
+npm run render storyboard.md      # render markdown → MP4 (9x16 default)
+npm run preview storyboard.md --edit  # live preview with auto-reload
+npm test                           # unit + integration tests
+npm run typecheck                  # TypeScript type check
+```
+
+## Input formats
+
+| Format | CLI | Description |
+|---|---|---|
+| Markdown | `markcut render storyboard.md` | `## Scene` headings, `- image src:...` bullets, `script:"narration"` |
+| Descriptive JSON | `markcut render video.json` | Same schema as markdown, JSON syntax |
+| Compiled JSON | `markcut render tree.json` | Pre-compiled stream tree (no pipeline needed) |
+
+See [docs/markdown-strict-descriptive.md](docs/markdown-strict-descriptive.md) for the complete markdown syntax reference.
+
+## Key concepts
+
+- **Scene** — narrative unit with `name`, `script` (TTS), `instruction` (visual intent), `children`
+- **Layout** — `parallel` (simultaneous), `series` (sequential), `transitionSeries` (sequential with transitions)
+- **Script → TTS → STT** — `script` field generates edge-tts audio, whisper transcribes to VTT subtitles
+- **Theme** — preset colors/fonts/effects: `cinematic`, `neon`, `minimal`, `corporate`
+- **TTL config** — root-level `tts.cli`, `tts.voice`, `tts.rate` with per-scene `tts` overrides
+- **Subtitle** — root-level VTT overlay from merged per-clip STT. Not a tree node. Supports animated caption types (`typewriter`, `fade`, `bounce`, `glowing`, etc.) via `remotion-subtitle`, HTML in cue text, and per-cue `<Sequence>` rendering for zero CPU when inactive.
+
+## Stream types
+
+| Type | Purpose |
+|---|---|
+| `root` | Canvas config: width, height, fps, theme, subtitle, stylesheet |
+| `scene` | Storyboard container: name, layout, script, children |
+| `folder` | Internal container (series/parallel) |
+| `image` | Still photo with fit mode |
+| `video` | Video clip with startFrom/endAt trimming, playbackRate |
+| `audio` | Soundtrack/SFX with foreground ducking, loop |
+| `component` | External React component by componentName + props |
+| `effect` | CSS keyframe animation wrapper (fadeIn, zoomIn, bounceIn, etc.) |
+| `include` | Embed external video JSON (file, URL, or data URI) |
+
+## CLI
+
+```bash
+markcut render <file.json|.md> [--aspect 16x9|9x16|1x1|all] [--output path]
+markcut preview <file.json|.md> [--edit] [--label] [--port 3001]
+```
+
+## Project structure
+
+```
+src/
+├── entry.tsx              → MarkCut + DescriptiveComposition
+├── descriptive/           → Compiler, markdown parser, resolve pipeline
+├── types/                 → React renderers (one per stream type)
+├── schema/                → Zod stream tree schemas
+├── themes/                → Theme presets + ThemeProvider
+├── render/cli.mjs         → CLI entry
+├── render/tts.ts          → TTS via CLI template + variable substitution
+├── player/pipeline.mjs    → Bundled pipeline (server imports this)
+├── player/server.mjs      → --edit server
+├── player/label-server.mjs→ --label server
+└── tests/                 → Vitest integration tests
+```
+
+## External component contract
+
+Register components at render time:
+
+```tsx
+<MarkCut
+  root={descriptiveJson}
+  compose={{ components: { AnimatedHeadline, StatCounter } }}
+/>
+```
+
+In descriptive markdown:
+
+```md
+- component componentName:StatCounter duration:3 props:{value:42}
+```
+
+Components receive props as defined in the descriptive JSON. No eval, no JSX parsing — just `React.createElement(registry[name], props)`.
+```
+
+## Stream Tree Architecture
+
+### Core Concept
+
+Everything is a **stream tree** — nested JSON nodes keyed by `type`.
+The tree is validated by Zod and rendered by Remotion via recursive React components.
+
+```json
+{ "id":"root", "type":"root", "width":1080, "height":1920, "fps":30,
+  "isSeries":true, "transition":"fade", "children":[...] }
+```
+
+### Composition Rules
+
+| Concept | Rule |
+|---------|------|
+| **Series** (`isSeries:true`) | Children play sequentially. Optional `transition` (fade/slide/wipe/flip/clockWipe) + `transitionTime` (default 0.5s). |
+| **Parallel** (`isSeries:false`) | Children play simultaneously. Duration = max child duration. |
+| **Background** (`isBackground:true`) | Loops for parent duration. Excluded from duration calculation. |
+| **Actions** | Every leaf has `actions[{start, end, startFrom?, endAt?, loop?, volume?, style?}]` — seconds relative to parent. |
+| **Scene** (`type:"scene"`) | UI storyboard card; engine treats as folder. Has `name` + `description` + `script`. |
+
+### Duration Calculation
+
+Computed by `getDurationInSeconds()` in `src/utils/index.ts`:
+- **Leaf nodes**: duration = last action's `end` value
+- **Series**: sum of children durations minus transition overlaps
+- **Parallel**: max of children durations
+- **Background children**: excluded from calculation
+- **Include with `src`**: treated as leaf (duration from action end)
+- Sets `durationInSeconds` on every node as a side effect
+
+### 12 Stream Types
+
+All types share base fields from `BaseShape`: `id`, `name`, `title`, `description`, `script`, `src`, `style`, `visible`, `isBackground`, `durationInSeconds`.
+
+| Type | Purpose | Key Fields |
+|------|---------|------------|
+| `root` | Canvas container | `width`, `height`, `fps`, `isSeries`, `transition`, `stylesheet` |
+| `folder` | Group children | `isSeries`, `transition`, `children[]` |
+| `scene` | Storyboard node (alias for folder) | `name`, `description`, `script`, `children[]` |
+| `image` | Still photo | `src`, `fit` (contain/cover/fill) |
+| `video` | Video clip | `src`, `volume`, `playbackRate` |
+| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent) |
+| `subtitle` | Text overlay | `src` (text/VTT) or `cues[]`, `fontSize`, `style` |
+| `component` | React component | `componentName`, `props`, `src` (remote ESM) |
+| `effect` | CSS animation wrapper | `animation`, `customKeyframes`, `children[]` |
+| `rhythm` | Beat-synced loop | `src`, `spots[]`, `children[]` |
+| `map` | Route visualization | `waypoints[{lat,lng,label}]`, `routeColor` |
+| `include` | Embed sub-tree | `src` (path/URL/data URI), `children[]` |
+
+## Key Implementation Details
+
+### Folder.tsx — Series/Parallel Engine
+
+- `FolderLeaf` is the recursive workhorse that renders all stream types
+- For `isSeries:true`: uses Remotion `<Series>` or `<TransitionSeries>` (if transition set)
+- For `isSeries:false`: renders children as parallel `<Sequence>` elements
+- Each child's duration comes from `child.durationInSeconds` (set by `getDurationInSeconds`)
+- Transition elements are interleaved between series children
+- Background children are wrapped in `<Loop>`
+- Scene nodes delegate to `SceneLeaf` → `FolderLeaf` (identity)
+- Effect nodes delegate to `EffectWrapper` → `FolderLeaf`
+
+### Video.tsx — startFrom/endAt Trimming
+
+- Uses Remotion `<OffthreadVideo>` for CPU-efficient video decoding
+- `startFrom` / `endAt` on actions trim the source video (in seconds)
+- `playbackRate` is capped at 1 (`Math.min(1, ...)`) so source longer than timeline plays at normal speed and is truncated by the Sequence
+- **Critical formula**: `OffthreadVideo endAt = startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)`
+  This sets `endAt` beyond the actual source end when `playbackRate < 1`, which prevents Remotion from rendering blank frames before the Sequence ends.
+- `endAt` without explicit value falls back to `stream.durationInSeconds ?? end - start`
+
+### Rendering Pipeline
+
+1. `Root.tsx` reads `getInputProps()` → parses via Zod `rootSchema`
+2. `getDurationInSeconds()` stamps `durationInSeconds` on every node
+3. `Composition.durationInFrames` is set to total duration
+4. `MarkCut` wraps everything in `ComposeContext` + `ThemeProvider` + `AbsoluteFill`
+5. `FolderLeaf` recursively renders the tree
+
+### CLI Usage
+
+```bash
+node src/render/cli.mjs render <file.json> [--aspect 16x9|9x16|1x1|all] [--output path]
+node src/render/cli.mjs render --template <id> --data <data.json>
+node src/render/cli.mjs preview <file.json> [--edit] [--label] [--port 3001]
+node src/render/cli.mjs templates
+```
+
+### Player Server (Edit Mode)
+
+- `--edit` flag starts a live-reload loop: edit JSON → player auto-refreshes
+- `--label` flag starts a labeling UI for selecting and annotating media
+- `--port` flag sets the server port (default 3001)
+- Two implementations: `server.mjs` (Remotion Player) and `label-server.mjs` (label input overlay)
+
+## Testing
+
+### Test Framework
+- **Vitest** with custom config in `tests/vitest.config.ts`
+- Non-parallel (`pool: "forks", fileParallelism: false`)
+- 600s timeout per test (integration tests render real MP4s)
+
+### Key Test Utilities (`tests/utils.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `renderFixture(path, opts)` | Render a stream tree JSON → MP4 using `npx remotion render` |
+| `renderScenes(path, opts)` | Render scene-based video.json using `Main16x9` composition |
+| `getVideoInfo(path)` | Extract metadata via ffprobe (duration, dimensions, FPS, audio) |
+| `extractFrame(video, time, out)` | Extract PNG frame at timestamp via ffmpeg |
+| `isFrameNonBlank(path)` | Check center pixel isn't black (>10 in any RGB channel) |
+| `getFrameFileSize(path)` | Get PNG file size (proxy for visual content) |
+| `extractAudio(video, out)` | Extract audio track to WAV |
+| `transcribeAudio(path)` | Run whisper STT on audio |
+
+### Test Categories (30 tests)
+
+1. Basic Rendering — empty composition, dimension verification
+2. Image + Subtitle — image rendering, inline/VTT/karaoke subtitles
+3. Built-in Components — AnimatedHeadline, StatCounter, GradientBackground
+4. Effects — fadeIn, bounceIn, custom keyframes
+5. Map Rendering — canvas route visualization
+6. Audio Rendering — audio track, non-silent verification
+7. Include — nested composition via include
+8. Full Feature Combination — multiple features
+9. Scene Node — scene-based rendering
+10. Audio STT — speech-to-text verification via whisper
+11. Multiple Aspect Ratios — 16x9, 9x16, 1x1
+12. Cross-Stream Types — parallel rendering, effect-wrapped children
+13. Frame-Accurate — timeline consistency, frame count
+14. Description Field — schema validation, render preservation
+15. Scene as Folder Alias — scene/folder interchangeability
+16. **Video startFrom/endAt Trimming** — video trimming + photo in series
+
+### Running Tests
+
+```bash
+npm test                    # all tests
+npm run test:integration    # render integration tests only
+npx vitest run tests/render.test.ts -t "Test Name"  # single test
+```
+
+## Known Issues & Gotchas
+
+1. **TransitionSeries + isBackground**: `TransitionSeries` from `@remotion/transitions` rejects non-Sequence/Transition children. Don't mix `isBackground:true` children with `isSeries:true, transition:"..."` at the same level.
+2. **Subvideo internal actions**: Should use `start:0` when placed in a series parent (series handles positioning).
+3. **Video endAt formula**: Must be `startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)` — changing to `endAt_source * fps` breaks slow-motion playback.
+4. **`signalstats` ffmpeg filter**: Doesn't output YAVG on all systems; use file size as proxy for visual content.
+5. **Asset paths**: Local files are resolved via `staticFile()` — files go in `public/` and are referenced without the `public/` prefix.
+6. **Map rendering**: Depends on external tile availability; may produce blank frames offline.
+
+## 3-Level Authoring Workflow (see SKILL.md)
+
+| Level | Format | Purpose |
+|-------|--------|---------|
+| **Label** | `labels.json` | Browse media, label clips, add descriptions |
+| **Storyboard** | `storyboard.json` | `scene` nodes with high-level structure + script |
+| **Assemble** | `video.json` | Full stream tree with all types, render to MP4 |
+
+### Script → TTS → STT → VTT Pipeline
+
+Every node carries an optional `script` field for narration/dialogue text. The pipeline:
+1. **Storyboard** — agent writes `script` on any node (scene, folder, leaf) as narrative text
+2. **TTS** — walk the tree, collect all `script` values with node id + timing, generate WAV audio per segment via `edge-tts`
+3. **STT** — transcribe each TTS audio or concatenated audio to VTT via whisper
+4. **Subtitle** — attach resulting VTT as a `subtitle` child node for final rendering
+
+This separates concerns: `script` = authoring text (human/agent-friendly), `subtitle` = rendered output (timed VTT cues).
+
+## Dependencies
+
+- **Remotion 4.0.469** — core rendering engine
+- **React 19** — component model
+- **Zod 4** — schema validation
+- **@remotion/transitions** — scene transitions (fade, slide, wipe, flip, clockWipe)
+- **@vis.gl/react-google-maps** — map visualization
+- **immer** — state management (player app)
+- **vitest** — test runner
+- **TypeScript 5.6** — strict mode with `noUncheckedIndexedAccess`

package/README.md

@@ -0,0 +1,219 @@
+# markcut — Markdown-to-Video Engine
+
+Write a storyboard in markdown, get a rendered video with TTS narration and subtitles.
+
+```bash
+# Render a storyboard to MP4
+npx markcut render storyboard.md --aspect 9x16
+
+# Preview with live edit (edit .md file, player auto-reloads)
+npx markcut preview storyboard.md --edit
+
+# Label clips in a stream tree
+npx markcut preview labels.json --label --port=3031
+```
+
+## How it works
+
+```
+storyboard.md  ──[parse]──▶  DescriptiveRoot  ──[compile]──▶  Stream Tree  ──[Remotion]──▶  MP4
+                                  │                                  │
+                             resolveMediaDurations()             <Sequence>
+                             resolveScripts() → TTS              <Series>
+                             resolveSubtitles() → VTT            <Img>, <OffthreadVideo>
+```
+
+1. **Write** a storyboard in markdown (scenes with `## headings`, media with `-` bullets)
+2. **Parse** the markdown into a descriptive tree
+3. **Resolve** media durations (ffprobe), generate TTS narration (edge-tts), transcribe to VTT (whisper)
+4. **Compile** the descriptive tree into a stream tree (the low-level Remotion JSON)
+5. **Render** with Remotion — no React code needed
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Markdown input** | Write `## Scene` headings, `- bullet` leaves. Components via `jsx:"<Tag />"` syntax |
+| **JS imports block** | `` ```js imports `` code fence with real ESM `import` statements instead of YAML |
+| **Dynamic components** | Load any React component from npm, GitHub, or any URL via `import { X } from "pkg"` |
+| **Tween animation** | `tween(from, to)` function calls in JSX for frame-accurate numeric animation |
+| **Compiled input** | Pre-compiled stream tree for direct Remotion rendering |
+| **TTS narration** | `script` field → edge-tts CLI → WAV audio. Configurable engine (mlx-audio, custom) |
+| **STT subtitles** | TTS audio → whisper → VTT → root subtitle overlay with animated caption types (typewriter, fade, bounce, etc.) |
+| **Tween animation** | `tween(from, to)` function calls in JSX for frame-accurate numeric animation |
+| **Styling** | Inline `style` strings on any node for CSS. JSX components use inline React styles |
+| **Live edit** | `--edit` watches the input file, re-runs pipeline, auto-reloads player |
+| **Label mode** | `--label` interactive player with per-scene label input, saves to labels.json |
+| **CLI** | `render`, `preview` commands for MP4 export and Remotion Studio |
+| **Programmatic** | `MarkCut` / `DescriptiveComposition` React components for embedding |
+
+## Example
+
+```md
+# video
+width:1080 height:1920 fps:30 layout:series
+
+## Hook
+layout:parallel script:"Set the mood with a beautiful landscape"
+- image src:cover.jpg duration:3
+
+## Features
+layout:transitionSeries transition:fade transitionTime:0.4 script:"Show what we built"
+- component duration:6 jsx:"<DeviceMockup src='screenshot.png' />"
+- component duration:4 jsx:"<StatCounter value={100} suffix='K' label='Users' />"
+```
+
+Components are registered via frontmatter `imports:` or a `` ```js imports `` code block:
+
+````
+```js imports
+import { DeviceMockup } from "mockup-component"
+import { StatCounter } from "stat-counter"
+
+// Inline component definition
+export function Greeting({ name }) {
+  return <h1 style={{color: '#fff'}}>Hello {name}</h1>;
+}
+```
+````
+
+### Dynamic Components
+
+Any React component from npm, GitHub, or any URL can be imported and used directly in JSX expressions. The engine loads them at render time via esm.sh — no build step required.
+
+```markdown
+- component duration:3 jsx:"<PieChart data={[{value:40,color:'#E38627'}]} />"
+```
+
+Inline components can be defined entirely in the imports block using `export function`, making the video self-contained with no external files.
+
+## Docs
+
+| Document | What it covers |
+|---|---|
+| [docs/json-descriptive.md](docs/json-descriptive.md) | Full JSON descriptive schema reference |
+| [docs/markdown-strict-descriptive.md](docs/markdown-strict-descriptive.md) | Markdown descriptive syntax reference |
+| [docs/label-mode.md](docs/label-mode.md) | Label mode player and workflow |
+| [docs/edit-mode.md](docs/edit-mode.md) | Live edit mode with SSE reload |
+
+
+## Variants
+
+Create different versions of the same video for different platforms, languages, or formats using **variant sections** in your markdown.
+
+### Defining Variants
+
+Add `# variant-name` headings alongside `# video` (the base). Each variant can override any property using variant-prefixed keys:
+
+```markdown
+# video
+width:1080 height:1920 fps:30 layout:series
+
+## Intro
+layout:parallel
+- component duration:3 jsx:"<h1>Hello</h1>"
+- image src:default.jpg duration:3
+
+# zh
+## Intro
+layout:parallel
+- component duration:3 zh:"<h1>你好</h1>"         ← bare key overrides jsx (primary content)
+- image zh-src:zh-image.jpg src:default.jpg       ← zh-src overrides src
+
+# youtube
+width:1920 height:1080 fps:30                     ← different aspect ratio
+## Intro
+layout:parallel
+- component duration:3 jsx:"<h1>YouTube Hello</h1>"
+```
+
+Two override mechanisms:
+- **Variant-prefixed keys**: `zh-src` → `src`, `zh-jsx` → `jsx`, `zh-script` → `script`
+- **Bare variant keys**: `zh:"<h1>你好</h1>"` replaces the node's primary content key (`jsx` for components, `src` for images/video, `script` for audio)
+
+### Multi-Variant Preview Server
+
+The `preview` command accepts multiple `--variant` flags, each defining a separate compilation target. Variants are compiled **sequentially** (not in parallel) to avoid resource contention from CLI tools like whisper and ffprobe.
+
+```bash
+# Preview 4 variants simultaneously
+npx markcut preview storyboard.md \
+  --variant default \
+  --variant zh-tiktok \
+  --variant en-tiktok \
+  --variant youtube
+
+# Each variant is served at its own URL:
+#   http://localhost:3001            → default
+#   http://localhost:3001/zh-tiktok  → zh + tiktok chain
+#   http://localhost:3001/en-tiktok  → en + tiktok chain
+#   http://localhost:3001/youtube    → youtube
+```
+
+Compound variant labels (like `zh-tiktok`) are split on `-` to form a **variant chain** — the parser applies `zh` overrides first, then `tiktok` overrides on top. Each variant gets its own compiled output and subtitle directory. Component bundles are stored in a shared cache (`.markcut/generated/components/`) — identical imports across variants reuse the same bundle.
+
+### Variant-Aware Browser
+
+The browser player reads `window.VARIANT` from the URL path and fetches the correct compiled data via `/api/video-data?variant=<name>`. A **variant switcher bar** at the top of the player lets you jump between variants instantly.
+
+## `.markcut/` Directory Layout
+
+When you run `preview` or `render`, all generated artifacts live under `.markcut/` next to the source file. With multiple variants, each gets its own subdirectory:
+
+```
+.markcut/
+  generated/                    ← shared, content-addressed (across all variants & files)
+    tts/                        ← TTS narration audio (content-hash filenames)
+    media/                      ← TTI/TTV media (content-hash filenames)
+    includes/                   ← compiled sub-video JSON (content-hash)
+    components/                 ← component bundles (content-hash, shared across variants)
+  <basename>/                   ← per-source-file
+    default/                    ← default variant artifacts
+      compiled.json             ← compiled stream tree
+      subtitles.vtt
+    zh-tiktok/                  ← variant-specific artifacts
+      compiled.json
+      subtitles.vtt
+    youtube/
+      compiled.json
+      subtitles.vtt
+```
+
+- **`generated/`** — shared artifacts using content-hash filenames, so identical scripts/prompts across different variants reuse the same cached file
+- **`generated/components/`** — component bundles shared across all variants and source files. Identical imports produce the same content hash, so variants with the same component registrations reuse the same bundle
+- **`<basename>/<variant>/compiled.json`** — the compiled stream tree for each variant, cached to disk for fast restarts
+- The server serves `.markcut/` as a document root, so components at `.markcut/generated/components/abc.js` are served as `/generated/components/abc.js`
+
+The `.markcut/` directory is gitignored by default — it's regenerated on each run.
+
+## Architecture
+
+```
+src/
+├── entry.tsx              ← Library entry: MarkCut + DescriptiveComposition
+├── index.ts               ← Remotion registerRoot (for studio/render CLI)
+├── Root.tsx               ← Remotion Composition wrapper
+├── schema/                ← Zod schemas for all stream types
+├── types/                 ← React renderers (Folder, Video, Image, Audio, etc.)
+├── descriptive/           ← Compiler, markdown parser, resolve pipeline
+├── themes/                ← Theme presets + ThemeProvider
+├── render/
+│   ├── cli.mjs            ← CLI entry point
+│   └── tts.ts             ← TTS via CLI template + variable substitution
+├── player/
+│   ├── server.mjs         ← --edit player server
+│   ├── label-server.mjs   ← --label player server
+│   ├── pipeline.ts        ← Pipeline entry (bundled to pipeline.mjs)
+│   └── browser.tsx        ← Browser player (bundled with esbuild)
+├── utils/                 ← Duration calc, VTT parser, helpers
+└── tests/                 ← Vitest integration tests
+```
+
+## Scripts
+
+```bash
+npm run render      # render a JSON stream tree to MP4
+npm run preview     # open Remotion Studio
+npm run typecheck   # TypeScript type check
+npm test            # run unit + integration tests
+```