@lalalic/markcut 2.4.0 → 2.4.2

package/AGENTS.md

@@ -47,7 +47,7 @@ See [docs/markdown-strict-descriptive.md](docs/markdown-strict-descriptive.md) f
 ## CLI
 
 ```bash
-markcut render <file.json|.md> [--aspect 16x9|9x16|1x1|all] [--output path]
+markcut render <file.json|.md> [--output path]
 markcut preview <file.json|.md> [--edit] [--label] [--port 3001]
 ```
 
@@ -176,7 +176,7 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 ### CLI Usage
 
 ```bash
-node src/render/cli.mjs render <file.json> [--aspect 16x9|9x16|1x1|all] [--output path]
+node src/render/cli.mjs render <file.json> [--output path]
 node src/render/cli.mjs render --template <id> --data <data.json>
 node src/render/cli.mjs preview <file.json> [--edit] [--label] [--port 3001]
 node src/render/cli.mjs templates

package/README.md

@@ -4,7 +4,7 @@ Write a storyboard in markdown, get a rendered video with TTS narration and subt
 
 ```bash
 # Render a storyboard to MP4
-npx markcut render storyboard.md --aspect 9x16
+npx markcut render storyboard.md
 
 # Preview with live edit (edit .md file, player auto-reloads)
 npx markcut preview storyboard.md --edit

package/package.json

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

package/skills/markcut/SKILL.md

