@lalalic/markcut 3.0.0 → 3.1.0

package/src/player/pipeline.mjs

@@ -343,6 +343,7 @@ function compileLeaf(node2, ctx, parentKind) {
       const stream = {
         ...base,
         type: "map",
+        view: node2.view ?? "route",
         waypoints: node2.waypoints,
         routeColor: node2.routeColor ?? "#4285F4",
         routeWeight: node2.routeWeight ?? 4,
@@ -353,6 +354,9 @@ function compileLeaf(node2, ctx, parentKind) {
         region: node2.region,
         travelMode: node2.travelMode ?? "DRIVING",
         routeMarker: node2.routeMarker ?? "\u{1F697}",
+        camera: node2.camera,
+        cinematic: node2.cinematic,
+        streetView: node2.streetView,
         googleMapsApiKey: ctx.googleMapsApiKey
       };
       return { stream, duration: end ?? 0 };
@@ -9953,18 +9957,41 @@ function parseWaypoints(raw) {
     const lat = Number(bits[0] ?? 0);
     const lng = Number(bits[1] ?? 0);
     const labelRaw = bits[2];
-    const label = labelRaw ? unquote(labelRaw) : void 0;
-    return { lat, lng, label };
+    const labelRawUq = labelRaw ? unquote(labelRaw) : void 0;
+    const label = labelRawUq ? labelRawUq : void 0;
+    const mediaRaw = bits[3];
+    const media = mediaRaw ? unquote(mediaRaw) : void 0;
+    return { lat, lng, label, media };
   });
 }
