@lalalic/markcut 2.9.0 → 3.1.0

package/src/player/pipeline.mjs

@@ -33,7 +33,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/utils/index.ts
 function uid() {
-  return Math.random().toString(36).slice(2, 10);
+  const raw = Math.random().toString(36).slice(2, 10);
+  const first = raw[0];
+  if (/^[0-9]/.test(first)) {
+    const letter = String.fromCharCode(97 + Math.floor(Math.random() * 26));
+    return letter + raw;
+  }
+  return raw;
 }
 function walkDown(node2, visit, parent = null, depth = 0) {
   const keep = visit(node2, parent, depth);
@@ -207,7 +213,8 @@ function wrapWithEffects(node2, result, parentKind) {
   const absStart = innerStream.start ?? 0;
   const absEnd = innerStream.end ?? result.duration;
   const duration = absEnd - absStart;
-  const resetStream = {
+  const isBgNoEnd = innerStream.isBackground && innerStream.end == null;
+  const resetStream = isBgNoEnd ? { ...innerStream } : {
     ...innerStream,
     start: 0,
     end: duration,
@@ -224,28 +231,33 @@ function wrapWithEffects(node2, result, parentKind) {
       id: uid(),
       type: "effect",
       animation: spec.animation,
+      animationDurationSeconds: spec.duration,
       durationInSeconds: spec.duration,
       animationTimingFunction: spec.animationTimingFunction,
       animationIterationCount: spec.animationIterationCount ?? 1,
       customKeyframes: spec.customKeyframes,
       children: [currentStream],
-      start: effStart,
-      end: effEnd,
-      visible: true,
+      // For background inner nodes: propagate start/end as-is so parent
+      // back-propagation fills the correct scene duration. The effect's
+      // durationInSeconds (animation spec) controls animation timing.
+      start: isOutermost && isBgNoEnd ? innerStream.start : effStart,
+      end: isOutermost && isBgNoEnd ? void 0 : effEnd,
+      visible: innerStream.visible ?? true,
       ...pickOn(node2)
     };
   }
   return { stream: currentStream, duration: result.duration };
 }
 function compileLeaf(node2, ctx, parentKind) {
-  const id = node2.id ?? uid();
+  const id = node2.id;
+  const hasExplicitId = node2.id != null;
   const hasOwnDuration = typeof node2.duration === "number" || typeof node2.endAt === "number";
   const isBgNoOwnTiming = node2.isBackground && !hasOwnDuration;
   const start = isBgNoOwnTiming ? typeof node2.start === "number" ? node2.start : void 0 : parentKind === "parallel" ? Math.max(0, node2.start ?? 0) : 0;
   const duration = isBgNoOwnTiming ? void 0 : deriveLeafDuration(node2, ctx);
   const end = duration != null ? start + duration : void 0;
   const base = {
-    id,
+    ...id ? { id } : {},
     style: node2.style,
     visible: node2.visible ?? true,
     isBackground: node2.isBackground,
@@ -305,8 +317,7 @@ function compileLeaf(node2, ctx, parentKind) {
       const bindings = {};
       for (const key of Object.keys(node2)) {
         if (!KNOWN_COMPONENT_KEYS.has(key)) {
-          const val = node2[key];
-          if (typeof val === "string") bindings[key] = val;
+          bindings[key] = node2[key];
         }
       }
       const stream = {
@@ -332,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,
@@ -342,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 };
@@ -407,13 +422,23 @@ function compileScene(node2, ctx, parentKind) {
   ];
   const sceneContentDuration = sceneKind === "parallel" ? aggregateDuration(compiledChildren, "parallel") : aggregateDuration(compiledChildren, sceneKind, resolved.time);
   const localDuration = Math.max(node2.duration ?? 0, sceneContentDuration);
-  for (const c of compiledChildren) {
-    if (c.stream.isBackground && c.stream.end == null) {
-      c.stream.end = localDuration;
-      c.stream.durationInSeconds = localDuration;
-      if (c.stream.start == null) c.stream.start = 0;
+  function backpropagate(stream2, dur) {
+    if (stream2.end == null) {
+      stream2.end = dur;
+      if (stream2.durationInSeconds == null) {
+        stream2.durationInSeconds = dur;
+      }
+      if (stream2.start == null) stream2.start = 0;
+    }
+    if (stream2.type === "effect" && Array.isArray(stream2.children)) {
+      for (const child of stream2.children) {
+        backpropagate(child, dur);
+      }
     }
   }
+  for (const c of compiledChildren) {
+    backpropagate(c.stream, localDuration);
+  }
   const start = parentKind === "parallel" ? Math.max(0, node2.start ?? 0) : 0;
   const end = start + localDuration;
   const stream = {
@@ -507,12 +532,22 @@ function compileContainer(node2, ctx, parentKind) {
   const resolved = node2.type === "transitionSeries" ? resolveTransition(node2.transition, node2.transitionTime) : { name: "fade", time: 0.5 };
   const children = compileChildren(node2.children, ctx, node2.type);
   const duration = aggregateDuration(children, node2.type, resolved.time);
-  for (const c of children) {
-    if (c.stream.isBackground && c.stream.end == null) {
-      c.stream.end = duration;
-      c.stream.durationInSeconds = duration;
-      if (c.stream.start == null) c.stream.start = 0;
+  function backpropagate(stream2, dur) {
+    if (stream2.end == null) {
+      stream2.end = dur;
+      if (stream2.durationInSeconds == null) {
+        stream2.durationInSeconds = dur;
+      }
+      if (stream2.start == null) stream2.start = 0;
     }
+    if (stream2.type === "effect" && Array.isArray(stream2.children)) {
+      for (const child of stream2.children) {
+        backpropagate(child, dur);
+      }
+    }
+  }
+  for (const c of children) {
+    backpropagate(c.stream, duration);
   }
   const stream = {
     id,
@@ -9922,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":'
     );
@@ -9949,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 {};
@@ -10122,6 +10180,7 @@ var TYPE_TOKENS = {
   video: "video",
   audio: "audio",
   component: "component",
+  event: "event",
   rhythm: "rhythm",
   include: "include",
   map: "map",
@@ -10201,6 +10260,10 @@ function preserveVariantAttrs(node2, attrs) {
     "mapType",
     "data",
     "prompt",
+    "view",
+    "camera",
+    "cinematic",
+    "streetView",
     "name",
     "title",
     "transition",
@@ -10341,6 +10404,21 @@ function parseNodeLine(content3, lineNum) {
       preserveVariantAttrs(node2, attrs);
       return node2;
     }
+    case "event": {
+      const node2 = {
+        type: "component",
+        id: attrs.id,
+        jsx: "",
+        duration: attrs.duration,
+        start: attrs.start,
+        instruction: attrs.instruction,
+        style: attrs.style,
+        effects: attrs.effects,
+        on: attrs.on
+      };
+      preserveVariantAttrs(node2, attrs);
+      return node2;
+    }
     case "rhythm": {
       const src = firstPositional ?? attrs.src;
       if (!src) throw new DslError("rhythm requires src", ctx);
@@ -10408,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,
@@ -10415,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,
@@ -10717,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 },
@@ -10762,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;
@@ -10783,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) => {
@@ -11195,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) {
@@ -11276,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);
@@ -11344,6 +11441,7 @@ async function resolveAll2(root, options = {}) {
       mergedOutputDir: options.subtitleOutputDir
     });
   }
+  result = relativizeAssetsUnder(result, options.baseDir);
   return result;
 }
 
@@ -11361,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,
@@ -11380,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) {