@lalalic/markcut 1.2.0 → 2.0.0

package/AGENTS.md

@@ -63,8 +63,12 @@ src/
 ├── render/cli.mjs         → CLI entry
 ├── render/tts.ts          → TTS via CLI template + variable substitution
 ├── player/pipeline.mjs    → Bundled pipeline (server imports this)
-├── player/server.mjs      → --edit server
-├── player/label-server.mjs→ --label server
+├── player/server.mjs      → Unified server (--edit, --label, preview)
+├── player/components/      → React control components (edit, label, variant bar)
+│   ├── index.ts
+│   ├── EditControls.tsx
+│   ├── LabelControls.tsx
+│   └── VariantBar.tsx
 └── tests/                 → Vitest integration tests
 ```
 
@@ -107,22 +111,22 @@ The tree is validated by Zod and rendered by Remotion via recursive React compon
 | **Series** (`isSeries:true`) | Children play sequentially. Optional `transition` (fade/slide/wipe/flip/clockWipe) + `transitionTime` (default 0.5s). |
 | **Parallel** (`isSeries:false`) | Children play simultaneously. Duration = max child duration. |
 | **Background** (`isBackground:true`) | Loops for parent duration. Excluded from duration calculation. |
-| **Actions** | Every leaf has `actions[{start, end, startFrom?, endAt?, loop?, volume?, style?}]` — seconds relative to parent. |
+| **Timing** | Every leaf carries base fields `start`/`end` (seconds, relative to parent) + optional `startFrom`/`endAt` (source trim) + `duration` (convenience). `end` is the source of truth; `duration` normalizes to `end = start + duration` when `end` is absent. Inside series parents `start` is 0 (positioning is implicit). |
 | **Scene** (`type:"scene"`) | UI storyboard card; engine treats as folder. Has `name` + `description` + `script`. |
 
 ### Duration Calculation
 
 Computed by `getDurationInSeconds()` in `src/utils/index.ts`:
-- **Leaf nodes**: duration = last action's `end` value
+- **Leaf nodes**: duration = `leafEnd(stream)` = `end ?? (start + duration)` (single deterministic read; `start`/`end`/`duration` live on the base node)
 - **Series**: sum of children durations minus transition overlaps
 - **Parallel**: max of children durations
 - **Background children**: excluded from calculation
-- **Include with `src`**: treated as leaf (duration from action end)
+- **Include with `src`**: treated as leaf (duration from base `end`)
 - Sets `durationInSeconds` on every node as a side effect
 
 ### 12 Stream Types
 
-All types share base fields from `BaseShape`: `id`, `name`, `title`, `description`, `script`, `src`, `style`, `visible`, `isBackground`, `durationInSeconds`.
+All types share base fields from `BaseShape`: `id`, `name`, `title`, `description`, `script`, `src`, `style`, `visible`, `isBackground`, `start`, `end`, `duration`, `startFrom`, `endAt`, `durationInSeconds`.
 
 | Type | Purpose | Key Fields |
 |------|---------|------------|
@@ -130,8 +134,8 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 | `folder` | Group children | `isSeries`, `transition`, `children[]` |
 | `scene` | Storyboard node (alias for folder) | `name`, `description`, `script`, `children[]` |
 | `image` | Still photo | `src`, `fit` (contain/cover/fill) |
-| `video` | Video clip | `src`, `volume`, `playbackRate` |
-| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent) |
+| `video` | Video clip | `src`, `volume`, `playbackRate`, `loop` |
+| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent), `loop` |
 | `subtitle` | Text overlay | `src` (text/VTT) or `cues[]`, `fontSize`, `style` |
 | `component` | React component | `componentName`, `props`, `src` (remote ESM) |
 | `effect` | CSS animation wrapper | `animation`, `customKeyframes`, `children[]` |
@@ -155,7 +159,7 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 ### Video.tsx — startFrom/endAt Trimming
 
 - Uses Remotion `<OffthreadVideo>` for CPU-efficient video decoding
-- `startFrom` / `endAt` on actions trim the source video (in seconds)
+- `startFrom` / `endAt` on the base node trim the source video (in seconds)
 - `playbackRate` is capped at 1 (`Math.min(1, ...)`) so source longer than timeline plays at normal speed and is truncated by the Sequence
 - **Critical formula**: `OffthreadVideo endAt = startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)`
   This sets `endAt` beyond the actual source end when `playbackRate < 1`, which prevents Remotion from rendering blank frames before the Sequence ends.
@@ -183,7 +187,7 @@ node src/render/cli.mjs templates
 - `--edit` flag starts a live-reload loop: edit JSON → player auto-refreshes
 - `--label` flag starts a labeling UI for selecting and annotating media
 - `--port` flag sets the server port (default 3001)
-- Two implementations: `server.mjs` (Remotion Player) and `label-server.mjs` (label input overlay)
+- Unified server: `server.mjs` serves all modes (preview, edit, label). React control components in `components/`.
 
 ## Testing
 
@@ -235,13 +239,13 @@ npx vitest run tests/render.test.ts -t "Test Name"  # single test
 ## Known Issues & Gotchas
 
 1. **TransitionSeries + isBackground**: `TransitionSeries` from `@remotion/transitions` rejects non-Sequence/Transition children. Don't mix `isBackground:true` children with `isSeries:true, transition:"..."` at the same level.
-2. **Subvideo internal actions**: Should use `start:0` when placed in a series parent (series handles positioning).
-3. **Video endAt formula**: Must be `startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)` — changing to `endAt_source * fps` breaks slow-motion playback.
-4. **`signalstats` ffmpeg filter**: Doesn't output YAVG on all systems; use file size as proxy for visual content.
-5. **Asset paths**: Local files are resolved via `staticFile()` — files go in `public/` and are referenced without the `public/` prefix.
-6. **Map rendering**: Depends on external tile availability; may produce blank frames offline.
-7. **CLI md render needs three things preview gets for free**: (a) `parseMarkdownVariants(raw)` (returns `{base, variants}`) — `parseMarkdownDescriptive` returns the root directly; (b) bundling the ` ```js imports ``` ` block via `bundleFromEntries` and setting `root.imports` (otherwise jsx components are unregistered → slides render as unstyled black frames); (c) staging `.markcut/` assets into `public/.render-assets/` and rewriting srcs to relative paths (remotion render only serves its publicDir). All three live in `src/render/cli.mjs`; the import-map shim for shared react/remotion instances is `src/utils/component-import-map.ts` (must stay in sync with `player/browser.tsx` + `bundler.mjs getSharedExternals`).
-8. **Publishing**: verify `npx @lalalic/markcut render <md>` from a clean temp dir before/after publish — v1.1.1 shipped with cli.mjs/pipeline.mjs out of sync and md rendering was completely broken. Also beware stale npx caches (`~/.npm/_npx`) silently running old code.
+2. **Video endAt formula**: Must be `startFrom_frames + ((endAt_source - startFrom_source) * fps / playbackRate)` — changing to `endAt_source * fps` breaks slow-motion playback.
+3. **`signalstats` ffmpeg filter**: Doesn't output YAVG on all systems; use file size as proxy for visual content.
+4. **Asset paths**: Local files are resolved via `staticFile()` — files go in `public/` and are referenced without the `public/` prefix.
+5. **Map rendering**: Depends on external tile availability; may produce blank frames offline.
+6. **CLI md render needs three things preview gets for free**: (a) `parseMarkdownVariants(raw)` (returns `{base, variants}`) — `parseMarkdownDescriptive` returns the root directly; (b) bundling the ` ```js imports ``` ` block via `bundleFromEntries` and setting `root.imports` (otherwise jsx components are unregistered → slides render as unstyled black frames); (c) staging `.markcut/` assets into `public/.render-assets/` and rewriting srcs to relative paths (remotion render only serves its publicDir). All three live in `src/render/cli.mjs`; the import-map shim for shared react/remotion instances is `src/utils/component-import-map.ts` (must stay in sync with `player/browser.tsx` + `bundler.mjs getSharedExternals`).
+7. **Publishing**: verify `npx @lalalic/markcut render <md>` from a clean temp dir before/after publish — v1.1.1 shipped with cli.mjs/pipeline.mjs out of sync and md rendering was completely broken. Also beware stale npx caches (`~/.npm/_npx`) silently running old code.
+8. **Clean break from `actions[]`**: leaf timing is now flat base fields (`start`/`end`/`duration`/`startFrom`/`endAt`). Old compiled JSON carrying `actions:[{...}]` no longer parses into a duration — re-compile from markdown/descriptive JSON, or migrate `actions[0]` → flat fields (drop `id`/`volume`/`style`/`effectId`; keep `start`/`end`/`startFrom`/`endAt`/`loop`).
 
 ## 3-Level Authoring Workflow (see SKILL.md)
 
@@ -261,6 +265,24 @@ Every node carries an optional `script` field for narration/dialogue text. The p
 
 This separates concerns: `script` = authoring text (human/agent-friendly), `subtitle` = rendered output (timed VTT cues).
 
+### Multi-turn Dialogue
+
+When `script` text contains multiple `SpeakerName: text` lines (2+), the pipeline auto-expands it into a multi-turn dialogue. Each line becomes a separate audio node with `speaker` field, wrapped in a `series` container for sequential playback.
+
+```md
+- script "Ray: Hello everyone
+Alice: Good day to you
+Ray: Let's begin"
+```
+
+Per-speaker voices are configured via `voices` on root. Each value is extra CLI flags appended to the TTS template:
+
+```md
+voices:{"Ray":"--voice en-US-GuyNeural","Alice":"--voice en-US-JennyNeural"}
+```
+
+The speaker name is matched against `voices` map and the extra flags are appended to the TTS CLI template, naturally supporting voice cloning or edge-tts features (rate, pitch, etc.). Subtitles include the speaker prefix (`Ray: Hello everyone`).
+
 ## Dependencies
 
 - **Remotion 4.0.469** — core rendering engine

package/README.md

@@ -201,10 +201,14 @@ src/
 │   ├── cli.mjs            ← CLI entry point
 │   └── tts.ts             ← TTS via CLI template + variable substitution
 ├── player/
-│   ├── server.mjs         ← --edit player server
-│   ├── label-server.mjs   ← --label player server
+│   ├── server.mjs         ← Unified server (--edit, --label, preview)
+│   ├── components/        ← React control components for all modes
+│   │   ├── index.ts
+│   │   ├── EditControls.tsx
+│   │   ├── LabelControls.tsx
+│   │   └── VariantBar.tsx
 │   ├── pipeline.ts        ← Pipeline entry (bundled to pipeline.mjs)
-│   └── browser.tsx        ← Browser player (bundled with esbuild)
+│   └── browser.tsx        ← Browser player (React, bundled to player.js)
 ├── utils/                 ← Duration calc, VTT parser, helpers
 └── tests/                 ← Vitest integration tests
 ```

