@lalalic/markcut 1.1.1 → 2.0.0

package/AGENTS.md

@@ -63,8 +63,12 @@ src/
 ├── 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
+├── player/server.mjs      → Unified server (--edit, --label, preview)
+├── player/components/      → React control components (edit, label, variant bar)
+│   ├── index.ts
+│   ├── EditControls.tsx
+│   ├── LabelControls.tsx
+│   └── VariantBar.tsx
 └── tests/                 → Vitest integration tests
 ```
 
@@ -107,22 +111,22 @@ The tree is validated by Zod and rendered by Remotion via recursive React compon
 | **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. |
+| **Timing** | Every leaf carries base fields `start`/`end` (seconds, relative to parent) + optional `startFrom`/`endAt` (source trim) + `duration` (convenience). `end` is the source of truth; `duration` normalizes to `end = start + duration` when `end` is absent. Inside series parents `start` is 0 (positioning is implicit). |
 | **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
+- **Leaf nodes**: duration = `leafEnd(stream)` = `end ?? (start + duration)` (single deterministic read; `start`/`end`/`duration` live on the base node)
 - **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)
+- **Include with `src`**: treated as leaf (duration from base `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`.
+All types share base fields from `BaseShape`: `id`, `name`, `title`, `description`, `script`, `src`, `style`, `visible`, `isBackground`, `start`, `end`, `duration`, `startFrom`, `endAt`, `durationInSeconds`.
 
 | Type | Purpose | Key Fields |
 |------|---------|------------|
@@ -130,8 +134,8 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 | `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) |
+| `video` | Video clip | `src`, `volume`, `playbackRate`, `loop` |
+| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent), `loop` |
 | `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[]` |
@@ -155,7 +159,7 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 ### Video.tsx — startFrom/endAt Trimming
 
 - Uses Remotion `<OffthreadVideo>` for CPU-efficient video decoding
