@lalalic/markcut 1.1.1 → 1.2.0

package/AGENTS.md

@@ -240,6 +240,8 @@ npx vitest run tests/render.test.ts -t "Test Name"  # single test
 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.
+7. **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`).
+8. **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.
 
 ## 3-Level Authoring Workflow (see SKILL.md)
 

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,18 @@ 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
+  - `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

package/docs/markdown-descriptive.md

@@ -707,6 +707,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/package.json

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

package/src/entry.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
-import { AbsoluteFill, continueRender, delayRender } from "remotion";
+import { AbsoluteFill, continueRender, delayRender, staticFile } from "remotion";
+import { ensureSharedImportMap } from "./utils/component-import-map";
 import { ComposeContext, EventProvider, type ComposeContextValue } from "./context/index";
 
 import { FolderLeaf } from "./types/Folder";
@@ -58,7 +59,12 @@ function useComponentRegistry(imports: unknown): Record<string, React.ComponentT
       if (!handleRef.current) {
         handleRef.current = delayRender("Loading component registry: " + imports);
       }
-      import(/* webpackIgnore: true */ imports)
+      // Absolute URLs and "/"-rooted paths (preview server) load as-is;
+      // relative paths (render CLI stages bundles into publicDir) resolve
+      // through staticFile so the Remotion render server can serve them.
+      const moduleUrl = /^(https?:|data:|blob:|\/)/.test(imports) ? imports : staticFile(imports);
+      ensureSharedImportMap();
+      import(/* webpackIgnore: true */ moduleUrl)
         .then((mod: any) => {
           // The bundle exports all components as named exports
           setRegistry(mod.default ?? mod);

package/src/render/cli.mjs

@@ -7,8 +7,9 @@
  *                                        (TTS/STT/durations)
  */
 import { execSync, spawn } from "node:child_process";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { resolve, dirname, join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { resolve, dirname, join, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -111,11 +112,42 @@ export function parseArgs(argv) {
  *
  * Use --verbose to see every frame line (original behavior).
  */
+/**
+ * Stage local absolute-path assets (TTS audio, TTI/TTV media, subtitles from
+ * .markcut/) into ROOT/public/.render-assets/ and rewrite srcs to relative
+ * paths, so `npx remotion render` (publicDir = ROOT/public) can serve them.
+ * The preview server handles these paths via multi-root serving; the render
+ * CLI needs them staged into the one public dir Remotion knows about.
+ */
+function stageLocalAssets(tree) {
+  const assetsDir = join(ROOT, "public", ".render-assets");
+  const seen = new Map();
+  const walk = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (typeof node.src === "string" && node.src.startsWith("/") && !node.src.startsWith("//") && existsSync(node.src)) {
+      let staged = seen.get(node.src);
+      if (!staged) {
+        const name = createHash("md5").update(node.src).digest("hex").slice(0, 12) + extname(node.src);
+        mkdirSync(assetsDir, { recursive: true });
+        copyFileSync(node.src, join(assetsDir, name));
+        staged = `.render-assets/${name}`;
+        seen.set(node.src, staged);
+      }
+      node.src = staged;
+    }
+    for (const value of Object.values(node)) {
+      if (value && typeof value === "object") walk(value);
+    }
+  };
+  walk(tree);
+  return tree;
+}
+
 function renderOne(streamTree, aspect, outputPath, verbose) {
   const dims = ASPECTS[aspect];
   if (!dims) throw new Error(`Unknown aspect: ${aspect}`);
 
-  const adapted = { ...streamTree, width: dims.width, height: dims.height };
+  const adapted = stageLocalAssets(JSON.parse(JSON.stringify({ ...streamTree, width: dims.width, height: dims.height })));
   const tmpProps = join(ROOT, ".tmp", `render-${aspect}.json`);
   mkdirSync(dirname(tmpProps), { recursive: true });
   writeFileSync(tmpProps, JSON.stringify({ root: adapted }));
@@ -262,10 +294,12 @@ async function main() {
 
   if (args.command === "render") {
     let streamTree;
+    let rawInput = "";
 
     if (args.file) {
       const filePath = resolve(args.file);
       const raw = readFileSync(filePath, "utf-8");
+      rawInput = raw;
 
       // Helper: all generated artifacts live under .markcut/generated/
       function generatedDir(filePath, sub) {
@@ -285,14 +319,14 @@ async function main() {
       // Helper: resolve variants from the parsed descriptive root
       async function resolveWithVariants(descriptive, options) {
         const { resolveVariantOverrides, compileDescriptiveRoot, resolveAll } = await import("../player/pipeline.mjs");
-        const { parseMarkdownDescriptive } = await import("../player/pipeline.mjs");
+        const { parseMarkdownVariants } = await import("../player/pipeline.mjs");
 
         let resolved = descriptive;
 
         // If variants are specified, apply variant-prefixed overrides
         if (args.variant && args.variant.length > 0) {
           // Also apply root config overrides from variant sections
-          const parsed = parseMarkdownDescriptive(raw);
+          const parsed = parseMarkdownVariants(raw);
           const variantRoot = parsed.variants.get(args.variant[0]);
           if (variantRoot) {
             // Merge variant root config into base (tts, stt, width, height, etc.)
@@ -308,9 +342,9 @@ async function main() {
       }
 
       if (filePath.endsWith(".md")) {
-        const { parseMarkdownDescriptive } = await import("../player/pipeline.mjs");
+        const { parseMarkdownVariants } = await import("../player/pipeline.mjs");
         const fileDir = dirname(filePath);
-        const parsed = parseMarkdownDescriptive(raw);
+        const parsed = parseMarkdownVariants(raw);
         streamTree = await resolveWithVariants(parsed.base, {
           baseDir: fileDir,
           scriptOutputDir: generatedDir(filePath, "tts"),
@@ -340,6 +374,27 @@ async function main() {
       process.exit(1);
     }
 
+    // Bundle the ```js imports``` component block (the preview server does this
+    // post-compile; the render CLI must do it too, otherwise jsx components are
+    // unregistered and slides render as unstyled raw text).
+    if (!streamTree.imports) {
+      const fenceMatch = rawInput.match(/^(```|~~~)\s*js imports\s*\n([\s\S]*?)^\1\s*$/m);
+      const rawSource = fenceMatch ? fenceMatch[2] : (streamTree.importsBlock ?? null);
+      if (rawSource && rawSource.trim()) {
+        const { parseImportsBlock, extractDependencySpecs } = await import("../player/pipeline.mjs");
+        const { bundleFromEntries } = await import("../player/bundler.mjs");
+        const entries = parseImportsBlock(rawSource);
+        const extraSpecs = extractDependencySpecs(rawSource);
+        const bundleDir = join(ROOT, "public", ".render-assets");
+        mkdirSync(bundleDir, { recursive: true });
+        const bundle = await bundleFromEntries(entries, extraSpecs, rawSource, bundleDir);
+        if (bundle.url) {
+          streamTree.imports = ".render-assets/" + bundle.url.split("/").pop();
+          console.log(`  \u2705 components \u2192 ${bundle.exports.join(", ")}`);
+        }
+      }
+    }
+
     const output = args.output ? resolve(args.output) : join(ROOT, "out", "video.mp4");
     await renderOne(streamTree, "16x9", output, args.verbose);
 

package/src/utils/component-import-map.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared-module import map for dynamically loaded component bundles.
+ *
+ * Component bundles are built with react/react-dom/remotion marked as
+ * --external (see player/bundler.mjs getSharedExternals), so their output
+ * contains bare imports like `import { useState } from "react"`. The page
+ * that dynamically imports such a bundle must provide an import map that
+ * resolves those bare specifiers back to the already-loaded module
+ * instances — otherwise the import fails ("Failed to resolve module
+ * specifier") or, worse, a duplicate React breaks hooks and context.
+ *
+ * The preview player injects this map itself (player/browser.tsx). This
+ * helper provides the same shim for the Remotion render page (headless
+ * Chrome during `markcut render`). Both use the `#rmtr-import-map` guard,
+ * so whichever runs first wins and the other becomes a no-op.
+ */
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import * as Remotion from "remotion";
+
+export function ensureSharedImportMap(): void {
+  if (typeof document === "undefined") return;
+  if (document.querySelector("#rmtr-import-map")) return;
+
+  const g = globalThis as any;
+  g.__remotionShared ??= {};
+  g.__remotionShared["react"] ??= React;
+  g.__remotionShared["react-dom"] ??= ReactDOM;
+  g.__remotionShared["remotion"] ??= Remotion;
+
+  // Stub for node:* imports that some component deps reference at module
+  // level for build-time helpers never called during rendering.
+  if (!g.__nodeModuleStub) {
+    const nodeModuleStubCode = `export function createRequire() { return () => ({ resolve: () => { throw new Error("node:module.createRequire is not available in the browser"); } }); }`;
+    g.__nodeModuleStub = URL.createObjectURL(
+      new Blob([nodeModuleStubCode], { type: "application/javascript" }),
+    );
+  }
+
+  try {
+    const imports: Record<string, string> = {};
+    for (const spec of ["node:module", "node:fs", "node:path", "node:os"]) {
+      imports[spec] = g.__nodeModuleStub;
+    }
+
+    for (const [specifier, mod] of Object.entries(g.__remotionShared) as [string, any][]) {
+      const lines: string[] = [
+        `const _mod = globalThis.__remotionShared[${JSON.stringify(specifier)}];`,
+      ];
+      for (const name of Object.keys(mod)) {
+        if (name === "default") continue;
+        lines.push(
+          `const __${name} = _mod[${JSON.stringify(name)}];`,
+          `export { __${name} as ${name} };`,
+        );
+      }
+      if ("default" in mod) lines.push("export default _mod.default;");
+      imports[specifier] = URL.createObjectURL(
+        new Blob([lines.join("\n")], { type: "application/javascript" }),
+      );
+    }
+
+    // react/jsx-runtime — built manually because it's a sub-path of react.
+    const blobJsx = new Blob(
+      [
+        `
+        const R = globalThis.__remotionShared["react"];
+        const { createElement, Fragment } = R;
+        export { Fragment };
+        export function jsx(type, props, key) {
+          return createElement(type, key != null ? { ...props, key } : props);
+        }
+        export function jsxs(type, props, key) {
+          return createElement(type, key != null ? { ...props, key } : props);
+        }
+        export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+          return createElement(type, key != null ? { ...props, key } : props);
+        }
+      `,
+      ],
+      { type: "application/javascript" },
+    );
+    imports["react/jsx-runtime"] = URL.createObjectURL(blobJsx);
+
+    const script = document.createElement("script");
+    script.type = "importmap";
+    script.id = "rmtr-import-map";
+    script.textContent = JSON.stringify({ imports });
+    document.head.appendChild(script);
+  } catch (e) {
+    console.warn("Failed to create shared module import map:", e);
+  }
+}

package/templates/courseware/TEMPLATE.md

@@ -0,0 +1,311 @@
+---
+name: courseware
+description: Turn a topic or teaching material into a professional slide-based course video with TTS narration, bullet-reveal slides, and a reviewer quality gate.
+when-to-use: lessons, lectures, training, tutorials, explainers — 1-5 minute educational videos built from slides + narration
+engine: "@lalalic/markcut — run via `npx @lalalic/markcut`"
+---
+
+# Courseware Template
+
+Follow this file top to bottom. It defines **what** a professional courseware video is and **how** to produce one. It does not re-teach the engine — markcut markdown syntax comes from the markcut skill (`SKILL.md` → `docs/markdown-descriptive.md`). Read those first if you have not.
+
+Layout of this template package:
+
+| Path | Runs in | Purpose |
+|---|---|---|
+| `TEMPLATE.md` | your context | everything: inputs, structure, rules, workflow, quality gate |
+| `prompts/*.md` | **your own (orchestrator) context** | fill-in prompt templates you execute yourself |
+| `agents/*.md` | **separate agent session** | subagent definitions (system prompt + task template) |
+
+## 0. Prerequisites
+
+- markcut skill loaded (engine contract: `SKILL.md` + `docs/markdown-descriptive.md`)
+- `npx @lalalic/markcut` runnable
+- TTS CLI available (default: `edge-tts`)
+- For the reviewer gate: `ffmpeg`/`ffprobe`, an STT CLI (e.g. whisper), and image-understanding capability
+
+## 1. Inputs — collect before starting
+
+| Input | Required | Default | Notes |
+|---|---|---|---|
+| Topic / source material | **yes** | — | plain topic, outline, doc, or article |
+| Audience level | no | beginner | beginner / intermediate / expert |
+| Language(s) | no | en | extra languages become variants (see §3) |
+| Target duration | no | 2 min | 1–5 min |
+| Voice per language | no | en: `en-US-GuyNeural`, zh: `zh-CN-YunxiNeural` | edge-tts voice names |
+| Accent color | no | `#61dafb` | theme knob, see §4 |
+
+**Rule:** if the topic/material is missing or ambiguous, ask the user. Never invent course content beyond the given material plus well-established knowledge of the topic. Never invent facts, numbers, or citations.
+
+## 2. Scene grammar — mandatory structure
+
+```
+# video                          ← root: width:1920 height:1080 fps:30 layout:series
+│                                  subtitle:{fontSize:"20px"} tts:"<edge-tts CLI template>"
+├── ## Hook                      ← 3–5s attention grabber, fixed duration
+├── ## Slides                    ← layout:transitionSeries transition:fade(0.5)
+│   ├── ### TitleSlide           ← transitionSeries, bullet-reveal (1 beat)
+│   ├── ### <Concept> × 3–6     ← transitionSeries, bullet-reveal (1 beat per bullet)
+│   └── ### Summary              ← transitionSeries, bullet-reveal (1 beat per takeaway)
+└── ## Thanks                    ← fixed duration:6, no script
+```
+
+Scene rules:
+
+- **Hook**: `- image duration:3 prompt:"<vivid visual, cinematic>"` (or `video`). If no TTI/TTV CLI is configured, use a `<Slide>` hook with a provocative question instead — never leave a broken `prompt:` node.
+- **Every scene inside Slides (TitleSlide, concepts, Summary)** uses the **bullet-reveal pattern** — this is mandatory, not optional:
+
+  ```
+  ### <SceneName>
+  layout:transitionSeries transition:fade(0.5)
+  - component id:<shortId> isBackground:true jsx:"<Slide current={current}>{source}</Slide>"
+    ~~~md source
+    ## Title
+    - 🎯 **Key point 1** — elaboration
+    - 🎯 **Key point 2** — elaboration
+    - 🎯 **Key point 3** — elaboration
+    ~~~
+  - script "Paragraph expanding bullet 1..." on:(start, <shortId>.current=1)
+  - script "Paragraph expanding bullet 2..." on:(start, <shortId>.current=2)
+  - script "Paragraph expanding bullet 3..." on:(start, <shortId>.current=3)
+  ```
+
+  - `id` must be unique per scene (e.g. `t`, `c1`, `c2`, `s`). The `id` connects the component to the script events.
+  - `current={current}` on the Slide component reads the event-driven bullet index and highlights the matching `<li>`.
+  - Each `- script "..."` node is one beat in the `transitionSeries`, so it gets a fade transition. The TTS duration of that script determines the segment length.
+  - The component has `isBackground:true` so its `<Slide>` spans all beats of the scene.
+  - **Beat count = bullet count**: TitleSlide gets 1 beat (just the welcome line), concept scenes get 1 beat per bullet, Summary gets 1 beat per row in the comparison table or per major takeaway.
+
+- **Thanks**: fixed-visual, `duration:6`, no script.
+
+- **Mermaid diagrams inside slides**: Fenced mermaid code blocks (` ```mermaid `) inside `~~~md source` are rendered by the `<Slide>` component (see §4). Use for flowcharts, architecture diagrams, sequence diagrams, timeline visualizations. The diagram renders as inline SVG — place it after bullet points or on its own.
+
+- **Duration is TTS-driven**: never set explicit `duration` on scenes that have a script. Only fixed-visual scenes (Hook, Thanks) get `duration:`.
+
+## 3. Authoring rules — the professional bar
+
+Slide content:
+
+- One idea per slide. ≤ 6 bullets. Bullet shape: `🔹 **bold key phrase** — short elaboration`.
+- Emoji bullet prefixes for scannability (🤖 📊 🔄 🏷️ 💡 ⚡ …), consistent within the course.
+- Use a markdown **table** whenever content is comparative (applications, methods, milestones).
+- Use a `>` quote block for the one memorable takeaway line.
+- Code blocks only when actually teaching code; keep ≤ 10 lines per slide.
+
+Narration script:
+
+- **One short paragraph per bullet.** Never merge bullets into a single monolithic script. Each bullet gets its own `- script "..."` node with `on:(start, id.current=N)`.
+- Paragraph length ≈ **15–30 words** per beat (≈6–12 seconds at 2.5 w/s). Total words = target minutes × 150.
+- Each paragraph **expands** that bullet — never reads it verbatim. The paragraph plus all sibling paragraphs must touch every bullet on the slide.
+- The concrete example gets its own bullet and its own script paragraph. Never bury the example in a generic paragraph.
+- Bullet ordering: concepts first (what/why), example last (concrete reinforcement). The example is the final beat before advancing to the next scene.
+- Summary: each row in the comparison table gets one beat. The final beat closes the course ("Thank you for watching…").
+
+Mermaid diagrams:
+
+- Use ` ```mermaid ` fenced code blocks inside `~~~md source` for charts, flowcharts, architecture diagrams, sequence diagrams, and timelines.
+- Place mermaid blocks after the bullet list, separated by a blank line.
+- The Slide component (see §4) renders mermaid code blocks as inline SVG. Ensure the diagram fits within the slide (keep node labels short, max 1–2 sentences per node).
+- For complex diagrams that take time to render, pre-render them as SVG files via `mmdc` (mermaid-cli) or your TTI CLI, and reference as `- image src:...` instead — this is more reliable for final render.
+
+Multi-language (variants):
+
+- For each extra language: a `<lang>:"..."` twin on every script node, a `~~~md <lang>-source` fence beside every `~~~md source`, and a `# <lang>` root block at the end of the file carrying that language's `tts:` voice.
+- See the worked example in §7 for the exact shape (`zh` variant).
+
+## 4. Components & styles — canonical, copy verbatim
+
+Copy both blocks into the generated `course.md` unchanged (except the theme knobs below).
+
+~~~~text
+~~~js imports
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm'
+import mermaid from 'mermaid'
+import { delayRender, continueRender } from 'remotion'
+
+// Initialize mermaid once. Theme matches the slide deck's dark scheme.
+mermaid.initialize({ startOnLoad: false, theme: 'dark', securityLevel: 'loose' })
+
+/**
+ * Renders a mermaid diagram as inline SVG.
+ * Uses Remotion's delayRender/continueRender so the diagram is guaranteed
+ * to be ready before the frame is captured.
+ */
+export function Mermaid({ source }) {
+  const ref = React.useRef(null)
+
+  React.useEffect(() => {
+    if (!source || !ref.current) return
+    const handle = delayRender('Mermaid rendering')
+    mermaid.render('mmd-' + Math.random().toString(36).slice(2), source)
+      .then((result) => {
+        if (ref.current) ref.current.innerHTML = result.svg
+        continueRender(handle)
+      })
+      .catch((err) => {
+        console.error('Mermaid error:', err)
+        continueRender(handle)
+      })
+  }, [source])
+
+  return (
+    <div
+      ref={ref}
+      style={{ width: '100%', maxWidth: 960, margin: '20px auto' }}
+    />
+  )
+}
+
+/**
+ * Courseware slide component.
+ * - Renders markdown via react-markdown
+ * - Highlights the Nth bullet when `current=N`
+ * - Renders mermaid code blocks ( ```mermaid ...``` ) as inline diagrams
+ */
+export function Slide({ current = 0, children }) {
+  let idx = 1
+  return (
+    <div className="slide">
+      <ReactMarkdown remarkPlugins={[remarkGfm]}
+        components={{
+          li: ({ children }) => {
+            const highlight = idx === current; idx++
+            return <li className={highlight ? 'highlight' : ''}>{children}</li>
+          },
+          // Fenced code blocks — detect mermaid, render as diagram
+          pre: ({ children }) => {
+            const code = React.Children.toArray(children)[0]
+            if (code?.props?.className === 'language-mermaid') {
+              return <Mermaid source={String(code.props.children)} />
+            }
+            return <pre>{children}</pre>
+          },
+        }}>{children}</ReactMarkdown>
+    </div>
+  )
+}
+~~~
+~~~~
+
+~~~~text
+~~~css stylesheet
+/* Container sizing for a perfect 16:9 widescreen presentation slide */
+.slide {
+  color: #f5f5f7;
+  padding: 40px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: flex-start;
+  font-family: 'Helvetica Neue', Arial, sans-serif;
+  font-size: 30px;
+
+  /* Typography rules optimized for visibility from a distance */
+  h1 {
+    font-size: 2.8em;
+    color: #61dafb;
+    margin-top: 0;
+    margin-bottom: 20px;
+    line-height: 1.2;
+  }
+
+  h2 {
+    font-size: 2em;
+    color: #a8dadc;
+    margin-top: 0;
+    margin-bottom: 15px;
+  }
+
+  p {
+    font-size: 1.3em;
+    line-height: 1.6;
+    color: #e0e0e6;
+    margin-bottom: 15px;
+  }
+
+  /* List styling specific to presentation bullet points */
+  ul, ol {
+    margin-left: 25px;
+    margin-bottom: 20px;
+  }
+
+  li {
+    font-size: 1.3em;
+    line-height: 1.8;
+    margin-bottom: 10px;
+    color: #e0e0e6;
+    list-style-type: none; /* Remove default bullets for custom styling */
+
+    /* Highlighted list item for event-driven bullet reveal */
+    &.highlight {
+      color: red;
+      font-weight: 700;
+    }
+  }
+
+  /* Code block handling inside slides */
+  pre {
+    background-color: #2d2d34;
+    padding: 15px;
+    border-radius: 6px;
+    width: 100%;
+    box-sizing: border-box;
+    overflow-x: auto;
+  }
+
+  code {
+    font-family: 'Courier New', Courier, monospace;
+    font-size: 1.1em;
+    color: #ffb703;
+  }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-bottom: 20px;
+
+      th, td {
+        border: 1px solid #444;
+        padding: 10px;
+        text-align: left;
+      }
+  }
+}
+~~~
+~~~~
+
+Theme knobs — change **values only**, never the structure:
+
+| Knob | Selector | Default |
+|---|---|---|
+| Accent (h1) | `.slide h1 { color }` | `#61dafb` |
+| Secondary (h2) | `.slide h2 { color }` | `#a8dadc` |
+| Reveal highlight | `.slide li.highlight { color }` | `red` |
+| Deck background | `.slide { background }` | transparent |
+| Font | `.slide { font-family }` | Helvetica Neue |
+
+## 5. Workflow
+
+Prompts in `prompts/` are fill-in templates: replace every `{placeholder}`, then execute the prompt **in your own context**. `agents/` definitions run in a **separate session** (e.g. a fresh-context subagent).
+
+1. **Outline** — fill `prompts/outline.md` → course outline. **Present the outline to the user and get confirmation** before continuing.
+2. **Scenes** — for each outline section, fill `prompts/scene.md` → slide source + narration script (all languages).
+3. **Assemble** — write `course.md`: §2 grammar, §3 rules, §4 blocks verbatim, root config line with the user's width/height/fps/voice.
+4. **Render** — `npx @lalalic/markcut render course.md`. On engine errors: fix and re-render, max 3 attempts per error, then ask the user.
+5. **Review (quality gate)** — run `agents/reviewer.md` in a fresh separate session. Give it absolute paths to: `course.md`, the rendered MP4, this `TEMPLATE.md`, plus target duration and language(s). It returns `{verdict, findings[]}` and never edits anything.
+6. **Fix loop** — on FAIL: fill `prompts/fix.md` with the findings, apply the edits yourself, go back to step 4. Max **3** review iterations, then escalate to the user with the open findings.
+
+## 6. Quality gate — exit criteria
+
+Done only when ALL hold:
+
+- [ ] reviewer verdict = `PASS` (zero blocker/major findings)
+- [ ] total duration within ±15% of target
+- [ ] structure matches §2 (hook, title, 3–6 concepts, summary, thanks)
+- [ ] no blank/black frames at scene boundaries; slides legible at target resolution
+- [ ] STT transcript of rendered audio matches scripts (≥90% content match)
+
+## 7. Reference — worked example
+
+Golden example: [`tests/fixtures/templates/courseware.md`](../../tests/fixtures/templates/courseware.md) — a bilingual (en + zh) "Introduction to Machine Learning" course demonstrating every rule above: hook with generated image, bullet-reveal with `on:(start, slide1.current=N)`, comparative tables, summary with selection guide, and the `# zh` variant block.

package/templates/courseware/agents/reviewer.md

@@ -0,0 +1,84 @@
+---
+name: courseware-reviewer
+description: Read-only quality gate for videos produced from the courseware template. Runs in a separate session with fresh context.
+context: fresh
+mode: read-only
+tools: read file, bash (ffmpeg/ffprobe, STT CLI), image understanding
+---
+
+# System prompt
+
+You are a strict, evidence-based QA reviewer for slide-based course videos. You review; you **never edit** any file. Every finding must cite concrete evidence (a frame image, an STT excerpt, a line in the source, a measured number). If you cannot verify a check, report it as a finding with severity `minor` and say why — never silently skip it.
+
+## Inputs (provided in the task)
+
+- `course_md` — absolute path to the generated courseware markdown
+- `mp4` — absolute path to the rendered video
+- `template_md` — absolute path to the courseware `TEMPLATE.md` (the rulebook: §2 grammar, §3 authoring rules, §6 exit criteria)
+- `duration_min` — target duration in minutes
+- `languages` — expected language(s)
+
+## Procedure
+
+### 1. Static review (source vs rulebook)
+
+Read `template_md` §2/§3, then check `course_md`:
+
+- structure: hook → title → 3–6 concepts → summary → thanks
+- every concept scene: `layout:parallel` (or `transitionSeries` when bullet-reveal), one `isBackground:true` slide component + script node(s)
+- bullet-reveal wiring: `id:slideN` ↔ `on:(start, slideN.current=K)` pairs are consistent and in order
+- slide rules: ≤6 bullets, bold-key-phrase shape, table where comparative, one idea per slide
+- script rules: word count ≈ scene budget (2.5 w/s), expands rather than reads the slide, concrete example present per concept
+- imports/stylesheet blocks match the template canon (only theme-knob values may differ)
+- language variants complete and mirrored (every script has its `<lang>:` twin, every source its `<lang>-source`)
+- factual sanity: no obviously invented facts, numbers, or citations
+
+### 2. Dynamic review (rendered artifact)
+
+- `ffprobe` the MP4: duration (compare to `duration_min` ±15%), resolution, fps, audio stream present
+- Extract frames: one at each scene midpoint plus each scene boundary ±0.5s (estimate boundaries from scene order and TTS-driven durations; evenly-spaced sampling of ~2× scene count is an acceptable fallback). For each frame, verify with image understanding:
+  - not blank/black
+  - it shows the expected slide for that timestamp (match heading/bullets against `course_md`)
+  - legibility: text within safe margins, no overflow/clipping, readable contrast
+- Extract audio (`ffmpeg` → wav), transcribe with the STT CLI, and compare against the scripts in `course_md`: ≥90% content match, correct language, scene order correct
+- Spot-check subtitle overlay in ≥2 frames if subtitles are configured
+
+### 3. Report
+
+Severity: `blocker` (broken output: blank frames, missing audio, wrong structure, unrendered scene) · `major` (professional-bar violation: slide/script mismatch, pacing off-budget >20%, illegible slide, missing example, variant out of sync) · `minor` (polish: emoji inconsistency, wording, small overflow).
+
+## Output — exactly this JSON, nothing after it
+
+```json
+{
+  "verdict": "PASS | FAIL",
+  "measured": { "duration_s": 0, "target_s": 0, "resolution": "", "stt_match_pct": 0 },
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "blocker | major | minor",
+      "scene": "<scene heading or 'global'>",
+      "check": "<which rule/check from the procedure>",
+      "issue": "<what is wrong>",
+      "evidence": "<frame path / STT excerpt / source line / measurement>",
+      "fix_hint": "<one-line suggestion for the orchestrator>"
+    }
+  ]
+}
+```
+
+`PASS` requires zero `blocker` and zero `major` findings.
+
+# Task template (orchestrator fills and sends)
+
+```
+Review a courseware video against its template.
+
+course_md: {course_md}
+mp4: {mp4}
+template_md: {template_md}
+duration_min: {duration_min}
+languages: {languages}
+
+Follow your procedure. Output the verdict JSON only.
+```

package/templates/courseware/prompts/fix.md

@@ -0,0 +1,30 @@
+# Prompt: Apply Reviewer Findings
+
+> Fill every `{placeholder}`, then execute in your own (orchestrator) context.
+> Used in TEMPLATE.md §5 step 6 after a FAIL verdict. You edit; the reviewer never does.
+
+---
+
+You are fixing a courseware video that failed review. Apply the findings below to `{course_md_path}` with **minimal, targeted edits** — do not rewrite passing scenes.
+
+Reviewer findings (JSON):
+
+{findings_json}
+
+Rules:
+
+- Address every `blocker` and `major` finding. Address `minor` findings only when the fix is trivial and local.
+- Each fix must respect TEMPLATE.md §2 scene grammar and §3 authoring rules — a fix that breaks a rule elsewhere is not a fix.
+- Slide/script mismatch → prefer fixing the **script** (cheaper: TTS regenerates; slide layout stays validated).
+- Pacing/duration findings → adjust script word counts toward budget (target duration × 150 words total).
+- Blank/illegible frame findings → check the scene's node (missing `isBackground:true`, broken `src`/`prompt`, oversized content) before touching styles.
+- Never modify the `~~~js imports` or `~~~css stylesheet` blocks except the documented theme knobs (TEMPLATE.md §4).
+- Keep all language variants in sync: an edit to a script or slide must be mirrored in every `<lang>:`/`<lang>-source` twin.
+
+After editing, list what changed:
+
+```
+- <finding id>: <file location> — <one-line description of the edit>
+```
+
+Then re-render and re-review (TEMPLATE.md §5 steps 4–5).

package/templates/courseware/prompts/outline.md

@@ -0,0 +1,53 @@
+# Prompt: Course Outline
+
+> Fill every `{placeholder}`, then execute in your own (orchestrator) context.
+> Output feeds `prompts/scene.md` and must be confirmed by the user before scene writing.
+
+---
+
+You are an instructional designer planning a {duration_min}-minute video course.
+
+Topic / source material:
+
+{material}
+
+Audience: {audience}
+Language(s): {languages}
+
+Requirements:
+
+- Structure: 1 hook + 1 title slide + 3–6 concept sections + 1 summary.
+- Total narration budget ≈ {duration_min} × 150 words. Allocate a word budget per section; the sum must fit the budget.
+- Per concept section provide:
+  - title (≤ 5 words)
+  - 3–6 key points, each as `**bold key phrase** — short elaboration`
+  - one concrete example (real product, scenario, or story) — gets its own key point
+  - whether the content is comparative → table (if yes, name the columns)
+  - whether a mermaid diagram would help (flowchart, architecture, timeline)
+  - word budget
+- Summary: one comparison table spanning all concepts (name the columns) + a selection/decision guide ("If X → use Y").
+- Hook: one vivid visual idea usable as an image/video generation prompt, OR a provocative question if generation is unavailable.
+- Stay strictly within the given material plus well-established knowledge. No invented facts, numbers, or citations.
+
+Output format (markdown):
+
+```
+## Hook
+- visual: <generation prompt or question>
+
+## Concept 1: <title>
+- points:
+  - **<key phrase>** — <elaboration>
+  - ... (last point = the concrete example)
+- table: no | yes (<col1>, <col2>, ...)
+- mermaid: no | yes (<type and description of diagram>)
+- words: <n>
+
+## Concept 2: ...
+
+## Summary
+- table columns: <dimension>, <per-concept columns...>
+- guide:
+  - <condition> → <concept>
+- words: <n>
+```

package/templates/courseware/prompts/scene.md

@@ -0,0 +1,64 @@
+# Prompt: Concept Scene (slide + script)
+
+> Fill every `{placeholder}`, then execute in your own (orchestrator) context.
+> Run once per outline section (TitleSlide, each Concept, Summary).
+> Constraints below mirror TEMPLATE.md §2/§3 — the reviewer checks against them.
+
+---
+
+You are writing one scene of a {duration_min}-minute course for a {audience} audience.
+
+Outline section:
+
+{outline_section}
+
+Course context (for continuity — do not repeat content already covered):
+
+{outline_full}
+
+Produce, for language(s) {languages}:
+
+**A. Slide source** (markdown, rendered by `<Slide>`):
+
+- `##` heading = section title
+- ≤ 6 bullets, shape: `<emoji> **bold key phrase** — short elaboration`
+- consistent emoji set across the course: {emoji_set}
+- markdown table if the outline marks this section comparative
+- `>` quote block only for a single memorable takeaway line
+- no bullet may exceed one line at 1.3em / 1920px width (~90 chars)
+- Optional mermaid diagram: add a fenced mermaid code block after the bullet list (` ```mermaid ...``` `) for flowcharts or architecture visuals.
+
+**B. Narration script** (per language, **one paragraph per bullet**):
+
+- **One paragraph per bullet** — never merge bullets into a single script. Each paragraph becomes a separate `- script "..."` node with `on:(start, <sceneId>.current=N)`.
+- Paragraph length ≈ **15–30 words** per beat (~6–12s at 2.5 w/s).
+- Each paragraph **expands** its bullet — never reads it verbatim.
+- Spoken register: short sentences, no markdown, no stage directions.
+- The concrete example gets its own bullet and its own paragraph. Place it last (final beat of the scene).
+- For TitleSlide: 1 paragraph (just the welcome/introduction line).
+- For Summary: 1 paragraph per row in the comparison table + 1 final closing paragraph ("Thank you for watching…").
+
+Output format:
+
+```
+### <SceneName (PascalCase, no spaces)>
+
+~~~md source
+<slide markdown>
+~~~
+<one extra fenced block per additional language: ~~~md <lang>-source>
+
+script (en):
+<p1: describes bullet 1>
+
+<p2: describes bullet 2>
+
+<p3: describes bullet 3 — concrete example>
+
+script (<lang>):
+<p1 translation>
+
+<p2 translation>
+
+<p3 translation>
+```

package/docs/dynamic-components.md

@@ -1,191 +0,0 @@
-# Dynamic Components
-
-Three ways to add custom visual content without rebuilding the engine.
-
-## 1. Effects on Any Node (CSS Keyframes)
-
-Add the `effects` key to any node to apply CSS keyframe animations. No wrapper node needed.
-
-```json
-{
-  "id": "animated-scene",
-  "type": "image",
-  "src": "photo.jpg",
-  "duration": 3,
-  "effects": ["bounceIn(1, ease-out, 2)"]
-}
-```
-
-### 25+ Built-in Animation Names
-
-| Fades | Slides | Zooms | Attention | Bounce | Rotations |
-|-------|--------|-------|-----------|--------|-----------|
-| `fadeIn` | `slideInDown` | `zoomIn` | `pulse` | `bounceIn` | `rotateIn` |
-| `fadeOut` | `slideInUp` | `zoomOut` | `flash` | | `rotateOut` |
-| `fadeInDown` | `slideInLeft` | | `bounce` | | |
-| `fadeInUp` | `slideInRight` | | `heartBeat` | | |
-| `fadeInLeft` | | | `rubberBand` | | |
-| `fadeInRight` | | | `shakeX` | | |
-| (8 total) | | | | | |
-
-### Custom Keyframes
-
-```json
-{
-  "type": "effect",
-  "animation": "custom",
-  "customKeyframes": {
-    "0":  { "opacity": "0", "transform": "scale3d(0,0,0) rotate(0deg)" },
-    "50": { "opacity": "0.5", "transform": "scale3d(1.2,1.2,1.2) rotate(180deg)" },
-    "100": { "opacity": "1", "transform": "scale3d(1,1,1) rotate(360deg)" }
-  },
-  "children": [...],
-  "actions": [{ "start": 0, "end": 2 }]
-}
-```
-
-Percentages `"0"`–`"100"` map to action duration. Any numeric CSS property works.
-
-## 2. Remote Components (bundler-based)
-
-Register remote React components via the `~~~js imports` code fence (markdown) or `root.imports` array (JSON descriptive). The player server bundles all registered components into a single ESM module at startup.
-
-```markdown
-~~~js imports
-export { BarChart } from "recharts"
-export { Hello } from "git:user/repo/path/to/Hello.tsx"
-export { Badge } from "https://cdn.example.com/components/badge.js"
-
-export function Slide(props) {
-  return <div style={{color: '#fff'}}>{props.children}</div>;
-}
-~~~
-```
-
-Then use them in component JSX:
-
-```json
-{
-  "type": "component",
-  "jsx": "<Badge text='LIVE' color='#ff0000' />",
-  "actions": [{ "start": 0, "end": 3 }]
-}
-```
-
-### How it works
-
-1. The server extracts the imports block from the source file
-2. `parseImportsBlock` resolves `export { X } from "spec"` and `export function X() {}` patterns
-3. Inline functions' source code is scanned for `import X from "pkg"` statements — those packages are added to dependencies
-4. `bundleFromEntries` creates a temp npm project, installs all packages, and runs `esbuild` to produce a single ESM file
-5. The bundled file URL is set on `root.imports` and served from `/.component-cache/<hash>.js`
-6. At runtime, `MarkCut.useComponentRegistry` does a dynamic `import(url)` to load all named exports
-7. react-jsx-parser resolves component tags from the loaded registry
-
-### Import spec forms
-
-| Pattern | Resolves to | Example |
-|---|---|---|
-| `pkg` or `npm:pkg` | npm package (installed + bundled) | `export { BarChart } from "recharts"` |
-| `git:user/repo` | GitHub repo source | `export { Comp } from "git:user/repo/src/Comp.tsx"` |
-| `https://...` | Raw URL (used as-is) | `export { X } from "https://cdn.example.com/x.js"` |
-| local path | Filesystem path | `export { X } from "./local/Component.tsx"` |
-
-### Inline functions
-
-Define components directly in the imports block. Dependencies used inside the function body are automatically detected and installed:
-
-```markdown
-~~~js imports
-import ReactMarkdown from "react-markdown"
-
-export function Slide({ children }) {
-  return <div className="slide"><ReactMarkdown>{children}</ReactMarkdown></div>;
-}
-~~~
-```
-
-The `import` statements at the top serve dual purpose: they bring packages into scope inside inline functions AND tell the bundler what to install. The packages are added to `package.json` during bundling.
-
-### Component Contract
-
-Props injected automatically:
-- Nothing special required — just standard React props. The engine passes any `data` bindings from the component node as JSX variables.
-
-For frame-accurate animation, use standard Remotion hooks inside inline functions:
-
-```markdown
-~~~js imports
-import { useCurrentFrame } from "remotion"
-
-export function FadeIn({ children }) {
-  const frame = useCurrentFrame();
-  const opacity = Math.min(1, frame / 15);
-  return <div style={{ opacity }}>{children}</div>;
-}
-~~~
-
-Note: `remotion` and `react` are automatically available in the bundle's external scope — they do NOT need to be imported. However, adding `import { useCurrentFrame } from "remotion"` in the imports block is harmless and makes the dependency explicit.
-
-## 3. Custom Components
-
-Create a React component file in `src/components/`, register in `builtinComponents`.
-
-### Component Contract
-
-Props the engine injects automatically:
-- `action: { start: number; end: number }` — action timing from the stream node
-
-Use `useCurrentFrame()` for frame-accurate animation, `useVideoConfig()` for canvas size.
-
-### Example
-
-```tsx
-// src/components/my/Badge.tsx
-import React from "react";
-import { useCurrentFrame, interpolate } from "remotion";
-
-export const Badge: React.FC<{text: string; color?: string; action: any}> =
-  ({ text, color, action }) => {
-    const frame = useCurrentFrame();
-    const local = frame - action.start * 30;
-    const opacity = interpolate(local, [0, 15], [0, 1]);
-    return (
-      <div style={{ opacity, padding: 12, background: color || theme.colors.primary,
-                    color: "white", borderRadius: 8, fontSize: 48 }}>
-        {text}
-      </div>
-    );
-  };
-```
-
-### Register
-
-```tsx
-// src/components/index.ts
-import { Badge } from "./my/Badge";
-export const builtinComponents = { ..., Badge };
-```
-
-### Reference in stream tree
-
-```json
-{
-  "type": "component",
-  "jsx": "<Badge text='NEW' color='#ff6b35' />",
-  "actions": [{ "start": 1, "end": 4 }]
-}
-```
-
-
-# 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

package/docs/templates.md

@@ -1,52 +0,0 @@
-# Video Templates
-
-Ready-to-use markdown templates for common video scenarios. Each template:
-
-- Contains **YAML frontmatter** with usage guidance (when, how, key decisions)
-- Lists **required external packages** (npm imports)
-- Uses **src:auto prompt:"..."** placeholders for AI-generated images/videos
-- Includes **TTS narration** with configured voice and pacing
-- Provides **scene structure** with named scenes, layouts, and durations
-
-## Quick Start
-
-```bash
-# 1. Pick a template
-cp docs/templates/courseware.md my-video.md
-
-# 2. Fill in [bracketed] placeholders with actual content
-# 3. Render
-npx markcut render my-video.md --aspect 16x9
-```
-
-## Template Catalog
-
-| Template | Scenario | Duration | Key Components |
-|---|---|---|---|
-| [courseware.md](templates/courseware.md) | 课件 / Lessons | 1-5 min | MarpSlide (markdown→slides), SlideText, MathDisplay |
-| [product-ad.md](templates/product-ad.md) | 产品广告 / Ads | 15-45s | TextReveal, DeviceMockup, QRCode, FeatureCard |
-| [movie-review.md](templates/movie-review.md) | 影视讲解 / Reviews | 1-3 min | CinematicText, StarRating, TextAnnotation, SplitScreen |
-| [audiobook.md](templates/audiobook.md) | 有声图书 / Audiobooks | 3-30 min | BookCover, AmbientBackground, ProgressBar |
-| [story-video.md](templates/story-video.md) | 故事视频 / Stories | 1-5 min | StoryTitle, SpeechBubble, ParticleEffect |
-| [travel-log.md](templates/travel-log.md) | 旅行日志 / Travel | 1-3 min | LocationCard, WeatherIcon, TravelStats, Map node |}
-
-## Frontmatter Fields Used by Templates
-
-| Field | Purpose | Example |
-|---|---|---|
-| `tts` | TTS CLI command with `{input}` `{output}` | `edge-tts --voice "zh-CN-XiaoxiaoNeural" --text "{input}" --write-media "{output}"` |
-| `stt` | STT CLI command with `{input}` `{output}` | `whisper "{input}" --model tiny --language zh --output_format vtt --output_dir "{output}"` |
-| `tti` | TTI CLI command with `{input}` `{output}` | `pi --model agnes-2.0-flash --print "generate image: {input}" --output "{output}"` |
-| `ttv` | TTV CLI command with `{input}` `{output}` | `pi --model agnes-2.0-flash --print "generate video: {input}" --output "{output}"` |
-
-## src:auto — AI-Generated Media
-
-Templates use a special `src:auto` value on `image` and `video` nodes to indicate AI generation:
-
-```md
-- image src:auto prompt:"sunset over Tokyo skyline, cinematic" duration:5
-- video src:auto prompt:"person walking through cherry blossom park" duration:3
-```
-
-The `prompt:` key provides the generation prompt to the configured TTI/TTV CLI.
-The pipeline resolves `src:auto` before compilation: runs the CLI command, gets the output path, and replaces `src:auto` with the actual generated file path.