@lalalic/markcut 3.0.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "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,328 @@
+# 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 §7 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. Per-leg travel modes (flight ✈️ / boat 🚢 / walk 🚶 / drive 🚗)
+
+A route is a sequence of **legs** — one per consecutive waypoint pair. Each
+waypoint can tag the leg that **leaves it** with its own travel mode. The
+parser is smart: a **bare (unquoted) mode word anywhere after lat/lng** is the
+outgoing-leg mode — no empty slots needed. Untagged waypoints fall back to
+the map's `travelMode` (default DRIVING).
+
+```
+[lat,lng,"Label","media",MODE]   # full
+[lat,lng,"Label",MODE]            # mode without media (no empty "") — smart
+[lat,lng,MODE]                     # just a mode
+```
+
+| mode | how it renders |
+|---|---|
+| `DRIVING` (default) | Google Directions road route — solid line, 🚗 marker |
+| `WALKING` | Google Directions pedestrian route — 🚶 marker |
+| `BICYCLING` | Google Directions bike route — 🚲 marker |
+| `TRANSIT` | Google Directions transit route — 🚌 marker |
+| `FLIGHT` | **synthetic great-circle arc** (no road) — dashed yellow line, ✈️ marker |
+| `BOAT` | **synthetic arc across water** — dashed teal line, 🚢 marker |
+
+FLIGHT/BOAT have no Directions route, so they're drawn as curved "as the crow
+flies" arcs and timed by distance at a cruise speed (✈️ ~850 km/h, 🚢 ~40 km/h).
+The traveling marker switches glyph to the current leg's mode as it moves, and
+time is split across legs **proportionally to each leg's duration**.
+
+Rules:
+- A mode word must be **unquoted** — quote it (`"FLIGHT"`) and it's a literal
+  label/media instead. That's the escape hatch if a media file is literally
+  named `FLIGHT`.
+- Quoted-empty `""` slots are still accepted (backward compat).
+- Remaining values map positionally: 1st = label, 2nd = media.
+
+Example — fly in, take a boat, walk, then drive:
+
+```md
+- map view:route duration:12 travelMode:DRIVING
+  waypoints:[37.8199,-122.4783,"SFO",FLIGHT; 33.94,-118.41,"LAX",BOAT; 33.75,-118.28,"Long Beach",WALKING; 33.77,-118.19,"Promenade",DRIVING; 33.94,-118.41,"LAX"]
+```
+
+Legs above: SFO→LAX by ✈️, LAX→Long Beach by 🚢, Long Beach→Promenade by 🚶,
+Promenade→LAX by 🚗 (the last waypoint has no outgoing leg, so its mode is
+ignored).
+
+## 6. Stops & anchored overlays (the vlog pattern)
+
+The typical vlog: the pin moves leg-to-leg, then **stops at a hotspot** while a
+photo/video/narration plays, then continues. Make other streams **children of
+the map** and anchor them with `at:"WaypointLabel"` — the map renders them at
+that waypoint's screen position (projected from the live map), so a photo
+grows out of the pin's location.
+
+```md
+- map view:route duration:16 travelMode:DRIVING
+  waypoints:[37.81,-122.48,"Golden Gate"; 37.77,-122.42,"Civic Center"; 37.62,-122.38,"SFO"]
+  - image src:gg.jpg at:"Golden Gate" duration:3 effects:[zoomIn]
+  - image src:civic.jpg at:"Civic Center" duration:3 effects:[zoomIn]
+```
+
+- `at:"Label"` anchors the child at the waypoint with that label. The renderer
+  projects the waypoint's lat/lng to its screen pixel each frame and centers
+  the child there — combine with `effects:[zoomIn]` for a "grows out of the
+  pin" reveal.
+- Children **without** `at` render full-screen over the map.
+- **Auto-timing (default)** — give the child a `duration` and *no* `start`; at
+  resolve time the map computes each leg's travel time (Directions REST for
+  road modes, cruise speed for `FLIGHT`/`BOAT`) and schedules the child to
+  start **at the pin's arrival** at that waypoint. The pin pauses (dwells)
+  while the child plays, then resumes. Real drive times are used only for
+  *ratios* — the video length stays the map's `duration`, or a default 10s
+  drive budget + dwells when the map has none, so a 40-minute drive still
+  plays as a short clip with the pin timing proportional to each leg.
+- **Manual timing (opt-out)** — set `start` explicitly and the resolver leaves
+  it untouched (it still contributes to the pin's pause window).
+- The map's own `duration`/`end` defines its span; children run inside it.
+
+## 7. 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.
+
+---
+
+## 8. 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.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+```
+
+> **Walk = snap between covered waypoints.** A `route` walk holds at each
+> waypoint's panorama and jumps between them (not continuous per-frame
+> movement — that would fire hundreds of Street View requests and get
+> rate-limited into black frames). Every waypoint needs imagery; gaps show the
+> last loaded panorama instead of black.
+
+### 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.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+```
+
+---
+
+## 9. 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`.
+
+---
+
+## 10. 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 (Google returns "no imagery here"); interpolating between sparse points also crosses uncovered blocks. Pick waypoints you've verified have imagery (open the coords in Google Maps, drag the pegman), keep a `route` walk's waypoints on the same covered street, and set `radius` (meters) so the panorama search is constrained nearby. If a `streetview` scene still looks dark, 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

