@lalalic/markcut 2.6.0 → 2.7.1

package/AGENTS.md

@@ -5,10 +5,11 @@
 ## Quick Start
 
 ```bash
-npm run render storyboard.md      # render markdown → MP4 (9x16 default)
-npm run preview storyboard.md --edit  # live preview with auto-reload
-npm test                           # unit + integration tests
-npm run typecheck                  # TypeScript type check
+npm run render storyboard.md                        # render markdown → MP4 (9x16 default)
+npm run preview storyboard.md --edit                # live preview with auto-reload
+npm run preview storyboard.md --storyboard          # fast structure preview (skips TTI/TTV, shows prompts as placeholders)
+npm test                                             # unit + integration tests
+npm run typecheck                                    # TypeScript type check
 ```
 
 ## Input formats
@@ -214,20 +215,19 @@ node src/render/cli.mjs templates
 
 1. Basic Rendering — empty composition, dimension verification
 2. Image + Subtitle — image rendering, inline/VTT/karaoke subtitles
-3. Built-in Components — AnimatedHeadline, StatCounter, GradientBackground
-4. Effects — fadeIn, bounceIn, custom keyframes
-5. Map Rendering — canvas route visualization
-6. Audio Rendering — audio track, non-silent verification
-7. Include — nested composition via include
-8. Full Feature Combination — multiple features
-9. Scene Node — scene-based rendering
-10. Audio STT — speech-to-text verification via whisper
-11. Multiple Aspect Ratios — 16x9, 9x16, 1x1
-12. Cross-Stream Types — parallel rendering, effect-wrapped children
-13. Frame-Accurate — timeline consistency, frame count
-14. Description Field — schema validation, render preservation
-15. Scene as Folder Alias — scene/folder interchangeability
-16. **Video startFrom/endAt Trimming** — video trimming + photo in series
+3. Effects — fadeIn, bounceIn, custom keyframes
+4. Map Rendering — canvas route visualization
+5. Audio Rendering — audio track, non-silent verification
+6. Include — nested composition via include
+7. Full Feature Combination — multiple features
+8. Scene Node — scene-based rendering
+9. Audio STT — speech-to-text verification via whisper
+10. Multiple Aspect Ratios — 16x9, 9x16, 1x1
+11. Cross-Stream Types — parallel rendering, effect-wrapped children
+12. Frame-Accurate — timeline consistency, frame count
+13. Description Field — schema validation, render preservation
+14. Scene as Folder Alias — scene/folder interchangeability
+15. **Video startFrom/endAt Trimming** — video trimming + photo in series
 
 ### Running Tests
 
@@ -242,9 +242,9 @@ npx vitest run tests/render.test.ts -t "Test Name"  # single test
 1. **TransitionSeries + isBackground**: `TransitionSeries` from `@remotion/transitions` rejects non-Sequence/Transition children. Don't mix `isBackground:true` children with `isSeries:true, transition:"..."` at the same level.
 2. **Video endAt formula**: Must be `startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)` — changing to `endAt_source * fps` breaks slow-motion playback.
 3. **`signalstats` ffmpeg filter**: Doesn't output YAVG on all systems; use file size as proxy for visual content.
-4. **Asset paths**: All `src` paths in markdown are resolved relative to the `.md` file's directory. Preview mode serves files via a multi-directory HTTP server; render mode uses absolute paths directly (bypassing `staticFile()`). Never use a `public/` prefix in markdown `src`.
+4. **Asset paths (unified preview + render)**: All `src` paths in markdown are resolved relative to the `.md` file's directory. Both surfaces store every project-local `src` **relative to the `.md` folder** (e.g. `.markcut/generated/tts/x.mp3`, `assets/pic.png`). Preview: the server's `makePathsRelative` strips the project dir and `resolveAssetPaths`/`toServerUrl` turn them into `/`-rooted URLs served from the project folder. Render: `cli.mjs relativizePaths(streamTree, mdDir)` does the same, then Remotion is invoked with `--public-dir=<mdDir>` so `staticFile()` resolves them (including `fetch()`-based assets like subtitles and includes). Never use a `public/` prefix in markdown `src`.
 5. **Map rendering**: Depends on external tile availability; may produce blank frames offline.
