@lalalic/markcut 3.0.0 → 3.1.0

package/package.json

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

package/skills/markcut/SKILL.md

@@ -36,6 +36,11 @@ Implies `--edit` so you can chat to reshape the story and see live reloads.
 ### Video Variants
 - define variants for different video configurations, such as different languages, aspects, platforms
 
+### Route / Vlog videos (map clips)
+- For **route / travel-vlog clips** (drone flyover, route map with photo stops, Street View walks) use the `map` stream type with `view: overview | route | cinematic | streetview` and `tween(from,to,easing)` camera moves.
+- Discover interesting stops along a route with `markcut spots --waypoints "lat,lng;lat,lng" --photos --markdown`, then compose a `map` storyboard from the returned `waypoints:[...]` line.
+- See [docs/map-dynamic-camera.md](docs/map-dynamic-camera.md) — the agent guide with effects, spots workflow, and copy-paste markdown examples.
+
 ### Viral Story requires
 - **Hooks** : why should the viewer watch this?
 - **Conflict** : what challenges or obstacles do the characters face?
@@ -60,6 +65,7 @@ npx @lalalic/markcut preview <file> --storyboard # fast structure preview: repla
 npx @lalalic/markcut render <file> # render the video to mp4
 npx @lalalic/markcut vision <folder> # vision understanding medias in folder
 npx @lalalic/markcut vision <folder> --label # an extra step to provide UI to label the medias with text, time ranges
