@lalalic/markcut 3.1.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.1.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/docs/map-dynamic-camera.md

@@ -16,7 +16,7 @@ Use `map` clips when the video is about **a place and getting around**:
 - 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
+Every map clip can carry a `script` narration next to it (see §7 for the
 scene pattern that plays map + narration together).
 
 ---
@@ -101,7 +101,85 @@ Full example:
 
 ---
 
-## 5. Discovering spots along a route — `markcut spots`
+## 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
@@ -132,7 +210,7 @@ npx @lalalic/markcut spots --waypoints "37.8199,-122.4783;37.6213,-122.3790" \
 
 ---
 
-## 6. Markdown examples (copy-paste)
+## 8. Markdown examples (copy-paste)
 
 ### 6.1 Simple route clip with narration
 
@@ -184,9 +262,15 @@ layout:parallel
 ## 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}}
+- 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 →
@@ -219,12 +303,12 @@ layout:parallel
 ## 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}}
+- 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}}
 ```
 
 ---
 
-## 7. Recipe — build a route/vlog clip
+## 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.
@@ -234,10 +318,10 @@ layout:parallel
 
 ---
 
-## 8. Tips & pitfalls
+## 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. If a `streetview` scene looks dark/empty, pick a nearby well-covered location or use `view:cinematic` instead.
+- **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.

package/src/descriptive/compiler.ts

@@ -137,6 +137,8 @@ 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. */
@@ -188,6 +190,9 @@ export interface DescriptiveMap extends DescriptiveBaseNode {
       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 {
@@ -531,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;
   }
@@ -560,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),
@@ -677,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);
       }
@@ -893,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,15 +183,25 @@ 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 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 };
+    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

package/src/descriptive/markdown.ts

@@ -588,7 +588,8 @@ function processMDASTListItem(item: any, parent: ParentNode, lines: string[]): v
         node.type === "transitionSeries" ||
         node.type === "effect" ||
         node.type === "include" ||
-        node.type === "rhythm"
+        node.type === "rhythm" ||
+        node.type === "map"
       ) {
         for (const subItem of child.children) {
           processMDASTListItem(subItem, node as ParentNode, lines);

package/src/descriptive/resolve.test.ts

@@ -962,3 +962,101 @@ describe("resolveIncludes — variant overrides", () => {
     expect(incNode.durationInSeconds).toBe(2);
   });
 });
+
+// ── resolveRouteStops (map overlay auto-timing) ─────────────────────────────
+
+describe("resolveRouteStops", () => {
+  it("auto-times map children from synthetic FLIGHT leg durations (no network)", async () => {
+    const { resolveRouteStops } = await import("./resolve");
+    const root: any = {
+      type: "root",
+      children: [
+        {
+          type: "scene",
+          children: [
+            {
+              type: "map",
+              view: "route",
+              travelMode: "FLIGHT",
+              waypoints: [
+                { lat: 37.7749, lng: -122.4194, label: "SF" },
+                { lat: 34.0522, lng: -118.2437, label: "LA" },
+                { lat: 33.9425, lng: -118.4081, label: "PIER" },
+              ],
+              children: [
+                { type: "image", at: "LA", duration: 4 },
+                { type: "image", at: "PIER", duration: 2 },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    await resolveRouteStops(root);
+
+    const map = root.children[0].children[0];
+    const [la, pier] = map.children;
+
+    // Map duration = default drive budget (10s) + dwells (4 + 2) = 16s.
+    expect(map.duration).toBeCloseTo(16, 1);
+
+    // First child arrives at LA after leg 1 (SF→LA ≈ 2367s of 2481s total)
+    // scaled into the 10s drive budget → ≈ 9.5s, dwells 4s.
+    expect(la.start).toBeGreaterThan(9);
+    expect(la.start).toBeLessThan(10);
+    expect(la.end - la.start).toBeCloseTo(4, 6);
+
+    // Second child arrives at PIER after leg 2 + the LA dwell → ≈ 14s.
+    expect(pier.start).toBeGreaterThan(13.5);
+    expect(pier.start).toBeLessThan(14.5);
+    expect(pier.end - pier.start).toBeCloseTo(2, 6);
+
+    // Children with explicit `start` are left untouched.
+    const explicit: any = {
+      type: "map",
+      view: "route",
+      travelMode: "FLIGHT",
+      waypoints: [
+        { lat: 37.7749, lng: -122.4194, label: "SF" },
+        { lat: 34.0522, lng: -118.2437, label: "LA" },
+      ],
+      children: [{ type: "image", at: "LA", duration: 4, start: 3, end: 7 }],
+    };
+    const explicitRoot: any = { type: "root", children: [explicit] };
+    await resolveRouteStops(explicitRoot);
+    expect(explicit.children[0].start).toBe(3);
+    expect(explicit.children[0].end).toBe(7);
+  });
+
+  it("respects an explicit map duration (drives shrink to fit drives+dwells)", async () => {
+    const { resolveRouteStops } = await import("./resolve");
+    const root: any = {
+      type: "root",
+      children: [
+        {
+          type: "map",
+          view: "route",
+          duration: 20,
+          travelMode: "FLIGHT",
+          waypoints: [
+            { lat: 37.7749, lng: -122.4194, label: "SF" },
+            { lat: 34.0522, lng: -118.2437, label: "LA" },
+            { lat: 33.9425, lng: -118.4081, label: "PIER" },
+          ],
+          children: [{ type: "image", at: "LA", duration: 4 }],
+        },
+      ],
+    };
+
+    await resolveRouteStops(root);
+
+    const map = root.children[0];
+    expect(map.duration).toBe(20);
+    // Dwell 4s stays; drives get the remaining 16s budget proportionally.
+    const la = map.children[0];
+    expect(la.start).toBeGreaterThan(14);
+    expect(la.start).toBeLessThan(17);
+    expect(la.end - la.start).toBeCloseTo(4, 6);
+  });
+});

package/src/descriptive/resolve.ts

@@ -384,15 +384,20 @@ export async function resolveScripts(
   const clone: DescriptiveRoot = JSON.parse(JSON.stringify(root));
   mkdirSync(options.outputDir, { recursive: true });
 
-  // Collect all audio nodes that have script text but no src yet
-  const allScriptNodes: Array<{ node: any; id: string }> = [];
-  walkDown(clone as any, (node) => {
-    if (node.type !== "audio") return;
-    if (!node.script || typeof node.script !== "string") return;
-    if (node.src) return; // already has real source
-    const id = node.id ?? `audio-${allScriptNodes.length}`;
-    allScriptNodes.push({ node, id });
-  });
+  // Collect all audio nodes that have script text but no src yet. Each node
+  // carries the nearest ancestor's `tts` override (root.tts by default), so a
+  // scene-level `tts` wins over root while other scenes keep root's voice.
+  const allScriptNodes: Array<{ node: any; id: string; ttsOverride?: string }> = [];
+  const collect = (node: any, inherited?: string): void => {
+    const ttsOverride =
+      typeof node.tts === "string" && node.tts.length > 0 ? node.tts : inherited;
+    if (node.type === "audio" && node.script && typeof node.script === "string" && !node.src) {
+      const id = node.id ?? `audio-${allScriptNodes.length}`;
+      allScriptNodes.push({ node, id, ttsOverride });
+    }
+    for (const c of node.children ?? []) collect(c, ttsOverride);
+  };
+  collect(clone as any);
 
   const totalScripts = allScriptNodes.length;
   let scriptsDone = 0;
@@ -403,10 +408,10 @@ export async function resolveScripts(
     console.log(`  🔊 TTS: generating ${totalScripts} script${totalScripts > 1 ? "s" : ""}...`);
   }
 
-  for (const { node, id } of allScriptNodes) {
+  for (const { node, id, ttsOverride } of allScriptNodes) {
     scriptsDone++;
-    // TTS CLI from root config only
-    let ttsCli = clone.tts ?? options.ttsCli ?? DEFAULT_TTS_CLI;
+    // TTS CLI: nearest ancestor `tts` (root.tts by default) → options → default
+    let ttsCli = ttsOverride ?? options.ttsCli ?? DEFAULT_TTS_CLI;
 
     // Per-speaker voice appends extra CLI flags from root voices config
     if (node.speaker && clone.voices) {
@@ -1212,6 +1217,11 @@ export async function resolveAll(
     });
   }
 
+  // Step 6: Auto-time map overlay children (at:"Waypoint") from the route —
+  // arrival + dwell, so the author writes no timing. Only maps with anchored
+  // children lacking explicit start trigger Directions calls.
+  result = await resolveRouteStops(result);
+
   // 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
@@ -1221,3 +1231,137 @@ export async function resolveAll(
 
   return result;
 }
+
+// ── Route stops (auto-time map overlay children) ─────────────────────────
+
+/** Default duration for a map child with no explicit duration / audio. */
+const DEFAULT_CHILD_SECONDS = 3;
+
+/** Default drive budget (seconds) when the map has no explicit duration —
+ *  drives fill this, dwells are added on top. Real Directions durations are
+ *  only used for leg ratios. */
+const DEFAULT_MAP_DRIVE_SECONDS = 10;
+
+/**
+ * For every `map` node with children anchored via `at:"WaypointLabel"`, derive
+ * each child's `start`/`end` from the route's travel times:
+ *
+ *   - leg durations from Directions REST (road modes) or haversine cruise
+ *     speed (FLIGHT/BOAT synthetic) — same math the renderer uses
+ *   - the pin holds (dwells) at a waypoint while its children play
+ *   - drives are scaled proportionally to leg duration across the remaining
+ *     budget, so arrivals match the renderer's `routePositionAtLegs`
+ *
+ * Children that already have an explicit `start` are left untouched (but still
+ * contribute to the pin's pause window). When the map has no explicit duration,
+ * it is set to drives + dwells.
+ */
+export async function resolveRouteStops(
+  root: DescriptiveRoot,
+): Promise<DescriptiveRoot> {
+  const { routeLegTimings } = await import("../utils/directions");
+
+  async function resolveMap(node: any): Promise<void> {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const n of node) await resolveMap(n);
+      return;
+    }
+
+    if (node.type === "map" && Array.isArray(node.children) && node.children.length) {
+      const children = node.children as any[];
+      const anchored = children.filter((c) => c && c.at);
+      if (anchored.length) {
+        await timeMapChildren(node, anchored, routeLegTimings);
+      }
+    }
+
+    for (const child of node.children ?? []) await resolveMap(child);
+  }
+
+  await resolveMap((root as any).children);
+  return root;
+}
+
+async function timeMapChildren(
+  map: any,
+  anchored: any[],
+  routeLegTimings: (waypoints: any[], defaultMode?: string) => Promise<{ durationSec: number }[]>,
+): Promise<void> {
+  const waypoints = map.waypoints ?? [];
+  if (waypoints.length < 2) return;
+
+  // 1. Per-leg travel times.
+  const legs = await routeLegTimings(waypoints, map.travelMode ?? "DRIVING");
+  const totalDrive = legs.reduce((s, l) => s + (l.durationSec || 0), 0);
+  if (totalDrive <= 0) return;
+
+  // 2. Per-waypoint dwell = max duration of anchored children there.
+  const childDuration = (c: any): number =>
+    typeof c.duration === "number" && c.duration > 0 ? c.duration : DEFAULT_CHILD_SECONDS;
+  const dwellAt = new Map<string, number>();
+  for (const c of anchored) {
+    const d = childDuration(c);
+    dwellAt.set(c.at, Math.max(dwellAt.get(c.at) ?? 0, d));
+  }
+  const totalDwell = [...dwellAt.values()].reduce((s, d) => s + d, 0);
+
+  // 3. Timeline: drives scaled proportionally across the drive budget; dwells
+  //    inserted after each arrival. arrival(i) = S·cumDrive(i)/D + cumDwells(<i).
+  //    Real Directions durations only provide RATIOS — the video length is the
+  //    author's map `duration` (or a default), so a 40-minute drive still plays
+  //    as a short clip with the pin timing proportional to each leg.
+  const hasOwnDur = typeof map.duration === "number" || typeof map.endAt === "number";
+  const totalDwellBudget = Math.max(0, map.duration ?? map.endAt ?? DEFAULT_MAP_DRIVE_SECONDS);
+  const mapDur = hasOwnDur
+    ? (map.duration ?? map.endAt ?? totalDwellBudget + totalDwell)
+    : totalDwellBudget + totalDwell;
+  const driveBudget = Math.max(0.1, mapDur - totalDwell);
+  const scale = driveBudget / totalDrive;
+
+  const arrivalAt = new Map<string, number>();
+  // The pin is at waypoint[0] from t=0 — `at` there means "from the start".
+  const wp0 = waypoints[0]!;
+  arrivalAt.set(wp0.label ?? String(wp0.lat) + "," + String(wp0.lng), 0);
+  let cumDrive = 0;
+  let cumDwells = 0;
+  for (let i = 0; i < legs.length; i++) {
+    cumDrive += legs[i]!.durationSec || 0;
+    const wp = waypoints[i + 1]!;
+    const arrival = (cumDrive * scale) + cumDwells;
+    arrivalAt.set(wp.label ?? String(wp.lat) + "," + String(wp.lng), arrival);
+    if (dwellAt.has(wp.label)) cumDwells += dwellAt.get(wp.label)!;
+  }
+
+  // 4. Stamp children that lack explicit timing.
+  const schedule: string[] = [];
+  for (const c of anchored) {
+    const arrival = arrivalAt.get(c.at);
+    if (arrival == null) {
+      console.warn(`  ⚠ map child at:"${c.at}" — no waypoint with that label; renders full-screen`);
+      continue;
+    }
+    if (typeof c.start === "number") {
+      schedule.push(`  🛑 ${c.at}: manual ${c.start.toFixed(1)}s (unchanged)`);
+      continue;
+    }
+    const dur = childDuration(c);
+    c.start = arrival;
+    c.end = arrival + dur;
+    schedule.push(`  🛑 ${c.at}: ${arrival.toFixed(1)}s → ${(arrival + dur).toFixed(1)}s (${dur.toFixed(1)}s)`);
+  }
+
+  if (schedule.length) {
+    console.log(`  🗺 route stops (${mapDur.toFixed(1)}s total):`);
+    for (const line of schedule) console.log(line);
+  }
+
+  // 5. Extend map duration if the author didn't set one (or it's too short).
+  if (!hasOwnDur) {
+    map.duration = mapDur;
+  } else if ((map.duration ?? 0) < mapDur) {
+    map.duration = mapDur;
+    console.log(`  🗺 extended map duration → ${mapDur.toFixed(1)}s (drives + dwells)`);
+  }
+}
+