-6. **CLI md render needs two 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). Asset staging (`stageLocalAssets`) was removed — render now keeps absolute paths from `resolve.ts`, bypassing `staticFile()` entirely. All 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`).
+6. **CLI md render needs two 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). Render and preview now share one folder layout **and** one path scheme: generated artifacts live in `.markcut/generated/{tts,media,includes,components}` (content-addressed, shared caches) and per-variant subtitles/compiled.json in `.markcut/<basename>/<label>/` (label defaults to `default`). Render makes paths relative to the `.md` folder and serves it via `--public-dir` (see gotcha 4) — do NOT revert to absolute paths, which break `fetch()`-based assets (subtitles, includes) that hit the render server origin and 404. All live in `src/render/cli.mjs`; the import-map shim for shared react/remotion instances is `src/utils/component-import-map.ts` (must stay in sync with `player/browser.tsx` + `bundler.mjs getSharedExternals`).
 7. **Publishing**: verify `npx @lalalic/markcut render <md>` from a clean temp dir before/after publish — v1.1.1 shipped with cli.mjs/pipeline.mjs out of sync and md rendering was completely broken. Also beware stale npx caches (`~/.npm/_npx`) silently running old code.
 8. **Clean break from `actions[]`**: leaf timing is now flat base fields (`start`/`end`/`duration`/`startFrom`/`endAt`). Old compiled JSON carrying `actions:[{...}]` no longer parses into a duration — re-compile from markdown/descriptive JSON, or migrate `actions[0]` → flat fields (drop `id`/`volume`/`style`/`effectId`; keep `start`/`end`/`startFrom`/`endAt`/`loop`).
 

package/README.md

@@ -9,6 +9,9 @@ npx markcut render storyboard.md
 # Preview with live edit (edit .md file, player auto-reloads)
 npx markcut preview storyboard.md --edit
 
+# Fast structure preview: show TTI/TTV prompts as placeholders, skip slow generation
+npx markcut preview storyboard.md --storyboard
+
 # Label clips in a stream tree
 npx markcut preview labels.json --label --port=3031
 ```
@@ -43,6 +46,7 @@ storyboard.md  ──[parse]──▶  DescriptiveRoot  ──[compile]──▶
 | **Tween animation** | `tween(from, to)` function calls in JSX for frame-accurate numeric animation |
 | **Styling** | Inline `style` strings on any node for CSS. JSX components use inline React styles |
 | **Live edit** | `--edit` watches the input file, re-runs pipeline, auto-reloads player |
+| **Storyboard** | `--storyboard` fast structure preview: replaces TTI/TTV prompts with placeholder components, skips slow generation. Implies `--edit` |
 | **Label mode** | `--label` interactive player with per-scene label input, saves to labels.json |
 | **CLI** | `render`, `preview` commands for MP4 export and Remotion Studio |
 | **Programmatic** | `MarkCut` / `DescriptiveComposition` React components for embedding |

package/package.json

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

package/skills/markcut/SKILL.md

