@lalalic/markcut 3.0.0 → 3.1.0

package/src/utils/tween.ts

@@ -14,7 +14,7 @@ import * as React from "react";
 import { interpolate, useCurrentFrame, Easing } from "remotion";
 
 /** Built-in easing name → Remotion easing function. */
-const EASING_MAP: Record<string, ((t: number) => number) | undefined> = {
+export const EASING_MAP: Record<string, ((t: number) => number) | undefined> = {
   linear: undefined,
   ease: Easing.ease,
   easeIn: Easing.in(Easing.ease),
@@ -116,3 +116,51 @@ export function useTweenBindings(action: { start?: number; end?: number }): Reco
 
   return { tween, interpolate };
 }
+
+// ---------------------------------------------------------------------------
+// Tween spec resolution (used by stream leaf renderers, e.g. Map.tsx)
+// ---------------------------------------------------------------------------
+
+/**
+ * A tween expression as parsed by the descriptive DSL: `tween(from, to, easing?)`
+ * becomes `{ __tween: [from, to, easing?] }` (see parseProps in dsl.ts).
+ */
+export interface TweenSpec {
+  __tween: Array<number | string>;
+}
+
+/** A static number OR a tween spec. */
+export type Tweenable = number | TweenSpec;
+
+/**
+ * Resolve a `Tweenable` to a per-frame value — deterministic per frame.
+ *
+ * - A plain number is returned as-is (static).
+ * - A `{__tween:[from,to,easing?]}` spec is interpolated over the node's
+ *   `[start, end]` (seconds) using the current frame.
+ * - Anything malformed falls back to `fallback`.
+ */
+export function resolveTween(
+  frame: number,
+  fps: number,
+  spec: Tweenable | undefined,
+  start: number,
+  end: number,
+  fallback: number,
+): number {
+  if (typeof spec === "number") return spec;
+  const tween = spec?.__tween;
+  if (!tween || tween.length < 2) return fallback;
+  const from = Number(tween[0]);
+  const to = Number(tween[1]);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return fallback;
+  const easingName = typeof tween[2] === "string" ? tween[2] : undefined;
+  const easingFn = easingName ? EASING_MAP[easingName] : undefined;
+  const startF = Math.max(0, Math.floor(start * fps));
+  const endF = Math.max(startF + 1, Math.floor(end * fps));
+  return interpolate(frame, [startF, endF], [from, to], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+    easing: easingFn,
+  });
+}

package/tests/dsl.test.ts

@@ -100,6 +100,19 @@ describe("dsl — parseWaypoints", () => {
     expect(parseWaypoints("[40.7,-74.0]")).toEqual([{ lat: 40.7, lng: -74.0, label: undefined }]);
   });
 
+  it("parses waypoint media as a 4th field", () => {
+    expect(parseWaypoints('[40.7,-74.0,"NYC","photo1.jpg"; 34.05,-118.25,"LA","clip.mp4"]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: "NYC", media: "photo1.jpg" },
+      { lat: 34.05, lng: -118.25, label: "LA", media: "clip.mp4" },
+    ]);
+  });
+
+  it("parses waypoint media without a label", () => {
+    expect(parseWaypoints('[40.7,-74.0,"","img.jpg"]')).toEqual([
+      { lat: 40.7, lng: -74.0, label: undefined, media: "img.jpg" },
+    ]);
+  });
+
   it("returns empty array for non-bracket input", () => {
     expect(parseWaypoints("not a list")).toEqual([]);
   });
