@lalalic/markcut 2.8.0 → 3.0.0

package/B]

@@ -0,0 +1,2 @@
+[main 2b839d7] mermaid.animateEdges=true|[A-
+ 5 files changed, 162 insertions(+), 18 deletions(-)

package/README.md

@@ -48,6 +48,7 @@ storyboard.md  ──[parse]──▶  DescriptiveRoot  ──[compile]──▶
 | **Built-in Mermaid** | `<Mermaid source="..." theme="dark" />` renders Mermaid diagrams as inline SVG. No imports needed |
 | **Styling** | Inline `style` strings on any node for CSS. JSX components use inline React styles |
 | **Live edit** | `--edit` watches the input file, re-runs pipeline, auto-reloads player |
+| **Player language** | Player UI supports English/Chinese. Use `?lang=en` or `?lang=zh` |
 | **Storyboard** | `--storyboard` fast structure preview: replaces TTI/TTV prompts with placeholder components, skips slow generation. Implies `--edit` |
 | **Label mode** | `--label` interactive player with per-scene label input, saves to labels.json |
 | **CLI** | `render`, `preview` commands for MP4 export and Remotion Studio |
@@ -159,6 +160,34 @@ Compound variant labels (like `zh-tiktok`) are split on `-` to form a **variant
 
 The browser player reads `window.VARIANT` from the URL path and fetches the correct compiled data via `/api/video-data?variant=<name>`. A **variant switcher bar** at the top of the player lets you jump between variants instantly.
 
+### Player UI Language (EN / ZH)
+
+The player UI (edit panel, placeholders, tooltips) supports English and Chinese.
+
+- `?lang=en` for English
+- `?lang=zh` for Chinese
+
+Examples:
+
+- `http://localhost:3001?lang=en`
+- `http://localhost:3001?lang=zh`
+
+If `lang` is not provided, the player falls back to browser language (Chinese browsers default to `zh`, otherwise `en`).
+
+### Map Language (EN / ZH)
+
+`map` nodes support `language`/`lang` and `region` keys.
+
+```md
+- map duration:3 lang:zh region:CN waypoints:[31.23,121.47,"上海";39.90,116.40,"北京"]
+- map duration:3 lang:en region:US waypoints:[37.77,-122.41,"SF";34.05,-118.24,"LA"]
+```
+
+Locale shorthand normalization:
+
+- `lang:zh` / `language:zh` → `zh-CN` (default region `CN`)
+- `lang:en` / `language:en` → `en` (default region `US`)
+
 ## `.markcut/` Directory Layout
 
 When you run `preview` or `render`, all generated artifacts live under `.markcut/` next to the source file. With multiple variants, each gets its own subdirectory:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"

package/skills/markcut/SKILL.md

@@ -80,52 +80,15 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Topic | File |
 |-------|------|
 | Markdown descriptive format (primary authoring format) | [docs/markdown-descriptive.md](docs/markdown-descriptive.md) |
+| Built-in components & common npm packages | [docs/components.md](docs/components.md) |
+| Sound effects | [docs/sound-effects.md](docs/sound-effects.md) |
 
 
-## Built-in Components (no imports needed)
 
-These components are available directly in `jsx:".."` fields or importable from the `~~~js imports` block via `@lalalic/markcut/components`:
+## Built-in Components
 
-### `<Markdown />` — render markdown content
-```md
-- component jsx:"<Markdown source='# Hello\n\n**bold** text.' />"
-```
-- Uses `react-markdown` + `remark-gfm` (tables, strikethrough, task lists)
-- Supports `plugins` and `components` props: define custom renderers in imports block and pass them in
-- ` ```mermaid ` code fences inside markdown are automatically rendered as Mermaid diagrams
-- Importable: `import {Markdown} from "@lalalic/markcut/components"`
-
-### `<Mermaid />` — render Mermaid diagrams as SVG
-```md
-- component jsx:"<Mermaid source='graph TD; A-->B; A-->C; B-->D;' />"
-```
-- Theme prop: `theme="default" | "dark" | "forest" | "neutral"` (default: `dark`)
-- Uses `delayRender`/`continueRender` for async rendering — diagram is ready before Remotion captures the frame
-- Errors shown inline in the output
-- Importable: `import {Mermaid} from "@lalalic/markcut/components"`
-
-### Wrapping built-ins in custom components
-```js
-import {Markdown, Mermaid} from "@lalalic/markcut/components"
-
-export function SuperMarkdown({ source }) {
-  return (
-    <Markdown
-      source={source}
-      components={{
-        li: ({children}) => <li style={{color:'#ffd700'}}>{children}</li>,
-      }}
-    />
-  )
-}
-```
+Built-in components available via `@lalalic/markcut/components`. See [docs/components.md](docs/components.md) for full reference.
 
-## Common npm packages (used via imports block)
-- `react-markdown` + `remark-gfm` — already bundled as built-in `<Markdown />` above
-- `remark-toc` — generate table of contents
-- `remark-math` + `rehype-katex` — render math formulas with KaTeX
-- `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
-- `@remotion/starburst` — render starburst animations
 
 ## Golden rule
 - always check stream start and duration to avoid
@@ -133,8 +96,12 @@ export function SuperMarkdown({ source }) {
   - video cut off
   - subtitle mismatch
   - sync issues between audio, video, and subtitles
-- don't set duration for script or stream's duration depending on audio script
-  - markcut resolver will automatically calculate the duration based on the audio script length
-- **don't** rm `.markcut` directory, which served as cache for all generated content. cache will auto update according to the content change. rm `.markcut` will cause all content to be regenerated, which is time consuming and wasteful.
+according to the content change. rm `.markcut` will cause all content to be regenerated, which is time consuming and wasteful.
 - put all manual assets in `assets` folder, such as bgm, logo, watermark, etc. don't put them in `.markcut` folder, which is auto generated and will be deleted when `markcut clean` command is run.
-- `npx @lalalic/markcut preview` stuck until user close the preview window.
+
+### Don'ts
+- **don't** set duration for script or stream's duration depending on audio script
+  - markcut resolver will automatically calculate the duration based on the audio script length
+- **don't** rm `.markcut` directory, which served as cache for all generated content. cache will auto update 
+- **don't** set timeout for `preview`, `vision`, `render` markcut commands, which may take long time to generate medias.
+- **don't** use skill to understand vision media. use `npx @lalalic/markcut vision <folder>`.

package/skills/markcut/docs/components.md

@@ -0,0 +1,89 @@
+## Built-in Components (no imports needed)
+
+These components are available directly in `jsx:".."` fields or importable from the `~~~js imports` block via `@lalalic/markcut/components`:
+
+### `<Markdown />` — render markdown content
+```md
+- component jsx:"<Markdown source='# Hello\n\n**bold** text.' />"
+```
+- Uses `react-markdown` + `remark-gfm` (tables, strikethrough, task lists)
+- Supports `plugins` and `components` props: define custom renderers in imports block and pass them in
+- ` ```mermaid ` code fences inside markdown are automatically rendered as Mermaid diagrams
+- **`highlight`** — array of 0-based list item indices to highlight (e.g., `highlight={[0,2]}`).
+  Matching `<li>` elements receive CSS class `highlight-list-item` with a default golden
+  left-border and background tint. Works for both ordered and unordered lists.
+  ```md
+  <Markdown highlight={[0,2]}
+    source={"1. First item\n2. Second item\n3. Third item\n4. Fourth item"} />
+  ```
+- Importable: `import {Markdown} from "@lalalic/markcut/components"`
+
+### `<Mermaid />` — render Mermaid diagrams as SVG
+```md
+- component jsx:"<Mermaid source='graph TD; A-->B; A-->C; B-->D;' />"
+```
+- Theme prop: `theme="default" | "dark" | "forest" | "neutral"` (default: `dark`)
+- **`highlight`** — node name(s) to highlight. String or array of strings.
+  Toggles CSS class `highlight` on matching SVG elements. The diagram source
+  must define the class via `classDef`:
+  ```md
+  classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px,color:#000
+  ```
+- **`animateEdges`** — edge(s) to animate with a flowing dash effect.
+  `true` = animate all edges. `string[]` = specific edges by source→target alias:
+  ```md
+  animateEdges={["A->B","D->F","F->G"]}
+  ```
+  Animates matching edge `<path>` elements via CSS `stroke-dasharray` + `stroke-dashoffset` keyframes.
+- Source from code fences: use `~~~mermaid` to define the diagram source in a
+  separate block, then reference it as `source={mermaid}` in the JSX:
+  ```md
+  - component id:flowChart duration:12
+    ~~~jsx
+    <Mermaid highlight={highlight} animateEdges={animateEdges}
+             theme='dark' source={mermaid}/>
+    ~~~
+    ~~~mermaid
+    graph TD
+      A["Receive Request"] --> B["Validate Input"]
+      B --> C{"Valid?"}
+      classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px
+    ~~~
+    highlight:"A"
+    animateEdges:true
+  ```
+- Dynamic highlight/edges via events: define `on` specs that mutate the
+  component's registered id:
+  ```md
+  - event duration:3 start:3 on:(start, flowChart.highlight="B")
+  - event duration:3 start:6 on:(start, flowChart.highlight="C")
+  - event duration:3 start:9 on:(start, flowChart.highlight=["D","G"])
+  ```
+- Errors shown inline in the output
+- Importable: `import {Mermaid} from "@lalalic/markcut/components"`
+
+### Wrapping built-ins in custom components
+```js
+import {Markdown, Mermaid} from "@lalalic/markcut/components"
+
+export function SuperMarkdown({ source }) {
+  return (
+    <Markdown
+      source={source}
+      components={{
+        li: ({children}) => <li style={{color:'#ffd700'}}>{children}</li>,
+      }}
+    />
+  )
+}
+```
+
+## Common npm packages (used via imports block)
+- `react-markdown` + `remark-gfm` — already bundled as built-in `<Markdown />` above
+    - `remark-toc` — generate table of contents
+    - `remark-math` + `rehype-katex` — render math formulas with KaTeX
+- `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
+- `@remotion/starburst` — render starburst animations
+- `react-webcam-pro` — render webcam video
+- `react-chartjs-2` — render charts with Chart.js at `https://react-chartjs-2.js.org/components`
+- `@xyflow/react` - render diagrams with `https://reactflow.dev/api-reference`

package/skills/markcut/docs/markdown-descriptive.md

@@ -69,6 +69,7 @@ Where:
 | `audio` | `audio` | Voiceover, BGM, SFX | `src` + (`duration` or `endAt`) |
 | `script "..."` | `audio` | Narration/TTS (shorthand for audio with script) | `script` text (the `"..."` is the primary content) |
 | `component` | `component` | JSX React component | `jsx` (inline or code fence) + `duration` (unless `isBackground`) |
+| `event` | `component` (stub) | **Event-only** — renders nothing, fires JS on registered components at a specific frame | `on:(when, state)` + `start` + `duration` |
 | `rhythm` | `rhythm` | Beat-synced audio with timed children | `src`, `spots`, `children` |
 | `map` | `map` | Animated route visualization | `duration`, `waypoints` |
 | `include` | `include` | Embed external `.md` sub-video | `src` (path to another `.md` file) |
@@ -112,10 +113,13 @@ Fire JS expression at a specific frame to mutate component state.
 ```
 - script "Narration" on:(start, slide.current=0)
 - script "Beat" on:(50%, slide.current++)
+- event duration:3 start:6 on:(start, slide.current=1)
 ```
 
 `when`: `start`/`end`/`50%` (percent) / `2.5s` (seconds value). `state`: any JS expression.
 
+Use the `event` type token to create an **event-only stub** — a node that renders nothing and exists solely to fire an event at a specific time. This avoids boilerplate like `- component duration:3 jsx:"<></>" start:6 on:(...)`.
+
 #### Lists — `spots:[n,n,n]`, `start:n`
 
 ```
@@ -160,8 +164,7 @@ When a property value is too long for a single line (JSX, prompts, scripts, mark
 | `~~~jsx jsx` or `~~~jsx` | `jsx` | Component JSX expression |
 | `~~~prompt prompt` | `prompt` | TTI/TTV generation prompt |
 | `~~~script script` or `~~~script` | `script` | Narration text on audio nodes |
-| `~~~css stylesheet` | `stylesheet` | Global CSS (only valid at root level) |
-| `~~~md <key>` | arbitrary | Markdown content for a specific key (e.g., `source` for `react-markdown`) |
+| `~~~css stylesheet` | `stylesheet` | Global CSS (only valid at root level) || `~~~mermaid` | `mermaid` | Mermaid diagram source (referenced as `{mermaid}` in JSX) || `~~~md <key>` | arbitrary | Markdown content for a specific key (e.g., `source` for `react-markdown`) |
 
 ### 7. Scene Metadata Block
 
@@ -331,6 +334,9 @@ Subtitles are configured at the root level as a VTT overlay. Set via `subtitle:`
 | `zoom` | int (default 10) | map |
 | `center` | `{lat:n,lng:n}` JSON | map |
 | `mapType` | `roadmap\|satellite\|hybrid\|terrain` | map |
+| `language` | map label/UI language. Supports `en`, `zh`, `zh-CN`, etc. | map |
+| `lang` | alias of `language` (e.g. `lang:zh`) | map |
+| `region` | region code hint (e.g. `CN`, `US`) | map |
 | `routeMarker` | emoji string e.g. `"🚗"` | map |
 | `title` | display title | scene |
 | `instruction` | visual intent / style / any prompt; NOT rendered | any |
@@ -433,6 +439,15 @@ When: animated route. Required: `duration`, `waypoints`.
 
 `- map duration:3 travelMode:DRIVING waypoints:[37.77,-122.41,"SF";34.05,-118.24,"LA"]`
 
+Language and region are optional:
+
+`- map duration:3 language:zh region:CN waypoints:[31.23,121.47,"上海";39.90,116.40,"北京"]`
+
+Shorthand aliases:
+
+- `language:zh` or `lang:zh` → normalized to `zh-CN` with `region:CN` default
+- `language:en` or `lang:en` → keeps English labels with `region:US` default
+
 ### `include`
 
 When: embed an external markdown file as a sub-video. The sub-video is

package/skills/markcut/docs/sound-effects.md

@@ -0,0 +1,45 @@
+# 🎧 Remotion Sound Effects
+
+## 1. URL Construction
+
+All sound effect URLs follow this pattern:
+
+`https://remotion.media/<name>.wav`
+
+such as `https://remotion.media/sanctuary-guardian-what.wav`
+---
+
+## 2. Available Names
+
+whip  
+whoosh  
+page-turn  
+switch  
+mouse-click  
+shutter-modern  
+shutter-old  
+ding  
+bruh  
+vine-boom  
+windows-xp-error  
+fah  
+spongebob-fail  
+omg-hell-nah  
+price-is-right-fail  
+romance-meme  
+bone-crack  
+anime-wow  
+yippee  
+loading-lag  
+wilhelm-scream  
+mac-quack  
+skedaddle  
+snapchat-notification  
+nelly-ahh  
+sanctuary-guardian-what  
+minecraft-hurt  
+oh-my-god-vine  
+illuminati-confirmed  
+dramatic-boomer  
+triggered  
+record-scratch  

package/src/components/Markdown.tsx

@@ -11,39 +11,153 @@ import { Mermaid } from "./Mermaid";
  *
  * The `source` prop is the markdown string to render.
  *
+ * `highlight` is an array of 0-based list item indices to highlight.
+ * Works for both ordered (`ol`) and unordered (`ul`) lists. Matching
+ * `<li>` elements get CSS class `highlight-list-item` (intended for use
+ * with a `classDef` or a custom stylesheet).
+ *
  * Built-in — no imports or frontmatter registration needed.
  */
 export interface MarkdownProps {
-    children?: string;
+  children?: string;
   source?: string;
   className?: string;
   plugins?: any[];
   components?: any;
+  /** 0-based indices of list items to highlight. */
+  highlight?: number[];
+}
+
+// Context to pass highlightList down to list renderers
+const ListCtx = React.createContext<number[]>([]);
+
+function OrderedList({
+  children,
+  ...props
+}: React.ComponentPropsWithoutRef<"ol">) {
+  const hl = React.useContext(ListCtx);
+  const items = React.Children.toArray(children).filter(
+    (c): c is React.ReactElement => React.isValidElement(c) && c.type === "li",
+  );
+  return (
+    <ol {...props}>
+      {items.map((child, i) => {
+        if (hl.includes(i)) {
+          return React.cloneElement(child, { className: "highlight-list-item", key: (child as any).key } as any);
+        }
+        return child;
+      })}
+    </ol>
+  );
+}
+
+function UnorderedList({
+  children,
+  ...props
+}: React.ComponentPropsWithoutRef<"ul">) {
+  const hl = React.useContext(ListCtx);
+  const items = React.Children.toArray(children).filter(
+    (c): c is React.ReactElement => React.isValidElement(c) && c.type === "li",
+  );
+  return (
+    <ul {...props}>
+      {items.map((child, i) => {
+        if (hl.includes(i)) {
+          return React.cloneElement(child, { className: "highlight-list-item", key: (child as any).key } as any);
+        }
+        return child;
+      })}
+    </ul>
+  );
 }
 
-export function Markdown({ children, source=children, className, plugins, components }: MarkdownProps) {
+export function Markdown({
+  children,
+  source = children,
+  className,
+  plugins,
+  components: propComponents,
+  highlight,
+}: MarkdownProps) {
+  const hl = React.useMemo(() => highlight ?? [], [highlight]);
+
+  // Inject default styles once
+  React.useEffect(() => {
+    const id = "markcut-markdown-defaults";
+    if (document.getElementById(id)) return;
+    const el = document.createElement("style");
+    el.id = id;
+    el.textContent = `
+      .highlight-list-item {
+        background: rgba(255, 215, 0, 0.15);
+        border-left: 3px solid #ffd700;
+        padding-left: 8px;
+        border-radius: 0 4px 4px 0;
+      }
+      .slide {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding: 24px;
+        text-align: center;
+      }
+      .slide h1 { font-size: 2em; margin: 0.4em 0; font-weight: 700; }
+      .slide h2 { font-size: 1.6em; margin: 0.35em 0; font-weight: 600; }
+      .slide h3 { font-size: 1.3em; margin: 0.3em 0; font-weight: 600; }
+      .slide p { margin: 0.6em 0; line-height: 1.6; }
+      .slide ul, .slide ol { margin: 0.5em 0; padding-left: 1.5em; text-align: left; }
+      .slide li { margin: 0.3em 0; }
+      .slide blockquote {
+        margin: 0.6em 0;
+        padding: 0.4em 1em;
+        border-left: 3px solid rgba(255,255,255,.3);
+        font-style: italic;
+        opacity: .85;
+      }
+      .slide code {
+        background: rgba(255,255,255,.08);
+        padding: 0.15em 0.4em;
+        border-radius: 4px;
+        font-size: 0.9em;
+      }
+      .slide pre { margin: 0.6em 0; text-align: left; width: 100%; }
+      .slide a { color: #4a9eff; text-decoration: none; }
+      .slide a:hover { text-decoration: underline; }
+    `;
+    document.head.appendChild(el);
+    return () => { document.getElementById(id)?.remove(); };
+  }, []);
+
+  const mergedComponents = React.useMemo(
+    () => ({
+      ...propComponents,
+      ol: OrderedList,
+      ul: UnorderedList,
+      pre: ({ children: preChildren }: { children: React.ReactNode }) => {
+        const code = React.Children.toArray(preChildren)[0] as React.ReactElement<any>;
+        if (code?.props?.className === "language-mermaid") {
+          return <Mermaid source={String(code.props.children)} />;
+        }
+        if (propComponents?.pre) {
+          return (propComponents.pre as any)({ children: preChildren });
+        }
+        return <pre>{preChildren}</pre>;
+      },
+    }),
+    [propComponents],
+  );
+
   return (
-    <div className={className}>
-      <ReactMarkdown
-        remarkPlugins={React.useMemo(() => [remarkGfm, ...(plugins || [])], [plugins])}
-        components={React.useMemo(
-          () => ({
-            ...components,
-            pre: ({ children }) => {
-                const code = React.Children.toArray(children)[0] as React.ReactElement<any>;
-                if (code?.props?.className === 'language-mermaid') {
-                    return <Mermaid source={String(code.props.children)} />
-                } else if (components.pre) {
-                  return components.pre({ children });
-                }
-                return <pre>{children}</pre>;
-              },
-          }),
-          [components]  
-        )}
-      >
-        {source}
-      </ReactMarkdown>
-    </div>
+    <ListCtx.Provider value={hl}>
+      <div className={className}>
+        <ReactMarkdown
+          remarkPlugins={React.useMemo(() => [remarkGfm, ...(plugins || [])], [plugins])}
+          components={mergedComponents}
+        >
+          {source}
+        </ReactMarkdown>
+      </div>
+    </ListCtx.Provider>
   );
 }