-- `startFrom` / `endAt` on actions trim the source video (in seconds)
+- `startFrom` / `endAt` on the base node 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.
@@ -183,7 +187,7 @@ node src/render/cli.mjs templates
 - `--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)
+- Unified server: `server.mjs` serves all modes (preview, edit, label). React control components in `components/`.
 
 ## Testing
 
@@ -235,11 +239,13 @@ 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.
+2. **Video endAt formula**: Must be `startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)` — changing to `endAt_source * fps` breaks slow-motion playback.
+3. **`signalstats` ffmpeg filter**: Doesn't output YAVG on all systems; use file size as proxy for visual content.
+4. **Asset paths**: Local files are resolved via `staticFile()` — files go in `public/` and are referenced without the `public/` prefix.
+5. **Map rendering**: Depends on external tile availability; may produce blank frames offline.
+6. **CLI md render needs three things preview gets for free**: (a) `parseMarkdownVariants(raw)` (returns `{base, variants}`) — `parseMarkdownDescriptive` returns the root directly; (b) bundling the ` ```js imports ``` ` block via `bundleFromEntries` and setting `root.imports` (otherwise jsx components are unregistered → slides render as unstyled black frames); (c) staging `.markcut/` assets into `public/.render-assets/` and rewriting srcs to relative paths (remotion render only serves its publicDir). All three live in `src/render/cli.mjs`; the import-map shim for shared react/remotion instances is `src/utils/component-import-map.ts` (must stay in sync with `player/browser.tsx` + `bundler.mjs getSharedExternals`).
+7. **Publishing**: verify `npx @lalalic/markcut render <md>` from a clean temp dir before/after publish — v1.1.1 shipped with cli.mjs/pipeline.mjs out of sync and md rendering was completely broken. Also beware stale npx caches (`~/.npm/_npx`) silently running old code.
+8. **Clean break from `actions[]`**: leaf timing is now flat base fields (`start`/`end`/`duration`/`startFrom`/`endAt`). Old compiled JSON carrying `actions:[{...}]` no longer parses into a duration — re-compile from markdown/descriptive JSON, or migrate `actions[0]` → flat fields (drop `id`/`volume`/`style`/`effectId`; keep `start`/`end`/`startFrom`/`endAt`/`loop`).
 
 ## 3-Level Authoring Workflow (see SKILL.md)
 
@@ -259,6 +265,24 @@ Every node carries an optional `script` field for narration/dialogue text. The p
 
 This separates concerns: `script` = authoring text (human/agent-friendly), `subtitle` = rendered output (timed VTT cues).
 
+### Multi-turn Dialogue
+
+When `script` text contains multiple `SpeakerName: text` lines (2+), the pipeline auto-expands it into a multi-turn dialogue. Each line becomes a separate audio node with `speaker` field, wrapped in a `series` container for sequential playback.
+
+```md
+- script "Ray: Hello everyone
+Alice: Good day to you
+Ray: Let's begin"
+```
+
+Per-speaker voices are configured via `voices` on root. Each value is extra CLI flags appended to the TTS template:
+
+```md
+voices:{"Ray":"--voice en-US-GuyNeural","Alice":"--voice en-US-JennyNeural"}
+```
+
+The speaker name is matched against `voices` map and the extra flags are appended to the TTS CLI template, naturally supporting voice cloning or edge-tts features (rate, pitch, etc.). Subtitles include the speaker prefix (`Ray: Hello everyone`).
+
 ## Dependencies
 
 - **Remotion 4.0.469** — core rendering engine

package/README.md

@@ -201,10 +201,14 @@ src/
 │   ├── 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
+│   ├── server.mjs         ← Unified server (--edit, --label, preview)
+│   ├── components/        ← React control components for all modes
+│   │   ├── index.ts
+│   │   ├── EditControls.tsx
+│   │   ├── LabelControls.tsx
+│   │   └── VariantBar.tsx
 │   ├── pipeline.ts        ← Pipeline entry (bundled to pipeline.mjs)
-│   └── browser.tsx        ← Browser player (bundled with esbuild)
+│   └── browser.tsx        ← Browser player (React, bundled to player.js)
 ├── utils/                 ← Duration calc, VTT parser, helpers
 └── tests/                 ← Vitest integration tests
 ```

package/SKILL.md

@@ -1,194 +1,45 @@
 ---
 name: markcut
-description: >-
-  Compose and render videos from streamline trees. CLI renders stream tree
-  to MP4. Run via `npx markcut` — no install, no code.
+description: use markdown to describe stream trees, provide CLI to render stream trees to video via `npx @lalalic/markcut`. use it to structure video scenes, and generate TTS, TTI, TTV, STT media automatically.
 ---
 
 ## Stream Tree Specs
 
-Everything video is a **stream tree**. see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
+Everything video is a **stream tree** described with markdown. see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
 
-## .markcut/ Directory Layout
 
-When you run `preview` or `render`, all generated artifacts live under `.markcut/` next to the source file:
+## video design utitlies
 