+function rewriteTweenExprs(s) {
+  return s.replace(
+    /tween\(\s*([^,()]+?)\s*,\s*([^,()]+?)\s*(?:,\s*([^()]+?))?\s*\)/g,
+    (_match, fromRaw, toRaw, easingRaw) => {
+      const scalar = (v) => {
+        const t = v.trim();
+        if (/^[+-]?(\d+(\.\d+)?|\.\d+)$/.test(t)) return t;
+        if (/^"(?:[^"\\]|\\.)*"$/.test(t)) return t;
+        if (t === "true" || t === "false" || t === "null") return t;
+        return JSON.stringify(t);
+      };
+      const items = [scalar(fromRaw), scalar(toRaw)];
+      if (easingRaw !== void 0 && easingRaw.trim()) {
+        items.push(scalar(easingRaw));
+      }
+      return `{"__tween":[${items.join(",")}]}`;
+    }
+  );
+}
 function parseProps(raw) {
   const s = raw.trim();
   if (!s.startsWith("{") && !s.startsWith("[")) return {};
   if (!s.endsWith("}") && !s.endsWith("]")) return {};
+  const withTweens = rewriteTweenExprs(s);
   try {
-    return JSON.parse(s);
+    return JSON.parse(withTweens);
   } catch {
-    let normalized = s.replace(
+    let normalized = withTweens.replace(
       /([{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:(?=\s*["{[]?)/g,
       '$1"$2":'
     );
@@ -9980,7 +10007,7 @@ function parseProps(raw) {
       return JSON.parse(normalized);
     } catch {
       try {
-        const result = (0, eval)("(" + s + ")");
+        const result = (0, eval)("(" + withTweens + ")");
         return typeof result === "object" && result !== null ? result : {};
       } catch {
         return {};
@@ -10233,6 +10260,10 @@ function preserveVariantAttrs(node2, attrs) {
     "mapType",
     "data",
     "prompt",
+    "view",
+    "camera",
+    "cinematic",
+    "streetView",
     "name",
     "title",
     "transition",
@@ -10455,6 +10486,7 @@ function parseNodeLine(content3, lineNum) {
         waypoints: attrs.waypoints ?? [],
         duration: attrs.duration,
         start: attrs.start,
+        view: attrs.view,
         routeMarker: attrs.routeMarker,
         travelMode: attrs.travelMode,
         routeColor: attrs.routeColor,
@@ -10462,6 +10494,9 @@ function parseNodeLine(content3, lineNum) {
         zoom: attrs.zoom,
         center: attrs.center,
         mapType: attrs.mapType,
+        camera: attrs.camera,
+        cinematic: attrs.cinematic,
+        streetView: attrs.streetView,
         language: attrs.language ?? attrs.lang,
         region: attrs.region,
         instruction: attrs.instruction,
@@ -10764,7 +10799,22 @@ function probeDuration(src, baseDir) {
 }
 function resolveSrc(src, baseDir) {
   if (/^(https?:|file:|\/)/.test(src)) return src;
-  return resolvePath(baseDir ?? process.cwd(), src);
+  return resolvePath(baseDir, src);
+}
+function relativizeAssetsUnder(node2, baseDir) {
+  if (!node2 || typeof node2 !== "object") return node2;
+  if (Array.isArray(node2)) return node2.map((v) => relativizeAssetsUnder(v, baseDir));
+  const out = {};
+  for (const [k, v] of Object.entries(node2)) {
+    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;
 }
 var COMMON_RESOLUTIONS = [
   { width: 1920, height: 1080 },
@@ -10809,7 +10859,7 @@ function resolveMediaSrc(src, targetWidth, targetHeight, baseDir) {
   console.warn(`  \u26A0 No matching media file for "${src}" at ${targetWidth}x${targetHeight}`);
   return exactAbs;
 }
-async function resolveMediaSrcs(root, options = {}) {
+async function resolveMediaSrcs(root, options) {
   const clone = JSON.parse(JSON.stringify(root));
   const baseDir = options.baseDir;
   const targetWidth = clone.width ?? 1080;
@@ -10830,7 +10880,7 @@ async function resolveMediaSrcs(root, options = {}) {
   });
   return clone;
 }
-async function resolveMediaDurations(root, options = {}) {
+async function resolveMediaDurations(root, options) {
   const clone = JSON.parse(JSON.stringify(root));
   const baseDir = options.baseDir;
   walkDown(clone, (node2) => {
@@ -11242,9 +11292,9 @@ function applyStoryboardOverrides(root, options) {
   }
   return clone;
 }
-async function resolveIncludes(root, options = {}) {
+async function resolveIncludes(root, options) {
   const clone = JSON.parse(JSON.stringify(root));
-  const baseDir = options.baseDir ?? process.cwd();
+  const baseDir = options.baseDir;
   const outputDir = options.includeOutputDir ?? join(baseDir, ".markcut", "generated", "includes");
   mkdirSync2(outputDir, { recursive: true });
   function extractImportEntriesFromRaw(raw) {
@@ -11323,7 +11373,7 @@ async function resolveIncludes(root, options = {}) {
   }
   return clone;
 }
-async function resolveAll2(root, options = {}) {
+async function resolveAll2(root, options) {
   let result = root;
   if (result.seed == null && options.seed == null && options.sourcePath) {
     const autoSeed = parseInt(computeCacheKey(result).slice(0, 8), 16);
@@ -11391,6 +11441,7 @@ async function resolveAll2(root, options = {}) {
       mergedOutputDir: options.subtitleOutputDir
     });
   }
+  result = relativizeAssetsUnder(result, options.baseDir);
   return result;
 }
 
@@ -11408,7 +11459,7 @@ function isDescriptiveRoot(data) {
   )) return true;
   return false;
 }
-async function resolveAndCompile(data, options = {}) {
+async function resolveAndCompile(data, options) {
   const resolved = await resolveAll2(data, {
     sourcePath: options.sourcePath,
     baseDir: options.baseDir,
@@ -11427,7 +11478,7 @@ async function resolveAndCompile(data, options = {}) {
   });
   return compiled;
 }
-async function resolveAndCompileMarkdown(markdown, options = {}) {
+async function resolveAndCompileMarkdown(markdown, options) {
   const descriptive = parseMarkdownDescriptive(markdown);
   return resolveAndCompile(descriptive, options);
 }

package/src/player/pipeline.ts

@@ -21,8 +21,9 @@ import type { DescriptiveRoot } from "../descriptive/compiler";
 import type { Root } from "../schema/index";
 
 export interface ResolveAndCompileOptions {
-  /** Base directory for resolving relative media src paths */
-  baseDir?: string;
+  /** Base directory (the source file's folder) for resolving/emitting asset paths.
+   *  Always set by the CLI/server; no fallback. */
+  baseDir: string;
   /** Output directory for generated TTS audio / STT VTT files */
   scriptOutputDir?: string;
   /** Output directory for generated TTI/TTV media files */
@@ -88,7 +89,7 @@ export function isDescriptiveRoot(data: any): boolean {
  */
 export async function resolveAndCompile(
   data: DescriptiveRoot,
-  options: ResolveAndCompileOptions = {},
+  options: ResolveAndCompileOptions,
 ): Promise<Root> {
   // 1. Async resolve: durations, TTS, STT, includes
   const resolved = await resolveAll(data, {
@@ -121,7 +122,7 @@ export async function resolveAndCompile(
  */
 export async function resolveAndCompileMarkdown(
   markdown: string,
-  options: ResolveAndCompileOptions = {},
+  options: ResolveAndCompileOptions,
 ): Promise<Root> {
   const descriptive = parseMarkdownDescriptive(markdown);
   return resolveAndCompile(descriptive, options);

package/src/player/server.mjs

@@ -326,59 +326,39 @@ function makePathsRelative(obj) {
 }
 
 /**
- * Convert relative (to MARKCUT_BASE) paths in the compiled root to server-relative URLs
- * for the browser. This is the inverse of makePathsRelative — it prepends "/" to paths
- * so the browser can fetch them from the server.
+ * Convert asset paths in the compiled root to server-relative URLs for the
+ * browser. The compiled JSON now carries md-folder-relative paths (e.g.
+ * ".markcut/generated/tts/x.mp3" or "assets/photo.jpg") because the resolve
+ * step emits them relative to the source .md folder — the server document
+ * root. This prepends "/" so the browser can fetch them (resolveAsset() then
+ * maps the URL back onto the md folder).
  *
- * Handles:
- *   - compiled.imports (component bundle URL)
- *   - compiled.subtitle.src (VTT file)
- *   - Any node.src (media/tts/images) that is a relative path under MARKCUT_BASE
+ * Also handles legacy absolute paths under MARKCUT_BASE (older cached trees).
  */
 function resolveAssetPaths(root) {
   const out = JSON.parse(JSON.stringify(root));
 
+  function toServerUrl(p) {
+    if (typeof p !== "string") return p;
+    if (/^(https?:|data:|blob:)/.test(p)) return p;
+    if (p.startsWith("/")) return p;                       // already a server URL
+    // Legacy: absolute path under the .markcut base (older cached trees)
+    if (p.startsWith(MARKCUT_BASE)) return p.slice(MARKCUT_BASE.length);
+    // md-folder-relative path (new scheme): ".markcut/...", "assets/..."
+    const rel = p.startsWith("./") ? p.slice(2) : p;
+    return "/" + rel;
+  }
+
   function walkNode(node) {
     if (!node || typeof node !== "object") return;
     if (Array.isArray(node)) { node.forEach(walkNode); return; }
 
-    // Convert src fields that are relative paths
-    if (typeof node.src === "string" && !node.src.startsWith("http://") && !node.src.startsWith("https://") && !node.src.startsWith("data:")) {
-      // Already a relative path under MARKCUT_BASE (shouldn't be absolute)
-      if (!node.src.startsWith("/") && !node.src.startsWith(".")) {
-        // Plain relative path — prefix with / (server serves from project root)
-        node.src = "/" + node.src;
-      } else if (node.src.startsWith("./")) {
-        // Dot-prefixed relative path — strip ./ and prefix with /
-        node.src = "/" + node.src.slice(2);
-      }
-      // Convert absolute paths under MARKCUT_BASE
-      if (typeof node.src === "string" && node.src.startsWith(MARKCUT_BASE)) {
-        node.src = "/" + node.src.replace(MARKCUT_BASE + "/", "");
-      }
-    }
-
-    // Convert subtitle src
+    if (typeof node.src === "string") node.src = toServerUrl(node.src);
     if (node.subtitle && typeof node.subtitle.src === "string") {
-      if (node.subtitle.src.startsWith(MARKCUT_BASE)) {
-        node.subtitle.src = "/" + node.subtitle.src.replace(MARKCUT_BASE + "/", "");
-      } else if (!node.subtitle.src.startsWith("/") && !node.subtitle.src.startsWith("http")) {
-        node.subtitle.src = "/" + node.subtitle.src;
-      }
-    }
-
-    // Convert imports (component bundle URL)
-    if (typeof node.imports === "string") {
-      if (node.imports.startsWith(MARKCUT_BASE)) {
-        node.imports = "/" + node.imports.replace(MARKCUT_BASE + "/", "");
-      } else if (!node.imports.startsWith("/") && !node.imports.startsWith("http")) {
-        node.imports = "/" + node.imports;
-      }
-    }
-
-    if (Array.isArray(node.children)) {
-      node.children.forEach(walkNode);
+      node.subtitle.src = toServerUrl(node.subtitle.src);
     }
+    if (typeof node.imports === "string") node.imports = toServerUrl(node.imports);
+    if (Array.isArray(node.children)) node.children.forEach(walkNode);
   }
 
   walkNode(out);

package/src/render/cli.mjs

@@ -80,6 +80,12 @@ Commands:
   vision <folder>                      Full pipeline: extract → normalize → percept → segments
     --label                            Add interactive labeling step before AI pipeline
     --instruct "text"                   Background context about people/places (injected into prompts)
+
+  spots --waypoints "lat,lng;..."      Discover POIs along a route (Directions + Places API)
+    --travelMode DRIVING               DRIVING | WALKING | BICYCLING (default DRIVING)
+    --limit 8                          Max spots after ranking
+    --photos                           Attach a static-map thumbnail per spot
+    --markdown                         Print waypoints:[...] markdown to stderr
     --prompts-file <path>              Path to prompts markdown file (default: vision_prompts.md)
     --vtt-sample-interval <n>          Sample one video frame every N seconds (default: 5)
     --skip-stt                         Skip speech-to-text for videos
@@ -90,6 +96,7 @@ Commands:
 }
 
 
+/**
 /**
  * Render a stream tree to an MP4 video with compact progress output.
  *
@@ -100,7 +107,7 @@ Commands:
  * Use --verbose to see every frame line (original behavior).
  */
 
-function renderOne(streamTree, outputPath, verbose) {
+function renderOne(streamTree, outputPath, verbose, publicDir) {
   const tmpProps = join(ROOT, ".tmp", "render-stream.json");
   mkdirSync(dirname(tmpProps), { recursive: true });
   writeFileSync(tmpProps, JSON.stringify({ root: streamTree }));
@@ -116,7 +123,10 @@ console.log(`\n▶ Rendering → ${outputPath}`);
     if (args.dev) {
       spawnOpts.env = { ...process.env, NODE_ENV: "development" };
     }
-    const proc = spawn("npx", ["remotion", "render", "Root", outputPath, "--props", tmpProps, "--config", "remotion.config.ts"], spawnOpts);
+    // Serve local media (TTS, subtitles, images) from the .markcut base dir.
+    const renderArgs = ["remotion", "render", "Root", outputPath, "--props", tmpProps, "--config", "remotion.config.ts"];
+    if (publicDir) renderArgs.push("--public-dir", publicDir);
+    const proc = spawn("npx", renderArgs, spawnOpts);
 
     let lastLoggedFrame = 0;
     let totalFrames = 0;
@@ -213,6 +223,11 @@ edit=${DEFAULT_EDIT_CLI}`);
     process.exit(0);
   }
 
+  if (args.command === "spots") {
+    await import("../spots/cli.mjs");  // self-executing top-level script
+    process.exit(0);
+  }
+
   if (args.command === "preview") {
     // --storyboard implies --edit: show story structure fast (prompts as
     // placeholder components) and let user chat to reshape before generation.
@@ -276,6 +291,7 @@ edit=${DEFAULT_EDIT_CLI}`);
   if (args.command === "render") {
     let streamTree;
     let rawInput = "";
+    let renderPublicDir;  // .markcut base dir → Remotion publicDir for local media
 
     if (args.file) {
       const filePath = resolve(args.file);
@@ -334,6 +350,10 @@ edit=${DEFAULT_EDIT_CLI}`);
           includeOutputDir: generatedDir(filePath, "includes"),
           subtitleOutputDir: variantDir(filePath),
         });
+        // Serve the source .md folder as Remotion's public dir (the "default
+        // root"): every asset in the JSON is md-folder-relative, so paths like
+        // .markcut/generated/... and assets/... resolve via staticFile.
+        renderPublicDir = fileDir;
       } else {
         const parsed = JSON.parse(raw);
         const root = parsed.root ?? parsed;
@@ -348,6 +368,7 @@ edit=${DEFAULT_EDIT_CLI}`);
             includeOutputDir: generatedDir(filePath, "includes"),
             subtitleOutputDir: variantDir(filePath),
           });
+          renderPublicDir = fileDir;
         } else {
           streamTree = root;
         }
@@ -378,8 +399,24 @@ edit=${DEFAULT_EDIT_CLI}`);
       }
     }
 
+    // Guard: every local asset must be relative to the source folder (the
+    // render publicDir). Absolute paths or ".." escapes would 404 in Remotion
+    // (staticFile serves --public-dir), so fail fast with actionable errors.
+    if (renderPublicDir) {
+      const { validateAssetsRelative } = await import("./validate-assets.mjs");
+      const assetErrors = validateAssetsRelative(streamTree, renderPublicDir);
+      if (assetErrors.length > 0) {
+        for (const e of assetErrors) emitError(e);
+        emitError(
+          `Aborting render: ${assetErrors.length} asset(s) not relative to baseDir ` +
+          `(${renderPublicDir}). Fix the source or re-run resolve, then retry.`
+        );
+        process.exit(1);
+      }
+    }
+
     const output = args.output ? resolve(args.output) : join(ROOT, "out", "video.mp4");
-    await renderOne(streamTree, output, args.verbose);
+    await renderOne(streamTree, output, args.verbose, renderPublicDir);
 
     console.log("\n✅ Render complete.");
     process.exit(0);
@@ -487,6 +524,20 @@ function hasScript(root) {
       }
       walkMedia(descriptive.children);
 
+      // ── Check: all assets relative to baseDir ───────────────────────────
+      // Every local asset must be a path relative to the source file's folder
+      // (the render publicDir). Absolute paths, "/..." and ".." escapes would
+      // 404 in render / break media in preview.
+      {
+        const { validateAssetsRelative } = await import("./validate-assets.mjs");
+        const baseDir = dirname(filePath);
+        // Descriptive trees: include.src may point outside baseDir legitimately
+        // (it is compiled against its own baseDir, then relativized).
+        for (const e of validateAssetsRelative(descriptive, baseDir, { skipIncludeSrc: true })) {
+          errors.push(e);
+        }
+      }
+
       // ── Results ─────────────────────────────────────────────────────────
       for (const w of warnings) emitWarn(w);
       if (errors.length > 0) {

package/src/render/validate-assets.mjs

@@ -0,0 +1,140 @@
+/**
+ * Asset-relative validation for stream trees.
+ *
+ * Render contract (2026-08-10): every local asset in the compiled tree is a
+ * path RELATIVE to the source folder — the source .md file's folder, the
+ * "default root". Remotion serves that folder via `--public-dir` (render) and
+ * the player serves it as the document root (preview). Absolute filesystem
+ * paths, paths starting with "/", or `..` escapes all break staticFile()
+ * resolution → 404 in render / broken media in preview.
+ *
+ *   validateAssetsRelative(tree, baseDir) → string[]  (empty = all OK)
+ *
+ * Used by:
+ *   - `markcut verify`  — walks the parsed descriptive tree (skips include.src,
+ *     which legitimately resolves against its own baseDir)
+ *   - `markcut render`  — guards the compiled tree right before rendering
+ */
+import { isAbsolute, relative, resolve } from "node:path";
+
+const REMOTE_RE = /^(https?:|data:|blob:|file:)/i;
+/** Subtitle `src` is only a file when it points at a .vtt — otherwise it is inline caption text. */
+const VTT_RE = /\.vtt(?:$|[?#])/i;
+const INLINE_VTT_RE = /-->/;
+
+/**
+ * Classify a single asset reference:
+ *   "remote"        — http(s)/data/blob/file URI, loaded as-is (OK)
+ *   "root-absolute" — starts with "/", rooted at the serve root, NOT source-folder-relative (ERROR)
+ *   "absolute"      — absolute filesystem path (ERROR)
+ *   "escapes"       — relative but starts with ".." (ERROR)
+ *   "relative"      — looks safe; callers should re-check against baseDir for nested ".."
+ *   "text"          — not a path at all (inline subtitle text / inline VTT body)
+ *   "empty"         — falsy
+ */
+export function classifyAssetPath(src, { subtitle = false } = {}) {
+  if (!src) return "empty";
+  if (subtitle && (INLINE_VTT_RE.test(src) || !VTT_RE.test(src))) return "text";
+  if (REMOTE_RE.test(src)) return "remote";
+  if (src.startsWith("/")) return "root-absolute";
+  if (isAbsolute(src)) return "absolute";
+  if (src.startsWith("..")) return "escapes";
+  return "relative";
+}
+
+function collectNodeAssets(node, path, out, skipIncludeSrc) {
+  if (!node || typeof node !== "object") return;
+
+  if (node.type === "include") {
+    // include.src may legitimately point outside baseDir in *descriptive* trees
+    // (it is compiled against its own baseDir, then relativized to the outer
+    // baseDir). Callers that validate descriptive trees pass skipIncludeSrc.
+    if (!skipIncludeSrc && typeof node.src === "string" && node.src) {
+      out.push({ node, field: "src", value: node.src, path, subtitle: false });
+    }
+    // NOTE: include.imports is a module bundle URL (dynamic import), not a
+    // staticFile asset — intentionally not validated.
+  } else {
+    const isSubtitle = node.type === "subtitle";
+    if (typeof node.src === "string" && node.src) {
+      out.push({ node, field: "src", value: node.src, path, subtitle: isSubtitle });
+    }
+    if (Array.isArray(node.waypoints)) {
+      node.waypoints.forEach((wp, i) => {
+        if (wp && typeof wp.media === "string" && wp.media) {
+          out.push({ node, field: `waypoints[${i}].media`, value: wp.media, path, subtitle: false });
+        }
+      });
+    }
+  }
+
+  if (Array.isArray(node.children)) {
+    node.children.forEach((c, i) => collectNodeAssets(c, `${path}.children[${i}]`, out, skipIncludeSrc));
+  }
+}
+
+/**
+ * Collect every asset reference in a tree.
+ *
+ * @param {object} tree - root node (may carry root.subtitle) or plain node
+ * @param {{skipIncludeSrc?: boolean}} [opts]
+ * @returns {Array<{node: object, field: string, value: string, path: string, subtitle: boolean}>}
+ */
+export function collectTreeAssets(tree, { skipIncludeSrc = false } = {}) {
+  const out = [];
+  if (tree && typeof tree.subtitle === "object" && tree.subtitle &&
+      typeof tree.subtitle.src === "string" && tree.subtitle.src) {
+    out.push({ node: tree, field: "subtitle.src", value: tree.subtitle.src, path: "root", subtitle: true });
+  }
+  if (tree && Array.isArray(tree.children)) {
+    tree.children.forEach((c, i) => collectNodeAssets(c, `root.children[${i}]`, out, skipIncludeSrc));
+  }
+  return out;
+}
+
+function formatError(ref, problem, baseDir) {
+  const where = ref.node?.id
+    ? `node "${ref.node.id}"`
+    : ref.node?.name
+      ? `node "${ref.node.name}"`
+      : ref.path;
+  const type = ref.node?.type ? ` (type: ${ref.node.type})` : "";
+  return [
+    `Asset not relative to baseDir: ${where}${type} — field ${ref.field} = "${ref.value}"`,
+    `  ${problem}. Local assets must be relative to the source folder: ${baseDir}`,
+    `  (e.g. assets/x.png or .markcut/generated/...) — absolute paths and ".." escapes 404 in render`,
+    `  because Remotion serves media from --public-dir = the source folder.`,
+    `  Fix: re-run resolve/render so the path is emitted source-folder-relative, or move the file under the source folder.`,
+  ].join("\n");
+}
+
+/**
+ * Walk a tree and return actionable errors for every asset that is not
+ * relative to `baseDir`. Empty array = all assets are baseDir-relative.
+ *
+ * @param {object} tree - root node of the (descriptive or compiled) tree
+ * @param {string} baseDir - source folder (md file's folder) assets must stay inside
+ * @param {{skipIncludeSrc?: boolean}} [opts] - pass skipIncludeSrc:true for descriptive trees
+ * @returns {string[]}
+ */
+export function validateAssetsRelative(tree, baseDir, opts = {}) {
+  const errors = [];
+  for (const ref of collectTreeAssets(tree, opts)) {
+    const kind = classifyAssetPath(ref.value, { subtitle: ref.subtitle });
+    let problem = null;
+    if (kind === "root-absolute") {
+      problem = `It starts with "/" — that is rooted at the serve root, not the source folder`;
+    } else if (kind === "absolute") {
+      problem = "It is an absolute filesystem path";
+    } else if (kind === "escapes") {
+      problem = 'It escapes the source folder via ".."';
+    } else if (kind === "relative") {
+      // Nested ".." like "a/../../x" isn't caught by the prefix check.
+      if (relative(baseDir, resolve(baseDir, ref.value)).startsWith("..")) {
+        problem = 'It escapes the source folder via ".."';
+      }
+    }
+    if (problem) errors.push(formatError(ref, problem, baseDir));
+  }
+  return errors;
+}

package/src/schema/index.ts

@@ -212,7 +212,7 @@ export const scene = base.extend({
 export type Scene = z.infer<typeof scene>;
 
 // ---------------------------------------------------------------------------
-// Map — animated route visualization
+// Map — animated route visualization with dynamic camera views
 // ---------------------------------------------------------------------------
 export const mapWaypoint = z.object({
   lat: z.number(),
@@ -221,8 +221,60 @@ export const mapWaypoint = z.object({
   media: z.string().optional().describe("image/video src for waypoint marker"),
 });
 
+/**
+ * A tween expression: `tween(from, to, easing?)` → `{__tween:[from,to,easing?]}`,
+ * parsed by the descriptive DSL (see parseProps in dsl.ts).
+ */
+export const tweenSpec = z.object({
+  __tween: z.array(z.union([z.number(), z.string()])),
+});
+export type TweenSpec = z.infer<typeof tweenSpec>;
+
+/** A static number OR an animated tween spec. */
+export const tweenableNumber = z.union([z.number(), tweenSpec]);
+export type TweenableNumber = z.infer<typeof tweenableNumber>;
+
+/** Generic camera tween shared by overview/route/cinematic-lite. */
+export const mapCamera = z.object({
+  zoom: tweenableNumber.optional(),
+  center: z.object({ lat: tweenableNumber, lng: tweenableNumber }).optional(),
+  heading: tweenableNumber.optional(),
+  tilt: tweenableNumber.optional(),
+});
+export type MapCamera = z.infer<typeof mapCamera>;
+
+/** Cinematic camera behavior (chase/tilt/flyTo/orbit, 3D flyover). All fields
+ * optional — the renderer applies defaults (mode flyAlong, tilt 45, etc.). */
+export const mapCinematic = z.object({
+  mode: z.enum(["flyAlong", "flyTo", "orbit"]).optional().describe("camera move; default flyAlong"),
+  followRoute: z.boolean().optional().describe("center follows the animated marker; default true"),
+  headingFollow: z.boolean().optional().describe("heading = route bearing (forward is up); default true"),
+  tilt: tweenableNumber.optional().describe("0 = top-down reveal, 45 = chase; tween(0,45) = tilt reveal; default 45"),
+  range: tweenableNumber.optional().describe("3D camera distance (m); tween(8000,300) = fly-to"),
+  altitude: z.number().optional().describe("3D center altitude (m)"),
+  roll: tweenableNumber.optional().describe("3D bank (deg); default 0"),
+  fallback: z.enum(["2d", "none"]).optional().describe("'2d' renders safe 2D chase; 'none' opts into experimental Map3D; default '2d'"),
+});
+export type MapCinematic = z.infer<typeof mapCinematic>;
+
+/** Immersive Street View config with POV/position animation. */
+export const mapStreetView = z.object({
+  pano: z.string().optional().describe("explicit panorama id (deterministic)"),
+  location: z.object({ lat: z.number(), lng: z.number() }).optional().describe("else nearest-pano search"),
+  route: z.array(z.object({ lat: z.number(), lng: z.number() })).optional().describe("walk/drive path (nearest pano per stop)"),
+  radius: z.number().optional().describe("nearest-pano search radius (m); default 50"),
+  source: z.enum(["default", "outdoor", "indoor"]).optional().describe("default 'default'"),
+  pov: z.object({
+    heading: tweenableNumber.optional().describe("tween(200,320) = pan"),
+    pitch: tweenableNumber.optional().describe("tween(0,-10) = tilt sweep"),
+  }).optional(),
+  zoom: tweenableNumber.optional().describe("street view field-of-view zoom; tween(0,1) = dolly-zoom feel"),
+});
+export type MapStreetView = z.infer<typeof mapStreetView>;
+
 export const mapStream = base.extend({
   type: z.literal("map").default("map"),
+  view: z.enum(["overview", "route", "cinematic", "streetview"]).default("route").describe("camera experience: static/dolly overview, animated route, cinematic flyover, immersive street view"),
   waypoints: z.array(mapWaypoint).default(() => []),
   routeColor: z.string().default("#4285F4"),
   routeWeight: z.number().default(4),
@@ -233,6 +285,9 @@ export const mapStream = base.extend({
   region: z.string().optional().describe("Google Maps region code, e.g. CN"),
   travelMode: z.enum(["DRIVING", "WALKING", "BICYCLING", "TRANSIT"]).default("DRIVING").describe("Directions API travel mode"),
   routeMarker: z.string().default("🚗").describe("emoji/character for the animated traveling marker"),
+  camera: mapCamera.optional().describe("generic camera tween (dolly/pan/tilt)"),
+  cinematic: mapCinematic.optional().describe("cinematic camera behavior"),
+  streetView: mapStreetView.optional().describe("immersive street view config"),
   googleMapsApiKey: z.string().optional().describe("injected by compiler from GOOGLE_MAPS_API_KEY env var"),
 });
 export type MapStream = z.infer<typeof mapStream>;