@lalalic/markcut 2.8.0 → 3.0.0

package/src/player/server.mjs

@@ -4,7 +4,7 @@
  *
  * Modes:
  *   --label   – playback with label input overlay; labels map to media timestamps
- *   --edit    – auto-reload when the JSON file changes (agent edits file, player refreshes)
+ *   --edit    – edit input mode with AI-assisted changes
  *
  * Usage:
  *   node src/player/server.mjs <video.json> [--label] [--edit] [--port 3001]
@@ -17,7 +17,7 @@ import { fileURLToPath } from "node:url";
 import { isDescriptiveRoot, resolveAndCompile, resolveAndCompileMarkdown, parseImportsBlock, extractDependencySpecs } from "./pipeline.mjs";
 import { bundleFromEntries } from "./bundler.mjs";
 import { extractScenes, MIME, serveFile, handleShutdown } from "./server-shared.mjs";
-import { DEFAULT_EDIT_CLI } from "../config.mjs";
+import { DEFAULT_EDIT_CLI, DEFAULT_STT_CLI, GOOGLE_MAPS_API_KEY } from "../config.mjs";
 
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -79,6 +79,14 @@ const VARIANT_CONFIGS = parseVariantConfigs();
 const sseClients = new Set();
 let shutdownTimer = null;
 
+/** Push a JSON event to all connected SSE clients. */
+function ssePush(data) {
+  const text = `data: ${JSON.stringify(data)}\n\n`;
+  for (const client of sseClients) {
+    try { client.write(text); } catch { sseClients.delete(client); }
+  }
+}
+
 // ─── Label store for label mode ───────────────────────────────────────────
 let labels = [];
 