-```
-.markcut/
-  generated/                    ← shared, content-addressed
-    tts/                        ← TTS audio (content-hash filenames)
-    media/                      ← TTI/TTV media (content-hash filenames)
-    includes/                   ← compiled sub-video JSON (content-hash)
-  <basename>/                   ← per-source-file artifacts
-    components/                 ← component bundles (per-file: imports differ)
-```
-
-- `generated/` — shared artifacts using content-hash filenames, so identical scripts/prompts across different source files reuse the same cached file
-- `<basename>/components/` — per-file component bundles; each source file has its own `imports` block, so bundles live under its basename
-- The server serves `.markcut/` as a document root, so components at `.markcut/slides/components/abc.js` are served as `/slides/components/abc.js`
-
-## Include (Sub-Video Embedding)
-
-The `include` node embeds an external `.md` file as a sub-video. The pipeline fully resolves it recursively:
-
-1. **`resolveIncludes()`** (step 0 of `resolveAll`): reads the referenced `.md`, parses it, resolves its own includes/TTS/media, compiles to a stream tree, writes the compiled JSON to `.markcut/generated/includes/<hash>.json`
-2. **`resolveIncludeImports()`** (server post-compile): if the sub-video has a ` ```js imports ``` ` block, bundles its components independently and writes the bundle URL into the compiled JSON
-3. **`IncludeLeaf`** (render): loads the compiled JSON, dynamically imports the sub-video's component bundle, creates a nested `ComposeContext` with the sub-video's registry merged, and renders via `FolderLeaf`
-
-The sub-video's own components are isolated from the parent's — naming conflicts are resolved by "sub-video wins" priority.
-
-```markdown
-# video
-## Main
-- component duration:3 jsx:"<MainTitle />"
-## Embedded
-- include src:./sub-video.md
-## End
-- component duration:2 jsx:"<Outro />"
-```
-
-```markdown
-# sub-video
-- component duration:3 jsx:"<SubSlide scene='1' />"
-
-```js imports
-export function SubSlide({ scene }) {
-  return <div style={{background:'#667eea', ...}}>Scene {scene}</div>;
-}
-```
-```
----
-
-## Video Design Best Practice (How-To)
-
-The engine supports four authoring phases. Each has a dedicated doc with full detail.
-
-### Label — annotate clips in a stream tree
-
-Load a stream tree, preview each clip, and attach descriptive labels.
-
-```bash
-npx markcut preview <flat stream tree file> --label
-```
-
-Labels save to `labels.json`. See [docs/label-mode.md](docs/label-mode.md) for:
-- Label player UI (thumbnails, player, label input)
-- Labels persistence format
-- Full workflow diagram
+### User labels — label media with text, time ranges
+- `uvx @lalalic/markcut preview --label` provides tool to label video and images with text.
 
 ### Storyboard — plan video structure with scene nodes
 
-Use `scene` nodes to organize your video. Each scene has `title`, `instruction`, `script` (TTS narration), `children`. Scenes can nest inside other scenes.
+- Use `scene` nodes to organize your video. Scenes can nest inside other scenes.
+- Use `description`, `scene.instruction`, `script`, `image|video.prompt` to structure your video content.
 