package/SKILL.md

@@ -58,8 +58,6 @@ some common issues (photo or video can't be displayed, audio missing), take belo
   - `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/edit-mode.md

@@ -177,7 +177,7 @@ The tree description walks the JSON recursively, showing:
 - **Nesting depth** via indentation
 - **Type** and **id/name** of each node
 - **Key fields** (dimensions, fps, theme, series/parallel, transitions)
-- **Timing** from actions (`[startend]`)
+- **Timing** from leaf span (`[start→end]`)
 - **isBackground** flag (`[bg]`)
 - **Component props** and node-specific fields (fontSize, fit, style, volume, etc.)
 

package/docs/label-mode.md

@@ -36,7 +36,7 @@ Labels are saved to the source file.
             "id": "scene-1-media",
             "type": "image",
             "src": "/media/photo.jpg",
-            "actions": [{ "start": 0, "end": 5 }],
+            "start": 0, "end": 5,
             "description": "Best group shot from the campfire"
           }
         ]
@@ -49,7 +49,7 @@ Labels are saved to the source file.
             "id": "scene-2-media",
             "type": "video",
             "src": "/media/clip.mp4",
-            "actions": [{ "start": 0, "end": 5 }],
+            "start": 0, "end": 5,
             "description": "Sunset timelapse — use for intro"
           }
         ]
@@ -94,12 +94,14 @@ Stream tree JSON (labels.json)
 
 ## Implementation
 
-Source: `src/player/label-server.mjs`
+Source: `src/player/server.mjs` (unified server, use `--label` flag)
+UI controls: `src/player/components/LabelControls.tsx` (React component)
 
 - Built on Node.js `http` module (no Express dependency)
 - Serves bundled `player.js` (esbuild output from `src/player/browser.tsx`)
 - Labels saved atomically to disk on each POST
-- Accepts stream tree JSON only (no media folder mode)
+- Supports stream tree JSON, descriptive JSON, and markdown input
+- React components in `src/player/components/` replace the old HTML-based `ui/` directory
 
 ## Reference
 

package/docs/markdown-descriptive.md

@@ -174,7 +174,9 @@ For compatibility, `import { Name } from "spec"` also works and produces the sam
 | `title` | display title | scene |
 | `instruction` | visual intent / style / any prompt; NOT rendered | any |
 | `script` | narration/dialogue text; TTS source; NOT rendered directly | audio | Only on audio nodes — see Narration section below |
-| `tts` | CLI template string; per-scene TTS override (overrides root `tts`) | root, scene |
+| `speaker` | speaker name for multi-turn dialogue; set automatically by dialogue expansion | audio | Used for per-speaker voice lookup and subtitle prefix |
+| `voices` | JSON object mapping speaker names to extra TTS CLI flags e.g. `{"Ray":"--voice en-US-GuyNeural"}` | root | Flags are appended to the resolved TTS CLI template |
+| `tts` | CLI template string e.g. `"edge-tts --voice en-US-GuyNeural --text {input} --write-media {output}"` | root | Set once at the root level; all TTS uses this template |
 | `metadata` | arbitrary metadata string | root |
 | `stylesheet` | global CSS string; selectors use `.className` on elements | root |
 | `style` | inline CSS applied to the node's container div e.g. `"border-radius:12px"` | any |
@@ -254,6 +256,37 @@ For longer text, use an indented code fence:
 
 All three patterns produce an `audio` node with a `script` field. The pipeline's TTS resolver (`resolveScripts`) picks up these nodes, generates speech audio files, and sets the `src` field to the output path. The `script` field is consumed by the resolver and is not present in the compiled stream tree.
 
+#### Multi-turn Dialogue
+
+When a `script` contains multiple lines matching `SpeakerName: text` format, the pipeline automatically expands it into a multi-turn dialogue where each line becomes a separate audio node with its own TTS generation. This allows different speakers to have different voices.
+
+```md
+- script "Ray: Hello everyone and welcome
+Alice: Good day to you all
+Ray: Let's get started"
+```
+
+The dialogue lines play sequentially. Each line is transcribed separately, and subtitles include the speaker prefix (e.g., `Ray: Hello everyone and welcome`).
+
+##### Per-Speaker Voices
+
+Configure different TTS voices for each speaker via the root `voices` config. Each value is **extra CLI flags** appended to the TTS template:
+
+```md
+# video
+voices:{"Ray":"--voice en-US-GuyNeural","Alice":"--voice en-US-JennyNeural"}
+- script "Ray: Tell us about your project
+Alice: I'm working on something exciting"
+```
+
+Since values are raw CLI flags, they naturally support voice cloning, rate, pitch, and any edge-tts feature:
+
+```md
+voices:{"Ray":"--voice en-US-GuyNeural --rate +20%","Clone":"--voice clone-xxx --pitch +5Hz"}
+```
+
+The final TTS command for a speaker: `<root tts cli> <speaker voice flags>`.
+
 ### `subtitle` (root-level overlay)
 
 Subtitles are configured at the root level as a VTT overlay, not as tree nodes. Set via YAML frontmatter `subtitle:` or `root.subtitle` in JSON.

package/docs/system-prompt-edit.md

@@ -0,0 +1,16 @@
+You are a video director editing a markdown-descriptive (.md) markcut video project.
+
+The markcut engine compiles markdown descriptions into rendered videos with TTS narration, transitions, and media generation.
+
+The file you are editing is: ${fileName}
+Full path: ${filePath}
+
+--- Markdown-Descriptive Format Reference ---
+@{docs/markdown-descriptive.md}
+
+TASKS:
+1. Read the .md file directly using your file tools to see its current content
+2. Edit the .md file directly — change content, add/remove sections, update frontmatter
+3. Save the changes to the .md file using your write/edit tools
+4. Output ONLY a one-line summary of what specific change you made
+5. Do NOT output explanations, reasoning, or extra text

package/package.json

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

package/src/config.mjs

@@ -37,6 +37,8 @@ export const DEFAULT_ITT_CLI =
 /**
  * Seconds between sampled video frames when using the default ITT-based VTT.
  */
+export const GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY || "";
+
 export const DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE_INTERVAL) || 5;
 
 /**
@@ -73,11 +75,14 @@ export const DEFAULT_TTS_CLI =
 
 /**
  * Default agent CLI — general-purpose text LLM.
- * Used for text-only tasks like detect-scenes.
- * Placeholders: {prompt}=the prompt text.
+ * Used for text-only tasks like detect-scenes and editing.
+ * Placeholders:
+ *   {systemprompt} = system prompt (role, instructions, knowledge)
+ *   {prompt}       = user prompt (current context + edit request)
+ *   {sessionid}    = unique session ID for conversation continuity
  * Override with MARKCUT_AGENT_CLI env var.
  */
-export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
+export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}';
 
 // ── Render-only pipeline CLI templates ─────────────────────────────────────
 // These are specific to the render pipeline (no vision pipeline equivalent).

package/src/descriptive/compiler.test.ts

@@ -132,7 +132,7 @@ export { BarChart } from "npm:recharts"`,
 });
 
 describe("compileDescriptiveRoot", () => {
-  it("compiles simple series into legacy root+actions", () => {
+  it("compiles simple series into flat start/end timing", () => {
     const compiled = compileDescriptiveRoot({
       width: 640,
       height: 480,
@@ -149,13 +149,13 @@ describe("compileDescriptiveRoot", () => {
     expect(compiled.children).toHaveLength(2);
 
     const first = compiled.children[0] as any;
-    expect(first.actions[0].start).toBe(0);
-    expect(first.actions[0].end).toBe(2);
+    expect(first.start).toBe(0);
+    expect(first.end).toBe(2);
 
     const second = compiled.children[1] as any;
-    expect(second.actions[0].startFrom).toBe(1);
-    expect(second.actions[0].endAt).toBe(4);
-    expect(second.actions[0].end).toBe(3);
+    expect(second.startFrom).toBe(1);
+    expect(second.endAt).toBe(4);
+    expect(second.end).toBe(3);
   });
 
   it("allows explicit start in parallel root", () => {
@@ -170,8 +170,8 @@ describe("compileDescriptiveRoot", () => {
     expect(compiled.isSeries).toBe(false);
     expect(compiled.durationInSeconds).toBe(3);
     const first = compiled.children[0] as any;
-    expect(first.actions[0].start).toBe(1);
-    expect(first.actions[0].end).toBe(3);
+    expect(first.start).toBe(1);
+    expect(first.end).toBe(3);
   });
 
   it("warns on duplicate ids", () => {
@@ -253,8 +253,8 @@ describe("compileDescriptiveRoot", () => {
 
     const includeWithSrc = withSrc.children[0] as any;
     expect(includeWithSrc.type).toBe("include");
-    expect(includeWithSrc.actions[0].start).toBe(0);
-    expect(includeWithSrc.actions[0].end).toBe(4);
+    expect(includeWithSrc.start).toBe(0);
+    expect(includeWithSrc.end).toBe(4);
 
     const withChildren = compileDescriptiveRoot({
       layout: "series",
@@ -273,7 +273,7 @@ describe("compileDescriptiveRoot", () => {
     const includeInline = withChildren.children[0] as any;
     expect(includeInline.type).toBe("include");
     expect(includeInline.children).toHaveLength(2);
-    expect(includeInline.actions[0].end).toBe(3);
+    expect(includeInline.end).toBe(3);
   });
 
   it("covers remaining types: effect (via effects:[]) and map", () => {
@@ -304,13 +304,13 @@ describe("compileDescriptiveRoot", () => {
     // effects:[] on image compiles into Effect wrapper stream
     const effect = compiled.children[0] as any;
     expect(effect.type).toBe("effect");
-    expect(effect.actions[0].start).toBe(0);
-    expect(effect.actions[0].end).toBe(2);
+    expect(effect.start).toBe(0);
+    expect(effect.end).toBe(2);
     expect(effect.children).toHaveLength(1);
 
     const map = compiled.children.find((c: any) => c.id === "map-1") as any;
     expect(map.type).toBe("map");
-    expect(map.actions[0].end).toBe(4);
+    expect(map.end).toBe(4);
     expect(map.waypoints).toHaveLength(2);
     expect(map.routeMarker).toBe("🚲");
     expect(map.travelMode).toBe("BICYCLING");
@@ -339,11 +339,11 @@ describe("compileDescriptiveRoot", () => {
     expect(fx.children[0].type).toBe("image");
     expect(fx.children[0].src).toBe("hero.jpg");
     // Effect action spans leaf duration
-    expect(fx.actions[0].start).toBe(0);
-    expect(fx.actions[0].end).toBe(3);
+    expect(fx.start).toBe(0);
+    expect(fx.end).toBe(3);
     // Inner leaf action is relative (start=0)
-    expect(fx.children[0].actions[0].start).toBe(0);
-    expect(fx.children[0].actions[0].end).toBe(3);
+    expect(fx.children[0].start).toBe(0);
+    expect(fx.children[0].end).toBe(3);
   });
 
   it("compiles leaf node with effects as object specs", () => {
@@ -371,11 +371,11 @@ describe("compileDescriptiveRoot", () => {
     expect(fx.animationTimingFunction).toBe("ease-out");
     expect(fx.animationIterationCount).toBe(2);
     // Outermost effect carries the absolute timing from parallel layout
-    expect(fx.actions[0].start).toBe(1);
-    expect(fx.actions[0].end).toBe(3);
+    expect(fx.start).toBe(1);
+    expect(fx.end).toBe(3);
     // Inner leaf timing is relative
-    expect(fx.children[0].actions[0].start).toBe(0);
-    expect(fx.children[0].actions[0].end).toBe(2);
+    expect(fx.children[0].start).toBe(0);
+    expect(fx.children[0].end).toBe(2);
   });
 
   it("compiles effects on container (parallel) nodes", () => {
@@ -471,9 +471,9 @@ describe("compileDescriptiveRoot", () => {
     expect(fx.animationTimingFunction).toBe("ease-out");
     expect(fx.animationIterationCount).toBe(3);
     // Effect duration from param overrides to 2s
-    expect(fx.actions[0].end - fx.actions[0].start).toBe(2);
+    expect(fx.end - fx.start).toBe(2);
     // Inner leaf still plays full 5s
-    expect(fx.children[0].actions[0].end - fx.children[0].actions[0].start).toBe(5);
+    expect(fx.children[0].end - fx.children[0].start).toBe(5);
   });
 
   it("compiles effect with comma-separated positional params (duration, timingFunction, iterationCount)", () => {
@@ -495,7 +495,7 @@ describe("compileDescriptiveRoot", () => {
     expect(fx.animation).toBe("fadeIn");
     expect(fx.animationTimingFunction).toBe("ease-in");
     expect(fx.animationIterationCount).toBe(3);
-    expect(fx.actions[0].end - fx.actions[0].start).toBe(2);
+    expect(fx.end - fx.start).toBe(2);
   });
 
   it("compiles effect with positional params — duration only", () => {
@@ -515,7 +515,7 @@ describe("compileDescriptiveRoot", () => {
     const fx = compiled.children[0] as any;
     expect(fx.type).toBe("effect");
     expect(fx.animation).toBe("fadeIn");
-    expect(fx.actions[0].end - fx.actions[0].start).toBe(1.5);
+    expect(fx.end - fx.start).toBe(1.5);
   });
 
   it("compiles effect with partial positional params — duration + timingFunction", () => {
@@ -536,7 +536,7 @@ describe("compileDescriptiveRoot", () => {
     expect(fx.animation).toBe("fadeIn");
     expect(fx.animationTimingFunction).toBe("ease-out");
     expect(fx.animationIterationCount).toBe(1);
-    expect(fx.actions[0].end - fx.actions[0].start).toBe(2.5);
+    expect(fx.end - fx.start).toBe(2.5);
   });
 
   it("supports deep nested layout containers across all modes", () => {
@@ -726,15 +726,15 @@ describe("compileDescriptiveRoot", () => {
     expect(rhythm.children).toHaveLength(4);
 
     // child[0] starts at beat 0.5, ends at beat 1.5 => duration 1
-    expect(rhythm.children[0].actions[0].start).toBe(0.5);
-    expect(rhythm.children[0].actions[0].end).toBe(1.5);
+    expect(rhythm.children[0].start).toBe(0.5);
+    expect(rhythm.children[0].end).toBe(1.5);
 
     // child[1] starts at beat 1.5, ends at beat 2.5 => duration 1
-    expect(rhythm.children[1].actions[0].start).toBe(1.5);
-    expect(rhythm.children[1].actions[0].end).toBe(2.5);
+    expect(rhythm.children[1].start).toBe(1.5);
+    expect(rhythm.children[1].end).toBe(2.5);
 
     // last child starts at last beat (3.5), extends by avg gap (1.0) => ends at 4.5
-    expect(rhythm.children[3].actions[0].end).toBe(4.5);
+    expect(rhythm.children[3].end).toBe(4.5);
     // rhythm duration = last spot + avg gap
     expect(rhythm.durationInSeconds).toBe(4.5);
   });
@@ -778,11 +778,11 @@ describe("compileDescriptiveRoot", () => {
     expect(bgm.type).toBe("audio");
     expect(bgm.volume).toBe(0.3);
     expect(bgm.foreground).toBe(false);
-    expect(bgm.actions[0].end).toBe(5);
+    expect(bgm.end).toBe(5);
 
     const sfx = compiled.children.find((c: any) => c.id === "sfx") as any;
-    expect(sfx.actions[0].start).toBe(2);
-    expect(sfx.actions[0].end).toBe(3);
+    expect(sfx.start).toBe(2);
+    expect(sfx.end).toBe(3);
   });
 
   it("compiles component node with props", () => {
@@ -801,7 +801,7 @@ describe("compileDescriptiveRoot", () => {
     const c = compiled.children[0] as any;
     expect(c.type).toBe("component");
     expect(c.jsx).toContain("AnimatedHeadline");
-    expect(c.actions[0].end).toBe(3);
+    expect(c.end).toBe(3);
   });
 
   it("compiles rhythm without children as audio leaf", () => {
@@ -817,7 +817,7 @@ describe("compileDescriptiveRoot", () => {
     expect(r.src).toBe("beat.mp3");
     expect(r.children).toEqual([]);
     // rhythm duration = last spot + avg gap = 2.5 + 2.0 = 4.5
-    expect(r.actions[0].end).toBeCloseTo(4.5);
+    expect(r.end).toBeCloseTo(4.5);
   });
 
   it("compiles include with src as leaf", () => {
@@ -831,7 +831,7 @@ describe("compileDescriptiveRoot", () => {
     const inc = compiled.children[0] as any;
     expect(inc.type).toBe("include");
     expect(inc.src).toBe("./child.json");
-    expect(inc.actions[0].end).toBe(3);
+    expect(inc.end).toBe(3);
   });
 
   it("compiles effects:[] with named params (duration, timingFunction, iterationCount)", () => {
@@ -865,10 +865,10 @@ describe("compileDescriptiveRoot", () => {
     });
 
     const img = compiled.children[0] as any;
-    expect(img.actions[0].end).toBe(3); // image default is 3s
+    expect(img.end).toBe(3); // image default is 3s
 
     const vid = compiled.children[1] as any;
-    expect(vid.actions[0].end).toBe(3); // video default is 3s
+    expect(vid.end).toBe(3); // video default is 3s
   });
 
   it("uses default duration when duration is missing", () => {
@@ -879,7 +879,7 @@ describe("compileDescriptiveRoot", () => {
       ],
     });
     const img = compiled.children[0] as any;
-    expect(img.actions[0].end).toBe(3); // image default is 3s
+    expect(img.end).toBe(3); // image default is 3s
   });
 
   it("preserves root-level instruction and stylesheet", () => {
@@ -916,7 +916,7 @@ describe("compileDescriptiveRoot", () => {
     expect(m.type).toBe("map");
     expect(m.waypoints).toHaveLength(2);
     expect(m.travelMode).toBe("DRIVING");
-    expect(m.actions[0].end).toBe(5);
+    expect(m.end).toBe(5);
   });
 
   it("filters invisible children", () => {