+npx @lalalic/markcut spots --waypoints "lat,lng;lat,lng" # discover POIs along a route (for route/vlog map clips)
 
 ```
 
@@ -80,6 +86,7 @@ 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) |
+| Route / vlog map clips (effects, spots, examples) | [docs/map-dynamic-camera.md](docs/map-dynamic-camera.md) |
 | Built-in components & common npm packages | [docs/components.md](docs/components.md) |
 | Sound effects | [docs/sound-effects.md](docs/sound-effects.md) |
 

package/skills/markcut/docs/map-dynamic-camera.md

@@ -0,0 +1,244 @@
+# Route & Vlog Map Videos — Agent Guide
+
+> Make route / travel-vlog video clips with the `map` stream type: establishing
+> dolly shots, route flyovers with photo stops, cinematic chase cameras, and
+> immersive Street View moves — all narrated by TTS. This is the **agent-facing**
+> reference: what effects you can get, how to discover spots, and copy-paste
+> markdown. No implementation details.
+
+---
+
+## 1. When to reach for this
+
+Use `map` clips when the video is about **a place and getting around**:
+
+- travel vlog: "we drove from the Golden Gate to SFO, stopping for photos"
+- city tour: establishing shot → flyover → street level
+- route explainers: commute, road trip, walking tour, "how to get there"
+
+Every map clip can carry a `script` narration next to it (see §6 for the
+scene pattern that plays map + narration together).
+
+---
+
+## 2. The 4 views = 4 effects
+
+`view` is the one field that decides the whole feel. Default is `route`.
+
+| view | effect | best for |
+|---|---|---|
+| `overview` | **Dolly** — camera starts far (satellite) and flies down to the city/street | establishing shot, "this is where we are" |
+| `route` | **Route map** — path + animated marker + optional photo thumbnails at each stop | itinerary, travel log |
+| `cinematic` | **Chase flyover** — camera follows the route like a drone, road always "forward-up" | exciting transitions between stops |
+| `streetview` | **Street View** — immersive pan / tilt / walk at ground level | being on location, "here we are" |
+
+Example — one line each:
+
+```md
+- map view:overview duration:4 camera:{zoom:tween(6, 12, easeInOut)}
+- map view:route duration:6 waypoints:[...] 
+- map view:cinematic duration:8 waypoints:[...] cinematic:{tilt:tween(0, 45)}
+- map view:streetview duration:6 streetView:{location:{lat:37.77,lng:-122.41}, pov:{heading:tween(200, 320)}}
+```
+
+---
+
+## 3. Animating the camera — `tween()`
+
+Any camera value can be **static** (a number) or **animated** with a tween
+expression written directly in markdown:
+
+```
+tween(from, to, easing?)
+```
+
+| easing | feel |
+|---|---|
+| `easeInOut` (default) | smooth ease at both ends — default for camera moves |
+| `easeIn` | starts slow, finishes fast |
+| `easeOut` | starts fast, settles |
+| `linear` | constant speed — use for constant pan |
+
+Fields that accept `tween(...)`:
+
+- `camera.zoom` — `tween(6, 12)` = dolly in (higher zoom = closer)
+- `camera.heading` — `tween(0, 90)` = rotate the map
+- `camera.tilt` — `tween(0, 45)` = tilt reveal (top-down → perspective)
+- `camera.center.{lat,lng}` — fly across the map
+- `cinematic.tilt` / `cinematic.range` / `cinematic.roll` — 3D camera moves
+- `streetView.pov.heading` — pan: `tween(200, 320)` sweeps the view;
+  `tween(200, 560)` = whip pan
+- `streetView.pov.pitch` — `tween(0, -10)` tilts from sky to street
+- `streetView.zoom` — Street View field-of-view: `tween(0, 1)` = dolly-zoom feel
+
+Rules of thumb:
+
+- **Zoom is not linear in perceived distance** — use `easeInOut` to hide the
+  "pop". For a strong dolly: `zoom:tween(5, 13)` (city region → streets).
+- Combine tweens for a richer move, e.g. dolly + tilt reveal:
+  `camera:{zoom:tween(12, 14, easeInOut)} cinematic:{tilt:tween(0, 45, easeInOut)}`.
+
+---
+
+## 4. Photo stops (the vlog touch)
+
+`waypoints` take an optional **4th field = media** (image path or URL). It
+renders as a small thumbnail marker at that stop — perfect for "here's the
+place" moments in a vlog:
+
+```
+[lat,lng,"Label"]                       # plain stop
+[lat,lng,"Label","assets/photo.jpg"]    # stop with photo thumbnail
+[lat,lng,"","assets/photo.jpg"]         # empty label = thumbnail only
+```
+
+Full example:
+
+```md
+- map view:route duration:6 travelMode:DRIVING mapType:roadmap routeColor:"#4285F4" routeWeight:5 routeMarker:"🚗"
+  waypoints:[37.8199,-122.4783,"Golden Gate","https://picsum.photos/seed/gg/96/96"; 37.7749,-122.4194,"Civic Center","https://picsum.photos/seed/civic/96/96"; 37.6213,-122.3790,"SFO","https://picsum.photos/seed/sfo/96/96"]
+```
+
+---
+
+## 5. Discovering spots along a route — `markcut spots`
+
+Don't hand-pick coordinates for a route video — **discover** interesting stops
+with the spots CLI. It samples points along a route (Directions API) and ranks
+nearby places by `rating × log(ratings)`, then hands you ready-to-paste
+markdown.
+
+```bash
+npx @lalalic/markcut spots --waypoints "37.8199,-122.4783;37.6213,-122.3790" \
+  --travelMode DRIVING --limit 8 --photos --markdown
+```
+
+| flag | meaning |
+|---|---|
+| `--waypoints "lat,lng;lat,lng"` | route endpoints (semicolon-separated) — required |
+| `--travelMode DRIVING\|WALKING\|BICYCLING` | how you travel the route (default DRIVING) |
+| `--limit <n>` | max spots after ranking (default 8) |
+| `--photos` | attach a photo URL per spot (becomes `waypoint.media`) |
+| `--markdown` | print a copy-paste `waypoints:[...]` line to stderr |
+| `--output spots.json` | also save the full JSON |
+
+**Agent workflow — the tool only discovers, you compose:**
+
+1. Get route endpoints from the user's media/GPS or pick two landmarks.
+2. `markcut spots --waypoints "..." --photos --markdown`
+3. Pick the 2–5 spots that fit the narrative arc (opening, highlights, ending).
+4. Build a `map` storyboard with those `waypoints` + `script` narration.
+5. `markcut preview` to check, `markcut render` to export.
+
+---
+
+## 6. Markdown examples (copy-paste)
+
+### 6.1 Simple route clip with narration
+
+Map + narration play together inside a `layout:parallel` scene; scenes are
+sequenced by the root `layout:series`:
+
+```md
+# video
+width:1080 height:1920 layout:series transition:fade transitionTime:0.5
+
+## The-Drive
+layout:parallel
+- script "We leave the Golden Gate and head down to the airport."
+- map view:route duration:6 travelMode:DRIVING mapType:roadmap routeColor:"#4285F4" routeWeight:5 routeMarker:"🚗"
+  waypoints:[37.8199,-122.4783,"Golden Gate"; 37.7749,-122.4194,"Civic Center"; 37.6213,-122.3790,"SFO"]
+```
+
+### 6.2 Establishing dolly → cinematic chase (two scenes)
+
+```md
+# video
+width:1080 height:1920 layout:series transition:fade
+
+## Opening-Dive-In
+layout:parallel
+- script "High above San Francisco, then we dive into the streets."
+- map view:overview mapType:satellite duration:4 camera:{zoom:tween(6, 12, easeInOut)}
+
+## Chase-The-Road
+layout:parallel
+- script "The camera chases the route like a drone."
+- map view:cinematic duration:8 travelMode:DRIVING mapType:satellite routeMarker:"🚗"
+  cinematic:{mode:flyAlong, headingFollow:true, tilt:tween(0, 45, easeInOut)}
+  camera:{zoom:tween(12, 14, easeInOut)}
+  waypoints:[37.8199,-122.4783,"Golden Gate"; 37.7749,-122.4194,"Civic Center"; 37.6213,-122.3790,"SFO"]
+```
+
+### 6.3 Street-level: pan, then walk
+
+```md
+# video
+width:1080 height:1920 layout:series transition:fade
+
+## On-The-Street-Pan
+layout:parallel
+- script "And here we are, right on the sidewalk."
+- map view:streetview duration:8 streetView:{location:{lat:37.7793,lng:-122.4193}, radius:50, pov:{heading:tween(200, 420, easeInOut), pitch:tween(0, -8)}, zoom:tween(0, 0.6, easeInOut)}
+
+## A-Quick-Walk
+layout:parallel
+- script "A short stroll down the block."
+- map view:streetview duration:6 streetView:{route:[{lat:37.7793,lng:-122.4193},{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+```
+
+### 6.4 Full route-vlog recipe (5 scenes)
+
+Combine everything for a complete vlog arc: **establish → route with photos →
+cinematic → street view pan → walk**.
+
+```md
+# video
+width:1080 height:1920 layout:series transition:fade transitionTime:0.5
+
+## Satellite-Dolly
+layout:parallel
+- script "We begin high above San Francisco, then dive into the city."
+- map view:overview mapType:satellite duration:4 center:{lat:37.7749,lng:-122.4194} camera:{zoom:tween(6, 12, easeInOut)}
+
+## Route
+layout:parallel
+- script "The route winds from the Golden Gate to the airport, with photos at each stop."
+- map view:route duration:6 travelMode:DRIVING mapType:roadmap routeColor:"#4285F4" routeWeight:5 routeMarker:"🚗" waypoints:[37.8199,-122.4783,"Golden Gate","https://picsum.photos/seed/gg-bridge/96/96"; 37.7749,-122.4194,"Civic Center","https://picsum.photos/seed/civic-center/96/96"; 37.6213,-122.3790,"SFO","https://picsum.photos/seed/sfo-airport/96/96"]
+
+## Cinematic
+layout:parallel
+- script "The camera tilts and chases the road like a drone."
+- map view:cinematic duration:8 travelMode:DRIVING mapType:satellite routeMarker:"🚗" cinematic:{mode:flyAlong, headingFollow:true, tilt:tween(0, 45, easeInOut)} camera:{zoom:tween(12, 14, easeInOut)} waypoints:[37.8199,-122.4783,"Golden Gate"; 37.7749,-122.4194,"Civic Center"; 37.6213,-122.3790,"SFO"]
+
+## Street-View
+layout:parallel
+- script "And finally, we land on the street itself."
+- map view:streetview duration:8 streetView:{location:{lat:37.7793,lng:-122.4193}, radius:50, pov:{heading:tween(200, 420, easeInOut), pitch:tween(0, -8)}, zoom:tween(0, 0.6, easeInOut)}
+
+## Street-View-Walk
+layout:parallel
+- script "A quick walk down the block."
+- map view:streetview duration:6 streetView:{route:[{lat:37.7793,lng:-122.4193},{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178},{lat:37.7769,lng:-122.4170}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+```
+
+---
+
+## 7. Recipe — build a route/vlog clip
+
+1. **Get the route** — endpoints from the user's media/GPS, or two landmarks.
+2. **Discover spots** — `markcut spots --waypoints "lat,lng;lat,lng" --photos --markdown`; pick 2–5 that tell the story.
+3. **Pick views per scene** — overview (establish) → route with photo stops (log) → cinematic (transition) → streetview (arrive).
+4. **Write narration** — one `script` per scene; the resolver sizes the clip from the TTS audio automatically (don't hand-set durations that depend on script length).
+5. **Verify** — `markcut preview book.md` (screenshot key frames, check map/pano loaded and captions), then `markcut render book.md --output out/vlog.mp4`.
+
+---
+
+## 8. Tips & pitfalls
+
+- **Map + narration**: put `- map ...` and `- script "..."` as sibling bullets in a `layout:parallel` scene so they play together. If the scene is `series`, narration plays alone first and the map shows nothing while speaking.
+- **Street View coverage is not universal** — a spot may have no panorama. If a `streetview` scene looks dark/empty, pick a nearby well-covered location or use `view:cinematic` instead.
+- **Route maps need ≥2 waypoints**; a single point falls back to a plain marker.
+- **Media assets** — photo thumbnails (`waypoint.media`), images, bgm etc. should live in the md file's folder (e.g. `assets/...`). See the asset-path rules in `markdown-descriptive.md` §14 (verify enforces md-folder-relative paths).
+- **Don't set duration from script length** — the resolver computes it from TTS audio.
+- **3D (Map3D)** is experimental and opt-in (`cinematic.fallback:"none"`); the default `fallback:"2d"` gives the safe drone-chase look.

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

@@ -268,6 +268,8 @@ all src paths are resolved relative to the markdown file's location. For example
 ### 14. verify
 - all assets path are resolved relative to the markdown file's location. 
 - `npx @lalalic/markcut verify book.md` to verify the markdown document is valid and can be rendered. It will check for missing required fields, invalid values, and other common issues.
+- **Asset-relative check**: `verify` also walks the tree and requires every local asset (image/video/audio/subtitle `.vtt`, map `waypoints[].media`, root `subtitle.src`) to be a path **relative to the markdown file's folder** — no absolute paths (`/...`), no `..` escapes. Remote URLs (`https:`, `data:`, etc.) and inline subtitle text are fine. Violations are printed as actionable errors (exit 1) so an agent can fix the source and re-run.
+- `markcut render` runs the same check on the compiled tree right before rendering and aborts with errors instead of failing mid-render with 404s.
 
 
 ## Template Variables

package/src/descriptive/compiler.ts

@@ -139,9 +139,18 @@ export interface DescriptiveMapWaypoint {
   media?: string;
 }
 
+/** A tween expression `tween(from, to, easing?)` parsed into a tagged spec. */
+export interface DescriptiveTween {
+  __tween: Array<number | string>;
+}
+
+/** A static number OR an animated tween expression. */
+export type DescriptiveTweenable = number | DescriptiveTween;
+
 export interface DescriptiveMap extends DescriptiveBaseNode {
   type: "map";
   waypoints: DescriptiveMapWaypoint[];
+  view?: "overview" | "route" | "cinematic" | "streetview";
   routeColor?: string;
   routeWeight?: number;
   zoom?: number;
@@ -151,6 +160,34 @@ export interface DescriptiveMap extends DescriptiveBaseNode {
   region?: string;
   travelMode?: "DRIVING" | "WALKING" | "BICYCLING" | "TRANSIT";
   routeMarker?: string;
+  camera?: {
+    zoom?: DescriptiveTweenable;
+    center?: { lat: DescriptiveTweenable; lng: DescriptiveTweenable };
+    heading?: DescriptiveTweenable;
+    tilt?: DescriptiveTweenable;
+  };
+  cinematic?: {
+    mode?: "flyAlong" | "flyTo" | "orbit";
+    followRoute?: boolean;
+    headingFollow?: boolean;
+    tilt?: DescriptiveTweenable;
+    range?: DescriptiveTweenable;
+    altitude?: number;
+    roll?: DescriptiveTweenable;
+    fallback?: "2d" | "none";
+  };
+  streetView?: {
+    pano?: string;
+    location?: { lat: number; lng: number };
+    route?: Array<{ lat: number; lng: number }>;
+    radius?: number;
+    source?: "default" | "outdoor" | "indoor";
+    zoom?: DescriptiveTweenable;
+    pov?: {
+      heading?: DescriptiveTweenable;
+      pitch?: DescriptiveTweenable;
+    };
+  };
 }
 
 export interface DescriptiveContainer extends DescriptiveBaseNode {
@@ -601,6 +638,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
       const stream: MapStream = {
         ...base,
         type: "map",
+        view: node.view ?? "route",
         waypoints: node.waypoints,
         routeColor: node.routeColor ?? "#4285F4",
         routeWeight: node.routeWeight ?? 4,
@@ -611,6 +649,9 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         region: node.region,
         travelMode: node.travelMode ?? "DRIVING",
         routeMarker: node.routeMarker ?? "🚗",
+        camera: node.camera,
+        cinematic: node.cinematic,
+        streetView: node.streetView,
         googleMapsApiKey: ctx.googleMapsApiKey,
       };
       return { stream, duration: end ?? 0 };

package/src/descriptive/dsl.ts

@@ -174,28 +174,65 @@ export function parseWaypoints(raw: string): DescriptiveMapWaypoint[] {
     const lat = Number(bits[0] ?? 0);
     const lng = Number(bits[1] ?? 0);
     const labelRaw = bits[2];
-    const label = labelRaw ? unquote(labelRaw) : undefined;
-    return { lat, lng, label };
+    const labelRawUq = labelRaw ? unquote(labelRaw) : undefined;
+    const label = labelRawUq ? labelRawUq : undefined;
+    const mediaRaw = bits[3];
+    const media = mediaRaw ? unquote(mediaRaw) : undefined;
+    return { lat, lng, label, media };
   });
 }
 
+/**
+ * Rewrite `tween(from, to, easing?)` expressions inside a JSON-ish string into
+ * a tagged literal `{"__tween":[from,to,"easing"]}` so the regular JSON parser
+ * can handle them. `from`/`to` may be numbers or quoted strings (e.g. colors);
+ * `easing` is a bare word or quoted string. No eval — deterministic, no scope.
+ *
+ *   tween(6, 12, easeInOut)  →  {"__tween":[6,12,"easeInOut"]}
+ */
+function rewriteTweenExprs(s: string): string {
+  return s.replace(
+    /tween\(\s*([^,()]+?)\s*,\s*([^,()]+?)\s*(?:,\s*([^()]+?))?\s*\)/g,
+    (_match, fromRaw: string, toRaw: string, easingRaw?: string) => {
+      // Scalar → JSON literal: numbers stay, quoted strings stay, bare words get quoted.
+      const scalar = (v: string): string => {
+        const t = v.trim();
+        if (/^[+-]?(\d+(\.\d+)?|\.\d+)$/.test(t)) return t;
+        if (/^"(?:[^"\\]|\\.)*"$/.test(t)) return t;
+        if (t === "true" || t === "false" || t === "null") return t;
+        return JSON.stringify(t);
+      };
+      const items = [scalar(fromRaw), scalar(toRaw)];
+      if (easingRaw !== undefined && easingRaw.trim()) {
+        items.push(scalar(easingRaw));
+      }
+      return `{"__tween":[${items.join(",")}]}`;
+    },
+  );
+}
+
 /**
  * Parse a JSON-like props/imports string into an object or array.
  *
  * Accepts standard JSON, then falls back to a lenient two-pass normalization
  * that quotes bare keys (`{foo:` → `{"foo":`) and bare string values, and
  * finally to `eval` for JSX-like expressions. Returns `{}` on total failure.
+ *
+ * Also understands `tween(from, to, easing?)` expressions (see
+ * {@link rewriteTweenExprs}), which are rewritten to a tagged JSON literal
+ * before parsing so camera/map configs can animate values.
  */
 export function parseProps(raw: string): unknown {
   const s = raw.trim();
   if (!s.startsWith("{") && !s.startsWith("[")) return {};
   if (!s.endsWith("}") && !s.endsWith("]")) return {};
+  const withTweens = rewriteTweenExprs(s);
   try {
-    return JSON.parse(s);
+    return JSON.parse(withTweens);
   } catch {
     // Lenient parse: add quotes around unquoted keys and string values.
     // First pass: quote bare keys: {foo: → {"foo":
-    let normalized = s.replace(
+    let normalized = withTweens.replace(
       /([{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:(?=\s*["{[]?)/g,
       '$1"$2":',
     );
@@ -214,7 +251,7 @@ export function parseProps(raw: string): unknown {
     } catch {
       // Last resort: eval (safe since this is a CLI tool)
       try {
-        const result = (0, eval)("(" + s + ")");
+        const result = (0, eval)("(" + withTweens + ")");
         return typeof result === "object" && result !== null ? result : {};
       } catch {
         return {};

package/src/descriptive/markdown.ts

@@ -101,6 +101,7 @@ function preserveVariantAttrs(node: Record<string, unknown>, attrs: Record<strin
     "foreground", "visible", "isBackground", "instruction", "style", "effects", "on",
     "spots", "waypoints", "routeColor", "routeWeight", "routeMarker",
     "travelMode", "zoom", "center", "mapType", "data", "prompt",
+    "view", "camera", "cinematic", "streetView",
     "name", "title", "transition", "transitionTime", "layout",
     "componentName", "props", "speaker",
   ]);
@@ -338,6 +339,7 @@ function parseNodeLine(content: string, lineNum?: number): DescriptiveNode {
         waypoints: (attrs.waypoints as DescriptiveMapWaypoint[] | undefined) ?? [],
         duration: attrs.duration as any,
         start: attrs.start as any,
+        view: attrs.view as any,
         routeMarker: attrs.routeMarker as any,
         travelMode: attrs.travelMode as any,
         routeColor: attrs.routeColor as any,
@@ -345,6 +347,9 @@ function parseNodeLine(content: string, lineNum?: number): DescriptiveNode {
         zoom: attrs.zoom as any,
         center: attrs.center as any,
         mapType: attrs.mapType as any,
+        camera: attrs.camera as any,
+        cinematic: attrs.cinematic as any,
+        streetView: attrs.streetView as any,
         language: (attrs.language as any) ?? (attrs.lang as any),
         region: attrs.region as any,
         instruction: attrs.instruction as any,

package/src/descriptive/resolve.test.ts

@@ -755,7 +755,7 @@ describe("resolveMediaDurations", () => {
         { type: "video", src: "nonexistent.mp4", duration: 5 },
       ],
     };
-    const result = await resolveMediaDurations(root);
+    const result = await resolveMediaDurations(root, { baseDir: tmpDir });
     expect(result).not.toBe(root);
     expect(result.children[0]!.duration).toBe(5);
   });
@@ -767,7 +767,7 @@ describe("resolveMediaDurations", () => {
         { type: "video", src: "anything.mp4", duration: 7 },
       ],
     };
-    const result = await resolveMediaDurations(root);
+    const result = await resolveMediaDurations(root, { baseDir: tmpDir });
     expect(result.children[0]!.duration).toBe(7);
   });
 
@@ -778,7 +778,7 @@ describe("resolveMediaDurations", () => {
         { type: "video", src: "anything.mp4", startFrom: 2, endAt: 5 },
       ],
     };
-    const result = await resolveMediaDurations(root);
+    const result = await resolveMediaDurations(root, { baseDir: tmpDir });
     expect((result.children[0] as any).endAt).toBe(5);
     expect((result.children[0] as any).duration).toBeUndefined();
   });
@@ -791,7 +791,7 @@ describe("resolveMediaDurations", () => {
         { type: "image", src: "photo.jpg" },
       ],
     };
-    const result = await resolveMediaDurations(root, { skip: /\.jpg$/ });
+    const result = await resolveMediaDurations(root, { baseDir: tmpDir, skip: /\.jpg$/ });
     // .jpg skipped, .mp4 tried but file doesn't exist so duration stays undefined
     expect(result.children[0]!.duration).toBeUndefined();
     expect(result.children[1]!.duration).toBeUndefined();
@@ -805,7 +805,7 @@ describe("resolveMediaDurations", () => {
       ],
     };
     const originalChildren = root.children[0];
-    const result = await resolveMediaDurations(root);
+    const result = await resolveMediaDurations(root, { baseDir: tmpDir });
     expect(result).not.toBe(root);
     expect(root.children[0]).toBe(originalChildren);
   });

package/src/descriptive/resolve.ts

@@ -46,8 +46,9 @@ function firstWords(text: string, n: number): string {
 }
 
 export interface ResolveMediaOptions {
-  /** Base directory for resolving relative src paths (default: cwd) */
-  baseDir?: string;
+  /** Source file's folder — every asset path is resolved/emitted relative to it.
+   *  Always set by the CLI/server (dirname of the source file); no fallback. */
+  baseDir: string;
   /** Skip nodes whose src matches this regex */
   skip?: RegExp;
 }
@@ -56,7 +57,7 @@ export interface ResolveMediaOptions {
  * Probe actual media duration via ffprobe.
  * Returns duration in seconds, or null if probe fails.
  */
-function probeDuration(src: string, baseDir?: string): number | null {
+function probeDuration(src: string, baseDir: string): number | null {
   const absPath = resolveSrc(src, baseDir);
   try {
     const out = execSync(
@@ -70,9 +71,37 @@ function probeDuration(src: string, baseDir?: string): number | null {
   }
 }
 
-function resolveSrc(src: string, baseDir?: string): string {
+function resolveSrc(src: string, baseDir: string): string {
   if (/^(https?:|file:|\/)/.test(src)) return src;
-  return resolvePath(baseDir ?? process.cwd(), src);
+  return resolvePath(baseDir, src);
+}
+
+/**
+ * Convert every generated asset path that lives under `baseDir` (the source
+ * .md folder) into a path relative to it, so the compiled JSON references
+ * every asset from the md folder's perspective. Render serves that folder via
+ * --public-dir and the preview server serves it as the document root — no
+ * render-time normalization needed. Paths outside baseDir (or remote) stay
+ * unchanged.
+ *
+ * Applied once at the end of resolveAll — all resolvers keep emitting
+ * absolute paths internally (needed for ffprobe/whisper), and this single
+ * walk relativizes them for the final JSON.
+ */
+function relativizeAssetsUnder(node: any, baseDir: string): any {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((v) => relativizeAssetsUnder(v, baseDir));
+  const out: Record<string, any> = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (typeof v === "string" && v.startsWith(baseDir + "/")) {
+      out[k] = v.slice(baseDir.length + 1);
+    } else if (v && typeof v === "object") {
+      out[k] = relativizeAssetsUnder(v, baseDir);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
 }
 
 /**
@@ -111,7 +140,7 @@ export function resolveMediaSrc(
   src: string,
   targetWidth: number,
   targetHeight: number,
-  baseDir?: string,
+  baseDir: string,
 ): string {
   // If no pattern, direct resolve
   if (!src.includes("${")) {
@@ -157,7 +186,7 @@ export function resolveMediaSrc(
  */
 export async function resolveMediaSrcs(
   root: DescriptiveRoot,
-  options: ResolveMediaOptions = {},
+  options: ResolveMediaOptions,
 ): Promise<DescriptiveRoot> {
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
   const baseDir = options.baseDir;
@@ -190,7 +219,7 @@ export async function resolveMediaSrcs(
  */
 export async function resolveMediaDurations(
   root: DescriptiveRoot,
-  options: ResolveMediaOptions = {},
+  options: ResolveMediaOptions,
 ): Promise<DescriptiveRoot> {
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
   const baseDir = options.baseDir;
@@ -411,7 +440,8 @@ export async function resolveScripts(
     }
     if (!generated) continue;
 
-    // Set resolved src (normalize to absolute for reliable probing later)
+    // Set resolved src (absolute for reliable probing; the final
+    // relativizeAssetsUnder pass in resolveAll makes it md-folder-relative)
     node.src = resolvePath(generated);
     delete node.script;
   }
@@ -485,6 +515,8 @@ export async function resolveSubtitles(
       const effectiveOffset = nodeStart + actionStart;
 
       if (node.type === "audio" && node.src) {
+        // node.src is still absolute here (relativization happens at the end of
+        // resolveAll), so whisper/existsSync can read the file directly.
         clips.push({ audioSrc: node.src, offset: effectiveOffset, speaker: node.speaker });
       }
 
@@ -937,10 +969,10 @@ export interface ResolveAllOptions extends ResolveMediaOptions {
  */
 export async function resolveIncludes(
   root: DescriptiveRoot,
-  options: ResolveAllOptions = {},
+  options: ResolveAllOptions,
 ): Promise<DescriptiveRoot> {
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
-  const baseDir = options.baseDir ?? process.cwd();
+  const baseDir = options.baseDir;
   const outputDir = options.includeOutputDir ?? join(baseDir, ".markcut", "generated", "includes");
   mkdirSync(outputDir, { recursive: true });
 
@@ -1076,7 +1108,7 @@ export async function resolveIncludes(
  */
 export async function resolveAll(
   root: DescriptiveRoot,
-  options: ResolveAllOptions = {},
+  options: ResolveAllOptions,
 ): Promise<DescriptiveRoot> {
   let result = root;
 
@@ -1180,5 +1212,12 @@ export async function resolveAll(
     });
   }
 
+  // Final step: emit every generated asset path relative to the source .md
+  // folder so the compiled JSON carries md-folder-relative paths. Render
+  // serves that folder via --public-dir and the preview server serves it as
+  // the document root — no render-time normalization needed. baseDir is
+  // always the source file's folder (set by the CLI/server) — no fallback.
+  result = relativizeAssetsUnder(result, options.baseDir);
+
   return result;
 }