@lalalic/markcut 2.8.0 → 3.0.0

package/src/components/Mermaid.tsx

@@ -1,5 +1,4 @@
 import * as React from "react";
-import { delayRender, continueRender } from "remotion";
 import mermaid from "mermaid";
 
 /**
@@ -10,13 +9,23 @@ import mermaid from "mermaid";
  *   <Mermaid source={diagram} theme="dark" />
  *
  * Props:
- *   source   — Mermaid diagram definition string
- *   theme    — Mermaid theme: "default" | "dark" | "forest" | "neutral" (default: "dark")
- *  className — Optional container className
+ *   source       — Mermaid diagram definition string
+ *   theme        — Mermaid theme: "default" | "dark" | "forest" | "neutral" (default: "dark")
+ *   className    — Optional container className
+ *   style        — Container inline style
+ *   highlight    — Node name(s) to highlight. String or array of strings.
+ *                  Toggles CSS class `highlight` on matching SVG elements.
+ *                  The diagram source should define the class, e.g.:
+ *                    classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px
+ *   animateEdges — Edge(s) to animate with a flowing dash effect.
+ *                  true = animate all edges.
+ *                  string[] = animate specific edges by source->target alias,
+ *                  e.g. ["A->B", "D->C"]. Edge paths are found via Mermaid's
+ *                  SVG id pattern: {prefix}-L_{source}_{target}_{index}.
+ *                  Adds CSS class `edge-animated` with a stroke-dashoffset
+ *                  keyframe animation.
  *
  * The diagram is rendered asynchronously via the mermaid library.
- * Uses delayRender/continueRender to ensure the SVG is ready before
- * the frame is captured by Remotion.
  *
  * Built-in — no imports or frontmatter registration needed.
  */
@@ -24,20 +33,147 @@ export interface MermaidProps {
   source?: string;
   children?: string;
   theme?: "default" | "dark" | "forest" | "neutral";
-    className?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  highlight?: string | string[];
+  animateEdges?: boolean | string[];
 }
 
 let initialized = false;
 