@@ -128,16 +136,24 @@ function handleAgentLine(obj) {
   const t = obj.type;
   if (t === "message_end") {
     const txt = extractAssistantText(obj.message);
-    if (txt) agentTurnText += (agentTurnText ? "\n" : "") + txt;
+    if (txt) {
+      agentTurnText += (agentTurnText ? "\n" : "") + txt;
+      // Push incremental assistant text to SSE clients
+      ssePush({ type: "edit:progress", text: agentTurnText });
+    }
     return;
   }
   if (t === "agent_settled" && pendingEditResolver) {
+    ssePush({ type: "edit:done", summary: agentTurnText.substring(0, 120) });
     finishAgentTurn({ ok: true });
     return;
   }
   if (t === "response" && obj.command === "prompt" && pendingEditResolver) {
     // Preflight result: success means "accepted, events incoming"; failure aborts.
-    if (obj.success === false) finishAgentTurn({ ok: false, error: obj.error || "prompt rejected" });
+    if (obj.success === false) {
+      ssePush({ type: "edit:error", error: obj.error || "prompt rejected" });
+      finishAgentTurn({ ok: false, error: obj.error || "prompt rejected" });
+    }
     return;
   }
   if (t === "extension_error" && obj.error) {
@@ -447,11 +463,14 @@ async function compileVariant(config, parsed, raw) {
       scriptOutputDir: TTS_OUTPUT_DIR,
       mediaOutputDir: MEDIA_OUTPUT_DIR,
       includeOutputDir: INCLUDE_CACHE_DIR,
+      sttCli: DEFAULT_STT_CLI,
       subtitleOutputDir: subtitleDir,
       storyboard: MODE_STORYBOARD,
       variants: config.chain.length > 0 ? config.chain : undefined,
     });
-    compiled = compileDescriptiveRoot(resolved);
+    compiled = compileDescriptiveRoot(resolved, {
+      googleMapsApiKey: GOOGLE_MAPS_API_KEY || "",
+    });
   } else {
     const parsedJson = JSON.parse(raw);
     const root = parsedJson.root || parsedJson;
@@ -471,6 +490,7 @@ async function compileVariant(config, parsed, raw) {
         scriptOutputDir: TTS_OUTPUT_DIR,
         mediaOutputDir: MEDIA_OUTPUT_DIR,
         includeOutputDir: INCLUDE_CACHE_DIR,
+        sttCli: DEFAULT_STT_CLI,
         subtitleOutputDir: subtitleDir,
         storyboard: MODE_STORYBOARD,
         variants: config.chain.length > 0 ? config.chain : undefined,
@@ -667,40 +687,36 @@ function getScenes(label) {
 // Will be awaited before announcing "Player ready"
 const initScenesPromise = compileAndExtractScenes();
 
-// ─── Watch file for changes (--edit mode) ───────────────────────────────
-if (MODE_EDIT) {
-  let lastContent = readFileSync(VIDEO_JSON, "utf-8");
-  watchFile(VIDEO_JSON, { interval: 1000 }, async (curr, prev) => {
-    if (curr.mtimeMs === prev.mtimeMs) return;
-    if (pipelineRunning) return;
-    const newContent = readFileSync(VIDEO_JSON, "utf-8");
-    if (newContent === lastContent) return;
-    lastContent = newContent;
-    pipelineRunning = true;
-    console.log(`  📁 ${VIDEO_JSON} changed, re-running all variants...`);
+// ─── Watch source file for changes (all modes) ──────────────────────────
+let lastContent = readFileSync(VIDEO_JSON, "utf-8");
+watchFile(VIDEO_JSON, { interval: 1000 }, async (curr, prev) => {
+  if (curr.mtimeMs === prev.mtimeMs) return;
+  if (pipelineRunning) return;
+  const newContent = readFileSync(VIDEO_JSON, "utf-8");
+  if (newContent === lastContent) return;
+  lastContent = newContent;
+  pipelineRunning = true;
+  console.log(`  📁 ${VIDEO_JSON} changed, re-running all variants...`);
 
-    try {
-      compiledRootCache.clear();
-      scenesCache.clear();
-      await compileAllVariants();
-
-      for (const config of VARIANT_CONFIGS) {
-        try {
-          const root = await loadCompiledRoot(config.label);
-          scenesCache.set(config.label, extractScenes(root));
-        } catch {}
-      }
+  try {
+    compiledRootCache.clear();
+    scenesCache.clear();
+    await compileAllVariants();
 
-      for (const client of sseClients) {
-        client.write("data: " + JSON.stringify({ type: "reload" }) + "\n\n");
-      }
-    } catch (e) {
-      console.error("  ⚠️  Failed to re-process after change:", e.message);
-    } finally {
-      pipelineRunning = false;
+    for (const config of VARIANT_CONFIGS) {
+      try {
+        const root = await loadCompiledRoot(config.label);
+        scenesCache.set(config.label, extractScenes(root));
+      } catch {}
     }
-  });
-}
+
+    ssePush({ type: "reload" });
+  } catch (e) {
+    console.error("  ⚠️  Failed to re-process after change:", e.message);
+  } finally {
+    pipelineRunning = false;
+  }
+});
 // ─── MIME imported from ./server-shared.mjs ──────────────────────────────
 
 // ─── Variant detection from URL path ─────────────────────────────────────
@@ -762,7 +778,7 @@ function getHtml(variantLabel) {
   html, body { width: 100%; height: 100%; overflow: hidden; background: #0a0a0a; }
   body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; display: flex; flex-direction: column; align-items: center; }
   #header { display: flex; align-items: center; justify-content: flex-end; width: 100%; max-width: 500px; padding: 8px 12px; flex-shrink: 0; gap: 8px; }
-  #header-status, #edit-status { font-size: 11px; color: rgba(255,255,255,.4); flex: 1; text-align: left; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  #header-status { font-size: 11px; color: rgba(255,255,255,.4); flex: 1; text-align: left; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
   #scene-info { font-size: 11px; color: rgba(255,255,255,.4); flex: 1; text-align: left; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
   #header-actions { display: flex; gap: 6px; align-items: center; flex-shrink: 0; }
   #close-btn { width: 22px; height: 22px; border-radius: 50%; border: 1px solid rgba(255,255,255,.15); background: rgba(0,0,0,.3); color: rgba(255,255,255,.4); font-size: 10px; cursor: pointer; display: flex; align-items: center; justify-content: center; transition: all .15s; }
@@ -771,7 +787,7 @@ function getHtml(variantLabel) {
   .variant-link { font-size: 11px; padding: 3px 10px; border-radius: 12px; background: rgba(255,255,255,.06); color: rgba(255,255,255,.4); text-decoration: none; white-space: nowrap; transition: all .15s; }
   .variant-link:hover { background: rgba(255,255,255,.12); color: rgba(255,255,255,.7); }
   .variant-link.active { background: rgba(74,158,255,.2); color: #4a9eff; }
-  #player-frame { flex: 1; width: 100%; max-width: 480px; min-height: 0; border-radius: 16px; overflow: hidden; border: 1px solid rgba(255,255,255,.08); background: #000; box-shadow: 0 4px 40px rgba(0,0,0,.6); margin: 0 12px; }
+  #player-frame { flex: 1; width: 100%; max-width: 480px; min-height: 0; border-radius: 16px; overflow: hidden; border: 1px solid rgba(255,255,255,.08); background: #000; box-shadow: 0 4px 40px rgba(0,0,0,.6); margin: 0 12px; position: relative; }
   #root { width: 100%; height: 100%; }
   #reload-toast { position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: rgba(74,158,255,.9); color: #fff; padding: 12px 24px; border-radius: 10px; font-size: 14px; font-weight: 600; opacity: 0; transition: opacity .3s; pointer-events: none; z-index: 200; backdrop-filter: blur(8px); }
   #reload-toast.show { opacity: 1; }
@@ -805,6 +821,136 @@ function getHtml(variantLabel) {
   .scene-pill { flex-shrink: 0; padding: 4px 12px; border-radius: 12px; cursor: pointer; border: 1px solid transparent; transition: all .15s; background: rgba(255,255,255,.06); color: rgba(255,255,255,.45); font-size: 11px; white-space: nowrap; }
   .scene-pill:hover { border-color: rgba(74,158,255,.4); color: rgba(255,255,255,.7); }
   .scene-pill.active { background: rgba(74,158,255,.2); border-color: #4a9eff; color: #4a9eff; }
+
+  .subtitle-overlay>*{width:100%}
+
+  /* ── Edit message panel ───────────────────────────────────────────── */
+  #edit-message-overlay {
+    position: absolute;
+    left: 8px;
+    right: 8px;
+    top: 8px;
+    z-index: 30;
+    pointer-events: none;
+  }
+  #edit-message-panel {
+    width: 100%;
+    max-width: 100%;
+    flex-shrink: 0;
+    background: rgba(12,12,12,.78);
+    border: 1px solid rgba(255,255,255,.08);
+    border-radius: 10px;
+    margin: 0;
+    overflow: hidden;
+    backdrop-filter: blur(8px);
+    pointer-events: auto;
+  }
+  #edit-message-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 6px 10px;
+    font-size: 11px;
+    color: rgba(255,255,255,.5);
+    border-bottom: 1px solid rgba(255,255,255,.06);
+  }
+  #edit-message-minimize {
+    width: 20px;
+    height: 20px;
+    padding: 0;
+    background: rgba(255,255,255,.06);
+    color: rgba(255,255,255,.4);
+    border: 1px solid rgba(255,255,255,.1);
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 10px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all .15s;
+  }
+  #edit-message-minimize:hover {
+    background: rgba(74,158,255,.2);
+    border-color: rgba(74,158,255,.4);
+    color: #4a9eff;
+  }
+  #edit-message-list {
+    max-height: 150px;
+    overflow-y: auto;
+    padding: 6px 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    scrollbar-width: thin;
+  }
+  #edit-message-list::-webkit-scrollbar { width: 4px; }
+  #edit-message-list::-webkit-scrollbar-thumb { background: rgba(255,255,255,.15); border-radius: 2px; }
+  .edit-message-empty {
+    font-size: 11px;
+    color: rgba(255,255,255,.25);
+    padding: 8px 0;
+    text-align: center;
+  }
+  .edit-message-entry {
+    font-size: 11px;
+    line-height: 1.5;
+    padding: 4px 6px;
+    border-radius: 6px;
+    background: rgba(255,255,255,.03);
+  }
+  .edit-message-entry.error {
+    background: rgba(255,60,60,.08);
+  }
+  .edit-role {
+    font-weight: 600;
+    color: rgba(255,255,255,.5);
+    margin-right: 4px;
+  }
+  .edit-message-request {
+    color: rgba(255,255,255,.6);
+  }
+  .edit-message-thinking {
+    color: rgba(74,158,255,.7);
+  }
+  .edit-dots span {
+    animation: editDotPulse 1.4s infinite;
+    opacity: 0;
+  }
+  .edit-dots span:nth-child(1) { animation-delay: 0s; }
+  .edit-dots span:nth-child(2) { animation-delay: 0.2s; }
+  .edit-dots span:nth-child(3) { animation-delay: 0.4s; }
+  @keyframes editDotPulse {
+    0%   { opacity: 0; }
+    50%  { opacity: 1; }
+    100% { opacity: 0; }
+  }
+  .edit-message-response {
+    color: rgba(74,222,128,.8);
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+  .edit-message-error {
+    color: rgba(255,100,100,.8);
+  }
+  #edit-message-bar {
+    display: block;
+    width: auto;
+    padding: 4px 12px;
+    margin: 4px 12px;
+    border-radius: 14px;
+    border: 1px solid rgba(255,255,255,.1);
+    background: rgba(74,158,255,.12);
+    color: rgba(74,158,255,.8);
+    font-size: 11px;
+    cursor: pointer;
+    transition: all .15s;
+    flex-shrink: 0;
+    white-space: nowrap;
+  }
+  #edit-message-bar:hover {
+    background: rgba(74,158,255,.2);
+    border-color: rgba(74,158,255,.4);
+  }
 </style>
 </head>
 <body>
@@ -963,6 +1109,9 @@ Edit request: ${text}`;
 
           console.log(`  🤖 edit: ${text}  (${currentTime !== undefined ? currentTime.toFixed(1) + "s" : ""} ${activeScene || ""})`);
 
+          // Push start event to SSE clients for real-time UI feedback
+          ssePush({ type: "edit:start", request: text });
+
           // Send to the persistent rpc agent (one cold start; conversation kept in memory)
           const result = await sendToAgent(userPrompt);
 
@@ -988,10 +1137,12 @@ Edit request: ${text}`;
           } else {
             const msg = result.error || "failed";
             console.error(`  ❌ edit ${msg}: ${(result.output || "").trim().substring(0, 100)}`);
+            ssePush({ type: "edit:error", error: msg });
             res.writeHead(500, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ error: msg, output: (result.output || "").trim().substring(0, 200) }));
           }
         } catch (e) {
+          ssePush({ type: "edit:error", error: e.message });
           res.writeHead(500, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: e.message }));
         }