@@ -137,11 +137,22 @@ export interface DescriptiveMapWaypoint {
   lng: number;
   label?: string;
   media?: string;
+  /** Travel mode for the leg leaving this waypoint (DRIVING|WALKING|BICYCLING|TRANSIT|FLIGHT|BOAT). */
+  mode?: 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 +162,37 @@ 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;
+    };
+  };
+  /** Overlay children rendered on top of the map.
+   *  A child with `at:"Label"` is positioned at that waypoint's screen pixel. */
+  children?: DescriptiveNode[];
 }
 
 export interface DescriptiveContainer extends DescriptiveBaseNode {
@@ -494,6 +536,7 @@ function wrapWithEffects(
       start: isOutermost && isBgNoEnd ? innerStream.start : effStart,
       end: isOutermost && isBgNoEnd ? undefined : effEnd,
       visible: innerStream.visible ?? true,
+      at: (node as any).at,
       ...pickOn(node),
     } as Effect;
   }
@@ -523,6 +566,7 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
     style: node.style,
     visible: node.visible ?? true,
     isBackground: node.isBackground,
+    at: (node as any).at,
     start: isBgNoOwnTiming ? (typeof node.start === "number" ? node.start : undefined) : start,
     end,
     startFrom: isBgNoOwnTiming ? undefined : (node.type === "video" || node.type === "audio" ? node.startFrom : undefined),
@@ -601,6 +645,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 +656,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 };
@@ -636,7 +684,7 @@ function compileChildren(
       } else if (isRhythm(child)) {
         result = compileRhythm(child, ctx, parentKind);
       } else if (isMap(child)) {
-        result = compileLeaf(child, ctx, parentKind);
+        result = compileMap(child, ctx, parentKind);
       } else {
         result = compileLeaf(child, ctx, parentKind);
       }
@@ -852,6 +900,58 @@ function compileRhythm(
   return { stream, duration: end };
 }
 