-export function Mermaid({ children, source=children, theme = "dark", className}: MermaidProps) {
+/**
+ * Recursively extract plain text from JsxParser children.
+ * JsxParser may wrap template literals in nested React elements.
+ */
+function extractText(x: unknown): string {
+  if (typeof x === "string") return x;
+  if (Array.isArray(x)) return x.map(extractText).join("");
+  if (x && typeof x === "object" && "props" in (x as any)) {
+    return extractText((x as any).props?.children);
+  }
+  return "";
+}
+
+/**
+ * Find the SVG element representing a named node.
+ * Strategy: search <text> + <title> elements by textContent,
+ * walk up to the containing <g> cluster.
+ */
+function findNodeGroup(svg: SVGSVGElement, name: string): Element | null {
+  // Strategy 1: SVG id containing the alias (e.g. `flowchart-A-1234` for "A")
+  // Mermaid embeds node aliases in auto-generated IDs.
+  const byId = svg.querySelector(`[id*="-${CSS.escape(name)}-"]`);
+  if (byId) {
+    let el: Element | null = byId;
+    while (el && el.tagName !== "g") el = el.parentElement;
+    return el || byId;
+  }
+  // Strategy 2: <text> elements whose text starts with the name
+  for (const t of svg.querySelectorAll<SVGTextElement>("text")) {
+    const text = t.textContent?.trim() ?? "";
+    if (text.startsWith(name)) {
+      let el: Element | null = t;
+      while (el && el.tagName !== "g") el = el.parentElement;
+      return el || t;
+    }
+  }
+  // Strategy 3: <title> elements (class diagram titles, state labels)
+  for (const t of svg.querySelectorAll("title")) {
+    if ((t.textContent?.trim() ?? "").startsWith(name) && t.parentElement) {
+      return t.parentElement;
+    }
+  }
+  return null;
+}
+
+/**
+ * Apply edge animation to matching paths in the rendered Mermaid SVG.
+ * Mermaid edge paths have IDs like `{prefix}-L_{source}_{target}_{index}`.
+ *
+ * @param svg - The rendered SVG element
+ * @param spec - true = animate all edges, string[] = specific edges by "A->B" pattern
+ */
+function applyEdgeAnimation(svg: SVGSVGElement, spec: boolean | string[] | undefined): void {
+  if (!spec) return;
+
+  const allEdges = Array.from(svg.querySelectorAll<SVGPathElement>(
+    'path[id*="-L_"]',
+  ));
+
+  if (spec === true) {
+    // Animate all edges
+    for (const path of allEdges) {
+      path.classList.add("edge-animated");
+    }
+    return;
+  }
+
+  // spec is string[] — parse patterns like "A->B"
+  for (const pattern of spec) {
+    const match = pattern.match(/^(\w+)\s*->\s*(\w+)$/);
+    if (!match) continue;
+    const source = match[1]!;
+    const target = match[2]!;
+
+    // Find matching path by ID pattern: *L_{source}_{target}_*
+    const suffix = `L_${source}_${target}_`;
+    for (const path of allEdges) {
+      if (path.id.includes(suffix)) {
+        path.classList.add("edge-animated");
+      }
+    }
+  }
+}
+
+export function Mermaid({
+  children,
+  source: sourceProp,
+  theme = "dark",
+  className,
+  style,
+  highlight,
+  animateEdges,
+}: MermaidProps) {
   const ref = React.useRef<HTMLDivElement>(null);
-  const [handle] = React.useState(() => delayRender("Mermaid rendering"));
+  const renderedRef = React.useRef(false);
+  const styleRef = React.useRef<HTMLStyleElement | null>(null);
 
+  // Inject edge animation CSS once
   React.useEffect(() => {
+    if (!styleRef.current) {
+      const el = document.createElement("style");
+      el.textContent = `
+        @keyframes mermaid-edge-flow {
+          to { stroke-dashoffset: -24; }
+        }
+        .edge-animated {
+          stroke-dasharray: 8 6 !important;
+          animation: mermaid-edge-flow 0.5s linear infinite !important;
+        }
+      `;
+      document.head.appendChild(el);
+      styleRef.current = el;
+    }
+    return () => {
+      if (styleRef.current) {
+        styleRef.current.remove();
+        styleRef.current = null;
+      }
+    };
+  }, []);
+
+  // Resolve source string: children from JsxParser may be nested React
+  // elements wrapping template literals.
+  const source = React.useMemo(
+    () => extractText(sourceProp ?? children),
+    [sourceProp, children],
+  );
+
+  // Render effect — runs once when source/theme changes
+  React.useEffect(() => {
+    let cancelled = false;
     if (!source || !ref.current) return;
 
-    // Initialize once — mermaid.initialize is idempotent but we guard to avoid
-    // redundant config writes on re-renders.
     if (!initialized) {
       mermaid.initialize({
         startOnLoad: false,
@@ -52,25 +188,90 @@ export function Mermaid({ children, source=children, theme = "dark", className}:
     mermaid
       .render(id, source)
       .then((result) => {
-        if (ref.current) ref.current.innerHTML = result.svg;
-        continueRender(handle);
+        if (cancelled || !ref.current) return;
+        ref.current.innerHTML = result.svg;
+        const svg = ref.current.querySelector<SVGSVGElement>("svg");
+        if (svg) {
+          svg.removeAttribute("width");
+          svg.removeAttribute("height");
+          svg.style.width = "100%";
+          svg.style.height = "100%";
+
+          // Apply initial highlight now that SVG exists.
+          // The highlight effect below only fires on prop changes, so the
+          // initial highlight would be missed if SVG wasn't ready yet.
+          if (highlight) {
+            const names = Array.isArray(highlight) ? highlight : [highlight];
+            for (const name of names) {
+              const node = findNodeGroup(svg, name);
+              if (node) node.classList.add("highlight");
+            }
+          }
+
+          // Apply edge animation now that SVG exists.
+          applyEdgeAnimation(svg, animateEdges);
+        }
+        renderedRef.current = true;
       })
       .catch((err) => {
+        if (cancelled) return;
         console.error("Mermaid error:", err);
-        // Show error inline so the user can diagnose diagram syntax
         if (ref.current) {
           ref.current.innerHTML = `<div style="color:#f87171;padding:1em;border:2px dashed #f87171;border-radius:8px;font-family:monospace;font-size:14px;">
             <strong>⚠ Mermaid Error</strong><br/>${String(err).replace(/</g, "&lt;").replace(/>/g, "&gt;")}
           </div>`;
         }
-        continueRender(handle);
       });
-  }, [source, theme, handle]);
 
-  return (
-    <div
-      ref={ref}
-      className={className}
-    />
-  );
+    return () => { cancelled = true; };
+  }, [source, theme]);
+
+  // Highlight effect — toggles CSS class `highlight` on matching nodes.
+  // The diagram source must define this class with desired styles, e.g.:
+  //   classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px
+  React.useEffect(() => {
+    const svg = ref.current?.querySelector<SVGSVGElement>("svg");
+    if (!svg) return;
+
+    // Remove class from all nodes
+    svg.querySelectorAll(".highlight").forEach((el) => {
+      el.classList.remove("highlight");
+    });
+
+    // Apply class to current highlight target(s)
+    const names = Array.isArray(highlight) ? highlight : (highlight ? [highlight] : []);
+    for (const name of names) {
+      const node = findNodeGroup(svg, name);
+      if (node) {
+        node.classList.add("highlight");
+      }
+    }
+  }, [highlight]);
+
+  // AnimateEdges effect — re-applies edge animation on prop changes.
+  // Runs in addition to the initial application in the render callback.
+  React.useEffect(() => {
+    const svg = ref.current?.querySelector<SVGSVGElement>("svg");
+    if (!svg) return;
+
+    // Remove animated class from all edges first
+    svg.querySelectorAll(".edge-animated").forEach((el) => {
+      el.classList.remove("edge-animated");
+    });
+
+    // Re-apply to current spec
+    applyEdgeAnimation(svg, animateEdges);
+  }, [animateEdges]);
+
+  // Default: center the SVG in the container. User style overrides individual properties.
+  const containerStyle: React.CSSProperties = {
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "center",
+    width: "100%",
+    height: "100%",
+    ...style,
+  };
+
+  return <div ref={ref} className={className} style={containerStyle} />;
 }

package/src/config.mjs

@@ -85,9 +85,9 @@ export const DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE
 
 
 /** Speech-to-text CLI. Override via --stt flag or MARKCUT_STT_CLI env var. */
-export const DEFAULT_STT_CLI = args.cliOverrides.stt || process.env.MARKCUT_STT_CLI || 'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
+export const DEFAULT_STT_CLI = args.cliOverrides.stt || process.env.MARKCUT_STT_CLI || 'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}" --word_timestamps True --max_line_count 1 --max_line_width 14';
 /** Text-to-speech CLI. Override via --tts flag or MARKCUT_TTS_CLI env var. */
-export const DEFAULT_TTS_CLI = args.cliOverrides.tts || process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
+export const DEFAULT_TTS_CLI = args.cliOverrides.tts || process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "zh-CN-YunxiNeural" --text "{input}" --write-media "{output}"';
 /** Default agent CLI. Override via --agent flag or MARKCUT_AGENT_CLI env var. */
 export const DEFAULT_AGENT_CLI = args.cliOverrides.agent || process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
 /** Default edit agent CLI. Override via --edit-cli flag or MARKCUT_EDIT_CLI env var. */

package/src/context/EventContext.tsx

@@ -74,6 +74,9 @@ export function EventProvider({ children }: { children: React.ReactNode }) {
     const keys = Object.keys(scope);
     const vals = Object.values(scope);
     try {
+      // Debug: log the exact code string
+      const codeChars = Array.from(code).map((c: string) => c.charCodeAt(0));
+      console.log(`EventContext.debug: keys=${JSON.stringify(keys)}, codeLen=${code.length}, codeChars=${JSON.stringify(codeChars)}, codeStr=${JSON.stringify(code)}`);
       const fn = new Function(...keys, code);
       fn(...vals);
       console.info(`Event evaluation succeeded: "${code}"`);

package/src/descriptive/compiler.ts

@@ -147,6 +147,8 @@ export interface DescriptiveMap extends DescriptiveBaseNode {
   zoom?: number;
   center?: { lat: number; lng: number };
   mapType?: "roadmap" | "satellite" | "hybrid" | "terrain";
+  language?: string;
+  region?: string;
   travelMode?: "DRIVING" | "WALKING" | "BICYCLING" | "TRANSIT";
   routeMarker?: string;
 }
@@ -446,15 +448,21 @@ function wrapWithEffects(
   const absEnd = innerStream.end ?? result.duration;
   const duration = absEnd - absStart;
 
-  // Reset inner stream's timing to be relative (start=0) so the effect
-  // wrapper owns the absolute timing. The EffectWrapper renders children
-  // with their relative timing inside its own Sequence.
-  const resetStream = {
-    ...innerStream,
-    start: 0,
-    end: duration,
-    durationInSeconds: duration,
-  } as any;
+  // For background nodes without explicit end, keep original timing
+  // (start/end undefined) so parent back-propagation fills the correct
+  // scene duration. The effect wrapper handles animation timing via
+  // durationInSeconds and the parent fills end for proper visibility span.
+  // Other nodes: reset to relative timing so the effect wrapper owns
+  // the absolute positioning in the parent timeline.
+  const isBgNoEnd = innerStream.isBackground && innerStream.end == null;
+  const resetStream = isBgNoEnd
+    ? { ...innerStream }
+    : {
+        ...innerStream,
+        start: 0,
+        end: duration,
+        durationInSeconds: duration,
+      } as any;
 
   // Build nested effect wrappers from innermost → outermost.
   // The outermost effect uses the original absolute timing;
@@ -474,14 +482,18 @@ function wrapWithEffects(
       id: uid(),
       type: "effect",
       animation: spec.animation,
+      animationDurationSeconds: spec.duration,
       durationInSeconds: spec.duration,
       animationTimingFunction: spec.animationTimingFunction,
       animationIterationCount: spec.animationIterationCount ?? 1,
       customKeyframes: spec.customKeyframes,
       children: [currentStream],
-      start: effStart,
-      end: effEnd,
-      visible: true,
+      // For background inner nodes: propagate start/end as-is so parent
+      // back-propagation fills the correct scene duration. The effect's
+      // durationInSeconds (animation spec) controls animation timing.
+      start: isOutermost && isBgNoEnd ? innerStream.start : effStart,
+      end: isOutermost && isBgNoEnd ? undefined : effEnd,
+      visible: innerStream.visible ?? true,
       ...pickOn(node),
     } as Effect;
   }
@@ -490,7 +502,10 @@ function wrapWithEffects(
 }
 
 function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | DescriptiveScene | DescriptiveInclude>, ctx: CompileContext, parentKind: "series" | "parallel" | "transitionSeries"): CompileResult {
-  const id = node.id ?? uid();
+  // Only set id when explicitly provided — auto-generated uids would register
+  // in EventContext and may create invalid JS identifiers (starting with digit).
+  const id = node.id;
+  const hasExplicitId = node.id != null;
 
   // Background nodes without explicit duration/endAt: let parent fill timing later
   const hasOwnDuration = typeof node.duration === "number" || typeof node.endAt === "number";
@@ -504,7 +519,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
   const end = duration != null ? start! + duration : undefined;
 
   const base = {
-    id,
+    ...(id ? { id } : {}),
     style: node.style,
     visible: node.visible ?? true,
     isBackground: node.isBackground,
@@ -555,11 +570,10 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         "type", "jsx", "id", "instruction", "style", "visible",
         "isBackground", "duration", "start", "on",
       ]);
-      const bindings: Record<string, string> = {};
+      const bindings: Record<string, unknown> = {};
       for (const key of Object.keys(node)) {
         if (!KNOWN_COMPONENT_KEYS.has(key)) {
-          const val = (node as any)[key];
-          if (typeof val === "string") bindings[key] = val;
+          bindings[key] = (node as any)[key];
         }
       }
 
@@ -593,6 +607,8 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         zoom: node.zoom ?? 10,
         center: node.center,
         mapType: node.mapType ?? "roadmap",
+        language: node.language,
+        region: node.region,
         travelMode: node.travelMode ?? "DRIVING",
         routeMarker: node.routeMarker ?? "🚗",
         googleMapsApiKey: ctx.googleMapsApiKey,
@@ -686,14 +702,27 @@ function compileScene(
     : aggregateDuration(compiledChildren, sceneKind, resolved.time);
   const localDuration = Math.max(node.duration ?? 0, sceneContentDuration);
 
-  // Back-propagate parent duration to background children without own timing
-  for (const c of compiledChildren) {
-    if (c.stream.isBackground && c.stream.end == null) {
-      c.stream.end = localDuration;
-      c.stream.durationInSeconds = localDuration;
-      if (c.stream.start == null) c.stream.start = 0;
+  // Back-propagate parent duration to nodes without own timing.
+  // Also recurses into effect wrappers so nested background children
+  // (wrapped by effects) get the correct scene duration.
+  function backpropagate(stream: Record<string, any>, dur: number): void {
+    if (stream.end == null) {
+      stream.end = dur;
+      if (stream.durationInSeconds == null) {
+        stream.durationInSeconds = dur;
+      }
+      if (stream.start == null) stream.start = 0;
+    }
+    // Recursively walk into effect wrapper children
+    if (stream.type === "effect" && Array.isArray(stream.children)) {
+      for (const child of stream.children) {
+        backpropagate(child, dur);
+      }
     }
   }
+  for (const c of compiledChildren) {
+    backpropagate(c.stream, localDuration);
+  }
 
   const start = parentKind === "parallel" ? Math.max(0, node.start ?? 0) : 0;
   const end = start + localDuration;
@@ -833,14 +862,24 @@ function compileContainer(node: DescriptiveContainer, ctx: CompileContext, paren
   const children = compileChildren(node.children, ctx, node.type);
   const duration = aggregateDuration(children, node.type, resolved.time);
 
-  // Back-propagate parent duration to background children without own timing
-  for (const c of children) {
-    if (c.stream.isBackground && c.stream.end == null) {
-      c.stream.end = duration;
-      c.stream.durationInSeconds = duration;
-      if (c.stream.start == null) c.stream.start = 0;
+  // Back-propagate parent duration to nodes without own timing.
+  function backpropagate(stream: Record<string, any>, dur: number): void {
+    if (stream.end == null) {
+      stream.end = dur;
+      if (stream.durationInSeconds == null) {
+        stream.durationInSeconds = dur;
+      }
+      if (stream.start == null) stream.start = 0;
+    }
+    if (stream.type === "effect" && Array.isArray(stream.children)) {
+      for (const child of stream.children) {
+        backpropagate(child, dur);
+      }
     }
   }
+  for (const c of children) {
+    backpropagate(c.stream, duration);
+  }
 
   const stream: Folder = {
     id,

package/src/descriptive/markdown.ts

@@ -38,6 +38,7 @@ const TYPE_TOKENS: Record<string, string> = {
   video: "video",
   audio: "audio",
   component: "component",
+  event: "event",
   rhythm: "rhythm",
   include: "include",
   map: "map",
@@ -251,6 +252,23 @@ function parseNodeLine(content: string, lineNum?: number): DescriptiveNode {
       preserveVariantAttrs(node, attrs);
       return node;
     }
+    case "event": {
+      // Event-only stub: compiles to a component with empty JSX (renders nothing),
+      // just fires events on other registered components via `on`.
+      const node: DescriptiveComponent = {
+        type: "component",
+        id: attrs.id as any,
+        jsx: "",
+        duration: attrs.duration as any,
+        start: attrs.start as any,
+        instruction: attrs.instruction as any,
+        style: attrs.style as any,
+        effects: attrs.effects as any,
+        on: attrs.on as any,
+      };
+      preserveVariantAttrs(node, attrs);
+      return node;
+    }
     case "rhythm": {
       const src = firstPositional ?? (attrs.src as string | undefined);
       if (!src) throw new DslError("rhythm requires src", ctx);
@@ -327,6 +345,8 @@ function parseNodeLine(content: string, lineNum?: number): DescriptiveNode {
         zoom: attrs.zoom as any,
         center: attrs.center as any,
         mapType: attrs.mapType as any,
+        language: (attrs.language as any) ?? (attrs.lang as any),
+        region: attrs.region as any,
         instruction: attrs.instruction as any,
         visible: attrs.visible as any,
         isBackground: attrs.isBackground as any,