@lalalic/markcut 1.1.1 → 2.0.0

package/tests/server.test.ts

@@ -48,7 +48,8 @@ function makeFixture(name: string): string {
               type: "component",
               id: `comp-${name}`,
               jsx: `<div>${name}</div>`,
-              actions: [{ start: 0, end: 3 }],
+              start: 0,
+              end: 3,
             },
           ],
         },
@@ -274,16 +275,18 @@ describe("HTML page variant injection", () => {
     }
   });
 
-  it("shows variant switcher bar with all variant links", async () => {
-    const fixture = makeFixture("html-bar");
+  it("sets mode and variant in globals for client-side rendering", async () => {
+    const fixture = makeFixture("html-mode");
     const port = nextPort();
     const stop = await startServer(fixture, ["default", "zh-tiktok", "youtube"], port);
     try {
       const res = await fetchUrl(`http://localhost:${port}/`);
       expect(res.status).toBe(200);
-      expect(res.text).toContain('href="/"');
-      expect(res.text).toContain('href="/zh-tiktok"');
-      expect(res.text).toContain('href="/youtube"');
+      // Variant bar is now rendered client-side by React (VariantBar.tsx).
+      // Server only provides the config globals and loads player.js.
+      expect(res.text).toContain('window.VARIANT = "default"');
+      expect(res.text).toContain('window.MODE = "preview"');
+      expect(res.text).toContain('src="/player.js"');
     } finally {
       stop();
     }

package/tests/utils.ts

@@ -376,10 +376,10 @@ export function getExpectedDuration(fixtureData: any): number {
     }
   }
 
-  // Leaf action duration
-  if (fixtureData.actions?.length) {
-    return Math.max(...fixtureData.actions.map((a: any) => a.end ?? 1));
-  }
+  // Leaf duration from base timing fields (end is source of truth)
+  const leafStart = fixtureData.start ?? 0;
+  if (typeof fixtureData.end === "number") return fixtureData.end;
+  if (typeof fixtureData.duration === "number") return leafStart + fixtureData.duration;
 
   return 1;
 }

package/docs/dynamic-components.md

@@ -1,191 +0,0 @@
-# Dynamic Components
-
-Three ways to add custom visual content without rebuilding the engine.
-
-## 1. Effects on Any Node (CSS Keyframes)
-
-Add the `effects` key to any node to apply CSS keyframe animations. No wrapper node needed.
-
-```json
-{
-  "id": "animated-scene",
-  "type": "image",
-  "src": "photo.jpg",
-  "duration": 3,
-  "effects": ["bounceIn(1, ease-out, 2)"]
-}
-```
-
-### 25+ Built-in Animation Names
-
-| Fades | Slides | Zooms | Attention | Bounce | Rotations |
-|-------|--------|-------|-----------|--------|-----------|
-| `fadeIn` | `slideInDown` | `zoomIn` | `pulse` | `bounceIn` | `rotateIn` |
-| `fadeOut` | `slideInUp` | `zoomOut` | `flash` | | `rotateOut` |
-| `fadeInDown` | `slideInLeft` | | `bounce` | | |
-| `fadeInUp` | `slideInRight` | | `heartBeat` | | |
-| `fadeInLeft` | | | `rubberBand` | | |
-| `fadeInRight` | | | `shakeX` | | |
-| (8 total) | | | | | |
-
-### Custom Keyframes
-
-```json
-{
-  "type": "effect",
-  "animation": "custom",
-  "customKeyframes": {
-    "0":  { "opacity": "0", "transform": "scale3d(0,0,0) rotate(0deg)" },
-    "50": { "opacity": "0.5", "transform": "scale3d(1.2,1.2,1.2) rotate(180deg)" },
-    "100": { "opacity": "1", "transform": "scale3d(1,1,1) rotate(360deg)" }
-  },
-  "children": [...],
-  "actions": [{ "start": 0, "end": 2 }]
-}
-```
-
-Percentages `"0"`–`"100"` map to action duration. Any numeric CSS property works.
-
-## 2. Remote Components (bundler-based)
-
-Register remote React components via the `~~~js imports` code fence (markdown) or `root.imports` array (JSON descriptive). The player server bundles all registered components into a single ESM module at startup.
-
-```markdown
-~~~js imports
-export { BarChart } from "recharts"
-export { Hello } from "git:user/repo/path/to/Hello.tsx"
-export { Badge } from "https://cdn.example.com/components/badge.js"
-
-export function Slide(props) {
-  return <div style={{color: '#fff'}}>{props.children}</div>;
-}
-~~~
-```
-
-Then use them in component JSX:
-
-```json
-{
-  "type": "component",
-  "jsx": "<Badge text='LIVE' color='#ff0000' />",
-  "actions": [{ "start": 0, "end": 3 }]
-}
-```
-
-### How it works
-
-1. The server extracts the imports block from the source file
-2. `parseImportsBlock` resolves `export { X } from "spec"` and `export function X() {}` patterns
-3. Inline functions' source code is scanned for `import X from "pkg"` statements — those packages are added to dependencies
-4. `bundleFromEntries` creates a temp npm project, installs all packages, and runs `esbuild` to produce a single ESM file
-5. The bundled file URL is set on `root.imports` and served from `/.component-cache/<hash>.js`
-6. At runtime, `MarkCut.useComponentRegistry` does a dynamic `import(url)` to load all named exports
-7. react-jsx-parser resolves component tags from the loaded registry
-
-### Import spec forms
-
-| Pattern | Resolves to | Example |
-|---|---|---|
-| `pkg` or `npm:pkg` | npm package (installed + bundled) | `export { BarChart } from "recharts"` |
-| `git:user/repo` | GitHub repo source | `export { Comp } from "git:user/repo/src/Comp.tsx"` |
-| `https://...` | Raw URL (used as-is) | `export { X } from "https://cdn.example.com/x.js"` |
-| local path | Filesystem path | `export { X } from "./local/Component.tsx"` |
-
-### Inline functions
-
-Define components directly in the imports block. Dependencies used inside the function body are automatically detected and installed:
-
-```markdown
-~~~js imports
-import ReactMarkdown from "react-markdown"
-
-export function Slide({ children }) {
-  return <div className="slide"><ReactMarkdown>{children}</ReactMarkdown></div>;
-}
-~~~
-```
-
-The `import` statements at the top serve dual purpose: they bring packages into scope inside inline functions AND tell the bundler what to install. The packages are added to `package.json` during bundling.
-
-### Component Contract
-
-Props injected automatically:
-- Nothing special required — just standard React props. The engine passes any `data` bindings from the component node as JSX variables.
-
-For frame-accurate animation, use standard Remotion hooks inside inline functions:
-
-```markdown
-~~~js imports
-import { useCurrentFrame } from "remotion"
-
-export function FadeIn({ children }) {
-  const frame = useCurrentFrame();
-  const opacity = Math.min(1, frame / 15);
-  return <div style={{ opacity }}>{children}</div>;
-}
-~~~
-
-Note: `remotion` and `react` are automatically available in the bundle's external scope — they do NOT need to be imported. However, adding `import { useCurrentFrame } from "remotion"` in the imports block is harmless and makes the dependency explicit.
-
-## 3. Custom Components
-
-Create a React component file in `src/components/`, register in `builtinComponents`.
-
-### Component Contract
-
-Props the engine injects automatically:
-- `action: { start: number; end: number }` — action timing from the stream node
-
-Use `useCurrentFrame()` for frame-accurate animation, `useVideoConfig()` for canvas size.
-
-### Example
-
-```tsx
-// src/components/my/Badge.tsx
-import React from "react";
-import { useCurrentFrame, interpolate } from "remotion";
-
-export const Badge: React.FC<{text: string; color?: string; action: any}> =
-  ({ text, color, action }) => {
-    const frame = useCurrentFrame();
-    const local = frame - action.start * 30;
-    const opacity = interpolate(local, [0, 15], [0, 1]);
-    return (
-      <div style={{ opacity, padding: 12, background: color || theme.colors.primary,
-                    color: "white", borderRadius: 8, fontSize: 48 }}>
-        {text}
-      </div>
-    );
-  };
-```
-
-### Register
-
-```tsx
-// src/components/index.ts
-import { Badge } from "./my/Badge";
-export const builtinComponents = { ..., Badge };
-```
-
-### Reference in stream tree
-
-```json
-{
-  "type": "component",
-  "jsx": "<Badge text='NEW' color='#ff6b35' />",
-  "actions": [{ "start": 1, "end": 4 }]
-}
-```
-
-
-# common used components
-- `react-markdown` — render markdown content, use plugins to extend functionality
-  - `remark-gfm` — support GitHub Flavored Markdown (tables, strikethrough, task lists)
-  - `remark-toc` — generate table of contents
-  - `remark-math` — support math formulas
-  - `rehype-katex` — render math formulas with KaTeX
-  - `remark-mermaidjs` — render mermaid diagrams in 
-- `react-markdown-mermaid` — render mermaid diagrams in standalone mode (no need to install mermaid separately)
-
-- `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
-- `@remotion/starburst` — render starburst animations

package/docs/templates.md

@@ -1,52 +0,0 @@
-# Video Templates
-
-Ready-to-use markdown templates for common video scenarios. Each template:
-
-- Contains **YAML frontmatter** with usage guidance (when, how, key decisions)
-- Lists **required external packages** (npm imports)
-- Uses **src:auto prompt:"..."** placeholders for AI-generated images/videos
-- Includes **TTS narration** with configured voice and pacing
-- Provides **scene structure** with named scenes, layouts, and durations
-
-## Quick Start
-
-```bash
-# 1. Pick a template
-cp docs/templates/courseware.md my-video.md
-
-# 2. Fill in [bracketed] placeholders with actual content
-# 3. Render
-npx markcut render my-video.md --aspect 16x9
-```
-
-## Template Catalog
-
-| Template | Scenario | Duration | Key Components |
-|---|---|---|---|
-| [courseware.md](templates/courseware.md) | 课件 / Lessons | 1-5 min | MarpSlide (markdown→slides), SlideText, MathDisplay |
-| [product-ad.md](templates/product-ad.md) | 产品广告 / Ads | 15-45s | TextReveal, DeviceMockup, QRCode, FeatureCard |
-| [movie-review.md](templates/movie-review.md) | 影视讲解 / Reviews | 1-3 min | CinematicText, StarRating, TextAnnotation, SplitScreen |
-| [audiobook.md](templates/audiobook.md) | 有声图书 / Audiobooks | 3-30 min | BookCover, AmbientBackground, ProgressBar |
-| [story-video.md](templates/story-video.md) | 故事视频 / Stories | 1-5 min | StoryTitle, SpeechBubble, ParticleEffect |
-| [travel-log.md](templates/travel-log.md) | 旅行日志 / Travel | 1-3 min | LocationCard, WeatherIcon, TravelStats, Map node |}
-
-## Frontmatter Fields Used by Templates
-
-| Field | Purpose | Example |
-|---|---|---|
-| `tts` | TTS CLI command with `{input}` `{output}` | `edge-tts --voice "zh-CN-XiaoxiaoNeural" --text "{input}" --write-media "{output}"` |
-| `stt` | STT CLI command with `{input}` `{output}` | `whisper "{input}" --model tiny --language zh --output_format vtt --output_dir "{output}"` |
-| `tti` | TTI CLI command with `{input}` `{output}` | `pi --model agnes-2.0-flash --print "generate image: {input}" --output "{output}"` |
-| `ttv` | TTV CLI command with `{input}` `{output}` | `pi --model agnes-2.0-flash --print "generate video: {input}" --output "{output}"` |
-
-## src:auto — AI-Generated Media
-
-Templates use a special `src:auto` value on `image` and `video` nodes to indicate AI generation:
-
-```md
-- image src:auto prompt:"sunset over Tokyo skyline, cinematic" duration:5
-- video src:auto prompt:"person walking through cherry blossom park" duration:3
-```
-
-The `prompt:` key provides the generation prompt to the configured TTI/TTV CLI.
-The pipeline resolves `src:auto` before compilation: runs the CLI command, gets the output path, and replaces `src:auto` with the actual generated file path.

package/scripts/artlist-dl.mjs

@@ -1,190 +0,0 @@
-#!/usr/bin/env node
-/**
- * artlist-dl — Download BGM/SFX from artlist.io CDN URLs or track pages.
- * 
- * Usage:
- *   node scripts/artlist-dl.mjs bgm <cdnUrl> <name>     → public/assets/bgm/<name>.mp3
- *   node scripts/artlist-dl.mjs sfx <cdnUrl> <name> [s]  → public/assets/sfx/<name>.mp3 (trimmed to s seconds)
- *   node scripts/artlist-dl.mjs grab <trackPageUrl> <name> [bgm|sfx] [s]  → auto-extract CDN URL from track page
- *   node scripts/artlist-dl.mjs list                      → show current assets
- *
- * CDN URLs are captured from artlist.io when playing a track (see SKILL.md).
- * Pattern: https://cms-public-artifacts.artlist.io/content/...
- * 
- * The `grab` command scrapes the track page HTML for base64-encoded CDN paths,
- * no browser or login needed — works with just curl.
- */
-import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, "..");
-
-const BGM_DIR = resolve(ROOT, "public/assets/bgm");
-const SFX_DIR = resolve(ROOT, "public/assets/sfx");
-
-function ensureDir(dir) {
-  mkdirSync(dir, { recursive: true });
-}
-
-function download(url, outPath, trimSeconds) {
-  const tmpPath = resolve(ROOT, ".tmp", `dl-${Date.now()}.aac`);
-  ensureDir(dirname(tmpPath));
-  ensureDir(dirname(outPath));
-
-  console.log(`⬇ Downloading: ${url.substring(0, 80)}...`);
-  execSync(`curl -sL "${url}" -o "${tmpPath}"`, { stdio: "inherit" });
-
-  const trimFlag = trimSeconds ? `-t ${trimSeconds}` : "";
-  console.log(`🔄 Converting to MP3${trimSeconds ? ` (${trimSeconds}s)` : ""}...`);
-  execSync(`ffmpeg -y -i "${tmpPath}" ${trimFlag} "${outPath}" 2>/dev/null`, { stdio: "inherit" });
-
-  execSync(`rm "${tmpPath}"`);
-
-  const size = statSync(outPath).size;
-  console.log(`✅ ${outPath} (${(size / 1024).toFixed(1)} KB)`);
-}
-
-function list() {
-  console.log("\n📁 BGM (public/assets/bgm/):");
-  if (existsSync(BGM_DIR)) {
-    for (const f of readdirSync(BGM_DIR)) {
-      const size = statSync(resolve(BGM_DIR, f)).size;
-      console.log(`  🎵 ${f} (${(size / 1024).toFixed(1)} KB)`);
-    }
-  }
-  console.log("\n📁 SFX (public/assets/sfx/):");
-  if (existsSync(SFX_DIR)) {
-    for (const f of readdirSync(SFX_DIR)) {
-      const size = statSync(resolve(SFX_DIR, f)).size;
-      console.log(`  🔊 ${f} (${(size / 1024).toFixed(1)} KB)`);
-    }
-  }
-}
-
-function search(term, type = "sfx", count = 10) {
-  const GRAPHQL = "https://search-api.artlist.io/v1/graphql";
-  let query, variables;
-  
-  if (type === "bgm" || type === "music") {
-    query = `query SongList($page: Int!, $songSortType: Int!, $take: Int!, $vocalMenuId: Int!, $searchTerm: String) {
-      songList(page: $page, songSortType: $songSortType, take: $take, vocalMenuId: $vocalMenuId, searchTerm: $searchTerm) {
-        songs { songId songName artistName duration sitePlayableFilePath nameForURL }
-      }
-    }`;
-    variables = { page: 1, songSortType: 0, take: count, vocalMenuId: 0, searchTerm: term };
-  } else {
-    query = `query SfxList($categoryIds: String!, $page: Float!, $tags: String!, $term: String!, $sortBy: SfxListRequestSortByOptions!) {
-      sfxList(categoryIds: $categoryIds, page: $page, tags: $tags, term: $term, sortBy: $sortBy) {
-        songs { songId songName artistName durationTime sitePlayableFilePath nameForURL }
-      }
-    }`;
-    variables = { categoryIds: "", page: 1, tags: "", term, sortBy: "STAFF_PICKS" };
-  }
-  
-  const body = JSON.stringify({ query, variables });
-  const result = execSync(
-    `curl -s '${GRAPHQL}' -H 'Content-Type: application/json' -d '${body.replace(/'/g, "'\\''")}'`,
-    { encoding: "utf-8" }
-  );
-  const data = JSON.parse(result);
-  const songs = type === "bgm" || type === "music"
-    ? data.data?.songList?.songs || []
-    : data.data?.sfxList?.songs || [];
-  
-  if (!songs.length) {
-    console.log(`No results for "${term}"`);
-    return;
-  }
-  
-  const typeLabel = type === "bgm" || type === "music" ? "Music" : "SFX";
-  console.log(`\n🔍 ${typeLabel} results for "${term}" (${songs.length} tracks):\n`);
-  for (const s of songs) {
-    const dur = s.duration || `${s.durationTime}s`;
-    const url = type === "bgm" || type === "music"
-      ? `https://artlist.io/royalty-free-music/song/${s.nameForURL}/${s.songId}`
-      : `https://artlist.io/sfx/track/${s.nameForURL}/${s.songId}`;
-    console.log(`  ${s.songId.padEnd(8)} ${s.songName} — ${s.artistName} (${dur})`);
-    console.log(`           ${url}`);
-  }
-  console.log(`\nTo download: node scripts/artlist-dl.mjs grab <url> <name> [bgm|sfx]`);
-}
-
-// CLI
-const [,, cmd, ...args] = process.argv;
-
-if (cmd === "list") {
-  list();
-} else if (cmd === "search" && args.length >= 1) {
-  const [term, type = "sfx", count] = args;
-  search(term, type, count ? Number(count) : 10);
-} else if (cmd === "grab" && args.length >= 2) {
-  const [trackUrl, name, type = "sfx", trim] = args;
-  // Parse track ID and type from URL
-  // SFX: artlist.io/sfx/track/.../81139  |  Music: artlist.io/royalty-free-music/song/.../6000953
-  const sfxMatch = trackUrl.match(/\/sfx\/track\/[^/]+\/(\d+)/);
-  const musicMatch = trackUrl.match(/\/(?:royalty-free-music|song)\/[^/]+\/[^/]+\/(\d+)/);
-  const trackId = sfxMatch?.[1] || musicMatch?.[1];
-  const isSfx = !!sfxMatch || type === "sfx";
-  const isMusic = !!musicMatch || type === "bgm";
-
-  if (!trackId) {
-    console.error("❌ Could not parse track ID from URL. Expected format:");
-    console.error("   SFX:   artlist.io/sfx/track/<name>/<id>");
-    console.error("   Music: artlist.io/royalty-free-music/song/<name>/<id>");
-    process.exit(1);
-  }
-
-  console.log(`🔍 Fetching ${isMusic ? "music" : "sfx"} track #${trackId} via GraphQL API...`);
-  try {
-    const query = isMusic
-      ? `query Songs($ids: [String!]!) { songs(ids: $ids) { songId songName sitePlayableFilePath duration artistName } }`
-      : `query Sfxs($ids: [Int!]!) { sfxs(ids: $ids) { songId songName sitePlayableFilePath duration artistName } }`;
-    const variables = isMusic ? { ids: [trackId] } : { ids: [Number(trackId)] };
-    const body = JSON.stringify({ query, variables });
-    
-    const result = execSync(
-      `curl -s 'https://search-api.artlist.io/v1/graphql' -H 'Content-Type: application/json' -d '${body.replace(/'/g, "'\\''")}'`,
-      { encoding: "utf-8" }
-    );
-    const data = JSON.parse(result);
-    const track = isMusic ? data.data?.songs?.[0] : data.data?.sfxs?.[0];
-    
-    if (!track?.sitePlayableFilePath) {
-      console.error("❌ Track not found or no audio URL available.");
-      process.exit(1);
-    }
-    
-    console.log(`✅ "${track.songName}" by ${track.artistName} (${track.duration})`);
-    const cdnUrl = track.sitePlayableFilePath;
-    const outDir = isMusic ? BGM_DIR : SFX_DIR;
-    const trimSec = trim ? Number(trim) : (isSfx && !isMusic ? 3 : undefined);
-    download(cdnUrl, resolve(outDir, `${name}.mp3`), trimSec);
-  } catch (e) {
-    console.error(`❌ Failed: ${e.message}`);
-    process.exit(1);
-  }
-} else if (cmd === "bgm" && args.length >= 2) {
-  const [url, name] = args;
-  download(url, resolve(BGM_DIR, `${name}.mp3`));
-} else if (cmd === "sfx" && args.length >= 2) {
-  const [url, name, trim] = args;
-  download(url, resolve(SFX_DIR, `${name}.mp3`), trim ? Number(trim) : 3);
-} else {
-  console.log(`
-Usage:
-  node scripts/artlist-dl.mjs search <term> [sfx|bgm] [count]      Search artlist.io
-  node scripts/artlist-dl.mjs grab <trackPageUrl> <name> [bgm|sfx]  Download from track page URL
-  node scripts/artlist-dl.mjs bgm <cdnUrl> <name>                   Download BGM from CDN URL
-  node scripts/artlist-dl.mjs sfx <cdnUrl> <name> [sec]             Download SFX from CDN URL (trim to sec)
-  node scripts/artlist-dl.mjs list                                   List current audio assets
-
-Examples:
-  node scripts/artlist-dl.mjs search "whoosh" sfx
-  node scripts/artlist-dl.mjs search "cinematic epic" bgm
-  node scripts/artlist-dl.mjs grab https://artlist.io/sfx/track/sci-fi-transitions---powerful-whoosh/81139 whoosh sfx
-  node scripts/artlist-dl.mjs grab https://artlist.io/royalty-free-music/song/dominion/6000953 dominion bgm
-  `);
-}