@@ -85,4 +85,6 @@ some common issues (photo or video can't be displayed, audio missing), take belo
   - subtitle mismatch
   - sync issues between audio, video, and subtitles
 - don't set duration for script or stream's duration depending on audio script
-  - markcut resolver will automatically calculate the duration based on the audio script length
+  - markcut resolver will automatically calculate the duration based on the audio script length
+- **don't** rm `.markcut` directory, which served as cache for all generated content. cache will auto update according to the content change. rm `.markcut` will cause all content to be regenerated, which is time consuming and wasteful.
+- put all manual assets in `assets` folder, such as bgm, logo, watermark, etc. don't put them in `.markcut` folder, which is auto generated and will be deleted when `markcut clean` command is run.

package/skills/markcut/docs/markdown-descriptive.md

@@ -6,7 +6,7 @@ Complete reference for LLM-driven video generation. The parser uses **remark** (
 
 A markdown document compiled into a renderable scene tree.
 
-- Top heading `# <name>` (heading text ignored, just marks document root; `# video`, `# sub-video`, `# anything` all work)
+- Top heading `# video` marks the document root. (Only `# video` is treated as the main section — `# anything_else` creates a **variant** section for alternate configs, see [Variants](#variants-language--platform--any-override).)
 - Optional YAML frontmatter block `---\n...\n---\n` at the very top
 - Root config line: `width:<n> height:<n> fps:<n> layout:<mode>` (key:value pairs on the line after `# video`)
 - Scenes via `##`/`###`/`####` headings
@@ -39,7 +39,7 @@ width:1920 height:1080 fps:30 layout:series
 ~~~css stylesheet
 .bg { background: #000; }
 ~~~
-subtitle:captions.vtt
+subtitle:{src:"captions.vtt",type:"Bounce"}
 ```
 
 Supported keys: `width`, `height`, `fps`, `layout`, `tts`, `stt`, `tti`, `ttv`,
@@ -49,12 +49,14 @@ Values containing spaces must be quoted with double or single quotes.
 
 ### Subtitle on the config line
 
+Set subtitle via `subtitle:` on the root config line:
+
 ```markdown
 # video
-width:640 height:480 subtitle:captions.vtt
+width:640 height:480 subtitle:{src:"captions.vtt",type:"Bounce",fontSize:48}
 ```
 
-Currently only `src` (a VTT file path) is supported via the config line.
+See the [Subtitle](#subtitle) section below for all supported fields.
 
 ## Template Variables
 
@@ -73,16 +75,18 @@ width:1920 height:1080
 
 > Template variables are NOT resolved in root config keys, jsx, script, style,
 > or other string fields — only in `src`, `prompt`, and `stylesheet`.
-  style: "color: yellow;"
-```
+
+### Subtitle
+
+Subtitles are configured at the root level as a VTT overlay. Set via `subtitle:` on the root config line, or `root.subtitle` in JSON.
 
 | Field | Required | Type | Notes |
 |---|---|---|---|
 | `src` | yes | string | VTT path/URL, inline VTT body, or plain text |
-| `type` | opt | string | caption animation: `Bounce`, `Fade`, `Typewriter`, `Colorful`, etc. Default: plain static caption |
-| `fontSize` | opt | number | default 56 |
+| `type` | opt | string | caption animation: `Bounce`, `Fade`, `Typewriter`, `Colorful`, `Glowing`, `Neon`, `Zoom`. Default: plain static caption |
+| `fontSize` | opt | number \| string | default 56 (accepts CSS value like `"2em"` or number) |
 | `fontFamily` | opt | string | font family |
-| `fontStyle` | opt | string | `normal`, `italic`, `bold`, etc. |
+| `fontStyle` | opt | string | `normal`, `italic`, `bold`, `bold italic` |
 | `style` | opt | string | inline CSS for the overlay container |
 
 > **HTML in cue text**: Cue text supports HTML tags with inline CSS, so you can style individual words:

package/src/config.mjs

@@ -20,7 +20,7 @@ export const args=(function parseArgs(argv) {
     "--tti": "tti",
     "--ttv": "ttv"
   };
-  const args = { command: "", file: "", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, showClis: false, scriptOutputDir: "", mediaOutputDir: "", variant: [], cliOverrides: {} };
+  const args = { command: "", file: "", output: "", forceNew: false, verbose: false, dev: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, showClis: false, scriptOutputDir: "", mediaOutputDir: "", variant: [], cliOverrides: {} };
   let i = 2;
   if (argv[i]) args.command = argv[i++];
   if (argv[i] && !argv[i].startsWith("--")) args.file = argv[i++];
@@ -34,6 +34,7 @@ export const args=(function parseArgs(argv) {
     else if (flag === "--compile") args.compile = true;
     else if (flag === "--force-new") args.forceNew = true;
     else if (flag === "--verbose") args.verbose = true;
+    else if (flag === "--dev") args.dev = true;
     else if (flag === "--label") args.label = true;
     else if (flag === "--edit") args.edit = true;
     else if (flag === "--no-browser") args.noBrowser = true;

package/src/descriptive/resolve.ts

@@ -412,11 +412,17 @@ export async function resolveScripts(
     allScriptNodes.push({ node, id });
   });
 
-  if (allScriptNodes.length > 0) {
-    console.log(`  🔊 TTS: generating ${allScriptNodes.length} script${allScriptNodes.length > 1 ? "s" : ""}...`);
+  const totalScripts = allScriptNodes.length;
+  let scriptsDone = 0;
+  let cacheHits = 0;
+  const ttsStart = Date.now();
+
+  if (totalScripts > 0) {
+    console.log(`  🔊 TTS: generating ${totalScripts} script${totalScripts > 1 ? "s" : ""}...`);
   }
 
   for (const { node, id } of allScriptNodes) {
+    scriptsDone++;
     // TTS CLI from root config only
     let ttsCli = clone.tts ?? options.ttsCli ?? DEFAULT_TTS_CLI;
 
@@ -440,13 +446,15 @@ export async function resolveScripts(
     const label = `${speakerLabel}${firstWords(node.script, 8)}`;
     if (cached) {
       generated = cached;
+      cacheHits++;
       console.log(`  ✓ TTS: ${label} (cached)`);
     } else {
+      console.log(`  🔊 TTS (${scriptsDone}/${totalScripts}): ${label}...`);
       generated = generateTTS(node.script, audioPath, ttsCli);
       if (generated) {
         updateCache(cache, `tts:${cacheKey}`, cacheKey, generated);
         cacheDirty = true;
-        console.log(`  ✓ TTS: ${label}`);
+        console.log(`  ✓ TTS (${scriptsDone}/${totalScripts}): ${label}`);
       } else {
         console.warn(`  ⚠ TTS produced no audio for "${label}". Audio will have no source. Check root.tts config.`);
       }
@@ -459,10 +467,11 @@ export async function resolveScripts(
   }
 
   if (cacheDirty) writeCacheManifest(options.outputDir, cache);
-  if (allScriptNodes.length > 0) {
+  if (totalScripts > 0) {
     try { writeFileSync(join(options.outputDir, ".cache.json"), JSON.stringify(cache, null, 2), "utf-8"); } catch {}
+    const ttsElapsed = Math.round((Date.now() - ttsStart) / 1000);
     const unique = new Set(allScriptNodes.filter(s => s.node.src).map(s => s.node.src)).size;
-    console.log(`  ✅ TTS: ${unique} unique audio file${unique > 1 ? "s" : ""} (${allScriptNodes.length} node${allScriptNodes.length > 1 ? "s" : ""})`);
+    console.log(`  ✅ TTS: ${unique} unique audio${unique > 1 ? "s" : ""} (${scriptsDone} nodes) in ${ttsElapsed}s (${cacheHits} cached)`);
   }
   return clone;
 }
@@ -713,27 +722,38 @@ export async function resolveGeneratedMedia(
   walkDown(clone as any, (node) => {
     if ((node.type !== "image" && node.type !== "video")) return;
     if (!node.prompt || typeof node.prompt !== "string") return;
-    // Skip if src is already set to a real path (prompt is just metadata).
-    // "auto" is a placeholder meaning "auto-generate via TTI/TTV".
     if (node.src && node.src !== "auto") return;
     const id = node.id ?? `${node.type}-${genNodes.length}`;
     genNodes.push({ node, id, type: node.type as "image" | "video", prompt: node.prompt });
   });
 
+  const total = genNodes.length;
+  let done = 0;
+  let cacheHits = 0;
+  const startTime = Date.now();
+
+  function progressLine() {
+    const elapsed = (Date.now() - startTime) / 1000;
+    const rate = done / Math.max(elapsed, 0.1);
+    const remaining = total - done;
+    const eta = rate > 0 ? Math.round(remaining / rate) : "?";
+    const etaStr = eta === "?" ? "" : `, ~${eta}s remaining`;
+    return `  ${done}/${total} generated (${cacheHits} cached)${etaStr}`;
+  }
+
+  if (total > 0) {
+    console.log(`  🎨 Generating ${total} media item${total > 1 ? "s" : ""}...`);
+  }
+
   for (const { node, id, type, prompt } of genNodes) {
+    done++;
     const ext = type === "image" ? "png" : "mp4";
 
-    // Resolve TTI/TTV config: root-level config overrides CLI defaults
     const cli = type === "image"
       ? (clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI)
       : (clone.ttv ?? options.ttvCli ?? DEFAULT_TTV_CLI);
 
-    // Use root.seed for reproducible generation (applied when CLI template has {seed}).
-    // seed is part of the cache key so different seeds produce different cached outputs.
     const seed = options.seed;
-
-    // Content-addressed filename: hash of prompt + CLI + type + seed, so identical
-    // prompts with different seeds produce distinct cached media.
     const cacheKey = computeCacheKey({ prompt, cli, type, seed });
     const outputPath = join(options.outputDir, `${cacheKey}.${ext}`);
 
@@ -743,12 +763,13 @@ export async function resolveGeneratedMedia(
 
     if (cached) {
       node.src = resolvePath(cached);
-      console.log(`  ✓ ${label}: ${labelText} (cached)`);
+      cacheHits++;
+      if (done % 5 === 0 || done === total) console.log(progressLine());
       continue;
     }
 
     try {
-      console.log(`  🔊 ${label}: ${labelText}...`);
+      console.log(`  🔊 ${label} (${done}/${total}): ${labelText}...`);
       const ttiCmd = clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI;
       const result = type === "image"
         ? generateTTI(prompt, outputPath, cli, seed)
@@ -757,7 +778,8 @@ export async function resolveGeneratedMedia(
         node.src = outputPath;
         updateCache(cache, `gen:${cacheKey}`, cacheKey, outputPath);
         cacheDirty = true;
-        console.log(`  ✓ ${label}: ${labelText}`);
+        console.log(`  ✓ ${label} (${done}/${total}): ${labelText}`);
+        if (done % 3 === 0 || done === total) console.log(progressLine());
       } else {
         const hint = cli.includes("echo")
           ? `No ${label} tool installed. The default CLI just echoes a message — set root.${type === "image" ? "tti" : "ttv"} to a real generation command.`
@@ -772,6 +794,11 @@ export async function resolveGeneratedMedia(
     }
   }
 
+  if (total > 0) {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    const mediaType = genNodes[0]?.type === "video" ? "TTV" : "TTI";
+    console.log(`  ✅ ${mediaType} complete: ${done} items in ${elapsed}s (${cacheHits} cached)`);
+  }
   if (cacheDirty) writeCacheManifest(options.outputDir, cache);
   return clone;
 }

package/src/player/bundle/player.js

@@ -44710,11 +44710,6 @@ function getCurrentStep(leg, currentInSecond) {
 // src/types/Include.tsx
 var React41 = __toESM(require_react(), 1);
 var import_jsx_runtime84 = __toESM(require_jsx_runtime(), 1);
-var ASPECT_DIMS = {
-  "16x9": { width: 1920, height: 1080 },
-  "9x16": { width: 1080, height: 1920 },
-  "1x1": { width: 1080, height: 1080 }
-};
 function isSceneBased(data2) {
   if (!data2 || typeof data2 !== "object") return false;
   const d2 = data2;
@@ -44837,8 +44832,7 @@ function IncludeLeaf({ stream: stream2 }) {
     if (isSceneBased(externalData)) {
       const vj = externalData;
       const vjFps = vj.meta.fps ?? parentFps;
-      const aspectKey = vj.meta.aspects?.[0] ?? "16x9";
-      const dims = ASPECT_DIMS[aspectKey] ?? { width: parentWidth, height: parentHeight };
+      const dims = { width: parentWidth, height: parentHeight };
       return /* @__PURE__ */ (0, import_jsx_runtime84.jsxs)(AbsoluteFill, { style: { backgroundColor: "#0a0a0a", width: dims.width, height: dims.height }, children: [
         vj.bgm && /* @__PURE__ */ (0, import_jsx_runtime84.jsx)(Audio, { src: vj.bgm.src, volume: vj.bgm.baseVolume }),
         vj.scenes.map((scene2) => {

package/src/render/cli.mjs

@@ -21,12 +21,6 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = resolve(__dirname, "../..");
 
-const ASPECTS = {
-  "16x9": { width: 1920, height: 1080 },
-  "9x16": { width: 1080, height: 1920 },
-  "1x1": { width: 1080, height: 1080 },
-};
-
 /**
  * How many "Rendered X/Y" lines to skip before printing one.
  * E.g. 50 means print every 50th frame — for 1860 frames that's ~37 lines.
@@ -52,6 +46,7 @@ markcut CLI — Markdown/JSON → video pipeline
 npx @lalalic/markcut <command> [options]
 
 global options:
+  --dev                                Use development build (unminified React error messages)
   --show-clis                          Print all default CLI templates and exit
 
   --tti <template>                     Override default TTI CLI template
@@ -92,7 +87,7 @@ Commands:
 
 
 /**
- * Render one aspect ratio with compact progress output.
+ * Render a stream tree to an MP4 video with compact progress output.
  *
  * In compact mode (default), "Rendered X/Y" lines are shown only every
  * PROGRESS_INTERVAL frames and at the final frame, drastically reducing
@@ -100,28 +95,49 @@ Commands:
  *
  * Use --verbose to see every frame line (original behavior).
  */
+
+/**
+ * Resolve a potentially relative source path against baseDir, skipping
+ * absolute paths, URLs, and data URIs.
+ */
+function resolveAssetPath(src, baseDir) {
+  if (!src || typeof src !== "string") return null;
+  // Already absolute on disk
+  if (src.startsWith("/")) return src;
+  // URL or data URI — can't stage locally
+  if (/^(https?:|data:|blob:)/.test(src)) return null;
+  // Relative path: resolve against the input file's directory
+  const abs = resolve(baseDir, src);
+  if (existsSync(abs)) return abs;
+  return null;
+}
+
 /**
- * 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.
+ * Stage all local src files (absolute and relative) into
+ * ROOT/public/.render-assets/ so `npx remotion render` (publicDir = ROOT/public)
+ * can serve them. Relative paths are resolved against `baseDir` (the input
+ * file's directory). 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) {
+function stageLocalAssets(tree, baseDir) {
   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);
+    if (typeof node.src === "string") {
+      const absPath = resolveAssetPath(node.src, baseDir);
+      if (absPath) {
+        let staged = seen.get(absPath);
+        if (!staged) {
+          const name = createHash("md5").update(absPath).digest("hex").slice(0, 12) + extname(absPath);
+          mkdirSync(assetsDir, { recursive: true });
+          copyFileSync(absPath, join(assetsDir, name));
+          staged = `.render-assets/${name}`;
+          seen.set(absPath, staged);
+        }
+        node.src = staged;
       }
-      node.src = staged;
     }
     for (const value of Object.values(node)) {
       if (value && typeof value === "object") walk(value);
@@ -131,21 +147,24 @@ function stageLocalAssets(tree) {
   return tree;
 }
 
-function renderOne(streamTree, aspect, outputPath, verbose) {
-  const dims = ASPECTS[aspect];
-  if (!dims) throw new Error(`Unknown aspect: ${aspect}`);
-
-  const adapted = stageLocalAssets(JSON.parse(JSON.stringify({ ...streamTree, width: dims.width, height: dims.height })));
-  const tmpProps = join(ROOT, ".tmp", `render-${aspect}.json`);
+function renderOne(streamTree, outputPath, verbose, baseDir) {
+  const adapted = stageLocalAssets(JSON.parse(JSON.stringify(streamTree)), baseDir);
+  const tmpProps = join(ROOT, ".tmp", "render-stream.json");
   mkdirSync(dirname(tmpProps), { recursive: true });
   writeFileSync(tmpProps, JSON.stringify({ root: adapted }));
 
   mkdirSync(dirname(outputPath), { recursive: true });
 
-  console.log(`\n▶ Rendering ${aspect} → ${outputPath}`);
+console.log(`\n▶ Rendering → ${outputPath}`);
 
   return new Promise((resolvePromise, reject) => {
-    const proc = spawn("npx", ["remotion", "render", "Root", outputPath, "--props", tmpProps, "--config", "remotion.config.ts"], { cwd: ROOT, stdio: ["ignore", "inherit", "pipe"] });
+    // Pass NODE_ENV=development to get unminified React error messages (--dev flag)
+    const spawnOpts = { cwd: ROOT, stdio: ["ignore", "inherit", "pipe"] };
+    // args is imported from config.mjs — check dev flag there
+    if (args.dev) {
+      spawnOpts.env = { ...process.env, NODE_ENV: "development" };
+    }
+    const proc = spawn("npx", ["remotion", "render", "Root", outputPath, "--props", tmpProps, "--config", "remotion.config.ts"], spawnOpts);
 
     let lastLoggedFrame = 0;
     let totalFrames = 0;
@@ -401,7 +420,8 @@ edit=${DEFAULT_EDIT_CLI}`);
     }
 
     const output = args.output ? resolve(args.output) : join(ROOT, "out", "video.mp4");
-    await renderOne(streamTree, "16x9", output, args.verbose);
+    const fileDir = dirname(resolve(args.file));
+    await renderOne(streamTree, output, args.verbose, fileDir);
 
     console.log("\n✅ Render complete.");
     process.exit(0);
@@ -441,12 +461,27 @@ function hasScript(root) {
     emitInfo(`File: ${filePath}`);
     emitInfo(`Format: ${isMarkdown ? "Markdown" : "JSON"}`);
 
-    const { compileDescriptiveRoot, parseMarkdownDescriptive, parseImportsBlock } = await import("../player/pipeline.mjs");
+    const { compileDescriptiveRoot, parseMarkdownDescriptive, parseMarkdownVariants, parseImportsBlock } = await import("../player/pipeline.mjs");
 
     try {
       let descriptive, needsTti, needsTtv;
       if (isMarkdown) {
         descriptive = parseMarkdownDescriptive(raw);
+
+        // Check if content accidentally went into a variant section
+        // (happens when root heading is e.g. "# My Movie" instead of "# video")
+        const hasChildren = (descriptive.children?.length ?? 0) > 0;
+        if (!hasChildren) {
+          const variantResult = parseMarkdownVariants(raw);
+          const variantNames = [...variantResult.variants.keys()];
+          const variantChildren = variantNames.filter(n => (variantResult.variants.get(n)?.children?.length ?? 0) > 0);
+          if (variantChildren.length > 0) {
+            warnings.push(
+              `No scenes found in the main section (use '# video' as the root heading). ` +
+              `Content appears in variant section(s): ${variantChildren.join(", ")}`,
+            );
+          }
+        }
       } else {
         const parsed = JSON.parse(raw);
         const root = parsed.root ?? parsed;

package/src/types/Include.tsx

@@ -5,15 +5,8 @@ import { cssJS, toClassName, getDurationInSeconds, type DurationStream } from ".
 import type { Include as IncludeStream, Root } from "../schema/index";
 import { FolderLeaf } from "./Folder";
 
-// Aspect dimensions for scene-based video content
-const ASPECT_DIMS: Record<string, { width: number; height: number }> = {
-  "16x9": { width: 1920, height: 1080 },
-  "9x16": { width: 1080, height: 1920 },
-  "1x1": { width: 1080, height: 1080 },
-};
-
 interface SceneBasedVideo {
-  meta: { title: string; fps: number; aspects?: string[] };
+  meta: { title: string; fps: number };
   voiceover?: { tts: string; voice: string };
   bgm?: { src: string; baseVolume: number };
   scenes: Array<{
@@ -207,9 +200,8 @@ export function IncludeLeaf({ stream }: { stream: IncludeStream }) {
       // ── Scene-based video.json ──────────────────────────────────
       const vj = externalData;
       const vjFps = vj.meta.fps ?? parentFps;
-      // Use first aspect's dimensions (default to 16x9)
-      const aspectKey = (vj.meta.aspects?.[0] ?? "16x9") as keyof typeof ASPECT_DIMS;
-      const dims = ASPECT_DIMS[aspectKey] ?? { width: parentWidth, height: parentHeight };
+      // Use parent composition dimensions (dimensions come from the stream file)
+      const dims = { width: parentWidth, height: parentHeight };
 
       return (
         <AbsoluteFill style={{ backgroundColor: "#0a0a0a", width: dims.width, height: dims.height }}>

package/src/types/Subtitle.tsx

@@ -288,9 +288,9 @@ export function SubtitleOverlay({ subtitle }: { subtitle: SubtitleOverlayConfig
     };
   }, [subtitle.src]);
 
-  if (!cues) return null;
+  if (!cues) return null;@
 
-  const boxCss = subtitle.style ? (cssJS(subtitle.style) as React.CSSProperties) : {};
+  const boxCss = subtitle.style ? (cssJS(subtitle.style) as React.CSSProperties) : {};@
 
   // Group consecutive cues with same plain text (word-level highlighting pattern)
   // so the caption component stays mounted across word transitions — no flash.

package/tests/render.test.ts

@@ -473,11 +473,11 @@ describe("Audio STT Verification", () => {
 });
 
 // ───────────────────────────────────────────────────────────────────────────
-// 11. Multiple Aspect Ratios
+// 11. Dimensions from Stream File
 // ───────────────────────────────────────────────────────────────────────────
 
-describe("Multiple Aspect Ratios", () => {
-  it("renders same fixture at 16x9, 9x16, and 1x1", async () => {
+describe("Dimensions from Stream File", () => {
+  it("respects width/height defined in the stream tree root", async () => {
     const fixture = {
       root: {
         id: "root",
@@ -490,7 +490,7 @@ describe("Multiple Aspect Ratios", () => {
           {
             id: "bg",
             type: "image",
-            src: "https://picsum.photos/seed/aspect-test/1920/1080",
+            src: "https://picsum.photos/seed/dim-test/1920/1080",
             fit: "cover",
             start: 0,
             end: 2,
@@ -498,7 +498,7 @@ describe("Multiple Aspect Ratios", () => {
           {
             id: "title",
             type: "image",
-            src: "https://picsum.photos/seed/aspect-title/1920/1080",
+            src: "https://picsum.photos/seed/dim-title/1920/1080",
             fit: "cover",
             start: 0.3,
             end: 1.7,
@@ -508,18 +508,16 @@ describe("Multiple Aspect Ratios", () => {
     };
 
     const { writeFileSync } = await import("node:fs");
-    const tmpFixture = outPath("_aspects.json");
+    const tmpFixture = outPath("_dims.json");
     writeFileSync(tmpFixture, JSON.stringify(fixture));
 
-    // Render with different aspect ratios via --props adaptation
-    // Note: Aspect adaptation happens in the CLI, so we test with the default
+    // Dimensions come from the stream file root, not from a CLI --aspect flag
     const output = renderFixture(tmpFixture, {
-      outputName: "aspect-default.mp4",
+      outputName: "dims-default.mp4",
       timeout: RENDER_TIMEOUT,
     });
 
     const info = getVideoInfo(output);
-    // Default aspect is whatever the fixture says (1920x1080)
     expect(info.width).toBe(1920);
     expect(info.height).toBe(1080);