@lalalic/markcut 2.4.6 → 2.5.1

package/package.json

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

package/src/config.mjs

@@ -92,7 +92,7 @@ export const DEFAULT_AGENT_CLI = args.cliOverrides.agent || process.env.MARKCUT_
 /** Default edit agent CLI. Override via --edit-cli flag or MARKCUT_EDIT_CLI env var. */
 export const DEFAULT_EDIT_CLI = args.cliOverrides.editCli || process.env.MARKCUT_EDIT_CLI || 'npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}';
 /** Text-to-image CLI. Override via --tti flag or MARKCUT_TTI_CLI env var. */
-export const DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
+export const DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 2 --prompt "{input}" --output "{output}" --seed {seed}';
 /** Text-to-video CLI. Override via --ttv flag or MARKCUT_TTV_CLI env var. */
 export const DEFAULT_TTV_CLI = args.cliOverrides.ttv || process.env.MARKCUT_TTV_CLI || '';
 /** Image-to-text CLI. Override via --itt flag or MARKCUT_ITT_CLI env var. */

package/src/descriptive/resolve.test.ts

@@ -395,11 +395,10 @@ describe("resolveScripts — additional", () => {
 
   it("caches TTS output and skips second generateTTS call", async () => {
     let callCount = 0;
-    (generateTTS as any).mockImplementation(() => {
+    (generateTTS as any).mockImplementation((_script, audioPath) => {
       callCount++;
-      const p = join(tmpDir, `hook.wav`);
-      writeFileSync(p, "");
-      return p;
+      writeFileSync(audioPath, "");
+      return audioPath;
     });
 
     const root: DescriptiveRoot = {
@@ -412,7 +411,7 @@ describe("resolveScripts — additional", () => {
     await resolveScripts(root, { outputDir: tmpDir });
     expect(callCount).toBe(1);
 
-    // Second call — should hit cache
+    // Second call — filesystem cache: file named by hash already exists
     const result = await resolveScripts(root, { outputDir: tmpDir });
     expect(callCount).toBe(1);
     const scene = result.children[0] as any;
@@ -552,8 +551,9 @@ describe("resolveSubtitles — additional", () => {
   it("merges VTT from multiple audio clips with correct offsets", async () => {
     const a1 = join(tmpDir, "clip1.wav");
     const a2 = join(tmpDir, "clip2.wav");
-    writeFileSync(a1, "fake");
-    writeFileSync(a2, "fake");
+    // Different content ensures distinct audio hashes (avoid STT cache collision)
+    writeFileSync(a1, "clip1-content");
+    writeFileSync(a2, "clip2-content");
     (generateSTT as any)
       .mockImplementationOnce(async () => {
         writeFileSync(join(tmpDir, "clip1.vtt"), "WEBVTT\n\n00:00:01.000 --> 00:00:02.000\nfirst\n");

package/src/descriptive/resolve.ts

@@ -9,7 +9,7 @@
  * has complete duration and renderable children.
  */
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, renameSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, dirname, resolve as resolvePath, relative } from "node:path";
 import {
@@ -28,62 +28,15 @@ import { compileDescriptiveRoot, parseImportsBlock, extractDependencySpecs, reso
 import { parseMarkdownDescriptive, parseMarkdownVariants } from "./markdown";
 
 // ── Content-hash cache for expensive operations (TTS, STT) ────────────────
-// Skips regeneration when input hasn't changed. Cache key is a hash of all
-// inputs that affect the output (script + cli template).
-
-interface CacheEntry {
-  hash: string;
-  output: string;
-}
+// Output files are named by content hash — the filesystem IS the cache.
+// If a file named `<hash>.<ext>` exists, it's guaranteed to match its inputs.
+// No manifest file needed.
 
 function computeCacheKey(parts: Record<string, unknown>): string {
   const json = JSON.stringify(parts);
   return createHash("sha1").update(json).digest("hex").slice(0, 12);
 }
 
-function readCacheManifest(outputDir: string): Record<string, CacheEntry> {
-  const manifestPath = join(outputDir, ".cache.json");
-  try {
-    return JSON.parse(readFileSync(manifestPath, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-function writeCacheManifest(outputDir: string, manifest: Record<string, CacheEntry>): void {
-  const manifestPath = join(outputDir, ".cache.json");
-  try {
-    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
-  } catch {
-    // best-effort
-  }
-}
-
-/**
- * Returns cached output path if inputs unchanged AND output file still exists.
- * Otherwise returns null (caller should regenerate).
- */
-function checkCache(
-  manifest: Record<string, CacheEntry>,
-  key: string,
-  cacheKey: string,
-): string | null {
-  const entry = manifest[key];
-  if (entry?.hash === cacheKey && entry.output && existsSync(entry.output)) {
-    return entry.output;
-  }
-  return null;
-}
-
-function updateCache(
-  manifest: Record<string, CacheEntry>,
-  key: string,
-  cacheKey: string,
-  output: string,
-): void {
-  manifest[key] = { hash: cacheKey, output };
-}
-
 // ── Media Duration ─────────────────────────────────────────────────────────
 
 /** First N words of a string, safe for log labels. */
@@ -399,8 +352,6 @@ export async function resolveScripts(
 ): Promise<DescriptiveRoot> {
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
   mkdirSync(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
 
   // Collect all audio nodes that have script text but no src yet
   const allScriptNodes: Array<{ node: any; id: string }> = [];
@@ -439,21 +390,18 @@ export async function resolveScripts(
     const cacheKey = computeCacheKey({ script: node.script, cli: ttsCli });
     const audioPath = join(options.outputDir, `${cacheKey}.mp3`);
 
-    // Check cache — skip TTS if script + config unchanged AND audio file exists
-    const cached = checkCache(cache, `tts:${cacheKey}`, cacheKey);
+    // Content-addressed cache: file is named by hash — if it exists, it's valid
     let generated: string;
     const speakerLabel = node.speaker ? `${node.speaker}: ` : "";
     const label = `${speakerLabel}${firstWords(node.script, 8)}`;
-    if (cached) {
-      generated = cached;
+    if (existsSync(audioPath)) {
+      generated = audioPath;
       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 (${scriptsDone}/${totalScripts}): ${label}`);
       } else {
         console.warn(`  ⚠ TTS produced no audio for "${label}". Audio will have no source. Check root.tts config.`);
@@ -466,9 +414,7 @@ export async function resolveScripts(
     delete node.script;
   }
 
-  if (cacheDirty) writeCacheManifest(options.outputDir, cache);
   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${unique > 1 ? "s" : ""} (${scriptsDone} nodes) in ${ttsElapsed}s (${cacheHits} cached)`);
@@ -502,8 +448,6 @@ export async function resolveSubtitles(
   if (!sttCli) return clone;
 
   mkdirSync(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
 
   // Collect { audioSrc, absoluteOffset } from the compiled tree
   const clips: Array<{ audioSrc: string; offset: number; speaker?: string }> = [];
@@ -596,30 +540,27 @@ export async function resolveSubtitles(
   let sttFailedCount = 0;
 
   for (const { audioSrc, offset, speaker } of clips) {
-    // Cache key: audio hash + STT CLI string
+    // Content-addressed STT cache: hash of (audio content + CLI) → hash-named VTT
     const audioHash = existsSync(audioSrc)
       ? createHash("sha1").update(readFileSync(audioSrc)).digest("hex").slice(0, 12)
       : audioSrc;
     const sttCacheKey = computeCacheKey({ audioHash, cli: sttCli });
-    const sttKey = `stt:${audioSrc.split("/").pop()}`;
     const clipName = audioSrc.split("/").pop()!;
+    const expectedVtt = join(options.outputDir, `${sttCacheKey}.vtt`);
 
     let vttPath: string | null = null;
-    // Cache per-clip STT by audio hash + CLI (individual VTT files are stable)
-    const cachedVtt = checkCache(cache, sttKey, sttCacheKey);
-    if (cachedVtt) {
-      vttPath = cachedVtt;
+    if (existsSync(expectedVtt)) {
+      vttPath = expectedVtt;
     } else {
       try {
         await generateSTT(audioSrc, options.outputDir, sttCli);
-        // Find generated VTT file
+        // Whisper names VTT after input audio file; rename to hash-based name
         const base = audioSrc.replace(/\.wav$/, "").replace(/\.mp3$/, "");
         const name = base.split("/").pop()!;
-        const candidate = join(options.outputDir, `${name}.vtt`);
-        if (existsSync(candidate)) {
-          vttPath = candidate;
-          updateCache(cache, sttKey, sttCacheKey, vttPath);
-          cacheDirty = true;
+        const whisperVtt = join(options.outputDir, `${name}.vtt`);
+        if (existsSync(whisperVtt)) {
+          renameSync(whisperVtt, expectedVtt);
+          vttPath = expectedVtt;
         }
       } catch {
         console.warn(`  ⚠ STT failed for ${clipName}. Install whisper (pip install openai-whisper) or set root.stt.`);
@@ -674,7 +615,6 @@ export async function resolveSubtitles(
     console.log(`  ✅ STT: subtitles ready (${cueIndex - 1} cues)`);
   }
 
-  if (cacheDirty) writeCacheManifest(options.outputDir, cache);
   return clone;
 }
 
@@ -708,8 +648,6 @@ export async function resolveGeneratedMedia(
 ): Promise<DescriptiveRoot> {
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
   mkdirSync(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
 
   // Collect all image/video nodes that have prompt but no src
   const genNodes: Array<{
@@ -753,16 +691,17 @@ export async function resolveGeneratedMedia(
       ? (clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI)
       : (clone.ttv ?? options.ttvCli ?? DEFAULT_TTV_CLI);
 
+    // Use the shared seed (from root, options, or content-derived default).
     const seed = options.seed;
     const cacheKey = computeCacheKey({ prompt, cli, type, seed });
     const outputPath = join(options.outputDir, `${cacheKey}.${ext}`);
 
-    const cached = checkCache(cache, `gen:${cacheKey}`, cacheKey);
     const label = type === "image" ? "TTI" : "TTV";
     const labelText = firstWords(prompt, 8);
 
-    if (cached) {
-      node.src = resolvePath(cached);
+    // Content-addressed cache: file is named by hash — if it exists, it's valid
+    if (existsSync(outputPath)) {
+      node.src = resolvePath(outputPath);
       cacheHits++;
       if (done % 5 === 0 || done === total) console.log(progressLine());
       continue;
@@ -776,8 +715,6 @@ export async function resolveGeneratedMedia(
         : generateTTV(prompt, outputPath, cli, ttiCmd, seed);
       if (result) {
         node.src = outputPath;
-        updateCache(cache, `gen:${cacheKey}`, cacheKey, outputPath);
-        cacheDirty = true;
         console.log(`  ✓ ${label} (${done}/${total}): ${labelText}`);
         if (done % 3 === 0 || done === total) console.log(progressLine());
       } else {
@@ -799,7 +736,6 @@ export async function resolveGeneratedMedia(
     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;
 }
 
@@ -830,6 +766,10 @@ export interface ResolveAllOptions extends ResolveMediaOptions {
    *  When set, include nodes parse their target .md files with variant awareness
    *  and apply variant overrides (zh-src → src, bare `zh` key → primary content). */
   variants?: string[];
+  /** 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,
+   *  making it stable across restarts for cache consistency. */
+  sourcePath?: string;
 }
 
 /**
@@ -993,6 +933,37 @@ export async function resolveAll(
 ): Promise<DescriptiveRoot> {
   let result = root;
 
+  // ── Auto-seed: persist a deterministic seed into the source file ───────────
+  // When no seed is set by the user (root.seed) or caller (options.seed),
+  // generate one from the content hash and write it back to the source file.
+  // This makes the seed visible and stable across restarts — the cache key
+  // never changes unless the content or the user intentionally edits the seed.
+  if (result.seed == null && options.seed == null && options.sourcePath) {
+    const autoSeed = parseInt(computeCacheKey(result as any).slice(0, 8), 16);
+    result = { ...result, seed: autoSeed };
+    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
+        const lines = raw.split("\n");
+        const headerEnd = lines.findIndex((l) => l.trim() === "" || l.startsWith("##"));
+        const insertAt = headerEnd > 1 ? headerEnd : Math.min(1, lines.length);
+        lines.splice(insertAt, 0, `seed:${autoSeed}`);
+        writeFileSync(options.sourcePath, lines.join("\n"), "utf-8");
+      } else if (options.sourcePath.endsWith(".json")) {
+        const parsed = JSON.parse(raw);
+        const target = parsed.root || parsed;
+        target.seed = autoSeed;
+        writeFileSync(options.sourcePath, JSON.stringify(parsed, null, 2), "utf-8");
+      }
+      console.log(`  🌱 Auto-seed: ${autoSeed} → ${options.sourcePath}`);
+    } catch (e: any) {
+      console.warn(`  ⚠ Could not write seed to source file: ${e.message}`);
+    }
+  }
+  const contentSeed = result.seed ?? options.seed ?? 0;
+  result = { ...result, seed: contentSeed };
+
   // Step 0: Resolve includes (pre-compile referenced .md files to JSON with accurate durations)
   result = await resolveIncludes(result, options);
 
@@ -1012,15 +983,12 @@ export async function resolveAll(
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
 
   // Step 3: Generate images/videos from prompts before probing durations.
-  // Use root.seed if set; otherwise inherit from options (for includes).
-  // Auto-generate a random seed so {seed} in the CLI template always gets a value.
-  const generationSeed = result.seed ?? options.seed ?? Math.floor(Math.random() * 2_147_483_647);
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,
       ttiCli: options.ttiCli,
       ttvCli: options.ttvCli,
-      seed: generationSeed,
+      seed: contentSeed,
     });
   }
 

package/src/player/browser.tsx

@@ -165,6 +165,11 @@ function PlayerApp() {
   const durationInSeconds = data ? (getDurationInSeconds(data, true) || 5) : 5;
   const durationInFrames = Math.max(1, Math.ceil(durationInSeconds * fps));
 
+  // Memoize inputProps to avoid Remotion Player composition restart on every render.
+  // Without memoization, inputProps creates a new object reference on each render,
+  // causing ~10 composition restarts/sec (audio nodes remount → audio jumps back).
+  const inputProps = React.useMemo(() => ({ root: data, compose: {} }), [data]);
+
   // ── Load data (does NOT set ready=false to avoid player unmount) ─────
   const loadData = React.useCallback((initial = false) => {
     if (initial) setReady(false);
@@ -446,7 +451,7 @@ function PlayerApp() {
         <Player
           ref={playerRef}
           component={MarkCut}
-          inputProps={{ root: data, compose: {} }}
+          inputProps={inputProps}
           durationInFrames={durationInFrames}
           fps={fps}
           compositionWidth={width}

package/src/player/bundle/player.js

@@ -45998,9 +45998,9 @@ function SubtitleOverlay({ subtitle }) {
       finish();
     };
   }, [subtitle.src]);
+  const cueGroups = React46.useMemo(() => cues ? groupConsecutiveCues(cues) : [], [cues]);
   if (!cues) return null;
   const boxCss = subtitle.style ? cssJS(subtitle.style) : {};
-  const cueGroups = React46.useMemo(() => groupConsecutiveCues(cues), [cues]);
   return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)("div", { className: `${subtitle.type || "default"} subtitle-overlay`, style: { ...DEFAULT_BOX_STYLE, ...boxCss }, children: cueGroups.map((group, gi) => /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(
     CueFrame,
     {
@@ -60558,6 +60558,7 @@ function PlayerApp() {
   const fps = data2?.fps ?? 30;
   const durationInSeconds = data2 ? getDurationInSeconds(data2, true) || 5 : 5;
   const durationInFrames = Math.max(1, Math.ceil(durationInSeconds * fps));
+  const inputProps = React55.useMemo(() => ({ root: data2, compose: {} }), [data2]);
   const loadData = React55.useCallback((initial = false) => {
     if (initial) setReady(false);
     const variant = window.VARIANT || "default";
@@ -60793,7 +60794,7 @@ function PlayerApp() {
           {
             ref: playerRef,
             component: MarkCut,
-            inputProps: { root: data2, compose: {} },
+            inputProps,
             durationInFrames,
             fps,
             compositionWidth: width,

package/src/player/pipeline.mjs

@@ -964,7 +964,7 @@ init_compiler();
 
 // src/descriptive/resolve.ts
 import { execSync as execSync2 } from "node:child_process";
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, dirname as dirname2, resolve as resolvePath, relative } from "node:path";
 
@@ -985,7 +985,7 @@ var args = (function parseArgs(argv) {
     "--tti": "tti",
     "--ttv": "ttv"
   };
-  const args2 = { 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 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: {} };
   let i = 2;
   if (argv[i]) args2.command = argv[i++];
   if (argv[i] && !argv[i].startsWith("--")) args2.file = argv[i++];
@@ -999,6 +999,7 @@ var args = (function parseArgs(argv) {
     else if (flag === "--compile") args2.compile = true;
     else if (flag === "--force-new") args2.forceNew = true;
     else if (flag === "--verbose") args2.verbose = true;
+    else if (flag === "--dev") args2.dev = true;
     else if (flag === "--label") args2.label = true;
     else if (flag === "--edit") args2.edit = true;
     else if (flag === "--no-browser") args2.noBrowser = true;
@@ -1022,7 +1023,7 @@ var DEFAULT_STT_CLI = args.cliOverrides.stt || process.env.MARKCUT_STT_CLI || 'u
 var DEFAULT_TTS_CLI = args.cliOverrides.tts || process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
 var DEFAULT_AGENT_CLI = args.cliOverrides.agent || process.env.MARKCUT_AGENT_CLI || "npx pi -p {prompt}";
 var DEFAULT_EDIT_CLI = args.cliOverrides.editCli || process.env.MARKCUT_EDIT_CLI || "npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}";
-var DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
+var DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 2 --prompt "{input}" --output "{output}" --seed {seed}';
 var DEFAULT_TTV_CLI = args.cliOverrides.ttv || process.env.MARKCUT_TTV_CLI || "";
 var DEFAULT_ITT_CLI = args.cliOverrides.itt || process.env.MARKCUT_ITT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';
 var DEFAULT_VTT_CLI = args.cliOverrides.vtt || process.env.MARKCUT_VTT_CLI || `uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs '{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}'`;
@@ -10133,6 +10134,7 @@ function preserveVariantAttrs(node2, attrs) {
     "duration",
     "startFrom",
     "endAt",
+    "loop",
     "width",
     "height",
     "fit",
@@ -10645,31 +10647,6 @@ function computeCacheKey(parts) {
   const json = JSON.stringify(parts);
   return createHash("sha1").update(json).digest("hex").slice(0, 12);
 }
-function readCacheManifest(outputDir) {
-  const manifestPath = join(outputDir, ".cache.json");
-  try {
-    return JSON.parse(readFileSync(manifestPath, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function writeCacheManifest(outputDir, manifest) {
-  const manifestPath = join(outputDir, ".cache.json");
-  try {
-    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
-  } catch {
-  }
-}
-function checkCache(manifest, key, cacheKey) {
-  const entry = manifest[key];
-  if (entry?.hash === cacheKey && entry.output && existsSync2(entry.output)) {
-    return entry.output;
-  }
-  return null;
-}
-function updateCache(manifest, key, cacheKey, output) {
-  manifest[key] = { hash: cacheKey, output };
-}
 function firstWords(text3, n) {
   if (!text3) return "";
   return text3.split(/\s+/).slice(0, n).join(" ").replace(/[^a-zA-Z0-9\u4e00-\u9fff\s-]/g, "").slice(0, 60) || text3.slice(0, 60);
@@ -10833,8 +10810,6 @@ function resolveDialogue(root) {
 async function resolveScripts(root, options) {
   const clone = JSON.parse(JSON.stringify(root));
   mkdirSync2(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
   const allScriptNodes = [];
   walkDown(clone, (node2) => {
     if (node2.type !== "audio") return;
@@ -10843,10 +10818,15 @@ async function resolveScripts(root, options) {
     const id = node2.id ?? `audio-${allScriptNodes.length}`;
     allScriptNodes.push({ node: node2, id });
   });
-  if (allScriptNodes.length > 0) {
-    console.log(`  \u{1F50A} 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(`  \u{1F50A} TTS: generating ${totalScripts} script${totalScripts > 1 ? "s" : ""}...`);
   }
   for (const { node: node2, id } of allScriptNodes) {
+    scriptsDone++;
     let ttsCli = clone.tts ?? options.ttsCli ?? DEFAULT_TTS_CLI;
     if (node2.speaker && clone.voices) {
       const speakerVoice = clone.voices[node2.speaker];
@@ -10856,19 +10836,18 @@ async function resolveScripts(root, options) {
     }
     const cacheKey = computeCacheKey({ script: node2.script, cli: ttsCli });
     const audioPath = join(options.outputDir, `${cacheKey}.mp3`);
-    const cached = checkCache(cache, `tts:${cacheKey}`, cacheKey);
     let generated;
     const speakerLabel = node2.speaker ? `${node2.speaker}: ` : "";
     const label = `${speakerLabel}${firstWords(node2.script, 8)}`;
-    if (cached) {
-      generated = cached;
+    if (existsSync2(audioPath)) {
+      generated = audioPath;
+      cacheHits++;
       console.log(`  \u2713 TTS: ${label} (cached)`);
     } else {
+      console.log(`  \u{1F50A} TTS (${scriptsDone}/${totalScripts}): ${label}...`);
       generated = generateTTS(node2.script, audioPath, ttsCli);
       if (generated) {
-        updateCache(cache, `tts:${cacheKey}`, cacheKey, generated);
-        cacheDirty = true;
-        console.log(`  \u2713 TTS: ${label}`);
+        console.log(`  \u2713 TTS (${scriptsDone}/${totalScripts}): ${label}`);
       } else {
         console.warn(`  \u26A0 TTS produced no audio for "${label}". Audio will have no source. Check root.tts config.`);
       }
@@ -10877,14 +10856,10 @@ async function resolveScripts(root, options) {
     node2.src = resolvePath(generated);
     delete node2.script;
   }
-  if (cacheDirty) writeCacheManifest(options.outputDir, cache);
-  if (allScriptNodes.length > 0) {
-    try {
-      writeFileSync(join(options.outputDir, ".cache.json"), JSON.stringify(cache, null, 2), "utf-8");
-    } catch {
-    }
+  if (totalScripts > 0) {
+    const ttsElapsed = Math.round((Date.now() - ttsStart) / 1e3);
     const unique = new Set(allScriptNodes.filter((s) => s.node.src).map((s) => s.node.src)).size;
-    console.log(`  \u2705 TTS: ${unique} unique audio file${unique > 1 ? "s" : ""} (${allScriptNodes.length} node${allScriptNodes.length > 1 ? "s" : ""})`);
+    console.log(`  \u2705 TTS: ${unique} unique audio${unique > 1 ? "s" : ""} (${scriptsDone} nodes) in ${ttsElapsed}s (${cacheHits} cached)`);
   }
   return clone;
 }
@@ -10893,8 +10868,6 @@ async function resolveSubtitles(root, options) {
   const sttCli = clone.stt ?? options.sttCli ?? DEFAULT_STT_CLI;
   if (!sttCli) return clone;
   mkdirSync2(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
   const clips = [];
   function walkSiblings(nodes, parentOffset, parentIsSeries, parentTransition, parentTransitionTime) {
     let seriesOffset = parentOffset;
@@ -10943,22 +10916,20 @@ async function resolveSubtitles(root, options) {
   for (const { audioSrc, offset, speaker } of clips) {
     const audioHash = existsSync2(audioSrc) ? createHash("sha1").update(readFileSync(audioSrc)).digest("hex").slice(0, 12) : audioSrc;
     const sttCacheKey = computeCacheKey({ audioHash, cli: sttCli });
-    const sttKey = `stt:${audioSrc.split("/").pop()}`;
     const clipName = audioSrc.split("/").pop();
+    const expectedVtt = join(options.outputDir, `${sttCacheKey}.vtt`);
     let vttPath = null;
-    const cachedVtt = checkCache(cache, sttKey, sttCacheKey);
-    if (cachedVtt) {
-      vttPath = cachedVtt;
+    if (existsSync2(expectedVtt)) {
+      vttPath = expectedVtt;
     } else {
       try {
         await generateSTT(audioSrc, options.outputDir, sttCli);
         const base = audioSrc.replace(/\.wav$/, "").replace(/\.mp3$/, "");
         const name = base.split("/").pop();
-        const candidate = join(options.outputDir, `${name}.vtt`);
-        if (existsSync2(candidate)) {
-          vttPath = candidate;
-          updateCache(cache, sttKey, sttCacheKey, vttPath);
-          cacheDirty = true;
+        const whisperVtt = join(options.outputDir, `${name}.vtt`);
+        if (existsSync2(whisperVtt)) {
+          renameSync(whisperVtt, expectedVtt);
+          vttPath = expectedVtt;
         }
       } catch {
         console.warn(`  \u26A0 STT failed for ${clipName}. Install whisper (pip install openai-whisper) or set root.stt.`);
@@ -11008,14 +10979,11 @@ async function resolveSubtitles(root, options) {
     clone.subtitle = { ...clone.subtitle ?? {}, src: mergedPath };
     console.log(`  \u2705 STT: subtitles ready (${cueIndex - 1} cues)`);
   }
-  if (cacheDirty) writeCacheManifest(options.outputDir, cache);
   return clone;
 }
 async function resolveGeneratedMedia(root, options) {
   const clone = JSON.parse(JSON.stringify(root));
   mkdirSync2(options.outputDir, { recursive: true });
-  const cache = readCacheManifest(options.outputDir);
-  let cacheDirty = false;
   const genNodes = [];
   walkDown(clone, (node2) => {
     if (node2.type !== "image" && node2.type !== "video") return;
@@ -11024,29 +10992,44 @@ async function resolveGeneratedMedia(root, options) {
     const id = node2.id ?? `${node2.type}-${genNodes.length}`;
     genNodes.push({ node: node2, id, type: node2.type, prompt: node2.prompt });
   });
+  const total = genNodes.length;
+  let done = 0;
+  let cacheHits = 0;
+  const startTime = Date.now();
+  function progressLine() {
+    const elapsed = (Date.now() - startTime) / 1e3;
+    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(`  \u{1F3A8} Generating ${total} media item${total > 1 ? "s" : ""}...`);
+  }
   for (const { node: node2, id, type, prompt } of genNodes) {
+    done++;
     const ext = type === "image" ? "png" : "mp4";
     const cli = type === "image" ? clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI : clone.ttv ?? options.ttvCli ?? DEFAULT_TTV_CLI;
     const seed = options.seed;
     const cacheKey = computeCacheKey({ prompt, cli, type, seed });
     const outputPath = join(options.outputDir, `${cacheKey}.${ext}`);
-    const cached = checkCache(cache, `gen:${cacheKey}`, cacheKey);
     const label = type === "image" ? "TTI" : "TTV";
     const labelText = firstWords(prompt, 8);
-    if (cached) {
-      node2.src = resolvePath(cached);
-      console.log(`  \u2713 ${label}: ${labelText} (cached)`);
+    if (existsSync2(outputPath)) {
+      node2.src = resolvePath(outputPath);
+      cacheHits++;
+      if (done % 5 === 0 || done === total) console.log(progressLine());
       continue;
     }
     try {
-      console.log(`  \u{1F50A} ${label}: ${labelText}...`);
+      console.log(`  \u{1F50A} ${label} (${done}/${total}): ${labelText}...`);
       const ttiCmd = clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI;
       const result = type === "image" ? generateTTI(prompt, outputPath, cli, seed) : generateTTV(prompt, outputPath, cli, ttiCmd, seed);
       if (result) {
         node2.src = outputPath;
-        updateCache(cache, `gen:${cacheKey}`, cacheKey, outputPath);
-        cacheDirty = true;
-        console.log(`  \u2713 ${label}: ${labelText}`);
+        console.log(`  \u2713 ${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 \u2014 set root.${type === "image" ? "tti" : "ttv"} to a real generation command.` : `The command ran but produced no output file. Check the CLI template or run the script manually to debug.`;
         console.error(`  \u26A0 ${label}: "${labelText}" produced no output. ${hint}`);
@@ -11056,7 +11039,11 @@ async function resolveGeneratedMedia(root, options) {
       console.error(`  \u2717 ${label}: "${labelText}" failed \u2014 ${err.message}. ${hint}`);
     }
   }
-  if (cacheDirty) writeCacheManifest(options.outputDir, cache);
+  if (total > 0) {
+    const elapsed = Math.round((Date.now() - startTime) / 1e3);
+    const mediaType = genNodes[0]?.type === "video" ? "TTV" : "TTI";
+    console.log(`  \u2705 ${mediaType} complete: ${done} items in ${elapsed}s (${cacheHits} cached)`);
+  }
   return clone;
 }
 async function resolveIncludes(root, options = {}) {
@@ -11142,6 +11129,30 @@ async function resolveIncludes(root, options = {}) {
 }
 async function resolveAll2(root, options = {}) {
   let result = root;
+  if (result.seed == null && options.seed == null && options.sourcePath) {
+    const autoSeed = parseInt(computeCacheKey(result).slice(0, 8), 16);
+    result = { ...result, seed: autoSeed };
+    try {
+      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);
+        lines.splice(insertAt, 0, `seed:${autoSeed}`);
+        writeFileSync(options.sourcePath, lines.join("\n"), "utf-8");
+      } else if (options.sourcePath.endsWith(".json")) {
+        const parsed = JSON.parse(raw);
+        const target = parsed.root || parsed;
+        target.seed = autoSeed;
+        writeFileSync(options.sourcePath, JSON.stringify(parsed, null, 2), "utf-8");
+      }
+      console.log(`  \u{1F331} Auto-seed: ${autoSeed} \u2192 ${options.sourcePath}`);
+    } catch (e) {
+      console.warn(`  \u26A0 Could not write seed to source file: ${e.message}`);
+    }
+  }
+  const contentSeed = result.seed ?? options.seed ?? 0;
+  result = { ...result, seed: contentSeed };
   result = await resolveIncludes(result, options);
   const { resolveAllTemplateVars: resolveAllTemplateVars2 } = await Promise.resolve().then(() => (init_compiler(), compiler_exports));
   result = resolveAllTemplateVars2(result, {
@@ -11151,13 +11162,12 @@ async function resolveAll2(root, options = {}) {
     variant: options.variants?.[0] ?? "video"
   });
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
-  const generationSeed = result.seed ?? options.seed ?? Math.floor(Math.random() * 2147483647);
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,
       ttiCli: options.ttiCli,
       ttvCli: options.ttvCli,
-      seed: generationSeed
+      seed: contentSeed
     });
   }
   result = await resolveMediaDurations(result, {
@@ -11201,6 +11211,7 @@ function isDescriptiveRoot(data) {
 }
 async function resolveAndCompile(data, options = {}) {
   const resolved = await resolveAll2(data, {
+    sourcePath: options.sourcePath,
     baseDir: options.baseDir,
     scriptOutputDir: options.scriptOutputDir,
     mediaOutputDir: options.mediaOutputDir,

package/src/player/pipeline.ts

@@ -42,6 +42,9 @@ export interface ResolveAndCompileOptions {
   /** Variant chain to apply to include nodes (e.g. ["zh", "tiktok"]).
    *  When set, included .md files are parsed with variant awareness. */
   variants?: string[];
+  /** 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;
 }
 
 /**
@@ -86,6 +89,7 @@ export async function resolveAndCompile(
 ): Promise<Root> {
   // 1. Async resolve: durations, TTS, STT, includes
   const resolved = await resolveAll(data, {
+    sourcePath: options.sourcePath,
     baseDir: options.baseDir,
     scriptOutputDir: options.scriptOutputDir,
     mediaOutputDir: options.mediaOutputDir,

package/src/player/server.mjs

@@ -436,6 +436,7 @@ async function compileVariant(config, parsed, raw) {
     console.log(`  📝 Variant "${config.label}": resolving...`);
     const { resolveAll, compileDescriptiveRoot } = await import("./pipeline.mjs");
     const resolved = await resolveAll(descriptive, {
+      sourcePath: VIDEO_JSON,
       baseDir: dirname(VIDEO_JSON),
       scriptOutputDir: TTS_OUTPUT_DIR,
       mediaOutputDir: MEDIA_OUTPUT_DIR,
@@ -458,6 +459,7 @@ async function compileVariant(config, parsed, raw) {
 
       console.log(`  📝 Variant "${config.label}": resolving...`);
       compiled = await resolveAndCompile(descriptive, {
+        sourcePath: VIDEO_JSON,
         baseDir: dirname(VIDEO_JSON),
         scriptOutputDir: TTS_OUTPUT_DIR,
         mediaOutputDir: MEDIA_OUTPUT_DIR,
@@ -1007,7 +1009,7 @@ Edit request: ${text}`;
       }
       req.on("close", () => {
         sseClients.delete(res);
-        if (MODE_EDIT && sseClients.size === 0) {
+        if (sseClients.size === 0) {
           shutdownTimer = setTimeout(() => {
             console.error("\n  🚪 Browser tab closed — shutting down\n");
             process.exit(0);

package/src/render/cli.mjs

@@ -317,6 +317,7 @@ edit=${DEFAULT_EDIT_CLI}`);
         const fileDir = dirname(filePath);
         const parsed = parseMarkdownVariants(raw);
         streamTree = await resolveWithVariants(parsed.base, {
+          sourcePath: filePath,
           baseDir: fileDir,
           scriptOutputDir: generatedDir(filePath, "tts"),
           mediaOutputDir: generatedDir(filePath, "media"),
@@ -330,6 +331,7 @@ edit=${DEFAULT_EDIT_CLI}`);
         if (isDescriptiveRoot(root)) {
           const fileDir = dirname(filePath);
           streamTree = await resolveAndCompile(root, {
+            sourcePath: filePath,
             baseDir: fileDir,
             scriptOutputDir: generatedDir(filePath, "tts"),
             mediaOutputDir: generatedDir(filePath, "media"),
@@ -518,6 +520,7 @@ function hasScript(root) {
 
     const baseDir = dirname(filePath);
     const baseOpts = {
+      sourcePath: filePath,
       baseDir,
       scriptOutputDir: args.scriptOutputDir || join(baseDir, "assets", "tts"),
       mediaOutputDir: args.mediaOutputDir || join(baseDir, "assets", "media"),

package/src/types/Subtitle.tsx

@@ -288,13 +288,14 @@ export function SubtitleOverlay({ subtitle }: { subtitle: SubtitleOverlayConfig
     };
   }, [subtitle.src]);
 
-  if (!cues) return null;@
-
-  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.
-  const cueGroups = React.useMemo(() => groupConsecutiveCues(cues), [cues]);
+  // Must be called unconditionally (before early return) to keep hooks order stable.
+  const cueGroups = React.useMemo(() => cues ? groupConsecutiveCues(cues) : [], [cues]);
+
+  if (!cues) return null;
+
+  const boxCss = subtitle.style ? (cssJS(subtitle.style) as React.CSSProperties) : {};
 
   return (
     <div className={`${subtitle.type || "default"} subtitle-overlay`} style={{ ...DEFAULT_BOX_STYLE, ...boxCss }}>