@lalalic/markcut 3.1.0 → 3.2.0

package/src/utils/directions.ts

@@ -0,0 +1,101 @@
+/**
+ * Server-side Google Directions REST helper.
+ *
+ * Used at resolve time (Node) to compute per-leg travel durations so map
+ * overlay children (`at:"Label"`) can be auto-timed (arrival + dwell). This
+ * is the same Directions REST pattern the spots CLI uses — one request per
+ * consecutive waypoint pair so mixed travel modes (FLIGHT/BOAT synthetic)
+ * can be interspersed with road legs.
+ *
+ * Requires GOOGLE_MAPS_API_KEY (Directions API enabled).
+ */
+import { makeSyntheticLeg, haversineKm } from "./route-legs";
+
+export interface RouteLegTiming {
+  mode: string;
+  from: { lat: number; lng: number };
+  to: { lat: number; lng: number };
+  /** Estimated travel time for this leg, in seconds. */
+  durationSec: number;
+}
+
+function apiKey(): string {
+  return (
+    (typeof process !== "undefined" && process.env.GOOGLE_MAPS_API_KEY) || ""
+  );
+}
+
+/** Directions travel modes (non-synthetic). */
+const ROAD_MODES = new Set(["DRIVING", "WALKING", "BICYCLING", "TRANSIT"]);
+
+/**
+ * Compute the travel time (seconds) for one leg. Road modes hit the
+ * Directions REST API; synthetic modes (FLIGHT/BOAT) are estimated from
+ * haversine distance at cruise speed — no API call, deterministic.
+ *
+ * Returns null when the Directions call fails (caller falls back to a
+ * straight-line estimate so timing still works offline).
+ */
+export async function legDurationSec(
+  from: { lat: number; lng: number },
+  to: { lat: number; lng: number },
+  mode: string,
+  key = apiKey(),
+): Promise<number | null> {
+  const m = (mode || "").toUpperCase();
+  if (!ROAD_MODES.has(m)) {
+    // Synthetic: distance at cruise speed (same math as the renderer).
+    return makeSyntheticLeg(from, to, m).durationSec;
+  }
+  if (!key) {
+    // No key → straight-line estimate (consistent, deterministic).
+    return straightLineSec(from, to);
+  }
+
+  const url = new URL("https://maps.googleapis.com/maps/api/directions/json");
+  url.searchParams.set("origin", `${from.lat},${from.lng}`);
+  url.searchParams.set("destination", `${to.lat},${to.lng}`);
+  url.searchParams.set("mode", m.toLowerCase());
+  url.searchParams.set("key", key);
+
+  try {
+    const res = await fetch(url);
+    const data = await res.json();
+    const dur = data?.routes?.[0]?.legs?.[0]?.duration?.value;
+    if (typeof dur === "number" && dur > 0) return dur;
+    return straightLineSec(from, to);
+  } catch {
+    return straightLineSec(from, to);
+  }
+}
+
+/** Fallback straight-line estimate (~50 km/h), so timing works without the API. */
+function straightLineSec(
+  from: { lat: number; lng: number },
+  to: { lat: number; lng: number },
+): number {
+  return (haversineKm(from, to) / 50) * 3600;
+}
+
+/**
+ * Compute per-leg timing for a full route.
+ *
+ * `modes[i]` is the travel mode of the leg leaving waypoints[i]
+ * (defaults to `defaultMode`). Returns one timing per consecutive pair.
+ */
+export async function routeLegTimings(
+  waypoints: { lat: number; lng: number; mode?: string }[],
+  defaultMode = "DRIVING",
+  key = apiKey(),
+): Promise<RouteLegTiming[]> {
+  if (waypoints.length < 2) return [];
+  const out: RouteLegTiming[] = [];
+  for (let i = 0; i < waypoints.length - 1; i++) {
+    const from = waypoints[i]!;
+    const to = waypoints[i + 1]!;
+    const mode = (from.mode ?? defaultMode).toUpperCase();
+    const durationSec = (await legDurationSec(from, to, mode, key)) ?? 0;
+    out.push({ mode, from, to, durationSec });
+  }
+  return out;
+}

package/src/utils/index.ts

@@ -104,6 +104,17 @@ export function getDurationInSeconds(stream: DurationStream, update = true): num
     return stream.durationInSeconds ?? 0;
   }
 