-```bash
 see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
 
-### 3. Assemble — render stream tree to MP4
-
-```bash
-npx markcut render <stream tree file> --aspect all  # MP4 output
-```
-
----
-
-## Template Variables
-
-`${width}`, `${height}`, `${fps}`, `${variant}` can be used in `src`,
-`prompt`, and `stylesheet` values. They resolve to the root config values.
+### Video Variants
+- define variants for different video configurations, such as different languages, aspects, platforms
 
-```markdown
-# video
-width:1920 height:1080
-## Scene
-- image src:photo_${width}x${height}.jpg
-- component jsx:"<h1>${width}</h1>"    ← NOT resolved (jsx excluded)
-```
-
-> Only `src`, `prompt`, and `stylesheet` support template variables.
-> Root config keys, jsx, script, style, etc. do not.
-
-## Frontmatter
-
-The YAML `---` block is **metadata only**. It does NOT affect video config.
-All configuration comes from the root config line after `# video`:
-
-```markdown
----
-title: My Campaign
----
-# video
-width:640 height:480 fps:30 layout:series tts:"edge-tts --voice '...' --text '{input}' --write-media '{output}'"
-```
-
-## AI Media Generation (TTS / STT / TTI(text-to-image) / TTV(text-to-video))
-
-All four pipelines are configured via a **single CLI string** on the root config line. The user/LLM embeds every tool-specific parameter directly in the string — only `{input}` and `{output}` are substituted by the engine.
-
-Default CLI templates (used when not overridden on the root config line):
-
-| Config | Default |
-|--------|---------|
-| `tts` | `uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"` |
-| `stt` | `uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"` |
-| `tti` | `uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}"` |
-| `ttv` | (uses TTI to create an image, then ffmpeg to loop it for 5s) |
-
-Override on the root config line:
-
-```markdown
-# video
-width:1920 height:1080 tts:"uvx edge-tts --voice 'zh-CN-YunxiNeural' --text '{input}' --write-media '{output}'"
-```
-
----
 
 ## 3. CLI
 
 ```bash
-npx markcut <command> [options]
-```
-
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `render <file>` | Render stream tree to MP4 |
-| `preview <file> --label` | Label clips in a simplified stream tree |
-| `preview <file> --edit` | Live editing loop (auto-reload on file change) |
-| `verify <file>` | Validate descriptive file + check imports |
-### Options
-
-| Flag | Values | Default |
-|------|--------|---------|
-| `--aspect` | `16x9` / `9x16` / `1x1` / `all` | `16x9` |
-| `--output` | path | `out/video-{aspect}.mp4` |
-| `--port` | number | `3001` |
-| `--verbose` | flag | `false` (compact progress) |
-| `--compile` | flag | `false` (resolve only) |
-| `--script-output-dir` | dir | `.markcut/generated/tts/` |
-| `--media-output-dir` | dir | `.markcut/generated/media/` |
-
-> Default output dirs auto-resolve to `.markcut/<basename>/<type>/` relative to the source file. You only need `--script-output-dir` / `--media-output-dir` to override.
-
-### Edit Mode for Agents
-
-```bash
-# Start player in background
-npx markcut preview <stream tree file> --edit --port 3001 &
-
-# Player auto-opens browser. Agent edits JSON → player auto-reloads.
-# User clicks ✕ → server exits → agent regains control.
-# Browser feedback input writes to feedback.txt.
+npx @lalalic/markcut <command> [options]
+npx @lalalic/markcut --help # get overall information
 ```
 
 ---
 
 ## self verification
 some common issues (photo or video can't be displayed, audio missing), take below actions to verify
-### preview or render mode
-- screenshot some key frames, and understand image to verify if the image is correct
+### preview
+- take screenshot for some key frames in player, and understand image to verify intent
+
 ### final video
-- screenshot some key frames, and understand image to verify if the image is correct
+- screenshot some key frames, and understand image to verify intent
 - stt the final video audio, and verify if vtt result is correct
 
 
@@ -197,13 +48,16 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Topic | File |
 |-------|------|
 | Markdown descriptive format (primary authoring format) | [docs/markdown-descriptive.md](docs/markdown-descriptive.md) |
-| **Video Templates** — ready-to-use markdown for common scenarios | **[docs/templates/](docs/templates/)** |
-| ┣ Courseware / 课件 | [docs/templates/courseware.md](docs/templates/courseware.md) |
-| ┣ Product Ad / 产品广告 | [docs/templates/product-ad.md](docs/templates/product-ad.md) |
-| ┣ Movie Review / 影视讲解 | [docs/templates/movie-review.md](docs/templates/movie-review.md) |
-| ┣ Audiobook / 有声图书 | [docs/templates/audiobook.md](docs/templates/audiobook.md) |
-| ┣ Story Video / 故事视频 | [docs/templates/story-video.md](docs/templates/story-video.md) |
-| ┣ Travel Log / 旅行日志 | [docs/templates/travel-log.md](docs/templates/travel-log.md) |
 | Label system (browse, label, export labels.json) | [docs/label-mode.md](docs/label-mode.md) |
 | Player servers (label + edit mode) | [docs/edit-mode.md](docs/edit-mode.md) |
-| Template overview and TTI/TTV config | [docs/templates.md](docs/templates.md) |
+
+
+## common used components
+- `react-markdown` — render markdown content, use plugins to extend functionality
+  - `remark-gfm` — support GitHub Flavored Markdown (tables, strikethrough, task lists)
+  - `remark-toc` — generate table of contents
+  - `remark-math` — support math formulas
+  - `rehype-katex` — render math formulas with KaTeX
+
+- `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
+- `@remotion/starburst` — render starburst animations

package/docs/edit-mode.md

@@ -177,7 +177,7 @@ The tree description walks the JSON recursively, showing:
 - **Nesting depth** via indentation
 - **Type** and **id/name** of each node
 - **Key fields** (dimensions, fps, theme, series/parallel, transitions)
-- **Timing** from actions (`[startend]`)
+- **Timing** from leaf span (`[start→end]`)
 - **isBackground** flag (`[bg]`)
 - **Component props** and node-specific fields (fontSize, fit, style, volume, etc.)
 

package/docs/label-mode.md

@@ -36,7 +36,7 @@ Labels are saved to the source file.
             "id": "scene-1-media",
             "type": "image",
             "src": "/media/photo.jpg",
-            "actions": [{ "start": 0, "end": 5 }],
+            "start": 0, "end": 5,
             "description": "Best group shot from the campfire"
           }
         ]
@@ -49,7 +49,7 @@ Labels are saved to the source file.
             "id": "scene-2-media",
             "type": "video",
             "src": "/media/clip.mp4",
-            "actions": [{ "start": 0, "end": 5 }],
+            "start": 0, "end": 5,
             "description": "Sunset timelapse — use for intro"
           }
         ]
@@ -94,12 +94,14 @@ Stream tree JSON (labels.json)
 
 ## Implementation
 
-Source: `src/player/label-server.mjs`
+Source: `src/player/server.mjs` (unified server, use `--label` flag)
+UI controls: `src/player/components/LabelControls.tsx` (React component)
 
 - Built on Node.js `http` module (no Express dependency)
 - Serves bundled `player.js` (esbuild output from `src/player/browser.tsx`)
 - Labels saved atomically to disk on each POST
-- Accepts stream tree JSON only (no media folder mode)
+- Supports stream tree JSON, descriptive JSON, and markdown input
+- React components in `src/player/components/` replace the old HTML-based `ui/` directory
 
 ## Reference
 

package/docs/markdown-descriptive.md

@@ -174,7 +174,9 @@ For compatibility, `import { Name } from "spec"` also works and produces the sam
 | `title` | display title | scene |
 | `instruction` | visual intent / style / any prompt; NOT rendered | any |
 | `script` | narration/dialogue text; TTS source; NOT rendered directly | audio | Only on audio nodes — see Narration section below |
-| `tts` | CLI template string; per-scene TTS override (overrides root `tts`) | root, scene |
+| `speaker` | speaker name for multi-turn dialogue; set automatically by dialogue expansion | audio | Used for per-speaker voice lookup and subtitle prefix |
+| `voices` | JSON object mapping speaker names to extra TTS CLI flags e.g. `{"Ray":"--voice en-US-GuyNeural"}` | root | Flags are appended to the resolved TTS CLI template |
+| `tts` | CLI template string e.g. `"edge-tts --voice en-US-GuyNeural --text {input} --write-media {output}"` | root | Set once at the root level; all TTS uses this template |
 | `metadata` | arbitrary metadata string | root |
 | `stylesheet` | global CSS string; selectors use `.className` on elements | root |
 | `style` | inline CSS applied to the node's container div e.g. `"border-radius:12px"` | any |
@@ -254,6 +256,37 @@ For longer text, use an indented code fence:
 
 All three patterns produce an `audio` node with a `script` field. The pipeline's TTS resolver (`resolveScripts`) picks up these nodes, generates speech audio files, and sets the `src` field to the output path. The `script` field is consumed by the resolver and is not present in the compiled stream tree.
 
+#### Multi-turn Dialogue
+
+When a `script` contains multiple lines matching `SpeakerName: text` format, the pipeline automatically expands it into a multi-turn dialogue where each line becomes a separate audio node with its own TTS generation. This allows different speakers to have different voices.
+
+```md
+- script "Ray: Hello everyone and welcome
+Alice: Good day to you all
+Ray: Let's get started"
+```
+
+The dialogue lines play sequentially. Each line is transcribed separately, and subtitles include the speaker prefix (e.g., `Ray: Hello everyone and welcome`).
+
+##### Per-Speaker Voices
+
+Configure different TTS voices for each speaker via the root `voices` config. Each value is **extra CLI flags** appended to the TTS template:
+
+```md
+# video
+voices:{"Ray":"--voice en-US-GuyNeural","Alice":"--voice en-US-JennyNeural"}
+- script "Ray: Tell us about your project
+Alice: I'm working on something exciting"
+```
+
+Since values are raw CLI flags, they naturally support voice cloning, rate, pitch, and any edge-tts feature:
+
+```md
+voices:{"Ray":"--voice en-US-GuyNeural --rate +20%","Clone":"--voice clone-xxx --pitch +5Hz"}
+```
+
+The final TTS command for a speaker: `<root tts cli> <speaker voice flags>`.
+
 ### `subtitle` (root-level overlay)
 
 Subtitles are configured at the root level as a VTT overlay, not as tree nodes. Set via YAML frontmatter `subtitle:` or `root.subtitle` in JSON.
@@ -707,6 +740,18 @@ Use `markcut verify` to parse and validate a descriptive markdown file without r
 markcut verify courseware.md
 ```
 
+# common used components
+- `react-markdown` — render markdown content, use plugins to extend functionality
+  - `remark-gfm` — support GitHub Flavored Markdown (tables, strikethrough, task lists)
+  - `remark-toc` — generate table of contents
+  - `remark-math` — support math formulas
+  - `rehype-katex` — render math formulas with KaTeX
+  - `remark-mermaidjs` — render mermaid diagrams in 
+- `react-markdown-mermaid` — render mermaid diagrams in standalone mode (no need to install mermaid separately)
+
+- `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
+- `@remotion/starburst` — render starburst animations
+
 ## Example
 
 ```md

package/docs/system-prompt-edit.md

@@ -0,0 +1,16 @@
+You are a video director editing a markdown-descriptive (.md) markcut video project.
+
+The markcut engine compiles markdown descriptions into rendered videos with TTS narration, transitions, and media generation.
+
+The file you are editing is: ${fileName}
+Full path: ${filePath}
+
+--- Markdown-Descriptive Format Reference ---
+@{docs/markdown-descriptive.md}
+
+TASKS:
+1. Read the .md file directly using your file tools to see its current content
+2. Edit the .md file directly — change content, add/remove sections, update frontmatter
+3. Save the changes to the .md file using your write/edit tools
+4. Output ONLY a one-line summary of what specific change you made
+5. Do NOT output explanations, reasoning, or extra text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"

package/src/config.mjs

@@ -37,6 +37,8 @@ export const DEFAULT_ITT_CLI =
 /**
  * Seconds between sampled video frames when using the default ITT-based VTT.
  */
+export const GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY || "";
+
 export const DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE_INTERVAL) || 5;
 
 /**
@@ -73,11 +75,14 @@ export const DEFAULT_TTS_CLI =
 
 /**
  * Default agent CLI — general-purpose text LLM.
- * Used for text-only tasks like detect-scenes.
- * Placeholders: {prompt}=the prompt text.
+ * Used for text-only tasks like detect-scenes and editing.
+ * Placeholders:
+ *   {systemprompt} = system prompt (role, instructions, knowledge)
+ *   {prompt}       = user prompt (current context + edit request)
+ *   {sessionid}    = unique session ID for conversation continuity
  * Override with MARKCUT_AGENT_CLI env var.
  */
-export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
+export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}';
 
 // ── Render-only pipeline CLI templates ─────────────────────────────────────
 // These are specific to the render pipeline (no vision pipeline equivalent).