@lalalic/markcut 2.5.1 → 2.7.0

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",

package/src/descriptive/markdown.ts

@@ -401,7 +401,11 @@ function internalParse(markdown: string): VariantParseResult {
   for (const node of (mdast as any).children) {
     switch (node.type) {
       case "yaml": {
-        // Frontmatter is metadata only — does not affect video config.
+        // Frontmatter is metadata only — store raw text for storyboard preview
+        const rawText = (node as any).value?.trim();
+        if (rawText) {
+          (targetRoot() as any).rawFrontmatter = rawText;
+        }
         break;
       }
       case "heading": {

package/src/descriptive/resolve.ts

@@ -198,6 +198,8 @@ export async function resolveMediaDurations(
   walkDown(clone as any, (node) => {
     const n = node as DescriptiveNode;
     if (n.type !== "video" && n.type !== "audio") return;
+    // Skip background nodes without explicit timing — parent container fills duration
+    if (n.isBackground && typeof n.duration !== "number" && typeof n.endAt !== "number") return;
     if (typeof n.duration === "number" && n.duration > 0) return;
     if (typeof n.endAt === "number") return; // trim already specified
     if (!n.src) return;
@@ -739,6 +741,148 @@ export async function resolveGeneratedMedia(
   return clone;
 }
 
+// ── Storyboard Mode ─────────────────────────────────────────────────────────
+
+/**
+ * Walk the descriptive tree and replace time-consuming nodes with built-in
+ * component placeholders so the user can preview the story structure fast:
+ *
+ * - `image`/`video` with `prompt` but no `src` → `<StoryboardSlot>` (TTI/TTV placeholder)
+ * - `audio` with `script` but no `src`     → `<StoryboardCaption>` (caption-style text)
+ *
+ * Also prepends a `<StoryboardInfo>` card showing root metadata (title,
+ * dimensions, fps, variants) at the very first frame.
+ *
+ * Called early in `resolveAll` (after template-variable resolution). Since the
+ * nodes are now component type, subsequent steps (resolveGeneratedMedia,
+ * resolveMediaDurations, etc.) simply skip them — no special-case logic needed.
+ *
+ * Only runs when `options.storyboard === true`.
+ */
+export function applyStoryboardOverrides(
+  root: DescriptiveRoot,
+  options?: { variants?: string[] },
+): DescriptiveRoot {
+  const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
+  let count = 0;
+
+  const walk = (nodes: any[]) => {
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      if (
+        (n.type === "image" || n.type === "video") &&
+        typeof n.prompt === "string" &&
+        (!n.src || n.src === "auto")
+      ) {
+        // ── Image/Video prompt → StoryboardSlot ───────────────────────
+        count++;
+        const kind = n.type === "video" ? "video" : "image";
+        nodes[i] = {
+          id: n.id,
+          type: "component",
+          jsx: `<StoryboardSlot kind="${kind}" prompt={prompt} />`,
+          prompt: n.prompt,
+          duration: n.duration,
+          start: n.start,
+          end: n.end,
+          style: n.style,
+          visible: n.visible,
+          isBackground: n.isBackground,
+          on: n.on,
+          instruction: n.instruction,
+        };
+      } else if (
+        n.type === "audio" &&
+        typeof n.script === "string" &&
+        (!n.src)
+      ) {
+        // ── Audio script → StoryboardCaption ──────────────────────────
+        count++;
+        // Default to 5s so the caption is readable; use node duration if set.
+        const dur = (typeof n.duration === "number" && n.duration > 0) ? n.duration : 5;
+        nodes[i] = {
+          id: n.id,
+          type: "component",
+          jsx: `<StoryboardCaption script={script}${n.speaker ? " speaker={speaker}" : ""} />`,
+          script: n.script,
+          speaker: n.speaker,
+          duration: dur,
+          start: n.start,
+          end: n.end,
+          style: n.style,
+          visible: n.visible,
+          isBackground: n.isBackground,
+          on: n.on,
+          instruction: n.instruction,
+        };
+      } else if (Array.isArray(n.children)) {
+        walk(n.children);
+      }
+    }
+  };
+
+  walk(clone.children);
+
+  // Prepend a StoryboardInfo card with root metadata at the first frame.
+  // This lets the user see project context immediately.
+  const rootNode = clone as any;
+  // All binding values must be strings (the compiler's component case only
+  // collects string fields). Non-string values are stringified.
+
+  // Build a formatted config summary of all root-level frontmatter fields.
+  const configLines: string[] = [];
+  if (rootNode.name ?? rootNode.title) configLines.push(`title: ${rootNode.name ?? rootNode.title}`);
+  if (clone.width) configLines.push(`width: ${clone.width}`);
+  if (clone.height) configLines.push(`height: ${clone.height}`);
+  if (clone.fps) configLines.push(`fps: ${clone.fps}`);
+  if (clone.layout) configLines.push(`layout: ${clone.layout}`);
+  if (clone.transition) {
+    const t = clone.transitionTime ? `${clone.transition}(${clone.transitionTime})` : clone.transition;
+    configLines.push(`transition: ${t}`);
+  }
+  if (clone.tts) configLines.push(`tts: ${clone.tts}`);
+  if (clone.stt) configLines.push(`stt: ${clone.stt}`);
+  if (clone.tti) configLines.push(`tti: ${clone.tti}`);
+  if (clone.ttv) configLines.push(`ttv: ${clone.ttv}`);
+  if (clone.seed != null) configLines.push(`seed: ${clone.seed}`);
+  if (clone.stylesheet) configLines.push(`stylesheet: yes`);
+  if (clone.importsBlock) configLines.push(`imports: yes`);
+  if (clone.voices) configLines.push(`voices: ${Object.keys(clone.voices).join(", ")}`);
+  if (clone.metadata) configLines.push(`metadata: ${clone.metadata}`);
+
+  const configStr = configLines.join("  ·  ");
+  const variantStr = (options?.variants ?? []).join(", ");
+  // Frontmatter is the raw YAML block from the markdown source (if any).
+  const frontmatter = (rootNode as any).rawFrontmatter ?? "";
+  const infoComponent: any = {
+    type: "component",
+    jsx: `<StoryboardInfo config={config} variants={variants} frontmatter={frontmatter} />`,
+    config: configStr,
+    variants: variantStr,
+    frontmatter,
+    duration: 3,
+    start: 0,
+    end: 3,
+    visible: true,
+  };
+  const infoScene: any = {
+    type: "scene",
+    id: "storyboard-info",
+    name: "Overview",
+    title: "Storyboard Info",
+    instruction: "Project metadata and variant overview",
+    duration: 3,
+    children: [infoComponent],
+  };
+  clone.children = [infoScene, ...clone.children];
+  count++;
+
+  if (count > 0) {
+    console.log(`  🎬 Storyboard: ${count} placeholder${count > 1 ? "s" : ""} (TTI/TTV/TTS preview)`);
+  }
+  return clone;
+}
+
 // ── Combined Pipeline ──────────────────────────────────────────────────────
 
 export interface ResolveAllOptions extends ResolveMediaOptions {
@@ -770,6 +914,9 @@ export interface ResolveAllOptions extends ResolveMediaOptions {
    *  a deterministic seed is auto-generated and written back to the source file,
    *  making it stable across restarts for cache consistency. */
   sourcePath?: string;
+  /** Storyboard mode: skip TTI/TTV generation. The compiler will convert
+   *  prompt image/video nodes to component placeholders instead. */
+  storyboard?: boolean;
 }
 
 /**
@@ -944,10 +1091,10 @@ export async function resolveAll(
     try {
       const raw = readFileSync(options.sourcePath, "utf-8");
       if (options.sourcePath.endsWith(".md")) {
-        // Insert seed: <N> after the first line (# video) or after existing header
+        // Insert seed: <N> right after the `# video` line, before any config.
         const lines = raw.split("\n");
-        const headerEnd = lines.findIndex((l) => l.trim() === "" || l.startsWith("##"));
-        const insertAt = headerEnd > 1 ? headerEnd : Math.min(1, lines.length);
+        const videoIdx = lines.findIndex((l) => l.trim().startsWith("# video"));
+        const insertAt = videoIdx >= 0 ? videoIdx + 1 : 1;
         lines.splice(insertAt, 0, `seed:${autoSeed}`);
         writeFileSync(options.sourcePath, lines.join("\n"), "utf-8");
       } else if (options.sourcePath.endsWith(".json")) {
@@ -978,11 +1125,19 @@ export async function resolveAll(
     variant: options.variants?.[0] ?? "video",
   });
 
-  // Step 2: Best-match media src resolution — for pattern-based src values
+  // Step 2: Storyboard mode — replace time-consuming nodes with built-in
+  // component placeholders for fast structural preview. Converts image/video
+  // prompts and audio scripts into StoryboardSlot / StoryboardCaption cards.
+  // Also prepends a StoryboardInfo overlay with root metadata.
+  if (options.storyboard) {
+    result = applyStoryboardOverrides(result, { variants: options.variants });
+  }
+
+  // Step 3: Best-match media src resolution — for pattern-based src values
   // (e.g. photo_${width}x${height}.jpg), find the closest existing file.
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
 
-  // Step 3: Generate images/videos from prompts before probing durations.
+  // Step 4: Generate images/videos from prompts before probing durations.
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,

package/src/entry.tsx

@@ -5,6 +5,9 @@ import { ComposeContext, EventProvider, type ComposeContextValue } from "./conte
 
 import { FolderLeaf } from "./types/Folder";
 import { SubtitleOverlay } from "./types/Subtitle";
+import { StoryboardSlot } from "./components/StoryboardSlot";
+import { StoryboardCaption } from "./components/StoryboardCaption";
+import { StoryboardInfo } from "./components/StoryboardInfo";
 import { getDurationInSeconds } from "./utils/index";
 import { root as rootSchema, type Root } from "./schema/index";
 import {
@@ -33,6 +36,20 @@ const DefaultContainer: ComposeContextValue["Container"] = ({ children, style, c
   </div>
 );
 
+/**
+ * Built-in components available to every video without registration.
+ * Currently includes the storyboard placeholder; add other universal
+ * components here as needed.
+ *
+ * User-provided components (via compose.components or root.imports) take
+ * precedence — they can override any builtin by using the same name.
+ */
+const BUILTIN_COMPONENTS: Record<string, React.ComponentType<any>> = {
+  StoryboardSlot,
+  StoryboardCaption,
+  StoryboardInfo,
+};
+
 /**
  * Load the component registry from root.imports.
  * - If string: import it as an ESM module (pre-bundled by server)
@@ -115,11 +132,17 @@ export function MarkCut({ root, compose, background = "#000" }: MarkCutProps) {
   React.useMemo(() => getDurationInSeconds(parsed as any, true), [parsed]);
 
   const value = React.useMemo<ComposeContextValue>(
-    () => ({
-      Container: compose?.Container ?? DefaultContainer,
-      onError: compose?.onError,
-      components: registry ?? compose?.components,
-    }),
+    () => {
+      const userComponents = registry ?? compose?.components;
+      const components = userComponents
+        ? { ...BUILTIN_COMPONENTS, ...userComponents }
+        : BUILTIN_COMPONENTS;
+      return {
+        Container: compose?.Container ?? DefaultContainer,
+        onError: compose?.onError,
+        components,
+      };
+    },
     [compose, registry],
   );