+  // Map is a leaf whose overlay children are positioned INSIDE it — its own
+  // base timing (end) defines the duration, not max(child durations).
+  if (stream.type === "map") {
+    const d = leafEnd(stream);
+    if (update) {
+      stream.durationInSeconds = d;
+      for (const child of stream.children ?? []) getDurationInSeconds(child, update);
+    }
+    return d;
+  }
+
   // include: if src is set, treat as leaf (duration from base end).
   // Otherwise fall back to inline children (legacy).
   if (stream.type === "include") {

package/src/utils/route-legs.ts

@@ -0,0 +1,199 @@
+/**
+ * Multi-leg route math for the `map` stream (view:"route").
+ *
+ * A route is a sequence of legs — one per consecutive waypoint pair. Each
+ * waypoint may tag the leg that LEAVES it with its own travel mode
+ * (`waypoint.mode ?? map.travelMode`). Supported modes:
+ *
+ *   DRIVING | WALKING | BICYCLING | TRANSIT   → Google Directions API
+ *   FLIGHT | BOAT                             → synthetic great-circle arc
+ *     (Directions has no air/water routes; we draw a curved arc and time it
+ *      from haversine distance at a cruise speed)
+ *
+ * Pure functions only (deterministic per second) so the animated marker and
+ * any future camera can share the same route-time math.
+ */
+export interface RouteLegStep {
+  path: { lat: number; lng: number }[];
+  durationSec: number;
+}
+
+export interface RouteLeg {
+  mode: string;
+  from: { lat: number; lng: number };
+  to: { lat: number; lng: number };
+  durationSec: number;
+  steps: RouteLegStep[];
+}
+
+/** Cruise speeds used to estimate synthetic leg durations (km/h). */
+export const FLIGHT_SPEED_KMH = 850;
+export const BOAT_SPEED_KMH = 40;
+
+/** Modes with no Directions route — rendered as synthetic great-circle arcs. */
+export function isSyntheticMode(mode?: string): boolean {
+  const m = (mode ?? "").toUpperCase();
+  return m === "FLIGHT" || m === "BOAT";
+}
+
+const EARTH_RADIUS_KM = 6371;
+const toRad = (d: number) => (d * Math.PI) / 180;
+const toDeg = (d: number) => (d * 180) / Math.PI;
+
+/** Great-circle (haversine) distance between two lat/lng points, in km. */
+export function haversineKm(
+  a: { lat: number; lng: number },
+  b: { lat: number; lng: number },
+): number {
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(a.lat)) * Math.cos(toRad(b.lat)) * Math.sin(dLng / 2) ** 2;
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.sqrt(h));
+}
+
+/**
+ * Interpolate the great-circle arc between two lat/lng points (the "as the
+ * crow flies" flight path), returning `points + 1` points including both ends.
+ */
+export function greatCirclePath(
+  a: { lat: number; lng: number },
+  b: { lat: number; lng: number },
+  points = 64,
+): { lat: number; lng: number }[] {
+  const φ1 = toRad(a.lat);
+  const λ1 = toRad(a.lng);
+  const φ2 = toRad(b.lat);
+  const λ2 = toRad(b.lng);
+  const d = haversineKm(a, b) / EARTH_RADIUS_KM; // angular distance (radians)
+  const out: { lat: number; lng: number }[] = [];
+  for (let i = 0; i <= points; i++) {
+    if (d === 0) {
+      out.push({ lat: a.lat, lng: a.lng });
+      continue;
+    }
+    const f = i / points;
+    const A = Math.sin((1 - f) * d) / Math.sin(d);
+    const B = Math.sin(f * d) / Math.sin(d);
+    const x = A * Math.cos(φ1) * Math.cos(λ1) + B * Math.cos(φ2) * Math.cos(λ2);
+    const y = A * Math.cos(φ1) * Math.sin(λ1) + B * Math.cos(φ2) * Math.sin(λ2);
+    const z = A * Math.sin(φ1) + B * Math.sin(φ2);
+    out.push({ lat: toDeg(Math.atan2(z, Math.sqrt(x * x + y * y))), lng: toDeg(Math.atan2(y, x)) });
+  }
+  return out;
+}
+
+/** Build a synthetic leg (FLIGHT ✈️ / BOAT 🚢) between two waypoints. */
+export function makeSyntheticLeg(
+  from: { lat: number; lng: number },
+  to: { lat: number; lng: number },
+  mode: string,
+): RouteLeg {
+  const speedKmh = (mode || "").toUpperCase() === "BOAT" ? BOAT_SPEED_KMH : FLIGHT_SPEED_KMH;
+  const durationSec = (haversineKm(from, to) / speedKmh) * 3600;
+  return {
+    mode: mode.toUpperCase(),
+    from,
+    to,
+    durationSec,
+    steps: [{ path: greatCirclePath(from, to), durationSec }],
+  };
+}
+
+/** Emoji glyph for a leg's travel mode (used for the traveling marker). */
+export function modeEmoji(mode?: string): string {
+  switch ((mode ?? "").toUpperCase()) {
+    case "FLIGHT": return "✈️";
+    case "BOAT": return "🚢";
+    case "WALKING": return "🚶";
+    case "BICYCLING": return "🚲";
+    case "TRANSIT": return "🚌";
+    case "DRIVING": return "🚗";
+    default: return "📍";
+  }
+}
+
+/** Position within one leg at normalized progress t ∈ [0,1] (step-timed). */
+export function positionAlongLeg(
+  leg: RouteLeg,
+  t: number,
+): { lat: number; lng: number } | null {
+  if (leg.steps.length === 0) return null;
+  const currentInSecond = t * leg.durationSec;
+  let acc = 0;
+  for (const step of leg.steps) {
+    if (currentInSecond <= acc + step.durationSec) {
+      const stepElapsed = currentInSecond - acc;
+      const stepProgress = step.durationSec > 0 ? stepElapsed / step.durationSec : 0;
+      const idx = Math.min(
+        Math.max(0, Math.floor(stepProgress * step.path.length)),
+        step.path.length - 1,
+      );
+      return step.path[idx] ?? null;
+    }
+    acc += step.durationSec;
+  }
+  const last = leg.steps[leg.steps.length - 1]!;
+  return last.path[last.path.length - 1] ?? null;
+}
+
+/**
+ * A dwell window where the pin holds still at a waypoint (a map overlay
+ * child is showing). `fromSec`/`toSec` are in the same timeline as
+ * `routePositionAtLegs`'s `seconds`.
+ */
+export interface RouteStopWindow {
+  label: string;
+  at: { lat: number; lng: number };
+  mode: string;
+  fromSec: number;
+  toSec: number;
+}
+
+/**
+ * Position of the traveling marker at a given timeline second, plus the mode
+ * of the leg it is currently on. Time is split across legs proportionally to
+ * each leg's duration. When `stops` is provided, the marker holds still at a
+ * waypoint during its dwell window (drive time is compressed around the
+ * dwells, matching the resolver's arrival math). Returns null when there is
+ * no route.
+ */
+export function routePositionAtLegs(
+  legs: RouteLeg[],
+  actionDuration: number,
+  seconds: number,
+  stops: RouteStopWindow[] = [],
+): { lat: number; lng: number; mode: string } | null {
+  if (legs.length === 0) return null;
+
+  // Inside a dwell window → hold at that waypoint.
+  const inStop = stops.find((s) => seconds >= s.fromSec && seconds < s.toSec);
+  if (inStop) {
+    return { lat: inStop.at.lat, lng: inStop.at.lng, mode: inStop.mode };
+  }
+
+  // Drive time = timeline seconds with completed/overlapping dwells removed.
+  let dwellBefore = 0;
+  for (const s of stops) {
+    if (seconds >= s.toSec) dwellBefore += s.toSec - s.fromSec;
+    else if (seconds > s.fromSec) dwellBefore += seconds - s.fromSec;
+  }
+  const driveTime = Math.max(0, seconds - dwellBefore);
+  const totalDwell = stops.reduce((s, st) => s + (st.toSec - st.fromSec), 0);
+  const driveBudget = Math.max(0.1, actionDuration - totalDwell);
+  const total = legs.reduce((s, l) => s + l.durationSec, 0);
+  const currentInSecond = driveTime * (total / driveBudget);
+  let acc = 0;
+  for (const leg of legs) {
+    if (currentInSecond <= acc + leg.durationSec) {
+      const t = leg.durationSec > 0 ? Math.min(Math.max((currentInSecond - acc) / leg.durationSec, 0), 1) : 0;
+      const pos = positionAlongLeg(leg, t);
+      return pos ? { ...pos, mode: leg.mode } : null;
+    }
+    acc += leg.durationSec;
+  }
+  const last = legs[legs.length - 1]!;
+  const pos = positionAlongLeg(last, 1);
+  return pos ? { ...pos, mode: last.mode } : null;
+}

