@lalalic/markcut 2.5.1 → 2.7.0

package/src/player/pipeline.mjs

@@ -224,18 +224,20 @@ function wrapWithEffects(node2, result, parentKind) {
 }
 function compileLeaf(node2, ctx, parentKind) {
   const id = node2.id ?? uid();
-  const start = parentKind === "parallel" ? Math.max(0, node2.start ?? 0) : 0;
-  const duration = deriveLeafDuration(node2, ctx);
-  const end = start + duration;
+  const hasOwnDuration = typeof node2.duration === "number" || typeof node2.endAt === "number";
+  const isBgNoOwnTiming = node2.isBackground && !hasOwnDuration;
+  const start = isBgNoOwnTiming ? typeof node2.start === "number" ? node2.start : void 0 : parentKind === "parallel" ? Math.max(0, node2.start ?? 0) : 0;
+  const duration = isBgNoOwnTiming ? void 0 : deriveLeafDuration(node2, ctx);
+  const end = duration != null ? start + duration : void 0;
   const base = {
     id,
     style: node2.style,
     visible: node2.visible ?? true,
     isBackground: node2.isBackground,
-    start,
+    start: isBgNoOwnTiming ? typeof node2.start === "number" ? node2.start : void 0 : start,
     end,
-    startFrom: node2.type === "video" || node2.type === "audio" ? node2.startFrom : void 0,
-    endAt: node2.type === "video" || node2.type === "audio" ? node2.endAt : void 0,
+    startFrom: isBgNoOwnTiming ? void 0 : node2.type === "video" || node2.type === "audio" ? node2.startFrom : void 0,
+    endAt: isBgNoOwnTiming ? void 0 : node2.type === "video" || node2.type === "audio" ? node2.endAt : void 0,
     durationInSeconds: end,
     ...pickOn(node2)
   };
@@ -250,7 +252,7 @@ function compileLeaf(node2, ctx, parentKind) {
         width: node2.width ?? 1080,
         height: node2.height ?? 1920
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "audio": {
       const stream = {
@@ -261,7 +263,7 @@ function compileLeaf(node2, ctx, parentKind) {
         foreground: node2.foreground,
         speaker: node2.speaker
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "image": {
       const stream = {
@@ -270,7 +272,7 @@ function compileLeaf(node2, ctx, parentKind) {
         src: node2.src,
         fit: node2.fit ?? "contain"
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "component": {
       const KNOWN_COMPONENT_KEYS = /* @__PURE__ */ new Set([
@@ -298,7 +300,7 @@ function compileLeaf(node2, ctx, parentKind) {
         jsx: node2.jsx,
         data: Object.keys(bindings).length ? bindings : void 0
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "rhythm": {
       const stream = {
@@ -309,7 +311,7 @@ function compileLeaf(node2, ctx, parentKind) {
         spots: node2.spots,
         children: []
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
     case "map": {
       const stream = {
@@ -325,7 +327,7 @@ function compileLeaf(node2, ctx, parentKind) {
         routeMarker: node2.routeMarker ?? "\u{1F697}",
         googleMapsApiKey: ctx.googleMapsApiKey
       };
-      return { stream, duration: end };
+      return { stream, duration: end ?? 0 };
     }
   }
 }
@@ -388,6 +390,13 @@ function compileScene(node2, ctx, parentKind) {
   ];
   const sceneContentDuration = sceneKind === "parallel" ? aggregateDuration(compiledChildren, "parallel") : aggregateDuration(compiledChildren, sceneKind, resolved.time);
   const localDuration = Math.max(node2.duration ?? 0, sceneContentDuration);
+  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, node2.start ?? 0) : 0;
   const end = start + localDuration;
   const stream = {
@@ -481,6 +490,13 @@ function compileContainer(node2, ctx, parentKind) {
   const resolved = node2.type === "transitionSeries" ? resolveTransition(node2.transition, node2.transitionTime) : { name: "fade", time: 0.5 };
   const children = compileChildren(node2.children, ctx, node2.type);
   const duration = aggregateDuration(children, node2.type, resolved.time);
+  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 = {
     id,
     type: "folder",
@@ -722,10 +738,20 @@ function compileDescriptiveRoot(input, options = {}) {
     googleMapsApiKey
   };
   const registry = resolveComponentSources(input);
+  registry.add("StoryboardSlot");
+  registry.add("StoryboardCaption");
+  registry.add("StoryboardInfo");
   warnUnregisteredComponents(input, registry);
   ensureUniqueIds(input.children, "root");
   const children = compileChildren(input.children, ctx, rootKind);
   const duration = aggregateDuration(children, rootKind, resolved.time);
+  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 = {
     id: "root",
     type: "root",
@@ -985,7 +1011,7 @@ var args = (function parseArgs(argv) {
     "--tti": "tti",
     "--ttv": "ttv"
   };
-  const args2 = { 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 args2 = { 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]) args2.command = argv[i++];
   if (argv[i] && !argv[i].startsWith("--")) args2.file = argv[i++];
@@ -1002,6 +1028,7 @@ var args = (function parseArgs(argv) {
     else if (flag === "--dev") args2.dev = true;
     else if (flag === "--label") args2.label = true;
     else if (flag === "--edit") args2.edit = true;
+    else if (flag === "--storyboard") args2.storyboard = true;
     else if (flag === "--no-browser") args2.noBrowser = true;
     else if (flag === "--port" && argv[i]) args2.port = parseInt(argv[i], 10);
     else if (flag.startsWith("--port=")) args2.port = parseInt(flag.split("=")[1], 10);
@@ -10410,6 +10437,10 @@ function internalParse(markdown) {
   for (const node2 of mdast.children) {
     switch (node2.type) {
       case "yaml": {
+        const rawText = node2.value?.trim();
+        if (rawText) {
+          targetRoot().rawFrontmatter = rawText;
+        }
         break;
       }
       case "heading": {
@@ -10738,6 +10769,7 @@ async function resolveMediaDurations(root, options = {}) {
   walkDown(clone, (node2) => {
     const n = node2;
     if (n.type !== "video" && n.type !== "audio") return;
+    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;
     if (!n.src) return;
@@ -11046,6 +11078,103 @@ async function resolveGeneratedMedia(root, options) {
   }
   return clone;
 }
+function applyStoryboardOverrides(root, options) {
+  const clone = JSON.parse(JSON.stringify(root));
+  let count = 0;
+  const walk = (nodes) => {
+    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")) {
+        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) {
+        count++;
+        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);
+  const rootNode = clone;
+  const configLines = [];
+  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("  \xB7  ");
+  const variantStr = (options?.variants ?? []).join(", ");
+  const frontmatter2 = rootNode.rawFrontmatter ?? "";
+  const infoComponent = {
+    type: "component",
+    jsx: `<StoryboardInfo config={config} variants={variants} frontmatter={frontmatter} />`,
+    config: configStr,
+    variants: variantStr,
+    frontmatter: frontmatter2,
+    duration: 3,
+    start: 0,
+    end: 3,
+    visible: true
+  };
+  const infoScene = {
+    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(`  \u{1F3AC} Storyboard: ${count} placeholder${count > 1 ? "s" : ""} (TTI/TTV/TTS preview)`);
+  }
+  return clone;
+}
 async function resolveIncludes(root, options = {}) {
   const clone = JSON.parse(JSON.stringify(root));
   const baseDir = options.baseDir ?? process.cwd();
@@ -11136,8 +11265,8 @@ async function resolveAll2(root, options = {}) {
       const raw = readFileSync(options.sourcePath, "utf-8");
       if (options.sourcePath.endsWith(".md")) {
         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")) {
@@ -11161,6 +11290,9 @@ async function resolveAll2(root, options = {}) {
     fps: result.fps ?? 30,
     variant: options.variants?.[0] ?? "video"
   });
+  if (options.storyboard) {
+    result = applyStoryboardOverrides(result, { variants: options.variants });
+  }
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
@@ -11220,7 +11352,8 @@ async function resolveAndCompile(data, options = {}) {
     sttCli: options.sttCli,
     subtitleOutputDir: options.subtitleOutputDir,
     seed: options.seed,
-    variants: options.variants
+    variants: options.variants,
+    storyboard: options.storyboard
   });
   const compiled = compileDescriptiveRoot(resolved, {
     googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY

package/src/player/pipeline.ts

@@ -45,6 +45,9 @@ export interface ResolveAndCompileOptions {
   /** Path to the source file (.md or .json). When set and root.seed is missing,
    *  a deterministic seed is auto-generated and written back to the source file. */
   sourcePath?: string;
+  /** Storyboard mode: skip TTI/TTV generation, convert prompt image/video nodes
+   *  to component placeholders for fast structural preview. */
+  storyboard?: boolean;
 }
 
 /**
@@ -99,6 +102,7 @@ export async function resolveAndCompile(
     subtitleOutputDir: options.subtitleOutputDir,
     seed: options.seed,
     variants: options.variants,
+    storyboard: options.storyboard,
   });
 
   // 2. Sync compile: descriptive → stream tree

package/src/player/server-shared.mjs

@@ -40,28 +40,44 @@ export function extractScenes(root) {
     for (const s of root.children) {
       if (!(s.type === "folder" || s.type === "scene" || s.children?.length)) continue;
       if (s.isBackground) continue;
-      // Use durationInSeconds (set by compiler) as the definitive duration.
-      // Fall back to leaf end-start for backward compatibility.
-      const leaf = (s.children || []).find(c => c.src && (c.type === "image" || c.type === "video"));
+      // Compute scene duration. Priority:
+      // 1. s.durationInSeconds (set by engine's getDurationInSeconds)
+      // 2. Sum of children's durationInSeconds (for series) or max (for parallel)
+      // 3. Leaf node's end-start (backward compat with old compiled JSON)
+      // 4. Default 5s
       let dur = s.durationInSeconds;
       if (!dur || dur <= 0) {
+        const kids = s.children || [];
+        const childDurs = kids
+          .filter(c => !c.isBackground)
+          .map(c => c.durationInSeconds ?? (c.end != null ? c.end - (c.start ?? 0) : 0))
+          .filter(d => d > 0);
+        if (childDurs.length > 0) {
+          // Series → sum; Parallel → max. We don't know which here, so sum is
+          // the safe upper bound (parallel scenes are rare as direct root children).
+          dur = childDurs.reduce((a, b) => a + b, 0);
+        }
+      }
+      if (!dur || dur <= 0) {
+        const leaf = (s.children || []).find(c => c.src && (c.type === "image" || c.type === "video"));
         const src2 = leaf || s;
         dur = (src2.end ?? 5) - (src2.start ?? 0);
       }
-      // Account for transition overlap: scene i starts at offset - i*overlap
-      const transitionOffset = scenes.length * overlap;
-      const start = Math.max(0, offset - transitionOffset);
+      const leaf = (s.children || []).find(c => c.src && (c.type === "image" || c.type === "video"));
+      // Use the raw cumulative offset as the scene start time. Transition overlap
+      // is a rendering detail — scene thumbnails seek to the raw boundary so the
+      // user lands on the first frame of the intended scene, not inside a transition.
       scenes.push({
         name: s.name || s.id || "scene",
-        start,
-        end: start + dur,
+        start: offset,
+        end: offset + dur,
         duration: dur,
         src: leaf?.src || "",
         mediaType: leaf?.type || "unknown",
       });
       offset += dur;
     }
-    totalDuration = offset - Math.max(0, (scenes.length - 1)) * overlap;
+    totalDuration = offset;
   }
 
   // Format 2: scenes wrapped in a "scenes" folder

package/src/player/server.mjs

@@ -30,6 +30,10 @@ const VIDEO_JSON = inputArg ? resolve(inputArg) : join(ROOT, "video.json");
 const IS_MARKDOWN = VIDEO_JSON.endsWith(".md");
 const MODE_LABEL = process.argv.includes("--label");
 const MODE_EDIT = process.argv.includes("--edit");
+// Storyboard mode: skip slow TTI/TTV generation. The compiler converts prompt
+// image/video nodes into component placeholders so the user can review the
+// story structure fast and chat to reshape it.
+const MODE_STORYBOARD = process.argv.includes("--storyboard");
 
 // ─── Variant configuration ─────────────────────────────────────────────────
 // Each --variant flag defines a separate compilation target.
@@ -326,9 +330,11 @@ function resolveAssetPaths(root) {
     if (typeof node.src === "string" && !node.src.startsWith("http://") && !node.src.startsWith("https://") && !node.src.startsWith("data:")) {
       // Already a relative path under MARKCUT_BASE (shouldn't be absolute)
       if (!node.src.startsWith("/") && !node.src.startsWith(".")) {
-        if (node.src.startsWith("generated/") || node.src.startsWith(BASENAME + "/")) {
-          node.src = "/" + node.src;
-        }
+        // Plain relative path — prefix with / (server serves from project root)
+        node.src = "/" + node.src;
+      } else if (node.src.startsWith("./")) {
+        // Dot-prefixed relative path — strip ./ and prefix with /
+        node.src = "/" + node.src.slice(2);
       }
       // Convert absolute paths under MARKCUT_BASE
       if (typeof node.src === "string" && node.src.startsWith(MARKCUT_BASE)) {
@@ -442,6 +448,7 @@ async function compileVariant(config, parsed, raw) {
       mediaOutputDir: MEDIA_OUTPUT_DIR,
       includeOutputDir: INCLUDE_CACHE_DIR,
       subtitleOutputDir: subtitleDir,
+      storyboard: MODE_STORYBOARD,
       variants: config.chain.length > 0 ? config.chain : undefined,
     });
     compiled = compileDescriptiveRoot(resolved);
@@ -465,6 +472,7 @@ async function compileVariant(config, parsed, raw) {
         mediaOutputDir: MEDIA_OUTPUT_DIR,
         includeOutputDir: INCLUDE_CACHE_DIR,
         subtitleOutputDir: subtitleDir,
+        storyboard: MODE_STORYBOARD,
         variants: config.chain.length > 0 ? config.chain : undefined,
       });
     } else {

package/src/render/cli.mjs

@@ -65,6 +65,9 @@ Commands:
 
   preview <file.json|.md>               Open player with live preview
     --label                           Open label input overlay
+    --storyboard                      Fast structure preview: show TTI/TTV prompts as
+                                      placeholder components (skips slow generation).
+                                      Implies --edit so you can reshape the story.
     --no-browser                      Skip opening browser automatically
     --port <num>                        Port for the player server (default: 3001)
 
@@ -72,11 +75,11 @@ Commands:
     --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
+  vision <folder>                      Full pipeline: extract → normalize → percept → segments
+    --label                            Add interactive labeling step before AI pipeline
+    --instruct "text"                   Background context about people/places (injected into prompts)
     --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)
     --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
@@ -209,6 +212,10 @@ edit=${DEFAULT_EDIT_CLI}`);
   }
 
   if (args.command === "preview") {
+    // --storyboard implies --edit: show story structure fast (prompts as
+    // placeholder components) and let user chat to reshape before generation.
+    if (args.storyboard) args.edit = true;
+
     // Auto-detect: markdown files must use the player server (not Remotion Studio)
     const isMarkdown = args.file?.endsWith(".md");
     if (isMarkdown && !args.edit && !args.label) {
@@ -223,12 +230,13 @@ edit=${DEFAULT_EDIT_CLI}`);
       }
       const labelFlag = args.label ? "--label" : "";
       const editFlag = args.edit ? "--edit" : "";
+      const storyboardFlag = args.storyboard ? "--storyboard" : "";
       const portFlag = `--port=${args.port || 3001}`;
       const fileFlag = args.file || join(ROOT, "video.json");
       const port = args.port || 3001;
       // Pass variant flags to the server
       const variantFlags = args.variant.map(v => `--variant=${v}`);
-      const serverArgs = [playerServer, resolve(fileFlag), labelFlag, editFlag, portFlag, ...variantFlags].filter(Boolean);
+      const serverArgs = [playerServer, resolve(fileFlag), labelFlag, editFlag, storyboardFlag, portFlag, ...variantFlags].filter(Boolean);
       const child = spawn("node", serverArgs, { cwd: ROOT, stdio: ["ignore", "pipe", "inherit"] });
       let serverReady = false;
       let stdoutBuffer = "";

package/src/schema/index.ts

@@ -57,7 +57,7 @@ export const folder = base.extend({
 export type Folder = z.infer<typeof folder>;
 
 export const subtitleOverlay = z.object({
-  src: z.string().describe("path or URL to VTT file covering the full video duration"),
+  src: z.string().optional().describe("path or URL to VTT file covering the full video duration; omitted when no subtitles are available"),
   style: z.string().optional().describe("inline css for the overlay container"),
   fontSize: z.union([z.number(), z.string()]).optional(),
   type: z.string().optional().describe("caption animation type: bounce, fade, typewriter, colorful, glowing, neon, etc."),

package/src/types/Folder.tsx

@@ -172,8 +172,8 @@ export function FolderLeaf({ stream }: { stream: FolderStream }) {
         style={containerStyle}
         className={`${orientation} ${stream.type}`.trim()}
       >
-        {isSeries ? <TypedSeries>{sequences}</TypedSeries> : sequences}
         {bgContent}
+        {isSeries ? <TypedSeries>{sequences}</TypedSeries> : sequences}
       </Container>
     </AudioContext.Provider>
   );

package/src/types/Subtitle.tsx

@@ -237,6 +237,9 @@ export function SubtitleOverlay({ subtitle }: { subtitle: SubtitleOverlayConfig
   const { fps } = useVideoConfig();
   const [cues, setCues] = React.useState<Cue[] | null>(null);
 
+  // No subtitle source — nothing to render
+  if (!subtitle.src) return null;
+
   const CaptionComponent = React.useMemo(
     () => resolveCaption(subtitle.type),
     [subtitle.type],
@@ -244,6 +247,7 @@ export function SubtitleOverlay({ subtitle }: { subtitle: SubtitleOverlayConfig
 
   React.useEffect(() => {
     const { src } = subtitle;
+    if (!src) return;
 
     // Inline VTT body
     if (src.includes("-->")) {

package/src/vision/cli.mjs

@@ -648,9 +648,12 @@ function buildPreviewTree(folder, metadata) {
   }
   entries.sort((a, b) => a.created.localeCompare(b.created));
 
+  // Random seed for TTI/TTV generation.
+  const seed = Math.floor(Math.random() * 0xFFFFFFFF);
+
   return {
     id: "root", type: "root", width: 1080, height: 1920, fps: 30,
-    isSeries: true, transition: "fade", transitionTime: 0.5,
+    seed, isSeries: true, transition: "fade", transitionTime: 0.5,
     children: entries.map((e) => ({
       id: e.name, type: "folder", isSeries: false,
       children: [{
@@ -1093,14 +1096,14 @@ function printUsage() {
 markcut vision — Analyze images and videos in a folder for video generation
 
 Usage:
-  markcut vision <folder>                Extract metadata into metadata.json
-  markcut vision <folder> --label        Full pipeline: preview → label → normalize → percept → segments
+  markcut vision <folder>                Full pipeline: extract → normalize → percept → segments
+  markcut vision <folder> --label        Same as default, plus interactive labeling step before AI
 
 Options:
-  --label              Open label preview → then continue with full AI pipeline
+  --label              Open interactive labeling preview before running AI pipeline
+  --instruct "text"    Background context about people/places (injected into prompts)
   --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
@@ -1134,9 +1137,8 @@ export async function main(args) {
 
     else if (flag === "--prompts-file" && args[i]) { promptsFile = resolve(args[i++]); }
     else if (flag === "--vtt-sample-interval" && args[i]) { vttSampleInterval = parseInt(args[i++], 10) || DEFAULT_VTT_SAMPLE_INTERVAL; }
-    else if (flag === "--context" && args[i]) { context = args[i++]; }
+    else if (flag === "--instruct" && args[i]) { context = args[i++]; }
     else if (flag === "--show-prompts") { console.log(readFileSync(promptsFile, "utf-8")); return; }
-
     else if (flag === "--skip-stt") { skipSTT = true; }
     else if (flag === "--pick" && args[i]) { for (const f of args[i++].split(",")) pickSet.add(f.trim()); }
     else if (flag === "--dry-run") { dryRun = true; }
@@ -1151,12 +1153,45 @@ export async function main(args) {
   for (const [name, value] of promptOverrides) prompts.set(name, value);
 
   if (doLabel) {
+    // Full pipeline with interactive labeling
     await runFullPipeline(folder, prompts, context, pickSet, vttSampleInterval, skipSTT, dryRun);
   } else {
-    await runMetadataMode(folder, pickSet, dryRun);
+    // Default: full pipeline without labeling (extract → normalize → percept → segments)
+    const metadataPath = join(folder, "metadata.json");
+    if (!existsSync(metadataPath)) {
+      emitInfo(`\n📋 Extracting metadata...`);
+      await runMetadataMode(folder, pickSet, false);
+    }
+    if (!existsSync(metadataPath) || Object.keys(JSON.parse(readFileSync(metadataPath, "utf-8"))).length === 0) {
+      emitError("No media files found — nothing to process.");
+      return;
+    }
+    emitInfo(`\n🔧 Running full pipeline (normalize → perceive)...`);
+    await runNormalizeAndPercept(folder, metadataPath, prompts, context, pickSet, vttSampleInterval, skipSTT);
   }
 }
 
+// ═════════════════════════════════════════════════════════════════════════
+// Exported for testing
+// ═════════════════════════════════════════════════════════════════════════
+
+export {
+  scanMedia,
+  buildPreviewTree,
+  mergeLabelsIntoMetadata,
+  buildMergedCues,
+  parseVTT,
+  loadPrompts,
+  substituteTemplate,
+  shQuote,
+  normalizePerception,
+  extractRawText,
+  stripThinkBlocks,
+  looseJSONParse,
+  formatTime,
+  timeToSeconds,
+};
+
 // Direct execution
 if (process.argv[1] && process.argv[1].includes("src/vision/cli.mjs")) {
   main(process.argv).catch((e) => { emitError(e.message); process.exit(1); });

package/tests/tmp/vision-1784830584961/images/metadata.json

@@ -0,0 +1,8 @@
+{
+  "test-photo": {
+    "width": 64,
+    "height": 64,
+    "created": null,
+    "location": null
+  }
+}