@lalalic/markcut 2.9.0 → 3.0.0

package/src/player/pipeline.mjs

@@ -33,7 +33,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/utils/index.ts
 function uid() {
-  return Math.random().toString(36).slice(2, 10);
+  const raw = Math.random().toString(36).slice(2, 10);
+  const first = raw[0];
+  if (/^[0-9]/.test(first)) {
+    const letter = String.fromCharCode(97 + Math.floor(Math.random() * 26));
+    return letter + raw;
+  }
+  return raw;
 }
 function walkDown(node2, visit, parent = null, depth = 0) {
   const keep = visit(node2, parent, depth);
@@ -207,7 +213,8 @@ function wrapWithEffects(node2, result, parentKind) {
   const absStart = innerStream.start ?? 0;
   const absEnd = innerStream.end ?? result.duration;
   const duration = absEnd - absStart;
-  const resetStream = {
+  const isBgNoEnd = innerStream.isBackground && innerStream.end == null;
+  const resetStream = isBgNoEnd ? { ...innerStream } : {
     ...innerStream,
     start: 0,
     end: duration,
@@ -224,28 +231,33 @@ function wrapWithEffects(node2, result, parentKind) {
       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 ? void 0 : effEnd,
+      visible: innerStream.visible ?? true,
       ...pickOn(node2)
     };
   }
   return { stream: currentStream, duration: result.duration };
 }
 function compileLeaf(node2, ctx, parentKind) {
-  const id = node2.id ?? uid();
+  const id = node2.id;
+  const hasExplicitId = node2.id != null;
   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,
+    ...id ? { id } : {},
     style: node2.style,
     visible: node2.visible ?? true,
     isBackground: node2.isBackground,
@@ -305,8 +317,7 @@ function compileLeaf(node2, ctx, parentKind) {
       const bindings = {};
       for (const key of Object.keys(node2)) {
         if (!KNOWN_COMPONENT_KEYS.has(key)) {
-          const val = node2[key];
-          if (typeof val === "string") bindings[key] = val;
+          bindings[key] = node2[key];
         }
       }
       const stream = {
@@ -407,13 +418,23 @@ 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;
+  function backpropagate(stream2, dur) {
+    if (stream2.end == null) {
+      stream2.end = dur;
+      if (stream2.durationInSeconds == null) {
+        stream2.durationInSeconds = dur;
+      }
+      if (stream2.start == null) stream2.start = 0;
+    }
+    if (stream2.type === "effect" && Array.isArray(stream2.children)) {
+      for (const child of stream2.children) {
+        backpropagate(child, dur);
+      }
     }
   }
+  for (const c of compiledChildren) {
+    backpropagate(c.stream, localDuration);
+  }
   const start = parentKind === "parallel" ? Math.max(0, node2.start ?? 0) : 0;
   const end = start + localDuration;
   const stream = {
@@ -507,13 +528,23 @@ 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;
+  function backpropagate(stream2, dur) {
+    if (stream2.end == null) {
+      stream2.end = dur;
+      if (stream2.durationInSeconds == null) {
+        stream2.durationInSeconds = dur;
+      }
+      if (stream2.start == null) stream2.start = 0;
+    }
+    if (stream2.type === "effect" && Array.isArray(stream2.children)) {
+      for (const child of stream2.children) {
+        backpropagate(child, dur);
+      }
     }
   }
+  for (const c of children) {
+    backpropagate(c.stream, duration);
+  }
   const stream = {
     id,
     type: "folder",
@@ -10122,6 +10153,7 @@ var TYPE_TOKENS = {
   video: "video",
   audio: "audio",
   component: "component",
+  event: "event",
   rhythm: "rhythm",
   include: "include",
   map: "map",
@@ -10341,6 +10373,21 @@ function parseNodeLine(content3, lineNum) {
       preserveVariantAttrs(node2, attrs);
       return node2;
     }
+    case "event": {
+      const node2 = {
+        type: "component",
+        id: attrs.id,
+        jsx: "",
+        duration: attrs.duration,
+        start: attrs.start,
+        instruction: attrs.instruction,
+        style: attrs.style,
+        effects: attrs.effects,
+        on: attrs.on
+      };
+      preserveVariantAttrs(node2, attrs);
+      return node2;
+    }
     case "rhythm": {
       const src = firstPositional ?? attrs.src;
       if (!src) throw new DslError("rhythm requires src", ctx);

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(),

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/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"])

package/tests/fixtures/md/electricity-grow.md

@@ -0,0 +1,130 @@
+# video
+seed:1793769080
+width:640 height:480 fps:30 layout:series
+
+## Title
+layout:parallel
+- component duration:3
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',display:'flex',flexDirection:'column',alignItems:'center',justifyContent:'center',background:'linear-gradient(135deg,#0c0c1d,#1a1a3e)'}}>
+    <h1 style={{color:'#ffd700',fontSize:36,margin:0}}>Global Electricity Generation</h1>
+    <p style={{color:'#88ccff',fontSize:20,marginTop:10}}>1985 → 2025</p>
+    <p style={{color:'#aaa',fontSize:14,marginTop:20}}>Data: Ember / Energy Institute (Our World in Data)</p>
+  </div>
+  ~~~
+
+## ChinaSurge
+layout:parallel
+- component duration:6
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',background:'#0c0c1d',padding:20,fontFamily:'Arial,sans-serif'}}>
+    <h2 style={{color:'#ffd700',fontSize:18,textAlign:'center',margin:'0 0 10px 0'}}>China's Electricity Generation (TWh)</h2>
+    <svg viewBox='0 0 580 380' width='100%' height='85%'>
+      {[1985,1990,1995,2000,2005,2010,2015,2020,2025].map((year,i)=>(
+        <g key={year}>
+          <rect x={20+i*62} y={350-tween(0,{1985:42,1990:63,1995:97,2000:137,2005:253,2010:425,2015:625,2020:786,2025:1069}[year])} width={42} height={tween(0,{1985:42,1990:63,1995:97,2000:137,2005:253,2010:425,2015:625,2020:786,2025:1069}[year])} fill='#ff4444' rx={3} />
+          <text x={20+i*62+21} y={365} textAnchor='middle' fill='#aaa' fontSize={9}>{year}</text>
+          <text x={20+i*62+21} y={345-tween(0,{1985:42,1990:63,1995:97,2000:137,2005:253,2010:425,2015:625,2020:786,2025:1069}[year])} textAnchor='middle' fill='#ff8888' fontSize={9}>{Math.round({1985:411,1990:621,1995:928,2000:1356,2005:2500,2010:4207,2015:6186,2020:7779,2025:10583}[year])}</text>
+        </g>
+      ))}
+      <text x={10} y={20} fill='#666' fontSize={10}>TWh</text>
+    </svg>
+  </div>
+  ~~~
+
+## World1985
+layout:parallel
+- component duration:5
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',background:'#0c0c1d',padding:20,fontFamily:'Arial,sans-serif'}}>
+    <h2 style={{color:'#ffd700',fontSize:18,textAlign:'center',margin:'0 0 10px 0'}}>Electricity Generation in 1985 (TWh)</h2>
+    <svg viewBox='0 0 580 380' width='100%' height='85%'>
+      {[
+        {name:'USA',val:2657,color:'#4477ff',scale:266},
+        {name:'Russia',val:962,color:'#cc4444',scale:96},
+        {name:'Japan',val:672,color:'#44cc44',scale:67},
+        {name:'Germany',val:523,color:'#ffaa00',scale:52},
+        {name:'Canada',val:459,color:'#ff66aa',scale:46},
+        {name:'France',val:344,color:'#aa66ff',scale:34},
+        {name:'UK',val:298,color:'#66cccc',scale:30},
+        {name:'Brazil',val:194,color:'#66ff66',scale:19},
+        {name:'India',val:186,color:'#ff8844',scale:19},
+        {name:'China',val:411,color:'#ff4444',scale:41},
+      ].map((c,i)=>(
+        <g key={c.name}>
+          <rect x={20+i*54} y={350-tween(0,c.scale)} width={40} height={tween(0,c.scale)} fill={c.color} rx={3}>
+            <animate attributeName='opacity' values='0;1' dur='2s' fill='freeze'/>
+          </rect>
+          <text x={20+i*54+20} y={365} textAnchor='middle' fill='#aaa' fontSize={9}>{c.name}</text>
+          <text x={20+i*54+20} y={345-tween(0,c.scale)} textAnchor='middle' fill='#fff' fontSize={9}>{c.val}</text>
+        </g>
+      ))}
+    </svg>
+  </div>
+  ~~~
+
+## World2025
+layout:parallel
+- component duration:5
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',background:'#0c0c1d',padding:20,fontFamily:'Arial,sans-serif'}}>
+    <h2 style={{color:'#ffd700',fontSize:18,textAlign:'center',margin:'0 0 10px 0'}}>Electricity Generation in 2025 (TWh)</h2>
+    <svg viewBox='0 0 580 380' width='100%' height='85%'>
+      {[
+        {name:'China',val:10583,color:'#ff4444',scale:280},
+        {name:'USA',val:4520,color:'#4477ff',scale:120},
+        {name:'India',val:2082,color:'#ff8844',scale:55},
+        {name:'Russia',val:1193,color:'#cc4444',scale:32},
+        {name:'Japan',val:1030,color:'#44cc44',scale:27},
+        {name:'Brazil',val:751,color:'#66ff66',scale:20},
+        {name:'Canada',val:652,color:'#ff66aa',scale:17},
+        {name:'S.Korea',val:625,color:'#66cccc',scale:17},
+        {name:'Germany',val:500,color:'#ffaa00',scale:13},
+        {name:'France',val:570,color:'#aa66ff',scale:15},
+      ].map((c,i)=>(
+        <g key={c.name}>
+          <rect x={20+i*54} y={350-tween(0,c.scale)} width={40} height={tween(0,c.scale)} fill={c.color} rx={3}/>
+          <text x={20+i*54+20} y={365} textAnchor='middle' fill='#aaa' fontSize={9}>{c.name}</text>
+          <text x={20+i*54+20} y={345-tween(0,c.scale)} textAnchor='middle' fill='#fff' fontSize={9}>{c.val}</text>
+        </g>
+      ))}
+    </svg>
+  </div>
+  ~~~
+
+## GrowthComparison
+layout:parallel
+- component duration:6
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',background:'#0c0c1d',padding:20,fontFamily:'Arial,sans-serif'}}>
+    <h2 style={{color:'#ffd700',fontSize:18,textAlign:'center',margin:'0 0 10px 0'}}>Growth: 1985 → 2025 (TWh)</h2>
+    <svg viewBox='0 0 580 380' width='100%' height='85%'>
+      {[
+        {name:'China',v1985:411,v2025:10583,growth:'+10172',color:'#ff4444',s1985:11,s2025:280},
+        {name:'USA',v1985:2657,v2025:4520,growth:'+1863',color:'#4477ff',s1985:70,s2025:120},
+        {name:'India',v1985:186,v2025:2082,growth:'+1896',color:'#ff8844',s1985:5,s2025:55},
+        {name:'Brazil',v1985:194,v2025:751,growth:'+557',color:'#66ff66',s1985:5,s2025:20},
+      ].map((c,i)=>(
+        <g key={c.name}>
+          <text x={20} y={50+i*80} fill='#aaa' fontSize={14}>{c.name}</text>
+          <rect x={20} y={58+i*80} width={tween(0,c.s1985)} height={14} fill={c.color} opacity={0.6} rx={2}/>
+          <rect x={20+tween(0,c.s1985)} y={58+i*80} width={tween(0,c.s2025-c.s1985)} height={14} fill={c.color} rx={2}/>
+          <text x={20+tween(0,c.s2025)+5} y={70+i*80} fill='#fff' fontSize={11}>{c.v1985} → {c.v2025}</text>
+          <text x={20} y={86+i*80} fill='#ffd700' fontSize={10}>Growth: {c.growth} TWh</text>
+        </g>
+      ))}
+      <text x={20} y={370} fill='#666' fontSize={9}>1985 bar (dim) → 2025 bar (bright)</text>
+    </svg>
+  </div>
+  ~~~
+
+## Closing
+layout:parallel
+- component duration:3
+  ~~~jsx jsx
+  <div style={{width:'100%',height:'100%',display:'flex',flexDirection:'column',alignItems:'center',justifyContent:'center',background:'linear-gradient(135deg,#0c0c1d,#1a1a3e)'}}>
+    <h2 style={{color:'#ffd700',fontSize:24,margin:0}}>China leads at 10,583 TWh</h2>
+    <p style={{color:'#88ccff',fontSize:16,marginTop:10}}>nearly 25x growth since 1985</p>
+    <p style={{color:'#aaa',fontSize:12,marginTop:30}}>Data: Our World in Data · Ember (2026) / Energy Institute (2025)</p>
+  </div>
+  ~~~

package/tests/tmp/vision-1785081637127-video/videos/metadata.json

@@ -0,0 +1,9 @@
+{
+  "test-clip": {
+    "width": 320,
+    "height": 240,
+    "created": "0000-00-00T00:00:00Z",
+    "location": null,
+    "duration": 3
+  }
+}

package/tests/tmp/vision-1785081637127-video/videos/test-clip.vtt

@@ -0,0 +1,5 @@
+WEBVTT
+
+00:00.000 --> 00:01.100
+Thank you.
+