package/tests/dsl.test.ts

@@ -113,6 +113,41 @@ describe("dsl — parseWaypoints", () => {
     ]);
   });
 
+  it("parses a bare travel mode without an empty media slot (smart)", () => {
+    expect(parseWaypoints('[40.7,-74.0,"NYC",FLIGHT; 34.05,-118.25,"LA","photo.jpg",BOAT]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: "NYC", media: undefined, mode: "FLIGHT" },
+      { lat: 34.05, lng: -118.25, label: "LA", media: "photo.jpg", mode: "BOAT" },
+    ]);
+  });
+
+  it("parses a bare travel mode as the only trailing field", () => {
+    expect(parseWaypoints('[40.7,-74.0,FLIGHT]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: undefined, media: undefined, mode: "FLIGHT" },
+    ]);
+  });
+
+  it("parses a bare mode even before the label", () => {
+    expect(parseWaypoints('[40.7,-74.0,BOAT,"Pier"]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: "Pier", media: undefined, mode: "BOAT" },
+    ]);
+  });
+
+  it("uppercases a lowercase bare mode", () => {
+    expect(parseWaypoints('[40.7,-74.0,"NYC",flight]')[0]!.mode).toBe("FLIGHT");
+  });
+
+  it("still accepts empty quoted media slots (backward compat)", () => {
+    expect(parseWaypoints('[40.7,-74.0,"NYC","",BOAT]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: "NYC", media: undefined, mode: "BOAT" },
+    ]);
+  });
+
+  it("treats a quoted mode word as a literal label/media (escape hatch)", () => {
+    expect(parseWaypoints('[40.7,-74.0,"NYC","FLIGHT"]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: "NYC", media: "FLIGHT", mode: undefined },
+    ]);
+  });
+
   it("returns empty array for non-bracket input", () => {
     expect(parseWaypoints("not a list")).toEqual([]);
   });

