@lalalic/markcut 1.0.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.0.1",
+  "version": "1.2.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -17,8 +17,8 @@
   },
   "scripts": {
     "render": "node src/render/cli.mjs render",
-    "render:all": "node src/render/cli.mjs render --aspect all",
-    "render:demo": "node src/render/cli.mjs render src/demo-components.json --aspect all",
+    "render:all": "node src/render/cli.mjs render",
+    "render:demo": "node src/render/cli.mjs render src/demo-components.json",
     "templates": "node src/render/cli.mjs templates",
     "preview": "node src/render/cli.mjs preview",
     "verify": "node src/render/cli.mjs verify",

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);
@@ -45,47 +46,46 @@ markcut CLI — Markdown/JSON → video pipeline
 
 Commands:
 
-  compile <file> --output <path>        Parse + compile → stream tree JSON (sync, no I/O)
-
   verify <file>                         Parse + validate descriptive file
     --cli                             Check required CLI tools are installed
 
-  resolve <file> --output <path>        Run async pipeline: TTS, STT, media durations
-    --script-output-dir <dir>           Directory for generated TTS/STT files
-    --media-output-dir <dir>            Directory for generated TTI/TTV media files
-    --compile                          Also compile to stream tree after resolving
-
-  render <file.json|.md>                Resolve + compile + render to MP4
-    --aspect <16x9|9x16|1x1|all>       Aspect ratio (default: 16x9)
-    --output <path>                     Output path (default: out/video-{aspect}.mp4)
-    --verbose                           Show full per-frame progress (default: compact)
-
   preview <file.json|.md>               Open player with live preview
     --edit                             Auto-reload on file change
     --label                           Open label input overlay
     --no-browser                      Skip opening browser automatically
     --port <num>                        Port for the player server (default: 3001)
 
-  vision <folder>                       Extract metadata into metadata.json
+  render <file.json|.md>                Resolve + compile + render to MP4
+    --output <path>                     Output path (default: out/video.mp4)
+    --verbose                           Show full per-frame progress (default: compact)
+
+  vision <folder>                      Extract metadata into metadata.json
     --label                            Full pipeline: preview → label → normalize → percept → segments
     --agent <template>                 Custom text LLM CLI for detect-scenes ({prompt})
     --itt <template>                   Custom ITT CLI template with {input}, {prompt}
     --vtt <template>                   Custom VTT CLI template with {input}, {prompt}
     --stt <template>                   Custom STT CLI template with {input}, {output}
-    --context "text"                   Background context (injected into prompts)
-    --<prompt-name> "text"             Override a prompt from vision_prompts.md
+    --prompts-file <path>              Path to prompts markdown file (default: vision_prompts.md)
+    --vtt-sample-interval <n>          Sample one video frame every N seconds (default: 5)
+    --context "text"                   Background context about people/places (injected into prompts)
+    --pick <files>                     Comma-separated filenames to process
+    --skip-stt                         Skip speech-to-text for videos
+    --dry-run                          Show what would be processed without running AI
+    --show-prompts                     Print the prompts file and exit
+    --show-clis                        Print the default ITT/VTT/STT CLI templates
+    --help                             Show this help
+    --<prompt-name> "text"             Override any prompt template from vision_prompts.md
 `);
 }
 
-function parseArgs(argv) {
-  const args = { command: "", file: "", aspect: "16x9", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, scriptOutputDir: "", mediaOutputDir: "", variant: [] };
+export function parseArgs(argv) {
+  const args = { command: "", file: "", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, scriptOutputDir: "", mediaOutputDir: "", variant: [] };
   let i = 2;
   if (argv[i]) args.command = argv[i++];
   if (argv[i] && !argv[i].startsWith("--")) args.file = argv[i++];
   while (i < argv.length) {
     const flag = argv[i++];
-    if (flag === "--aspect" && argv[i]) args.aspect = argv[i++];
-    else if (flag === "--output" && argv[i]) args.output = argv[i++];
+    if (flag === "--output" && argv[i]) args.output = argv[i++];
     else if (flag === "--script-output-dir" && argv[i]) args.scriptOutputDir = argv[i++];
     else if (flag === "--media-output-dir" && argv[i]) args.mediaOutputDir = argv[i++];
     else if (flag === "--cli") args.cli = true;
@@ -112,11 +112,42 @@ 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 }));
@@ -263,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) {
@@ -286,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.)
@@ -309,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"),
@@ -341,16 +374,31 @@ async function main() {
       process.exit(1);
     }
 
-    const aspects = args.aspect === "all" ? Object.keys(ASPECTS) : [args.aspect];
-
-    for (const aspect of aspects) {
-      const output = args.output && aspects.length === 1
-        ? resolve(args.output)
-        : join(ROOT, "out", `video-${aspect}.mp4`);
-      await renderOne(streamTree, aspect, output, args.verbose);
+    // 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(", ")}`);
+        }
+      }
     }
 
-    console.log("\n✅ All renders complete.");
+    const output = args.output ? resolve(args.output) : join(ROOT, "out", "video.mp4");
+    await renderOne(streamTree, "16x9", output, args.verbose);
+
+    console.log("\n✅ Render complete.");
     process.exit(0);
   }
 
@@ -622,7 +670,9 @@ function hasScript(root) {
   process.exit(1);
 }
 
-main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+if (process.argv[1] && process.argv[1].endsWith("cli.mjs")) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}

package/src/render/cli.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { parseArgs } from "./cli.mjs";
+
+describe("parseArgs", () => {
+  it("supports render without an aspect flag", () => {
+    const args = parseArgs(["node", "markcut", "render", "input.md", "--output", "out/video.mp4"]);
+
+    expect(args.command).toBe("render");
+    expect(args.file).toBe("input.md");
+    expect(args.output).toBe("out/video.mp4");
+    expect(args).not.toHaveProperty("aspect");
+  });
+});

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);
+  }
+}