@@ -1032,7 +1183,10 @@ Edit request: ${text}`;
       try {
         const root = await loadCompiledRoot(variantLabel);
         const rootOut = resolveAssetPaths(root);
-        res.writeHead(200, { "Content-Type": "application/json" });
+        res.writeHead(200, {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-store",
+        });
         res.end(JSON.stringify(rootOut));
       } catch (e) {
         res.writeHead(500, { "Content-Type": "application/json" });
@@ -1044,7 +1198,10 @@ Edit request: ${text}`;
     // API: Get scenes with media info for a specific variant
     if (path === "/api/scenes") {
       const { scenes, totalDuration } = getScenes(variantLabel);
-      res.writeHead(200, { "Content-Type": "application/json" });
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+      });
       res.end(JSON.stringify(scenes));
       return;
     }
@@ -1052,7 +1209,10 @@ Edit request: ${text}`;
     // API: Get current video info for a specific variant
     if (path === "/api/video-info") {
       const { scenes, totalDuration } = getScenes(variantLabel);
-      res.writeHead(200, { "Content-Type": "application/json" });
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+      });
       res.end(JSON.stringify({
         scenes,
         totalDuration,
@@ -1115,6 +1275,6 @@ server.listen(PORT, async () => {
       console.log(`   ${config.label}: ${url}`);
     }
   }
-  if (MODE_EDIT) console.log(`   Watching: ${VIDEO_JSON.split("/").pop()}`);
+  console.log(`   Watching: ${VIDEO_JSON.split("/").pop()}`);
   console.log("");
 });

package/src/render/cli.mjs

@@ -496,7 +496,7 @@ function hasScript(root) {
 
       // Compile to validate
       const compiled = compileDescriptiveRoot(descriptive);
-      emitSuccess(`Valid. Duration: ~${compiled.durationInSeconds ?? "?"}s, Scenes: ${compiled.children?.length ?? 0}`);
+      emitSuccess(`Valid`);
       process.exit(0);
 
     } catch (err) {

package/src/schema/index.ts

@@ -133,7 +133,7 @@ export type Image = z.infer<typeof image>;
 export const component = base.extend({
   type: z.literal("component").default("component"),
   jsx: z.string().describe("usage JSX expression compiled at runtime; tag names resolved from imports"),
-  data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe("extra variables (e.g. from ~~~md source code fences) available in JSX scope"),
+  data: z.record(z.string(), z.unknown()).optional().describe("extra variables (e.g. from ~~~md source code fences) available in JSX scope"),
 });
 export type Component = z.infer<typeof component>;
 
@@ -143,6 +143,7 @@ export type Component = z.infer<typeof component>;
 export const effect = base.extend({
   type: z.literal("effect").default("effect"),
   animation: z.string().optional().describe("builtin keyframe name or 'custom'"),
+  animationDurationSeconds: z.number().optional().describe("animation duration (separate from wrapper durationInSeconds which getDurationInSeconds may overwrite)"),
   animationTimingFunction: z
     .enum(["linear", "ease", "ease-in", "ease-out", "ease-in-out"])
     .optional(),
@@ -228,6 +229,8 @@ export const mapStream = base.extend({
   zoom: z.number().default(10),
   center: z.object({ lat: z.number(), lng: z.number() }).optional().describe("map view center (defaults to first waypoint)"),
   mapType: z.enum(["roadmap", "satellite", "hybrid", "terrain"]).default("roadmap").describe("Google Maps style"),
+  language: z.string().optional().describe("Google Maps UI/label language, e.g. zh-CN"),
+  region: z.string().optional().describe("Google Maps region code, e.g. CN"),
   travelMode: z.enum(["DRIVING", "WALKING", "BICYCLING", "TRANSIT"]).default("DRIVING").describe("Directions API travel mode"),
   routeMarker: z.string().default("🚗").describe("emoji/character for the animated traveling marker"),
   googleMapsApiKey: z.string().optional().describe("injected by compiler from GOOGLE_MAPS_API_KEY env var"),

package/src/types/Component.tsx

@@ -72,7 +72,30 @@ export function ComponentLeaf({ stream }: { stream: Component }) {
     [stream.data, components, eventState],
   );
 
-  if (!stream.jsx) return null;
+  if (!stream.jsx) {
+    // Event-only stub: no JSX to render, but may fire events on `on`.
+    // Still needs EventAwareComponent for useFrameEvents to register
+    // and fire at the right frame.
+    const start = stream.start ?? 0;
+    const end = stream.end ?? start + (stream.duration ?? 1);
+    const durFrames = Math.max(1, Math.floor(fps * (end - start)));
+    return (
+      <Sequence
+        durationInFrames={durFrames}
+        from={Math.floor(fps * start)}
+        layout="none"
+      >
+        <EventAwareComponent
+          jsx=""
+          components={components}
+          data={bindings}
+          action={{ start, end }}
+          durFrames={durFrames}
+          on={stream.on}
+        />
+      </Sequence>
+    );
+  }
 
   const start = stream.start ?? 0;
   const end = stream.end ?? start + (stream.duration ?? 1);
@@ -118,6 +141,9 @@ function EventAwareComponent({
   // Fire events at the right frame for this node's timeline
   useFrameEvents(on, durFrames);
 
+  // If no JSX, this is an event-only stub — nothing to render
+  if (!jsx) return null;
+
   return (
     <TweenedJsxParser
       jsx={jsx}

package/src/types/Effect.tsx

@@ -34,17 +34,24 @@ export function EffectWrapper({
     const durationInFrames = end - start;
     if (durationInFrames <= 0) return [] as Record<string, string>[];
 
+    // Use animationDurationSeconds for animation timing when available
+    // (set by wrapWithEffects for background nodes where end is set to parent
+    //  duration but the animation spec duration is preserved separately).
+    const animDurationSec = stream.animationDurationSeconds ?? stream.durationInSeconds ?? (durationInFrames / fps);
+    const animDurationFrames = Math.ceil(animDurationSec * fps);
+
     const animation = stream.animation;
     const timingFn = stream.animationTimingFunction;
     const iterCount = stream.animationIterationCount ?? 1;
     const style = (cssJS(stream.style) ?? {}) as Record<string, string>;
 
-    // Handle iteration count: loop the animation within the span
+    // Handle iteration count: loop the animation within the span.
+    // The animation period is animDurationFrames (not the full span duration).
     let currentFrame = frame;
-    if (iterCount > 0 && durationInFrames > 0) {
-      const iteration = Math.floor((frame - start) / durationInFrames);
+    if (iterCount > 0 && animDurationFrames > 0) {
+      const iteration = Math.floor((frame - start) / animDurationFrames);
       if (iteration < iterCount) {
-        currentFrame = start + ((frame - start) % durationInFrames);
+        currentFrame = start + ((frame - start) % animDurationFrames);
       }
     }
 
@@ -56,7 +63,7 @@ export function EffectWrapper({
         if (config) {
           const animStyle = interpolateKeyframes(config, actionFrame, {
             fps,
-            durationInSeconds: durationInFrames / fps,
+            durationInSeconds: animDurationSec,
             timingFunction: timingFn,
           });
           if (animStyle) Object.assign(style, animStyle);
@@ -65,7 +72,7 @@ export function EffectWrapper({
     }
 
     return Object.keys(style).length > 0 ? [style] : [];
-  }, [frame, fps, startSec, endSec, stream.animation, stream.animationTimingFunction, stream.animationIterationCount, stream.customKeyframes, stream.style]);
+  }, [frame, fps, startSec, endSec, stream.animation, stream.animationTimingFunction, stream.animationIterationCount, stream.customKeyframes, stream.style, stream.animationDurationSeconds, stream.durationInSeconds]);
 
   if (styles.length === 0) return <>{children}</>;
 

package/src/types/Folder.tsx

@@ -62,7 +62,7 @@ export function FolderLeaf({ stream }: { stream: FolderStream }) {
   // Background children are rendered outside the series (parallel overlays),
   // so TransitionSeries doesn't reject the <Loop> wrapper.
   const bgChildren = visibleChildren.filter((c) => c.isBackground);
-  const seriesChildren = isSeries ? visibleChildren.filter((c) => !c.isBackground) : visibleChildren;
+  const seriesChildren = visibleChildren.filter((c) => !c.isBackground);
 
   // When all non-background series children are audio, skip transitions to
   // avoid audio overlap (both audio tracks play simultaneously during a fade).

package/src/types/Map.tsx

@@ -39,6 +39,15 @@ function resolveApiKey(stream: MapStream): string {
   return "";
 }
 
+function resolveMapLocale(language?: string, region?: string): { language?: string; region?: string } {
+  if (!language) return { language: undefined, region };
+  const lang = language.trim().toLowerCase();
+  if (lang === "zh") return { language: "zh-CN", region: region ?? "CN" };
+  if (lang === "en") return { language: "en", region: region ?? "US" };
+  if (lang.startsWith("zh-")) return { language, region: region ?? "CN" };
+  return { language, region };
+}
+
 // ============================================================
 // MapLeaf — entry point, renders each action as a Sequence
 // ============================================================
@@ -58,13 +67,53 @@ export function MapLeaf({ stream }: { stream: MapStream }) {
   const mapType = stream.mapType ?? "roadmap";
   const travelMode = stream.travelMode ?? "DRIVING";
   const markerEmoji = stream.routeMarker ?? "🚗";
+  const mapLocale = React.useMemo(
+    () => resolveMapLocale(stream.language, stream.region),
+    [stream.language, stream.region],
+  );
+  const mapLoadHandleRef = React.useRef<number | null>(null);
+  const mapLoadContinuedRef = React.useRef(false);
+
+  React.useEffect(() => {
+    mapLoadHandleRef.current = delayRender("Waiting for map tiles to load...");
+    mapLoadContinuedRef.current = false;
+
+    // Avoid hanging indefinitely when map tiles fail to load.
+    const fallbackTimer = window.setTimeout(() => {
+      if (!mapLoadContinuedRef.current && mapLoadHandleRef.current !== null) {
+        continueRender(mapLoadHandleRef.current);
+        mapLoadContinuedRef.current = true;
+      }
+    }, 8000);
+
+    return () => {
+      window.clearTimeout(fallbackTimer);
+      if (!mapLoadContinuedRef.current && mapLoadHandleRef.current !== null) {
+        continueRender(mapLoadHandleRef.current);
+        mapLoadContinuedRef.current = true;
+      }
+      mapLoadHandleRef.current = null;
+    };
+  }, [stream.id, start, end]);
+
+  const handleTilesLoaded = React.useCallback(() => {
+    if (!mapLoadContinuedRef.current && mapLoadHandleRef.current !== null) {
+      continueRender(mapLoadHandleRef.current);
+      mapLoadContinuedRef.current = true;
+    }
+  }, []);
+
   return (
     <Sequence
       durationInFrames={durFrames}
       from={Math.floor(fps * start)}
       layout="none"
     >
-      <APIProvider apiKey={apiKey}>
+      <APIProvider
+        apiKey={apiKey}
+        language={mapLocale.language}
+        region={mapLocale.region}
+      >
         <GoogleMap
           mapId={String(stream.id ?? "map")}
           defaultCenter={center}
@@ -74,6 +123,7 @@ export function MapLeaf({ stream }: { stream: MapStream }) {
             disableDefaultUI: true,
             zoomControl: false,
           }}
+          onTilesLoaded={handleTilesLoaded}
           style={{ width: "100%", height: "100%", position: "absolute" }}
         >
           <RouteWithMarker

package/src/utils/index.ts

@@ -4,7 +4,15 @@
  */
 
 export function uid(): string {
-  return Math.random().toString(36).slice(2, 10);
+  // Ensure the first character is a letter (valid JS identifier start)
+  const raw = Math.random().toString(36).slice(2, 10);
+  const first = raw[0]!;
+  // If first char is a digit, prepend a random letter
+  if (/^[0-9]/.test(first)) {
+    const letter = String.fromCharCode(97 + Math.floor(Math.random() * 26));
+    return letter + raw;
+  }
+  return raw;
 }
 
 const KEBAB = /[^a-zA-Z0-9_-]+/g;
@@ -135,7 +143,11 @@ export function getDurationInSeconds(stream: DurationStream, update = true): num
     getDurationInSeconds(child, update);
   }
 
-  const visible = stream.children.filter((c) => !c.isBackground);
+  // Effect wrappers encompass all children visually; background children
+  // still contribute to the effect's visible duration.
+  const visible = stream.type === "effect"
+    ? stream.children
+    : stream.children.filter((c) => !c.isBackground);
   if (stream.isSeries) {
     const overlap = stream.transition ? (stream.transitionTime ?? 0.5) : 0;
     for (let i = 0; i < visible.length; i++) {

package/tests/fixtures/md/animate-diagrams.md

@@ -0,0 +1,40 @@
+# video
+seed:2660286133
+width:640 height:480 fps:30 layout:series
+
+## Title
+layout:parallel
+- component duration:3
+  ~~~jsx jsx
+  <div style={{position:'absolute',top:0,left:0,width:640,height:480,display:'flex',flexDirection:'column',alignItems:'center',justifyContent:'center',background:'linear-gradient(135deg,#1a1a2e,#16213e)'}}>
+    <h1 style={{color:'#00d4ff',fontSize:28,margin:0}}>Animated Diagrams</h1>
+    <p style={{color:'#aaa',fontSize:16,marginTop:10}}>Mermaid Diagrams with Dynamic Highlight</p>
+  </div>
+  ~~~
+
+## FlowChart
+layout:parallel
+- component id:flowChart duration:12
+  ~~~jsx
+  <div style={{position:'absolute',top:0,left:0,width:640,height:480,background:'#1a1a2e',padding:10,fontFamily:'monospace',boxSizing:'border-box',display:'flex',flexDirection:'column'}}>
+    <p style={{color:'#00d4ff',fontSize:12,textAlign:'center',margin:'0 0 4px 0',flexShrink:0}}>Flow — {highlight}</p>
+    <div style={{flex:1,display:'flex',justifyContent:'center',alignItems:'center',overflow:'hidden'}}>
+      <Mermaid highlight={highlight} animateEdges={animateEdges} theme='dark' source={mermaid}/>
+    </div>
+  </div>
+  ~~~
+  ~~~mermaid
+  graph TD
+    A["Receive Request"] --> B["Validate Input"]
+    B --> C{"Valid?"}
+    C -->|Yes| D["Process Data"]
+    C -->|No| E["Return Error"]
+    D --> F["Format Response"]
+    F --> G["Send Response"]
+    classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px,color:#000
+  ~~~
+  highlight:"A"
+  animateEdges:true
+- event duration:3 start:3 on:(start, flowChart.highlight="B";flowChart.animateEdges=["B->C"])
+- event duration:3 start:6 on:(start, flowChart.highlight="C")
+- event duration:3 start:9 on:(start, flowChart.highlight=["D","G"])