@@ -10,8 +10,9 @@ Everything video is a **stream tree** described with markdown. see [docs/markdow
 
 ## Video Design Utilities
 
-### User labels — label media with text, time ranges
-- `npx @lalalic/markcut preview --label` provides tool to label video and images with text.
+### Vision — understand video and images
+- `npx @lalalic/markcut vision <folder>` provides tool to understand video and images in a folder, and generate a `metadata.json` file with with text description, duration, and other metadata for each media file.
+- `npx @lalalic/markcut vision <folder> --label`, interactive mode, provides tool to label video and images with text, and above metadata.
 
 ### Storyboard — plan video structure with scene nodes
 
@@ -20,6 +21,18 @@ Everything video is a **stream tree** described with markdown. see [docs/markdow
 
 see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
 
+### `--storyboard` — fast structure preview
+```bash
+npx @lalalic/markcut preview video.md --storyboard
+```
+
+Skips slow TTI/TTV/STT generation and renders a fast preview where:
+- `image`/`video` nodes with `prompt` but no `src` → `<StoryboardSlot>` placeholder showing the prompt text
+- `audio`/`script` nodes → `<StoryboardCaption>` overlays showing narration text
+- A `<StoryboardInfo>` card with root metadata (title, dimensions, fps) appears at the first frame
+
+Implies `--edit` so you can chat to reshape the story and see live reloads.
+
 ### Video Variants
 - define variants for different video configurations, such as different languages, aspects, platforms
 
@@ -43,10 +56,11 @@ npx @lalalic/markcut <command> [options]
 npx @lalalic/markcut --help # get overall information
 npx @lalalic/markcut --show-clis # get command specific information
 npx @lalalic/markcut preview <file> # assemble and preview the video with a local server, and chat to edit the video and auto refresh
+npx @lalalic/markcut preview <file> --storyboard # fast structure preview: replaces TTI/TTV prompts with placeholder components, skips slow generation
 npx @lalalic/markcut render <file> # render the video to mp4
 npx @lalalic/markcut vision <folder> # vision understanding medias in folder
 npx @lalalic/markcut vision <folder> --label # an extra step to provide UI to label the medias with text, time ranges
-
+  
 ```
 
 ---

package/src/components/StoryboardCaption.tsx

@@ -0,0 +1,74 @@
+import * as React from "react";
+
+/**
+ * Built-in component rendered by `--storyboard` preview mode instead of a
+ * TTS-generated audio clip. Shows the script text as a caption-style bar at
+ * the bottom of the frame.
+ *
+ * Usage in compiled JSON:
+ *   <StoryboardCaption script={script} speaker={speaker} />
+ *
+ * No imports or frontmatter registration needed — it's a built-in.
+ */
+export interface StoryboardCaptionProps {
+  /** The narration/dialogue text */
+  script: string;
+  /** Optional speaker name (for multi-turn dialogue) */
+  speaker?: string;
+}
+
+export function StoryboardCaption({ script, speaker }: StoryboardCaptionProps) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        bottom: "10%",
+        left: "5%",
+        right: "5%",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        pointerEvents: "none",
+      }}
+    >
+      <div
+        style={{
+          maxWidth: "90%",
+          background: "rgba(0,0,0,0.7)",
+          backdropFilter: "blur(4px)",
+          borderRadius: 16,
+          padding: "2.5vh 4vh",
+          textAlign: "center",
+          color: "#fff",
+          fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+        }}
+      >
+        {speaker && (
+          <div
+            style={{
+              fontSize: "2vh",
+              fontWeight: 700,
+              color: "#93c5fd",
+              marginBottom: "0.6vh",
+              letterSpacing: "0.04em",
+            }}
+          >
+            {speaker}
+          </div>
+        )}
+        <div
+          style={{
+            fontSize: "2.6vh",
+            lineHeight: 1.5,
+            fontWeight: 500,
+            textShadow: "0 1px 4px rgba(0,0,0,0.4)",
+            whiteSpace: "pre-wrap",
+            wordBreak: "break-word",
+          }}
+        >
+          {script}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/StoryboardInfo.tsx

@@ -0,0 +1,195 @@
+import * as React from "react";
+
+/**
+ * Built-in component rendered by `--storyboard` preview mode as the first
+ * frame of the video. Shows all project frontmatter config and variant info
+ * so the user has full context before reviewing the storyboard scenes.
+ *
+ * All props are strings (the compiler only collects string bindings).
+ *
+ * Usage in compiled JSON:
+ *   <StoryboardInfo config="width: 1080 · height: 1920 · fps: 30 · layout: series"
+ *                   variants="default, zh-tiktok" />
+ *
+ * No imports or frontmatter registration needed — it's a built-in.
+ */
+export interface StoryboardInfoProps {
+  /** Formatted string of all root config fields (separated by " · ") */
+  config?: string;
+  /** Comma-separated list of variant labels */
+  variants?: string;
+  /** Raw YAML frontmatter from the markdown source (if any) */
+  frontmatter?: string;
+}
+
+export function StoryboardInfo({ config, variants, frontmatter }: StoryboardInfoProps) {
+  const parts = (config ?? "").split("  ·  ").filter(Boolean);
+  const variantList = (variants ?? "").split(/,\s*/).filter(Boolean);
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        background: "linear-gradient(135deg,#0f172a,#1e293b,#334155)",
+        color: "#fff",
+        fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+        padding: "8%",
+        boxSizing: "border-box",
+      }}
+    >
+      {/* decorative rings */}
+      <div
+        style={{
+          position: "absolute",
+          inset: "5%",
+          border: "2px solid rgba(255,255,255,0.08)",
+          borderRadius: "50%",
+        }}
+      />
+      <div
+        style={{
+          position: "absolute",
+          inset: "12%",
+          border: "1px solid rgba(255,255,255,0.05)",
+          borderRadius: "50%",
+        }}
+      />
+
+      {/* header icon */}
+      <div style={{ fontSize: "6vh", marginBottom: "2.5vh", opacity: 0.7 }}>🎬</div>
+
+      {/* title */}
+      <div
+        style={{
+          fontSize: "4.2vh",
+          fontWeight: 800,
+          letterSpacing: "0.02em",
+          marginBottom: "3vh",
+          textAlign: "center",
+          textShadow: "0 2px 12px rgba(0,0,0,0.5)",
+        }}
+      >
+        Storyboard Preview
+      </div>
+
+      {/* config fields as a table */}
+      {parts.length > 0 && (
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            justifyContent: "center",
+            gap: "1.2vh",
+            maxWidth: "85%",
+            marginBottom: variantList.length > 0 ? "2.5vh" : 0,
+          }}
+        >
+          {parts.map((entry) => {
+            const colonIdx = entry.indexOf(":");
+            const label = colonIdx > 0 ? entry.slice(0, colonIdx).trim() : "";
+            const value = colonIdx > 0 ? entry.slice(colonIdx + 1).trim() : entry;
+            return (
+              <div
+                key={label || entry}
+                style={{
+                  background: "rgba(255,255,255,0.07)",
+                  border: "1px solid rgba(255,255,255,0.12)",
+                  borderRadius: 12,
+                  padding: "1.2vh 2.2vh",
+                  textAlign: "center",
+                  minWidth: "16vh",
+                }}
+              >
+                {label && (
+                  <div
+                    style={{
+                      fontSize: "1.6vh",
+                      fontWeight: 600,
+                      color: "#93c5fd",
+                      letterSpacing: "0.08em",
+                      textTransform: "uppercase" as const,
+                      marginBottom: "0.4vh",
+                    }}
+                  >
+                    {label}
+                  </div>
+                )}
+                <div
+                  style={{
+                    fontSize: "2.2vh",
+                    fontWeight: 700,
+                    whiteSpace: "pre-wrap",
+                    wordBreak: "break-word",
+                    opacity: value.startsWith("http") ? 0.8 : 1,
+                  }}
+                >
+                  {value}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {/* frontmatter block */}
+      {frontmatter && (
+        <div
+          style={{
+            maxWidth: "85%",
+            background: "rgba(255,255,255,0.05)",
+            border: "1px solid rgba(255,255,255,0.1)",
+            borderRadius: 12,
+            padding: "1.5vh 2.5vh",
+            marginBottom: "2.5vh",
+            fontFamily: "monospace",
+            fontSize: "1.8vh",
+            lineHeight: 1.6,
+            color: "rgba(255,255,255,0.8)",
+            whiteSpace: "pre-wrap",
+            wordBreak: "break-word",
+            textAlign: "left",
+            maxHeight: "28vh",
+            overflow: "auto",
+          }}
+        >
+          {frontmatter}
+        </div>
+      )}
+
+      {/* variants */}
+      {variantList.length > 0 && (
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            justifyContent: "center",
+            gap: "1vh",
+          }}
+        >
+          {variantList.map((v) => (
+            <div
+              key={v}
+              style={{
+                background: "rgba(251,191,36,0.15)",
+                border: "1px solid rgba(251,191,36,0.35)",
+                borderRadius: 999,
+                padding: "0.8vh 2vh",
+                fontSize: "1.8vh",
+                fontWeight: 600,
+                color: "#fbbf24",
+                letterSpacing: "0.04em",
+              }}
+            >
+              {v}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/StoryboardSlot.tsx

@@ -0,0 +1,96 @@
+import * as React from "react";
+
+/**
+ * Built-in component rendered by `--storyboard` preview mode instead of a
+ * generated image (TTI) or video (TTV). Shows the generation prompt with a
+ * clear type indicator so the user can review the story structure fast and
+ * chat to reshape it before committing to slow media generation.
+ *
+ * Usage in markdown / compiled JSON:
+ *   <StoryboardSlot kind="image" prompt={prompt} />
+ *   <StoryboardSlot kind="video" prompt={prompt} />
+ *
+ * The `prompt` variable comes from the component node's data bindings.
+ * No imports or frontmatter registration needed — it's a built-in.
+ */
+export interface StoryboardSlotProps {
+  kind: "image" | "video";
+  prompt?: string;
+}
+
+export function StoryboardSlot({ kind, prompt }: StoryboardSlotProps) {
+  const isVideo = kind === "video";
+
+  const bgGrad = isVideo
+    ? "linear-gradient(135deg,#7c2d12,#b91c1c)"
+    : "linear-gradient(135deg,#1e3a8a,#6d28d9)";
+  const accentColor = isVideo ? "#fbbf24" : "#93c5fd";
+  const label = isVideo ? "Video" : "Image";
+  const emoji = isVideo ? "🎬" : "🖼️";
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        overflow: "hidden",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        background: bgGrad,
+        color: "#fff",
+        fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+        padding: "6%",
+        boxSizing: "border-box",
+      }}
+    >
+      {/* dashed border frame */}
+      <div
+        style={{
+          position: "absolute",
+          inset: "4%",
+          border: "3px dashed rgba(255,255,255,0.35)",
+          borderRadius: 24,
+          pointerEvents: "none",
+        }}
+      />
+
+      {/* type badge */}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "0.5em",
+          background: "rgba(0,0,0,0.35)",
+          border: `2px solid ${accentColor}`,
+          borderRadius: 999,
+          padding: "0.5em 1.1em",
+          fontSize: "2.2vh",
+          fontWeight: 800,
+          letterSpacing: "0.12em",
+          marginBottom: "3vh",
+        }}
+      >
+        <span style={{ fontSize: "3.4vh", lineHeight: 1 }}>{emoji}</span>
+      </div>
+
+      {/* prompt text */}
+      <div
+        style={{
+          position: "relative",
+          maxWidth: "88%",
+          textAlign: "center",
+          fontSize: "3.4vh",
+          lineHeight: 1.4,
+          fontWeight: 600,
+          textShadow: "0 2px 8px rgba(0,0,0,0.5)",
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+        }}
+      >
+        {prompt ?? (isVideo ? "(no video prompt)" : "(no image prompt)")}
+      </div>
+    </div>
+  );
+}

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, dev: 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, storyboard: 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++];
@@ -37,6 +37,7 @@ export const args=(function parseArgs(argv) {
     else if (flag === "--dev") args.dev = true;
     else if (flag === "--label") args.label = true;
     else if (flag === "--edit") args.edit = true;
+    else if (flag === "--storyboard") args.storyboard = true;
     else if (flag === "--no-browser") args.noBrowser = true;
     else if (flag === "--port" && argv[i]) args.port = parseInt(argv[i], 10);
     else if (flag.startsWith("--port=")) args.port = parseInt(flag.split("=")[1], 10);

package/src/descriptive/compiler.ts

@@ -490,19 +490,27 @@ function wrapWithEffects(
 
 function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | DescriptiveScene | DescriptiveInclude>, ctx: CompileContext, parentKind: "series" | "parallel" | "transitionSeries"): CompileResult {
   const id = node.id ?? uid();
-  const start = parentKind === "parallel" ? Math.max(0, node.start ?? 0) : 0;
-  const duration = deriveLeafDuration(node, ctx);
-  const end = start + duration;
+
+  // Background nodes without explicit duration/endAt: let parent fill timing later
+  const hasOwnDuration = typeof node.duration === "number" || typeof node.endAt === "number";
+  const isBgNoOwnTiming = node.isBackground && !hasOwnDuration;
+
+  // For background without own timing, skip deriving duration — will be filled by parent
+  const start = isBgNoOwnTiming
+    ? (typeof node.start === "number" ? node.start : undefined)
+    : (parentKind === "parallel" ? Math.max(0, node.start ?? 0) : 0);
+  const duration = isBgNoOwnTiming ? undefined : deriveLeafDuration(node, ctx);
+  const end = duration != null ? start! + duration : undefined;
 
   const base = {
     id,
     style: node.style,
     visible: node.visible ?? true,
     isBackground: node.isBackground,
-    start,
+    start: isBgNoOwnTiming ? (typeof node.start === "number" ? node.start : undefined) : start,
     end,
-    startFrom: node.type === "video" || node.type === "audio" ? node.startFrom : undefined,
-    endAt: node.type === "video" || node.type === "audio" ? node.endAt : undefined,
+    startFrom: isBgNoOwnTiming ? undefined : (node.type === "video" || node.type === "audio" ? node.startFrom : undefined),
+    endAt: isBgNoOwnTiming ? undefined : (node.type === "video" || node.type === "audio" ? node.endAt : undefined),
     durationInSeconds: end,
     ...pickOn(node),
   };
@@ -518,7 +526,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         width: node.width ?? 1080,
         height: node.height ?? 1920,
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "audio": {
       const stream: Audio = {
@@ -529,7 +537,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         foreground: node.foreground,
         speaker: node.speaker,
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "image": {
       const stream: Image = {
@@ -538,7 +546,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         src: node.src,
         fit: node.fit ?? "contain",
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "component": {
       // Collect extra properties from descriptive node (e.g. `source` from ~~~md source fences)
@@ -560,7 +568,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         jsx: node.jsx,
         data: Object.keys(bindings).length ? bindings : undefined,
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "rhythm": {
       // rhythm without children compiles as a plain audio leaf
@@ -572,7 +580,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         spots: node.spots,
         children: [],
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "map": {
       const stream: MapStream = {
@@ -588,7 +596,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         routeMarker: node.routeMarker ?? "🚗",
         googleMapsApiKey: ctx.googleMapsApiKey,
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
   }
 }
@@ -676,6 +684,16 @@ function compileScene(
     ? aggregateDuration(compiledChildren, "parallel")
     : aggregateDuration(compiledChildren, sceneKind, resolved.time);
   const localDuration = Math.max(node.duration ?? 0, sceneContentDuration);
+
+  // Back-propagate parent duration to background children without own timing
+  for (const c of compiledChildren) {
+    if (c.stream.isBackground && c.stream.end == null) {
+      c.stream.end = localDuration;
+      c.stream.durationInSeconds = localDuration;
+      if (c.stream.start == null) c.stream.start = 0;
+    }
+  }
+
   const start = parentKind === "parallel" ? Math.max(0, node.start ?? 0) : 0;
   const end = start + localDuration;
 
@@ -814,6 +832,15 @@ function compileContainer(node: DescriptiveContainer, ctx: CompileContext, paren
   const children = compileChildren(node.children, ctx, node.type);
   const duration = aggregateDuration(children, node.type, resolved.time);
 
+  // Back-propagate parent duration to background children without own timing
+  for (const c of children) {
+    if (c.stream.isBackground && c.stream.end == null) {
+      c.stream.end = duration;
+      c.stream.durationInSeconds = duration;
+      if (c.stream.start == null) c.stream.start = 0;
+    }
+  }
+
   const stream: Folder = {
     id,
     type: "folder",
@@ -1200,6 +1227,10 @@ export function compileDescriptiveRoot(input: DescriptiveRoot, options: CompileO
 
   // Resolve frontmatter imports / inline component defs onto each component node.
   const registry = resolveComponentSources(input);
+  // Add built-in components so warnUnregisteredComponents doesn't flag them.
+  registry.add("StoryboardSlot");
+  registry.add("StoryboardCaption");
+  registry.add("StoryboardInfo");
   warnUnregisteredComponents(input, registry);
 
   ensureUniqueIds(input.children, "root");
@@ -1207,6 +1238,15 @@ export function compileDescriptiveRoot(input: DescriptiveRoot, options: CompileO
   const children = compileChildren(input.children, ctx, rootKind);
   const duration = aggregateDuration(children, rootKind, resolved.time);
 
+  // Back-propagate root duration to background children without own timing
+  for (const c of children) {
+    if (c.stream.isBackground && c.stream.end == null) {
+      c.stream.end = duration;
+      c.stream.durationInSeconds = duration;
+      if (c.stream.start == null) c.stream.start = 0;
+    }
+  }
+
   const compiled: Root = {
     id: "root",
     type: "root",