package/tests/evals/README.md

@@ -0,0 +1,41 @@
+# markcut storyboard evals
+
+DeepEval suite that scores an agent authoring markcut storyboards from a
+video brief, using the markcut skill.
+
+## Components
+
+| File | Purpose |
+| --- | --- |
+| `openrouter_model.py` | Token-capped OpenRouter LLM wrapper (free-tier friendly, with model fallback rotation) |
+| `gen_dataset.py` | Generates goldens from scratch via the Synthesizer |
+| `dataset.json` | The golden dataset (committed, editable) |
+| `storyboard_app.py` | Traced app: runs `pi` CLI with the markcut skill to author a storyboard |
+| `metrics.py` | Judge metrics: TaskCompletion, Storyboard Format GEval, Story Narrative GEval |
+| `test_storyboard.py` | pytest traced single-turn evals |
+
+## Regenerate the dataset
+
+```bash
+.venv-evals/bin/python tests/evals/gen_dataset.py
+```
+
+## Run the evals
+
+```bash
+cd tests/evals && ../../.venv-evals/bin/deepeval test run test_storyboard.py \
+  --identifier "iterating-on-storyboard-authoring-round-1"
+```
+
+Each test runs the pi agent on the golden's video brief and asserts
+trace-level metrics. Failures typically indicate the agent violated a
+skill rule (e.g. `duration:` on scripted scenes, missing
+`isBackground:true`) or produced weak narrative structure.
+
+## Notes
+
+- Evaluation model runs on OpenRouter free models; the wrapper caps
+  max_tokens at 16000 to fit the workspace key's daily budget and
+  rotates through fallback models on rate limits.
+- Traces are local (Confident AI not enabled); view latest results via
+  `deepeval view --latest` offline report in `.deepeval/`.

package/tests/evals/dataset.json