+function compileMap(
+  node: DescriptiveMap,
+  ctx: CompileContext,
+  parentKind: "series" | "parallel" | "transitionSeries",
+): CompileResult {
+  const id = node.id ?? uid();
+  const start = parentKind === "parallel" ? Math.max(0, node.start ?? 0) : 0;
+  const ownDuration = deriveLeafDuration(node as any, ctx);
+  const end = ownDuration != null ? start + ownDuration : undefined;
+
+  // Compile overlay children (they play in parallel on top of the map).
+  // Children with `at:"Label"` carry it through compilation on their base.
+  const children = node.children ?? [];
+  const compiledChildren = children.length
+    ? compileChildren(children, ctx, "parallel")
+    : [];
+
+  // Map duration covers its own span + any children that extend past it.
+  const maxChildEnd = compiledChildren.reduce((max, c) => Math.max(max, c.duration), 0);
+  const mapDuration = Math.max(end ?? 0, maxChildEnd, ownDuration ?? 0);
+
+  const stream: MapStream = {
+    id,
+    type: "map",
+    style: node.style,
+    visible: node.visible ?? true,
+    isBackground: node.isBackground,
+    start,
+    end: mapDuration,
+    durationInSeconds: mapDuration,
+    view: node.view ?? "route",
+    waypoints: node.waypoints,
+    routeColor: node.routeColor ?? "#4285F4",
+    routeWeight: node.routeWeight ?? 4,
+    zoom: node.zoom ?? 10,
+    center: node.center,
+    mapType: node.mapType ?? "roadmap",
+    language: node.language,
+    region: node.region,
+    travelMode: node.travelMode ?? "DRIVING",
+    routeMarker: node.routeMarker ?? "🚗",
+    camera: node.camera,
+    cinematic: node.cinematic,
+    streetView: node.streetView,
+    googleMapsApiKey: ctx.googleMapsApiKey,
+    children: compiledChildren.map((c) => c.stream),
+    ...pickOn(node),
+  };
+
+  return { stream, duration: mapDuration };
+}
+
 function compileContainer(node: DescriptiveContainer, ctx: CompileContext, parentKind: "series" | "parallel" | "transitionSeries"): CompileResult {
   const id = node.id ?? uid();
   ensureUniqueIds(node.children, id);

package/src/descriptive/dsl.ts

@@ -162,7 +162,17 @@ export function parseNumberMaybe(v: string): number | string | boolean {
  * Parse a map `waypoints:[...]` value into an array of waypoints.
  *
  * Format: `[lat,lng,"Label"; lat,lng,"Label"]` — semicolon-separated entries,
- * comma-separated fields. Returns `[]` on any structural mismatch.
+ * comma-separated fields. After lat/lng, the optional fields are parsed
+ * smartly:
+ *   - a BARE (unquoted) token that names a travel mode (DRIVING, WALKING,
+ *     BICYCLING, TRANSIT, FLIGHT, BOAT) is the outgoing-leg mode, wherever it
+ *     appears — so `[lat,lng,"Label",FLIGHT]` or `[lat,lng,FLIGHT]` work with
+ *     no empty media slot;
+ *   - quoted-empty `""` slots are skipped (backward compat for
+ *     `[lat,lng,"Label","",MODE]`);
+ *   - remaining values map positionally: 1st = label, 2nd = media.
+ * Quoted tokens are always literal (a quoted "FLIGHT" is a label/media, not a
+ * mode). Returns `[]` on any structural mismatch.
  */
 export function parseWaypoints(raw: string): DescriptiveMapWaypoint[] {
   const s = raw.trim();
@@ -173,29 +183,76 @@ export function parseWaypoints(raw: string): DescriptiveMapWaypoint[] {
     const bits = splitTokens(part.replace(/,/g, " "));
     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 };
+    let mode: string | undefined;
+    const values: string[] = [];
+    for (const tok of bits.slice(2)) {
+      const value = unquote(tok);
+      if (!isQuoted(tok) && value && KNOWN_TRAVEL_MODES.has(value.toUpperCase())) {
+        mode = value.toUpperCase();
+        continue;
+      }
+      values.push(value); // keep position — a quoted-empty "" means "no value here"
+    }
+    const label = values[0] || undefined;
+    const media = values[1] || undefined;
+    return { lat, lng, label, media, mode };
   });
 }
 
+/** Bare (unquoted) waypoint tokens recognized as a travel mode. */
+const KNOWN_TRAVEL_MODES = new Set(["DRIVING", "WALKING", "BICYCLING", "TRANSIT", "FLIGHT", "BOAT"]);
+
+/**
+ * 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 +271,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 {};