@lalalic/markcut 3.0.0 → 3.1.1

package/tests/fixtures/streetview-walk.json

@@ -0,0 +1,36 @@
+{
+  "root": {
+    "type": "root",
+    "width": 640,
+    "height": 480,
+    "fps": 30,
+    "layout": "series",
+    "children": [
+      {
+        "type": "map",
+        "id": "sv-walk",
+        "view": "streetview",
+        "start": 0,
+        "end": 6,
+        "duration": 6,
+        "streetView": {
+          "route": [
+            {
+              "lat": 37.7785,
+              "lng": -122.4185
+            },
+            {
+              "lat": 37.7777,
+              "lng": -122.4178
+            }
+          ],
+          "radius": 50,
+          "pov": {
+            "heading": 15,
+            "pitch": -5
+          }
+        }
+      }
+    ]
+  }
+}

package/tests/md-descriptive.test.ts

@@ -897,6 +897,139 @@ 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] });
+  });
+});
+
+// ── Map Multi-Leg Travel Modes ─────────────────────────────────────────────
+
+describe("map multi-leg travel modes (per-waypoint)", () => {
+  const md = `
+# video
+width:640 height:480 fps:30 layout:series
+
+## Trip
+layout:parallel
+- 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"]
+`;
+
+  it("parses a per-waypoint travel mode as the 5th field", () => {
+    const parsed = parseMarkdownDescriptive(md);
+    const map = (parsed.children as any[])[0].children.find((c: any) => c.type === "map");
+    expect(map.waypoints.map((w: any) => w.mode)).toEqual([
+      "FLIGHT", "BOAT", "WALKING", "DRIVING", undefined,
+    ]);
+    expect(map.waypoints[0].media).toBeUndefined();
+    expect(map.waypoints[0].label).toBe("SFO");
+  });
+
+  it("compiles waypoint modes into the stream tree", () => {
+    const compiled = compileDescriptiveRoot(parseMarkdownDescriptive(md));
+    const map = (compiled.children as any[])[0].children.find((c: any) => c.type === "map");
+    expect(map.waypoints.map((w: any) => w.mode)).toEqual([
+      "FLIGHT", "BOAT", "WALKING", "DRIVING", undefined,
+    ]);
+  });
+});
+
+// ── Map Overlay Children (at:"Waypoint") ──────────────────────────────────
+
+describe("map overlay children (at:\"Waypoint\")", () => {
+  const md = `
+# video
+width:640 height:480 fps:30 layout:series
+
+## Tour
+layout:parallel
+- map view:route duration:12 travelMode:DRIVING
+  waypoints:[37.81,-122.48,"Golden Gate"; 37.77,-122.42,"Civic Center"]
+  - image src:gg.jpg at:"Golden Gate" start:3 duration:3 effects:[zoomIn]
+  - image src:civic.jpg at:"Civic Center" start:7 duration:3 effects:[zoomIn]
+`;
+
+  it("parses nested children with at onto the map node", () => {
+    const parsed = parseMarkdownDescriptive(md);
+    const map = (parsed.children as any[])[0].children.find((c: any) => c.type === "map");
+    expect(map.children).toHaveLength(2);
+    expect(map.children[0].type).toBe("image");
+    expect(map.children[0].at).toBe("Golden Gate");
+    expect(map.children[1].at).toBe("Civic Center");
+  });
+
+  it("compiles children into the map stream and propagates at through effects", () => {
+    const compiled = compileDescriptiveRoot(parseMarkdownDescriptive(md));
+    const map = (compiled.children as any[])[0].children.find((c: any) => c.type === "map");
+    expect(map.children).toHaveLength(2);
+    // effects:[zoomIn] wraps each child in an effect node that carries `at`
+    expect(map.children[0].type).toBe("effect");
+    expect(map.children[0].at).toBe("Golden Gate");
+    expect(map.children[0].start).toBe(3);
+    expect(map.children[1].at).toBe("Civic Center");
+  });
+
+  it("keeps the map duration from its own end, not max(children)", () => {
+    const compiled = compileDescriptiveRoot(parseMarkdownDescriptive(md));
+    const map = (compiled.children as any[])[0].children.find((c: any) => c.type === "map");
+    expect(map.durationInSeconds).toBe(12);
+    expect(map.end).toBe(12);
+  });
+});
+
 // ── Helper ────────────────────────────────────────────────────────────────
 
 function findComponents(node: any): any[] {

package/tests/render.test.ts

@@ -21,6 +21,7 @@ import {
   FIXTURES_DIR,
 } from "./utils";
 import { existsSync, rmSync, mkdirSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { resolve } from "node:path";
 
 // Increase timeout for integration tests (rendering + STT can take a while)
@@ -258,6 +259,97 @@ describe("Map Rendering", () => {
     // Check file size as proxy for visual content.
     expect(getFrameFileSize(frame)).toBeGreaterThan(1000);
   });
+
+  it("renders anchored overlay children at waypoints (dwell vs drive)", async () => {
+    const output = renderFixture(fixturePath("map-overlay.json"), {
+      outputName: "map-overlay.mp4",
+      timeout: RENDER_TIMEOUT,
+    });
+
+    const info = getVideoInfo(output);
+    expect(info.width).toBe(640);
+
+    // The map has a solid-magenta photo anchored at "Golden Gate" (0–4s,
+    // zoomIn), then the pin drives to SFO. The photo must be visible during
+    // the dwell and gone during the drive — guards regressions where anchored
+    // overlays silently never render (getProjection() null / lazy effect path).
+    const dwell = outPath("frames/map-overlay-dwell.png");
+    const drive = outPath("frames/map-overlay-drive.png");
+    extractFrame(output, 2.5, dwell);
+    extractFrame(output, 6, drive);
+
+    const magentaFraction = (f: string): number => {
+      const p = execSync(
+        `ffmpeg -loglevel error -i "${f}" -vf scale=160:120 -f rawvideo -pix_fmt rgb24 pipe:1`,
+      );
+      let count = 0;
+      for (let i = 0; i < p.length; i += 3) {
+        if (p[i]! > 200 && p[i + 1]! < 80 && p[i + 2]! > 200) count++;
+      }
+      return count / (p.length / 3);
+    };
+
+    expect(magentaFraction(dwell)).toBeGreaterThan(0.02); // photo visible during dwell
+    expect(magentaFraction(drive)).toBeLessThan(0.001); // gone during drive
+  });
+
+  it("renders street view panoramas non-dark", async () => {
+    const output = renderFixture(fixturePath("map-dynamic.json"), {
+      outputName: "map-dynamic-streetview.mp4",
+      timeout: RENDER_TIMEOUT,
+    });
+
+    // map-dynamic.json is a series: dolly 0–3s, cinematic 3–11s, then the
+    // static streetview-pan scene plays ~11–17s. Its panorama must not be
+    // black — guards regressions where static Street View captures dark frames
+    // (pano_changed race + too-short fallback).
+    const frame = outPath("frames/map-dynamic-streetview.png");
+    extractFrame(output, 13, frame);
+
+    const darkFraction = (f: string): number => {
+      const p = execSync(
+        `ffmpeg -loglevel error -i "${f}" -vf scale=120:90 -f rawvideo -pix_fmt rgb24 pipe:1`,
+      );
+      let dark = 0;
+      for (let i = 0; i < p.length; i += 3) {
+        const v = (p[i]! + p[i + 1]! + p[i + 2]!) / 3;
+        if (v < 20) dark++;
+      }
+      return dark / (p.length / 3);
+    };
+
+    expect(darkFraction(frame)).toBeLessThan(0.5);
+  });
+
+  it("renders street view walk (route) non-dark at both waypoints", async () => {
+    const output = renderFixture(fixturePath("streetview-walk.json"), {
+      outputName: "streetview-walk.mp4",
+      timeout: RENDER_TIMEOUT,
+    });
+
+    // The snap-walk holds at route[0] (101 Grove St) for the first half and
+    // route[1] (95 Hayes St) for the second. Both have imagery; neither frame
+    // should be black. Guards regressions where the walk's per-frame pano
+    // requests get rate-limited (429) and render dark frames.
+    const darkFraction = (f: string): number => {
+      const p = execSync(
+        `ffmpeg -loglevel error -i "${f}" -vf scale=120:90 -f rawvideo -pix_fmt rgb24 pipe:1`,
+      );
+      let dark = 0;
+      for (let i = 0; i < p.length; i += 3) {
+        const v = (p[i]! + p[i + 1]! + p[i + 2]!) / 3;
+        if (v < 20) dark++;
+      }
+      return dark / (p.length / 3);
+    };
+
+    const wp0 = outPath("frames/streetview-walk-wp0.png");
+    const wp1 = outPath("frames/streetview-walk-wp1.png");
+    extractFrame(output, 2, wp0);
+    extractFrame(output, 4.5, wp1);
+    expect(darkFraction(wp0)).toBeLessThan(0.5);
+    expect(darkFraction(wp1)).toBeLessThan(0.5);
+  });
 });
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -385,6 +477,7 @@ describe("Full Feature Combination", () => {
       "effects.json",
       "subtitle.json",
       "map.json",
+      "map-dynamic.json",
       "audio.json",
       "subvideo.json",
       "full.json",

package/tests/route-legs.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from "vitest";
+import {
+  haversineKm,
+  greatCirclePath,
+  makeSyntheticLeg,
+  modeEmoji,
+  routePositionAtLegs,
+  isSyntheticMode,
+  type RouteLeg,
+} from "../src/utils/route-legs";
+
+const SF = { lat: 37.7749, lng: -122.4194 };
+const LA = { lat: 34.0522, lng: -118.2437 };
+const PIER = { lat: 34.0094, lng: -118.4969 };
+
+describe("haversineKm", () => {
+  it("is ~0 for identical points", () => {
+    expect(haversineKm(SF, SF)).toBeCloseTo(0, 6);
+  });
+
+  it("is ~560 km for SF→LA (great-circle)", () => {
+    expect(haversineKm(SF, LA)).toBeGreaterThan(500);
+    expect(haversineKm(SF, LA)).toBeLessThan(620);
+  });
+});
+
+describe("greatCirclePath", () => {
+  it("includes both endpoints and is monotonic in length", () => {
+    const path = greatCirclePath(SF, LA, 32);
+    expect(path.length).toBe(33);
+    expect(path[0]).toEqual(SF);
+    const last = path[path.length - 1]!;
+    expect(last.lat).toBeCloseTo(LA.lat, 4);
+    expect(last.lng).toBeCloseTo(LA.lng, 4);
+  });
+
+  it("handles identical endpoints without NaN", () => {
+    const path = greatCirclePath(SF, SF, 8);
+    expect(path.every((p) => Number.isFinite(p.lat) && Number.isFinite(p.lng))).toBe(true);
+    expect(path[0]).toEqual(SF);
+  });
+});
+
+describe("makeSyntheticLeg", () => {
+  it("builds a FLIGHT leg with a cruise-speed duration and single arc step", () => {
+    const leg = makeSyntheticLeg(SF, LA, "FLIGHT");
+    expect(leg.mode).toBe("FLIGHT");
+    expect(leg.durationSec).toBeGreaterThan(0);
+    // SF→LA ~559 km @ 850 km/h ≈ 0.66 h ≈ 2370 s
+    expect(leg.durationSec).toBeGreaterThan(2000);
+    expect(leg.durationSec).toBeLessThan(2700);
+    expect(leg.steps).toHaveLength(1);
+    expect(leg.steps[0]!.path.length).toBeGreaterThan(10);
+  });
+
+  it("builds a BOAT leg with a slower speed (longer duration for same distance)", () => {
+    const boat = makeSyntheticLeg(SF, LA, "BOAT");
+    const flight = makeSyntheticLeg(SF, LA, "FLIGHT");
+    expect(boat.mode).toBe("BOAT");
+    expect(boat.durationSec).toBeGreaterThan(flight.durationSec);
+  });
+});
+
+describe("isSyntheticMode / modeEmoji", () => {
+  it("flags FLIGHT and BOAT as synthetic", () => {
+    expect(isSyntheticMode("FLIGHT")).toBe(true);
+    expect(isSyntheticMode("BOAT")).toBe(true);
+    expect(isSyntheticMode("flight")).toBe(true);
+    expect(isSyntheticMode("DRIVING")).toBe(false);
+    expect(isSyntheticMode("WALKING")).toBe(false);
+    expect(isSyntheticMode(undefined)).toBe(false);
+  });
+
+  it("maps modes to emoji", () => {
+    expect(modeEmoji("FLIGHT")).toBe("✈️");
+    expect(modeEmoji("BOAT")).toBe("🚢");
+    expect(modeEmoji("WALKING")).toBe("🚶");
+    expect(modeEmoji("BICYCLING")).toBe("🚲");
+    expect(modeEmoji("TRANSIT")).toBe("🚌");
+    expect(modeEmoji("DRIVING")).toBe("🚗");
+    expect(modeEmoji(undefined)).toBe("📍");
+  });
+});
+
+describe("routePositionAtLegs", () => {
+  const makeLeg = (mode: string, durationSec: number, path: { lat: number; lng: number }[]): RouteLeg => ({
+    mode,
+    from: path[0]!,
+    to: path[path.length - 1]!,
+    durationSec,
+    steps: [{ path, durationSec }],
+  });
+
+  const straight = (a: { lat: number; lng: number }, b: { lat: number; lng: number }, n = 20) => {
+    const out: { lat: number; lng: number }[] = [];
+    for (let i = 0; i <= n; i++) {
+      const t = i / n;
+      out.push({ lat: a.lat + (b.lat - a.lat) * t, lng: a.lng + (b.lng - a.lng) * t });
+    }
+    return out;
+  };
+
+  const legs: RouteLeg[] = [
+    makeLeg("FLIGHT", 10, straight(SF, LA)),
+    makeLeg("DRIVING", 30, straight(LA, PIER)),
+  ];
+
+  it("returns null for no legs", () => {
+    expect(routePositionAtLegs([], 40, 0)).toBeNull();
+  });
+
+  it("starts at the first waypoint and ends at the last", () => {
+    const start = routePositionAtLegs(legs, 40, 0)!;
+    expect(start.lat).toBeCloseTo(SF.lat, 5);
+    expect(start.lng).toBeCloseTo(SF.lng, 5);
+    expect(start.mode).toBe("FLIGHT");
+
+    const end = routePositionAtLegs(legs, 40, 40)!;
+    expect(end.lat).toBeCloseTo(PIER.lat, 5);
+    expect(end.lng).toBeCloseTo(PIER.lng, 5);
+    expect(end.mode).toBe("DRIVING");
+  });
+
+  it("splits time proportionally to leg duration and reports the current leg mode", () => {
+    // leg durations 10 + 30 = 40 total; actionDuration 40s
+    // → flight leg occupies t∈[0,10], driving leg t∈[10,40]
+    const atFlightEnd = routePositionAtLegs(legs, 40, 9.99)!;
+    expect(atFlightEnd.mode).toBe("FLIGHT");
+
+    const atDrivingStart = routePositionAtLegs(legs, 40, 10.01)!;
+    expect(atDrivingStart.mode).toBe("DRIVING");
+    expect(atDrivingStart.lat).toBeCloseTo(LA.lat, 4);
+  });
+
+  it("mid-leg position tracks the leg's path (proportional timing)", () => {
+    // leg durations [10,30]; actionDuration 40. At t=20 the driving leg is
+    // (20-10)/30 = 1/3 of the way from LA → PIER (with point quantization).
+    const atThird = 1 / 3;
+    const mid = routePositionAtLegs(legs, 40, 20)!;
+    expect(mid.mode).toBe("DRIVING");
+    expect(mid.lat).toBeCloseTo(LA.lat + (PIER.lat - LA.lat) * atThird, 2);
+    expect(mid.lng).toBeCloseTo(LA.lng + (PIER.lng - LA.lng) * atThird, 2);
+  });
+
+  it("clamps past-the-end seconds to the destination", () => {
+    const end = routePositionAtLegs(legs, 40, 100)!;
+    expect(end.lat).toBeCloseTo(PIER.lat, 5);
+    expect(end.mode).toBe("DRIVING");
+  });
+
+  it("holds at a waypoint during a dwell window", () => {
+    const stops = [{ label: "LA", at: LA, mode: "FLIGHT", fromSec: 8, toSec: 12 }];
+    // Inside the dwell → pin holds at LA, not on the flight arc.
+    const during = routePositionAtLegs(legs, 40, 10, stops)!;
+    expect(during.mode).toBe("FLIGHT");
+    expect(during.lat).toBeCloseTo(LA.lat, 4);
+    expect(during.lng).toBeCloseTo(LA.lng, 4);
+
+    // At toSec the dwell is over and motion resumes (no longer holding at LA).
+    const resumed = routePositionAtLegs(legs, 40, 12, stops)!;
+    expect(resumed.mode).toBe("FLIGHT");
+    expect(resumed.lat).toBeGreaterThan(LA.lat);
+  });
+
+  it("compresses drive time around dwells (dwell removed from drive budget)", () => {
+    const stops = [{ label: "LA", at: LA, mode: "FLIGHT", fromSec: 8, toSec: 12 }];
+    // With the 4s dwell at LA, at wall-clock t=12 the pin is only ~89% along
+    // the flight arc (still north of LA) because the drive budget shrank.
+    const withStop = routePositionAtLegs(legs, 40, 12, stops)!;
+    expect(withStop.mode).toBe("FLIGHT");
+    expect(withStop.lat).toBeGreaterThan(LA.lat);
+    expect(withStop.lat).toBeLessThan(SF.lat);
+
+    // Without the stop, t=12 is already 20% into the LA→PIER driving leg.
+    const noStop = routePositionAtLegs(legs, 40, 12)!;
+    expect(noStop.mode).toBe("DRIVING");
+  });
+});

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,78 @@ 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();
+  });
+
+  it("carries per-waypoint travel modes (FLIGHT/BOAT/DRIVING...)", () => {
+    const m = mapStream.parse({
+      ...base,
+      waypoints: [
+        { lat: 37.77, lng: -122.41, mode: "FLIGHT" },
+        { lat: 34.05, lng: -118.25, mode: "BOAT" },
+        { lat: 34.01, lng: -118.5, mode: "WALKING" },
+      ],
+    });
+    expect(m.waypoints.map((w) => w.mode)).toEqual(["FLIGHT", "BOAT", "WALKING"]);
+  });
+
+  it("rejects an invalid waypoint travel mode", () => {
+    expect(() =>
+      mapStream.parse({ ...base, waypoints: [{ lat: 37.77, lng: -122.41, mode: "TELEPORT" }] }),
+    ).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
-  }
-}