@@ -133,6 +146,36 @@ describe("dsl — parseProps", () => {
   it("returns {} for unclosed object", () => {
     expect(parseProps("{a:1")).toEqual({});
   });
+
+  it("parses tween() expressions into tagged specs", () => {
+    expect(parseProps("{zoom:tween(6, 12)}")).toEqual({ zoom: { __tween: [6, 12] } });
+  });
+
+  it("parses tween() with easing", () => {
+    expect(parseProps("{zoom:tween(6, 12, easeInOut)}")).toEqual({
+      zoom: { __tween: [6, 12, "easeInOut"] },
+    });
+  });
+
+  it("parses tween() nested inside objects and arrays", () => {
+    expect(parseProps("{center:{lat:tween(37.0, 37.9), lng:120}, pov:{heading:tween(200, 320)}}")).toEqual({
+      center: { lat: { __tween: [37.0, 37.9] }, lng: 120 },
+      pov: { heading: { __tween: [200, 320] } },
+    });
+  });
+
+  it("parses tween() with quoted string values (colors)", () => {
+    expect(parseProps('{color:tween("#000000", "#FFFFFF", easeOut)}')).toEqual({
+      color: { __tween: ["#000000", "#FFFFFF", "easeOut"] },
+    });
+  });
+
+  it("keeps static numbers alongside tweens", () => {
+    expect(parseProps("{zoom:tween(6, 12), tilt:45}")).toEqual({
+      zoom: { __tween: [6, 12] },
+      tilt: 45,
+    });
+  });
 });
 
 describe("dsl — parseOnSpec", () => {

package/tests/fixtures/map-dynamic.json

@@ -0,0 +1,52 @@
+{
+  "id": "root",
+  "type": "root",
+  "width": 640,
+  "height": 480,
+  "fps": 30,
+  "isSeries": true,
+  "transition": "fade",
+  "transitionTime": 0.3,
+  "children": [
+    {
+      "id": "overview",
+      "type": "map",
+      "view": "overview",
+      "name": "satellite-dolly",
+      "mapType": "satellite",
+      "center": { "lat": 37.7749, "lng": -122.4194 },
+      "zoom": 6,
+      "camera": { "zoom": { "__tween": [6, 12, "easeInOut"] } },
+      "start": 0,
+      "end": 3
+    },
+    {
+      "id": "cinematic",
+      "type": "map",
+      "view": "cinematic",
+      "name": "cinematic-flyover",
+      "waypoints": [
+        { "lat": 37.7749, "lng": -122.4194, "label": "SF" },
+        { "lat": 34.0522, "lng": -118.2437, "label": "LA" }
+      ],
+      "cinematic": { "mode": "flyAlong", "headingFollow": true, "tilt": { "__tween": [20, 45] } },
+      "camera": { "zoom": { "__tween": [12, 14, "easeInOut"] } },
+      "start": 0,
+      "end": 8
+    },
+    {
+      "id": "streetview",
+      "type": "map",
+      "view": "streetview",
+      "name": "streetview-pan",
+      "streetView": {
+        "location": { "lat": 37.7749, "lng": -122.4194 },
+        "radius": 50,
+        "pov": { "heading": { "__tween": [200, 320, "easeInOut"] }, "pitch": 0 },
+        "zoom": { "__tween": [0, 0.5, "easeInOut"] }
+      },
+      "start": 0,
+      "end": 6
+    }
+  ]
+}

package/tests/fixtures/md/animate-diagrams.md

@@ -13,8 +13,8 @@ layout:parallel
   ~~~
 
 ## FlowChart
-layout:parallel
-- component id:flowChart duration:12
+layout:series
+- component id:flowChart isBackground:true 
   ~~~jsx
   <div style={{position:'absolute',top:0,left:0,width:640,height:480,background:'#1a1a2e',padding:10,fontFamily:'monospace',boxSizing:'border-box',display:'flex',flexDirection:'column'}}>
     <p style={{color:'#00d4ff',fontSize:12,textAlign:'center',margin:'0 0 4px 0',flexShrink:0}}>Flow — {highlight}</p>
@@ -33,8 +33,10 @@ layout:parallel
     F --> G["Send Response"]
     classDef highlight fill:#ffd700,stroke:#ff6600,stroke-width:3px,color:#000
   ~~~
-  highlight:"A"
-  animateEdges:true
-- event duration:3 start:3 on:(start, flowChart.highlight="B";flowChart.animateEdges=["B->C"])
-- event duration:3 start:6 on:(start, flowChart.highlight="C")
-- event duration:3 start:9 on:(start, flowChart.highlight=["D","G"])
+- script on:(start, flowChart.highlight="A")
+  ~~~script
+  
+  ~~~
+- script on:(start, flowChart.highlight="B")
+- script on:(start, flowChart.highlight="C")
+- script on:(start, flowChart.highlight=["D","G"])

package/tests/fixtures/md/map-all-views.md

@@ -0,0 +1,28 @@
+# video
+seed:2668727180
+width:640 height:480 fps:30 layout:series transition:fade transitionTime:0.5
+
+## Satellite-Dolly
+layout:parallel
+- script "We begin high above San Francisco, then dive into the city."
+- map view:overview mapType:satellite duration:4 center:{lat:37.7749,lng:-122.4194} camera:{zoom:tween(6, 12, easeInOut)}
+
+## Route
+layout:parallel
+- script "The route winds from the Golden Gate to the airport, with photos at each stop."
+- map view:route duration:6 travelMode:DRIVING mapType:roadmap routeColor:"#4285F4" routeWeight:5 routeMarker:"🚗" waypoints:[37.8199,-122.4783,"Golden Gate","https://picsum.photos/seed/gg-bridge/96/96"; 37.7749,-122.4194,"Civic Center","https://picsum.photos/seed/civic-center/96/96"; 37.6213,-122.3790,"SFO","https://picsum.photos/seed/sfo-airport/96/96"]
+
+## Cinematic
+layout:parallel
+- script "The camera tilts and chases the road like a drone."
+- map view:cinematic duration:8 travelMode:DRIVING mapType:satellite routeMarker:"🚗" cinematic:{mode:flyAlong, headingFollow:true, tilt:tween(0, 45, easeInOut)} camera:{zoom:tween(12, 14, easeInOut)} waypoints:[37.8199,-122.4783,"Golden Gate"; 37.7749,-122.4194,"Civic Center"; 37.6213,-122.3790,"SFO"]
+
+## Street-View
+layout:parallel
+- script "And finally, we land on the street itself."
+- map view:streetview duration:8 streetView:{location:{lat:37.7793,lng:-122.4193}, radius:50, pov:{heading:tween(200, 420, easeInOut), pitch:tween(0, -8)}, zoom:tween(0, 0.6, easeInOut)}
+
+## Street-View-Walk
+layout:parallel
+- script "A quick walk down the block."
+- map view:streetview duration:6 streetView:{route:[{lat:37.7793,lng:-122.4193}, {lat:37.7785,lng:-122.4185}, {lat:37.7777,lng:-122.4178}, {lat:37.7769,lng:-122.4170}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}

package/tests/md-descriptive.test.ts

@@ -897,6 +897,64 @@ describe("resolveDialogue", () => {
   });
 });
 
+// ── Map Dynamic Views ─────────────────────────────────────────────────────
+
+describe("map dynamic views (tween camera)", () => {
+  const md = `
+# video
+width:640 height:480 fps:30 layout:series
+
+## Overview
+layout:parallel
+- script "This is the city."
+- map view:overview mapType:satellite duration:4 camera:{zoom:tween(6, 12, easeInOut)}
+
+## Cinematic
+layout:parallel
+- script "Flying over."
+- map view:cinematic duration:8 cinematic:{mode:flyAlong, tilt:tween(0,45)} waypoints:[37.77,-122.41,"SF","photo1.jpg"; 34.05,-118.25,"LA","photo2.jpg"]
+
+## Streetview
+layout:parallel
+- script "On the ground."
+- map view:streetview duration:6 streetView:{location:{lat:37.77,lng:-122.41}, pov:{heading:tween(200,320)}, zoom:tween(0,1)}
+`;
+
+  it("parses view/camera/cinematic/streetView into descriptive nodes", () => {
+    const parsed = parseMarkdownDescriptive(md);
+    const scenes = parsed.children as any[];
+    const overview = scenes[0].children.find((c: any) => c.type === "map");
+    expect(overview.view).toBe("overview");
+    expect(overview.camera?.zoom).toEqual({ __tween: [6, 12, "easeInOut"] });
+
+    const cinematic = scenes[1].children.find((c: any) => c.type === "map");
+    expect(cinematic.view).toBe("cinematic");
+    expect(cinematic.cinematic?.mode).toBe("flyAlong");
+    expect(cinematic.cinematic?.tilt).toEqual({ __tween: [0, 45] });
+    expect(cinematic.waypoints[0].media).toBe("photo1.jpg");
+    expect(cinematic.waypoints[1].media).toBe("photo2.jpg");
+
+    const street = scenes[2].children.find((c: any) => c.type === "map");
+    expect(street.view).toBe("streetview");
+    expect(street.streetView?.pov?.heading).toEqual({ __tween: [200, 320] });
+    expect(street.streetView?.zoom).toEqual({ __tween: [0, 1] });
+  });
+
+  it("compiles view fields into the stream tree", () => {
+    const compiled = compileDescriptiveRoot(parseMarkdownDescriptive(md));
+    const maps = (compiled.children as any[]).flatMap((c: any) =>
+      (c.children ?? []).filter((ch: any) => ch.type === "map"),
+    );
+    expect(maps).toHaveLength(3);
+    expect(maps[0].view).toBe("overview");
+    expect(maps[0].camera?.zoom).toEqual({ __tween: [6, 12, "easeInOut"] });
+    expect(maps[1].view).toBe("cinematic");
+    expect(maps[1].cinematic?.tilt).toEqual({ __tween: [0, 45] });
+    expect(maps[2].view).toBe("streetview");
+    expect(maps[2].streetView?.pov?.heading).toEqual({ __tween: [200, 320] });
+  });
+});
+
 // ── Helper ────────────────────────────────────────────────────────────────
 
 function findComponents(node: any): any[] {

package/tests/render.test.ts

@@ -385,6 +385,7 @@ describe("Full Feature Combination", () => {
       "effects.json",
       "subtitle.json",
       "map.json",
+      "map-dynamic.json",
       "audio.json",
       "subvideo.json",
       "full.json",

package/tests/schema.test.ts

@@ -6,7 +6,7 @@
  * field that the player server sets after bundling frontmatter imports.
  */
 import { describe, it, expect } from "vitest";
-import { root, component } from "../src/schema/index";
+import { root, component, mapStream } from "../src/schema/index";
 
 describe("root.imports — component registry passthrough", () => {
   it("preserves a string bundle URL through root.parse()", () => {
@@ -69,3 +69,60 @@ describe("component node", () => {
     ).toThrow();
   });
 });
+
+describe("map stream — dynamic camera views", () => {
+  const base = { type: "map", waypoints: [{ lat: 37.77, lng: -122.41 }], start: 0, end: 5 };
+
+  it("defaults view to route", () => {
+    expect(mapStream.parse(base).view).toBe("route");
+  });
+
+  it("accepts all views", () => {
+    for (const view of ["overview", "route", "cinematic", "streetview"] as const) {
+      expect(mapStream.parse({ ...base, view }).view).toBe(view);
+    }
+  });
+
+  it("carries camera tween specs and static numbers", () => {
+    const m = mapStream.parse({
+      ...base,
+      view: "overview",
+      camera: { zoom: { __tween: [6, 12, "easeInOut"] }, tilt: 45 },
+    });
+    expect(m.camera?.zoom).toEqual({ __tween: [6, 12, "easeInOut"] });
+    expect(m.camera?.tilt).toBe(45);
+  });
+
+  it("carries cinematic config with tweenable tilt/range", () => {
+    const m = mapStream.parse({
+      ...base,
+      view: "cinematic",
+      cinematic: { mode: "flyTo", tilt: { __tween: [0, 45] }, range: 2000, fallback: "2d" },
+    });
+    expect(m.cinematic?.mode).toBe("flyTo");
+    expect(m.cinematic?.tilt).toEqual({ __tween: [0, 45] });
+    expect(m.cinematic?.range).toBe(2000);
+    expect(m.cinematic?.fallback).toBe("2d");
+  });
+
+  it("carries streetView config with pov tweens, zoom and walk route", () => {
+    const m = mapStream.parse({
+      ...base,
+      view: "streetview",
+      streetView: {
+        location: { lat: 37.77, lng: -122.41 },
+        pov: { heading: { __tween: [200, 320] }, pitch: -10 },
+        zoom: 0.5,
+        route: [{ lat: 37.77, lng: -122.41 }, { lat: 37.78, lng: -122.42 }],
+      },
+    });
+    expect(m.streetView?.pov?.heading).toEqual({ __tween: [200, 320] });
+    expect(m.streetView?.pov?.pitch).toBe(-10);
+    expect(m.streetView?.zoom).toBe(0.5);
+    expect(m.streetView?.route?.length).toBe(2);
+  });
+
+  it("rejects an invalid view", () => {
+    expect(() => mapStream.parse({ ...base, view: "drone" })).toThrow();
+  });
+});

package/tests/validate-assets.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import {
+  classifyAssetPath,
+  collectTreeAssets,
+  validateAssetsRelative,
+} from "../src/render/validate-assets.mjs";
+
+const BASE = "/proj/md";
+
+describe("classifyAssetPath", () => {
+  it("allows remote URIs", () => {
+    expect(classifyAssetPath("https://x/y.png")).toBe("remote");
+    expect(classifyAssetPath("http://x/y.mp4")).toBe("remote");
+    expect(classifyAssetPath("data:image/png;base64,AAA")).toBe("remote");
+    expect(classifyAssetPath("blob:https://x/id")).toBe("remote");
+    expect(classifyAssetPath("file:///tmp/a.png")).toBe("remote");
+  });
+
+  it("flags root-absolute and absolute paths", () => {
+    expect(classifyAssetPath("/Users/me/a.png")).toBe("root-absolute");
+    expect(classifyAssetPath("/a/b.png")).toBe("root-absolute");
+  });
+
+  it("flags .. escapes", () => {
+    expect(classifyAssetPath("../x.png")).toBe("escapes");
+    expect(classifyAssetPath("../../x.png")).toBe("escapes");
+  });
+
+  it("accepts source-folder-relative paths", () => {
+    expect(classifyAssetPath("assets/x.png")).toBe("relative");
+    expect(classifyAssetPath(".markcut/generated/tts/a.mp3")).toBe("relative");
+    expect(classifyAssetPath("a/b/c.png")).toBe("relative");
+  });
+
+  it("treats non-.vtt subtitle src as inline text (not a path)", () => {
+    expect(classifyAssetPath("Hello world", { subtitle: true })).toBe("text");
+    expect(classifyAssetPath("00:00:00.000 --> 00:00:02.000\nhi", { subtitle: true })).toBe("text");
+    expect(classifyAssetPath("subs.vtt", { subtitle: true })).toBe("relative");
+    expect(classifyAssetPath("subs.vtt?lang=en", { subtitle: true })).toBe("relative");
+  });
+});
+
+describe("validateAssetsRelative", () => {
+  const tree = {
+    type: "root",
+    subtitle: { src: ".markcut/sub/subtitles.vtt" },
+    children: [
+      { id: "bg", type: "image", src: "assets/bg.png" },
+      { id: "clip", type: "video", src: "/Users/me/abs.mp4" },
+      { id: "walk", type: "audio", src: "a/../../escape.mp3" },
+      { id: "m", type: "map", waypoints: [{ media: "../outside.png" }] },
+      { id: "sub", type: "subtitle", src: "caption text" },
+      { id: "inc", type: "include", src: "../other.md" },
+    ],
+  };
+
+  it("returns no errors when all assets are baseDir-relative", () => {
+    const ok = {
+      type: "root",
+      subtitle: { src: ".markcut/sub/subtitles.vtt" },
+      children: [
+        { id: "bg", type: "image", src: "assets/bg.png" },
+        { id: "clip", type: "video", src: ".markcut/generated/media/photo_1920x1080.jpg" },
+        { id: "a", type: "audio", src: "assets/tts/1.mp3" },
+        { id: "m", type: "map", waypoints: [{ media: "assets/thumb.png" }] },
+      ],
+    };
+    expect(validateAssetsRelative(ok, BASE)).toEqual([]);
+  });
+
+  it("flags absolute, root-absolute and escaping assets with node id + field", () => {
+    const errors = validateAssetsRelative(tree, BASE);
+    // clip (root-absolute), walk (nested ..), m.waypoints[0].media (..),
+    // inc.src (..) — subtitle text + bg are fine.
+    expect(errors).toHaveLength(4);
+    const joined = errors.join("\n");
+    expect(joined).toContain('node "clip" (type: video) — field src = "/Users/me/abs.mp4"');
+    expect(joined).toContain('node "walk" (type: audio)');
+    expect(joined).toContain("waypoints[0].media");
+    expect(joined).toContain('node "inc" (type: include)');
+    expect(joined).toContain("relative to the source folder");
+  });
+
+  it("skips include.src for descriptive trees (skipIncludeSrc)", () => {
+    const errors = validateAssetsRelative(tree, BASE, { skipIncludeSrc: true });
+    expect(errors).toHaveLength(3);
+    expect(errors.join("\n")).not.toContain('node "inc"');
+  });
+
+  it("collects root.subtitle.src as an asset reference", () => {
+    const refs = collectTreeAssets(tree);
+    expect(refs.some((r) => r.field === "subtitle.src" && r.value === ".markcut/sub/subtitles.vtt")).toBe(true);
+  });
+
+  it("flags a bad root subtitle path", () => {
+    const bad = { type: "root", subtitle: { src: "../shared/subs.vtt" }, children: [] };
+    const errors = validateAssetsRelative(bad, BASE);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("subtitle.src");
+  });
+
+  it("is robust to empty trees", () => {
+    expect(validateAssetsRelative({ type: "root" }, BASE)).toEqual([]);
+    expect(validateAssetsRelative(null, BASE)).toEqual([]);
+  });
+});

package/B]

@@ -1,2 +0,0 @@
-[main 2b839d7] mermaid.animateEdges=true|[A-
- 5 files changed, 162 insertions(+), 18 deletions(-)

package/tests/tmp/vision-1785081637127-video/videos/metadata.json

@@ -1,9 +0,0 @@
-{
-  "test-clip": {
-    "width": 320,
-    "height": 240,
-    "created": "0000-00-00T00:00:00Z",
-    "location": null,
-    "duration": 3
-  }
-}

package/tests/tmp/vision-1785081637127-video/videos/test-clip.vtt

@@ -1,5 +0,0 @@
-WEBVTT
-
-00:00.000 --> 00:01.100
-Thank you.
-