@@ -0,0 +1,170 @@
+[
+    {
+        "input": "30s cinematic coastal drive vlog w/ voiceover detailing scenic landmarks & geography",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Detail how teaser reveals specs, competitive edge, and launch strategy.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Draft a 2‑speaker dialogue explaining quantum computing, with visual analogy and real‑world app.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Develop a 5‑min pasta recipe paired with lo‑fi background music for enhanced cooking experience",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "How did 1960s Ford integrate sustainability into its corporate brand story?",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Create a cinematic sci-fi thriller trailer, <2 min, featuring dystopian cityscape and AI antagonist",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare walkthrough of modern luxury villa vs historic estate: design, amenities, layout.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare high-energy cuts vs. slow cinematic pacing for fitness motivation shorts.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Produce a short historical documentary snippet on the Indus. Rev., focusing on inventions",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare dashboard walkthroughs in SW A and B tutorials, noting UI similarities and differences.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare a 15‑s skincare ad with strong CTA vs a 30‑s ad: effectiveness, engagement, conversion.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Describe how pressure adaptations let deep-sea creatures survive extreme conditions in the clip.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "30s cinematic coastal drive vlog w/ voiceover detailing scenic landmarks & geography",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Detail how teaser reveals specs, competitive edge, and launch strategy.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Draft a 2‑speaker dialogue explaining quantum computing, with visual analogy and real‑world app.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Develop a 5‑min pasta recipe paired with lo‑fi background music for enhanced cooking experience",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "How did 1960s Ford integrate sustainability into its corporate brand story?",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Create a cinematic sci-fi thriller trailer, <2 min, featuring dystopian cityscape and AI antagonist",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare walkthrough of modern luxury villa vs historic estate: design, amenities, layout.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare high-energy cuts vs. slow cinematic pacing for fitness motivation shorts.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Produce a short historical documentary snippet on the Indus. Rev., focusing on inventions",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare dashboard walkthroughs in SW A and B tutorials, noting UI similarities and differences.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Compare a 15‑s skincare ad with strong CTA vs a 30‑s ad: effectiveness, engagement, conversion.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    },
+    {
+        "input": "Describe how pressure adaptations let deep-sea creatures survive extreme conditions in the clip.",
+        "actual_output": null,
+        "expected_output": null,
+        "context": null,
+        "source_file": null
+    }
+]

package/tests/evals/gen_dataset.py

@@ -0,0 +1,63 @@
+"""Generate the markcut storyboard goldens with a token-capped OpenRouter model.
+
+Run:
+  OPENROUTER_API_KEY=... .venv-evals/bin/python tests/evals/gen_dataset.py
+"""
+
+import os
+
+from deepeval.synthesizer import Synthesizer
+from deepeval.synthesizer.config import StylingConfig
+
+from openrouter_model import OpenRouterLLM
+
+SCENARIO = (
+    "Video creators and AI agents using the markcut markdown-to-video skill "
+    "to author video storyboards from a brief. markcut uses a markdown "
+    "descriptive format: '## scene' headings, '- image prompt:...' bullets, "
+    "script \"...\" narration, isBackground:true for visuals under scripted "
+    "scenes, map stream type with view/tween camera moves for route vlogs, "
+    "built-in components, TTS/TTI/STT media pipeline, and golden rules such "
+    "as never set duration on scripted scenes, keep manual assets in the "
+    "assets/ folder, and review md then compiled json then rendered video."
+)
+TASK = (
+    "Act as a storyboard author: given a video brief, produce a markcut "
+    "storyboard in markdown descriptive format that follows the skill's "
+    "scene/isBackground/duration rules and narrative structure (hook, "
+    "conflict, resolution, emotion, call to action)."
+)
+INPUT_FORMAT = (
+    "A short video brief, e.g. 'a 30s travel vlog of a coastal route with "
+    "narration', 'a product launch teaser with stats', 'a two-speaker "
+    "dialogue explainer', 'a recipe short with background music'."
+)
+EXPECTED_OUTPUT_FORMAT = (
+    "A complete markcut storyboard markdown using ## scene headings, "
+    "- image/script bullets, correct isBackground usage, and no manual "
+    "durations on scripted scenes."
+)
+
+
+def main():
+    model = OpenRouterLLM()
+    synthesizer = Synthesizer(
+        model=model,
+        styling_config=StylingConfig(
+            scenario=SCENARIO,
+            task=TASK,
+            input_format=INPUT_FORMAT,
+            expected_output_format=EXPECTED_OUTPUT_FORMAT,
+        ),
+    )
+    goldens = synthesizer.generate_goldens_from_scratch(num_goldens=12)
+    synthesizer.save_as(
+        file_type="json",
+        directory="tests/evals",
+        file_name="dataset",
+    )
+    print(f"Saved {len(goldens)} goldens to tests/evals/dataset.json")
+
+
+if __name__ == "__main__":
+    main()