@lalalic/markcut 1.0.0

package/docs/templates.md

@@ -0,0 +1,52 @@
+# 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/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@lalalic/markcut",
+  "version": "1.0.0",
+  "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
+  "bin": {
+    "markcut": "./src/render/cli.mjs"
+  },
+  "type": "module",
+  "main": "./src/entry.tsx",
+  "exports": {
+    ".": "./src/entry.tsx",
+    "./schema": "./src/schema/index.ts",
+    "./themes": "./src/themes/index.tsx",
+    "./descriptive": "./src/descriptive/compiler.ts",
+    "./descriptive-markdown": "./src/descriptive/markdown.ts",
+    "./descriptive-resolve": "./src/descriptive/resolve.ts"
+  },
+  "scripts": {
+    "render": "node src/render/cli.mjs render",
+    "render:all": "node src/render/cli.mjs render --aspect all",
+    "render:demo": "node src/render/cli.mjs render src/demo-components.json --aspect all",
+    "templates": "node src/render/cli.mjs templates",
+    "preview": "node src/render/cli.mjs preview",
+    "verify": "node src/render/cli.mjs verify",
+    "resolve": "node src/render/cli.mjs resolve",
+    "render:pixelle": "remotion render examples/pixelle/index.tsx Root out/pixelle-asset-default.mp4 --props=./examples/pixelle/asset-default.json",
+    "render:gallery": "remotion render examples/pixelle/index.tsx Root out/pixelle-gallery.mp4 --props=./examples/pixelle/gallery.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config tests/vitest.config.ts",
+    "test:integration": "vitest run --config tests/vitest.config.ts tests/render.test.ts",
+    "test:watch": "vitest --config tests/vitest.config.ts",
+    "build": "scripts/build-pipeline.sh && scripts/build-player.sh",
+    "vision": "node src/render/cli.mjs vision",
+    "push": "GIT_SSH_COMMAND=\"ssh -i ~/.ssh/id_ed25519_1 -o IdentitiesOnly=yes\" git push"
+  },
+  "dependencies": {
+    "@babel/standalone": "^8.0.3",
+    "@remotion/cli": "4.0.469",
+    "@remotion/media-parser": "4.0.469",
+    "@remotion/media-utils": "4.0.469",
+    "@remotion/player": "^4.0.469",
+    "@remotion/transitions": "4.0.469",
+    "@vis.gl/react-google-maps": "^1.8.3",
+    "immer": "^10.1.1",
+    "js-yaml": "^5.2.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-jsx-parser": "^2.4.1",
+    "react-markdown": "^10.1.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "remotion": "4.0.469",
+    "systemjs": "^6.15.1",
+    "unified": "^11.0.5",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/remotion.config.ts

@@ -0,0 +1,5 @@
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("jpeg");
+Config.setOverwriteOutput(true);
+Config.setEntryPoint("./src/index.ts");

package/scripts/artlist-dl.mjs

@@ -0,0 +1,190 @@
+#!/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
+  `);
+}

package/scripts/build-pipeline.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Build the server-side pipeline bundle (descriptive resolve + compile).
+# Run from project root: bash scripts/build-pipeline.sh
+set -e
+
+cd "$(dirname "$0")/.."
+OUT_DIR="src/player"
+OUT_FILE="$OUT_DIR/pipeline.mjs"
+
+echo "Building pipeline bundle..."
+npx esbuild src/player/pipeline.ts \
+  --bundle \
+  --outfile="$OUT_FILE" \
+  --format=esm \
+  --platform=node \
+  --target=node18 \
+  2>&1
+
+echo "Done → $OUT_FILE ($(wc -c < "$OUT_FILE") bytes)"

package/scripts/build-player.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Build the browser player bundle.
+# Run from project root: bash scripts/build-player.sh
+set -e
+
+cd "$(dirname "$0")/.."
+OUT_DIR="src/player/bundle"
+mkdir -p "$OUT_DIR"
+
+echo "Building browser player..."
+npx esbuild src/player/browser.tsx \
+  --bundle \
+  --outfile="$OUT_DIR/player.js" \
+  --format=esm \
+  --platform=browser \
+  --target=es2020 \
+  --define:process.env.NODE_ENV='"production"' \
+  2>&1
+
+echo "Done → $OUT_DIR/player.js ($(wc -c < "$OUT_DIR/player.js") bytes)"

package/src/Root.tsx

@@ -0,0 +1,55 @@
+import { Composition, getInputProps } from "remotion";
+import { MarkCut } from "./entry";
+import { getDurationInSeconds } from "./utils";
+import { root as rootSchema } from "./schema";
+
+const RootComposition = (props: any) => (
+  <MarkCut
+    {...props}
+    compose={{
+      ...(props.compose ?? {}),
+      components: props.compose?.components ?? {},
+    }}
+  />
+);
+
+export const RemotionRoot: React.FC = () => {
+  const inputProps = getInputProps() as { root?: unknown };
+  const data = inputProps.root as any;
+  if (data) {
+    // Dynamic composition from --props
+    const parsed = rootSchema.parse(data);
+    const fps = parsed.fps;
+    const width = parsed.width;
+    const height = parsed.height;
+    const durationInSeconds = getDurationInSeconds(parsed as any, true) || 1;
+    const durationInFrames = Math.max(1, Math.ceil(durationInSeconds * fps));
+
+    return (
+      <Composition
+        id="Root"
+        component={RootComposition as any}
+        durationInFrames={durationInFrames}
+        fps={fps}
+        width={width}
+        height={height}
+        defaultProps={{
+          root: data,
+        } as any}
+      />
+    );
+  }
+
+  // Static 10s placeholder composition for the studio UI
+  return (
+    <Composition
+      id="Root"
+      component={RootComposition as any}
+      durationInFrames={300}
+      fps={30}
+      width={1080}
+      height={1920}
+      defaultProps={{}}
+    />
+  );
+};

package/src/config.mjs

@@ -0,0 +1,88 @@
+/**
+ * Default CLI templates and constants for the markcut pipeline.
+ *
+ * All CLIs support {input} / {prompt} / {output} placeholders as documented.
+ * These can be overridden at runtime via --itt, --vtt, --stt, --tts, --agent flags,
+ * or via MARKCUT_*_CLI environment variables.
+ *
+ * @module
+ */
+
+// ── Media type sets ───────────────────────────────────────────────────────
+
+export const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tiff", ".heic", ".avif"]);
+export const VIDEO_EXTS = new Set([".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v", ".wmv"]);
+
+// ── Normalization limits ──────────────────────────────────────────────────
+
+/** Longest side in px for normalized images. */
+export const MAX_IMAGE_DIMENSION = Number(process.env.MARKCUT_MAX_IMAGE_DIMENSION) || 384;
+/** Max seconds for normalized video clip. */
+export const MAX_VIDEO_DURATION = Number(process.env.MARKCUT_MAX_VIDEO_DURATION) || 60;
+/** Max height/width for normalized video. */
+export const MAX_VIDEO_DIMENSION = Number(process.env.MARKCUT_MAX_VIDEO_DIMENSION) || 360;
+
+// ── Vision pipeline CLI templates ─────────────────────────────────────────
+
+/**
+ * Image-to-text (ITT) CLI.
+ * Reads an image file and returns a text description.
+ * Placeholders: {input}=image path(s), {prompt}=description prompt.
+ * Override with MARKCUT_ITT_CLI env var.
+ */
+export const DEFAULT_ITT_CLI =
+  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';
+
+/**
+ * Seconds between sampled video frames when using the default ITT-based VTT.
+ */
+export const DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE_INTERVAL) || 5;
+
+/**
+ * Video-to-text (VTT) CLI — direct video model.
+ * When set to null/empty, falls back to ITT via frame extraction.
+ * Placeholders: {input}=video path, {prompt}=description prompt.
+ * Override with MARKCUT_VTT_CLI env var.
+ */
+export const DEFAULT_VTT_CLI =
+  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}\'';
+
+/**
+ * Speech-to-text (STT) CLI.
+ * Extracts audio and generates VTT subtitles.
+ * Placeholders: {input}=audio path, {output}=output directory.
+ * Override with MARKCUT_STT_CLI env var.
+ * Used by both vision and render pipelines.
+ */
+export const DEFAULT_STT_CLI =
+  process.env.MARKCUT_STT_CLI ||
+  'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
+
+/**
+ * Text-to-speech (TTS) CLI.
+ * Generates audio from text.
+ * Placeholders: {input}=text, {output}=audio file path.
+ * Override with MARKCUT_TTS_CLI env var.
+ * Used by both vision and render pipelines.
+ */
+export const DEFAULT_TTS_CLI =
+  process.env.MARKCUT_TTS_CLI ||
+  'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
+
+/**
+ * Default agent CLI — general-purpose text LLM.
+ * Used for text-only tasks like detect-scenes.
+ * Placeholders: {prompt}=the prompt text.
+ * Override with MARKCUT_AGENT_CLI env var.
+ */
+export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
+
+// ── Render-only pipeline CLI templates ─────────────────────────────────────
+// These are specific to the render pipeline (no vision pipeline equivalent).
+
+export const DEFAULT_TTI_CLI =
+  process.env.MARKCUT_TTI_CLI ||
+  'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}"';
+export const DEFAULT_TTV_CLI = process.env.MARKCUT_TTV_CLI || '';

package/src/context/EventContext.tsx

@@ -0,0 +1,168 @@
+/**
+ * Event System — cross-node state event context.
+ *
+ * Lets any node in the stream tree mutate a named component's state at runtime
+ * via `on` event specs. Events fire at specific frames (start, end, 50%, 2.5s)
+ * and evaluate JS expressions with registered component proxies in scope.
+ *
+ * Usage in markdown:
+ *   - component id:slide1 jsx:"<Slide current={current}>{source}</Slide>"
+ *   - script "Narration 1" on:[{when:start, state:"slide1.current=0"}]
+ *   - script "Narration 2" on:[{when:start, state:"slide1.current++"}]
+ */
+
+import * as React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import type { EventSpec } from "../schema/index";
+
+interface EventContextValue {
+  register: (id: string, setState: (partial: Record<string, any>) => void) => void;
+  unregister: (id: string) => void;
+  evaluate: (code: string) => void;
+}
+
+const EventContext = React.createContext<EventContextValue | null>(null);
+
+/**
+ * Creates a Proxy wrapper around a target object.
+ * The `set` trap calls `setState` so React re-renders when the proxy is mutated.
+ */
+function createComponentProxy(
+  target: Record<string, any>,
+  setState: (partial: Record<string, any>) => void,
+): Record<string, any> {
+  return new Proxy(target, {
+    set(obj, prop, value) {
+      obj[prop] = value;
+      setState({ [prop]: value });
+      return true;
+    },
+    get(obj, prop) {
+      if (typeof prop === "string" && prop in obj) return obj[prop];
+      return undefined;
+    },
+  });
+}
+
+/**
+ * Wraps the render tree, maintaining a registry of named component proxies.
+ * Each registered component gets a Proxy whose setter triggers React re-render.
+ */
+export function EventProvider({ children }: { children: React.ReactNode }) {
+  const registryRef = React.useRef<
+    Map<string, { proxy: Record<string, any>; setState: (partial: Record<string, any>) => void }>
+  >(new Map());
+
+  const register = React.useCallback(
+    (id: string, setState: (partial: Record<string, any>) => void) => {
+      const target: Record<string, any> = {};
+      const proxy = createComponentProxy(target, setState);
+      registryRef.current.set(id, { proxy, setState });
+    },
+    [],
+  );
+
+  const unregister = React.useCallback((id: string) => {
+    registryRef.current.delete(id);
+  }, []);
+
+  const evaluate = React.useCallback((code: string) => {
+    const scope: Record<string, any> = {};
+    for (const [id, reg] of registryRef.current) {
+      scope[id] = reg.proxy;
+    }
+    const keys = Object.keys(scope);
+    const vals = Object.values(scope);
+    try {
+      const fn = new Function(...keys, code);
+      fn(...vals);
+      console.info(`Event evaluation succeeded: "${code}"`);
+    } catch (err) {
+      console.warn(`Event evaluation failed: "${code}"`, err);
+    }
+  }, []);
+
+  const value = React.useMemo(
+    () => ({ register, unregister, evaluate }),
+    [register, unregister, evaluate],
+  );
+
+  return (
+    <EventContext.Provider value={value}>
+      {children}
+    </EventContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the event context.
+ */
+export function useEventContext(): EventContextValue {
+  const ctx = React.useContext(EventContext);
+  if (!ctx) {
+    throw new Error("useEventContext must be used within an EventProvider");
+  }
+  return ctx;
+}
+
+/**
+ * Convert a `when` string to an absolute frame number.
+ *
+ * Supported formats:
+ *   'start'   → 0
+ *   'end'     → durationInFrames
+ *   '50%'     → 50% of durationInFrames
+ *   '2.5s'    → 2.5 * fps
+ */
+export function resolveWhenToFrame(
+  when: string,
+  durationInFrames: number,
+  fps: number,
+): number {
+  if (when === "start") return 0;
+  if (when === "end") return durationInFrames;
+
+  // Percentage: "50%", "100%"
+  const pct = /^(\d+(?:\.\d+)?)%$/.exec(when);
+  if (pct) {
+    return Math.floor((Number(pct[1]) / 100) * durationInFrames);
+  }
+
+  // Seconds: "2.5s", "0s"
+  const sec = /^(\d+(?:\.\d+)?)s$/.exec(when);
+  if (sec) {
+    return Math.floor(Number(sec[1]) * fps);
+  }
+
+  console.warn(`Unknown when format: "${when}", defaulting to start`);
+  return 0;
+}
+
+/**
+ * Hook that fires an event at the correct frame.
+ *
+ * @param on - A single event spec from the stream node
+ * @param durationInFrames - Duration of the node in frames (used to compute target frame)
+ */
+export function useFrameEvents(
+  on: EventSpec | undefined,
+  durationInFrames: number,
+): void {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const { evaluate } = useEventContext();
+  const handledRef = React.useRef(false);
+
+  React.useEffect(() => {
+    if (!on || durationInFrames <= 0) return;
+
+    const targetFrame = resolveWhenToFrame(on.when, durationInFrames, fps);
+    if (frame === targetFrame && !handledRef.current) {
+      handledRef.current = true;
+      evaluate(on.state);
+    }
+
+    // Reset so event can fire again if component re-mounts
+    if (frame > targetFrame) handledRef.current = false;
+  }, [frame, on, durationInFrames, fps, evaluate]);
+}