@lalalic/markcut 3.0.0 → 3.1.1

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,
@@ -583,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

@@ -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);
   });
@@ -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

@@ -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;
@@ -355,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;
@@ -374,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) {
@@ -411,7 +445,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 +520,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 +974,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 +1113,7 @@ export async function resolveIncludes(
  */
 export async function resolveAll(
   root: DescriptiveRoot,
-  options: ResolveAllOptions = {},
+  options: ResolveAllOptions,
 ): Promise<DescriptiveRoot> {
   let result = root;
 
@@ -1180,5 +1217,151 @@ 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
+  // 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;
 }
+
+// ── 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)`);
+  }
+}
+