@lalalic/markcut 3.0.0 → 3.1.1

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

@@ -42,6 +42,7 @@ const BaseShape = {
   endAt: z.number().min(0).optional().describe("trim seconds at source end (video/audio)"),
   durationInSeconds: z.number().optional().describe("set by engine; do not edit by hand"),
   on: eventSpec.optional().describe("event that fires at a specific frame, mutating registered component state"),
+  at: z.string().optional().describe("when child of a map: waypoint label to anchor at (renderer positions at that waypoint's screen pixel)"),
 };
 
 export const base = z.object(BaseShape);
@@ -212,17 +213,71 @@ 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(),
   lng: z.number(),
   label: z.string().optional(),
   media: z.string().optional().describe("image/video src for waypoint marker"),
+  mode: z.enum(["DRIVING", "WALKING", "BICYCLING", "TRANSIT", "FLIGHT", "BOAT"]).optional()
+    .describe("travel mode for the leg FROM this waypoint to the next; defaults to map travelMode"),
 });
 
+/**
+ * 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,7 +288,11 @@ 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"),
+  children: z.array(z.lazy((): z.ZodTypeAny => stream)).default(() => []).describe("overlay children rendered on top of the map; use at:\"Label\" to anchor at a waypoint"),
 });
 export type MapStream = z.infer<typeof mapStream>;
 

package/src/spots/cli.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * `markcut spots` — Discover points of interest (spots) along a route.
+ *
+ * Given a set of waypoints, this fetches the driving/walking route via the
+ * Directions REST API, samples points along it, and runs a Places Nearby Search
+ * at each sample to find notable POIs (landmarks, parks, museums, etc.). Results
+ * are deduplicated, ranked by prominence/rating, and emitted as both JSON and
+ * copy-pasteable `waypoints:[...]` markdown so an agent can drop them into a
+ * storyboard.
+ *
+ * The agent then picks the spots it wants to narrate and composes the video
+ * (this tool only DISCOVERS spots — it doesn't write the storyboard).
+ *
+ * Usage:
+ *   node src/spots/cli.mjs --waypoints "37.77,-122.41;34.05,-118.25"
+ *   node src/spots/cli.mjs --waypoints "..." --travelMode DRIVING --limit 8 --photos
+ *   node src/spots/cli.mjs --waypoints "..." --output spots.json
+ *
+ * Options:
+ *   --waypoints "lat,lng;lat,lng[,...]"   Semicolon-separated coordinates (required)
+ *   --travelMode DRIVING|WALKING|BICYCLING  Directions travel mode (default DRIVING)
+ *   --radius <m>        Nearby search radius around each route sample (default 1500)
+ *   --samples <n>       Number of points to sample along the route (default 6)
+ *   --type <type>       Place type filter, e.g. tourist_attraction, museum, park
+ *                       (default: tourist_attraction|point_of_interest)
+ *   --limit <n>         Max spots to return after ranking (default 8)
+ *   --photos            Fetch one photo URL per spot (waypoint.media)
+ *   --output <path>     Write JSON to file (default: print to stdout)
+ *   --api-key <key>     Google Maps API key (default: $GOOGLE_MAPS_API_KEY)
+ *   --markdown          Also print waypoints:[...] markdown to stderr
+ *   --help              Show this help
+ *
+ * Requires: GOOGLE_MAPS_API_KEY env var (Directions + Places API enabled).
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.waypoints) {
+  process.stderr.write(`Usage: markcut spots --waypoints "lat,lng;lat,lng" [options]
+
+Discovers points of interest along a route via the Directions + Places APIs,
+ranked by prominence, for an agent to narrate in a video.
+
+Options:
+  --waypoints "lat,lng;lat,lng"   Semicolon-separated coordinates (required)
+  --travelMode <mode>             DRIVING | WALKING | BICYCLING (default DRIVING)
+  --radius <m>                    Nearby search radius per sample (default 1500)
+  --samples <n>                   Route sample points (default 6)
+  --type <type>                   Place type filter (default tourist_attraction|point_of_interest)
+  --limit <n>                     Max spots (default 8)
+  --photos                        Fetch one photo URL per spot
+  --output <path>                 Write JSON to file
+  --markdown                      Print waypoints:[...] markdown to stderr
+  --api-key <key>                 Google Maps API key (default $GOOGLE_MAPS_API_KEY)
+  --help                          Show this help
+`);
+  process.exit(args.help ? 0 : 1);
+}
+
+const API_KEY = args.apiKey || process.env.GOOGLE_MAPS_API_KEY;
+if (!API_KEY) {
+  console.error("❌ GOOGLE_MAPS_API_KEY not set (or pass --api-key)");
+  process.exit(1);
+}
+
+const waypoints = parseWaypoints(args.waypoints);
+if (waypoints.length < 2) {
+  console.error("❌ Need at least 2 waypoints");
+  process.exit(1);
+}
+
+const travelMode = (args.travelMode || "DRIVING").toUpperCase();
+const radius = Number(args.radius || 1500);
+const samples = Number(args.samples || 6);
+const placeType = args.type || "tourist_attraction|point_of_interest";
+const limit = Number(args.limit || 8);
+const wantPhotos = !!args.photos;
+
+emitInfo(`Route: ${waypoints.length} waypoints, mode=${travelMode}, samples=${samples}, radius=${radius}m`);
+
+// 1. Fetch the route → decoded polyline → sampled points
+const routePts = await fetchRoutePoints(waypoints, travelMode, samples);
+if (routePts.length === 0) {
+  console.error("❌ No route found between waypoints");
+  process.exit(1);
+}
+emitInfo(`Route decoded: ${routePts.length} sample points`);
+
+// 2. Nearby search at each sample, merge + dedupe by place_id
+const seen = new Map();  // place_id → spot
+for (let i = 0; i < routePts.length; i++) {
+  const pt = routePts[i];
+  const places = await nearbySearch(pt, radius, placeType);
+  for (const p of places) {
+    if (seen.has(p.place_id)) continue;
+    seen.set(p.place_id, {
+      lat: p.geometry.location.lat,
+      lng: p.geometry.location.lng,
+      label: p.name,
+      types: p.types ?? [],
+      rating: p.rating,
+      userRatings: p.user_ratings_total,
+      vicinity: p.vicinity,
+      routeSample: i,
+    });
+  }
+}
+emitInfo(`Places found: ${seen.size} unique (before ranking)`);
+
+// 3. Rank: rating × log(ratings), boosted by earlier route position (narrative arc)
+const ranked = [...seen.values()]
+  .map((s) => ({
+    ...s,
+    score: (s.rating ?? 3) * Math.log10((s.userRatings ?? 10) + 10),
+  }))
+  .sort((a, b) => b.score - a.score)
+  .slice(0, limit);
+
+// 4. Optional photos
+if (wantPhotos) {
+  for (const s of ranked) {
+    const photo = await fetchPlacePhoto(s, routePts[0]);
+    if (photo) s.media = photo;
+  }
+}
+
+// 5. Emit
+const out = { waypoints, travelMode, radius, samples, spots: ranked };
+const json = JSON.stringify(out, null, 2);
+if (args.output) {
+  writeFileSync(resolve(args.output), json);
+  emitSuccess(`Wrote ${ranked.length} spots → ${args.output}`);
+} else {
+  process.stdout.write(json + "\n");
+}
+
+if (args.markdown) {
+  const md = "waypoints:[" + ranked
+    .map((s) => `${s.lat},${s.lng},"${s.label.replace(/"/g, "")}"${s.media ? `,"${s.media}"` : ""}`)
+    .join(";") + "]";
+  process.stderr.write(`\n📋 waypoints markdown:\n  - map ... ${md}\n\n`);
+}
+
+emitSuccess(`${ranked.length} spots ready`);
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function emitInfo(m) { console.error(`  ℹ️  ${m}`); }
+function emitSuccess(m) { console.error(`✅ ${m}`); }
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) { out[key] = next; i++; }
+      else out[key] = true;
+    }
+  }
+  return out;
+}
+
+function parseWaypoints(s) {
+  return s.split(";").map((part) => {
+    const [lat, lng] = part.split(",").map(Number);
+    return { lat, lng };
+  }).filter((p) => Number.isFinite(p.lat) && Number.isFinite(p.lng));
+}
+
+/** Fetch the route via Directions REST API, decode the polyline, sample N points. */
+async function fetchRoutePoints(wps, mode, sampleCount) {
+  const origin = wps[0];
+  const dest = wps[wps.length - 1];
+  const via = wps.slice(1, -1);
+  const url = new URL("https://maps.googleapis.com/maps/api/directions/json");
+  url.searchParams.set("origin", `${origin.lat},${origin.lng}`);
+  url.searchParams.set("destination", `${dest.lat},${dest.lng}`);
+  if (via.length) url.searchParams.set("waypoints", via.map((w) => `${w.lat},${w.lng}`).join("|"));
+  url.searchParams.set("mode", mode.toLowerCase());
+  url.searchParams.set("key", API_KEY);
+
+  const res = await fetch(url);
+  const data = await res.json();
+  if (data.status !== "OK" || !data.routes?.length) return [];
+
+  // Flatten all legs' steps' polyline points into one path
+  const path = [];
+  for (const leg of data.routes[0].legs ?? []) {
+    for (const step of leg.steps ?? []) {
+      if (step.polyline?.points) {
+        path.push(...decodePolyline(step.polyline.points));
+      }
+    }
+  }
+  if (path.length === 0) return [];
+
+  // Sample N evenly-spaced points along the path
+  if (path.length <= sampleCount) return path;
+  const out = [];
+  for (let i = 0; i < sampleCount; i++) {
+    out.push(path[Math.floor((i / (sampleCount - 1)) * (path.length - 1))]);
+  }
+  return out;
+}
+
+/** Places Nearby Search (REST) at a point. */
+async function nearbySearch(pt, searchRadius, type) {
+  const url = new URL("https://maps.googleapis.com/maps/api/place/nearbysearch/json");
+  url.searchParams.set("location", `${pt.lat},${pt.lng}`);
+  url.searchParams.set("radius", String(searchRadius));
+  url.searchParams.set("type", type);
+  url.searchParams.set("key", API_KEY);
+  const res = await fetch(url);
+  const data = await res.json();
+  return data.results ?? [];
+}
+
+/** Fetch one photo URL for a place via the Place Details + Photos API. */
+async function fetchPlacePhoto(spot) {
+  // Use Place Details to get photo references
+  const detUrl = new URL("https://maps.googleapis.com/maps/api/place/details/json");
+  detUrl.searchParams.set("place_id", spot.placeId ?? "");
+  // Nearby search doesn't return place_id in our shape; re-query by location+name
+  // Simpler: use Find Place From Text by name to get place_id, then photo.
+  // To keep this lightweight, fall back to a Static Maps thumbnail of the spot.
+  const sm = new URL("https://maps.googleapis.com/maps/api/staticmap");
+  sm.searchParams.set("center", `${spot.lat},${spot.lng}`);
+  sm.searchParams.set("zoom", "16");
+  sm.searchParams.set("size", "128x128");
+  sm.searchParams.set("maptype", "satellite");
+  sm.searchParams.set("key", API_KEY);
+  return sm.toString();
+}
+
+/**
+ * Decode an encoded polyline string into {lat, lng} points.
+ * Google's polyline encoding format (Algorithm: https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
+ */
+function decodePolyline(encoded) {
+  const coords = [];
+  let index = 0, lat = 0, lng = 0;
+  while (index < encoded.length) {
+    let b, shift = 0, result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    const dLat = (result & 1 ? ~(result >> 1) : result >> 1);
+    lat += dLat;
+    shift = 0; result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    const dLng = (result & 1 ? ~(result >> 1) : result >> 1);
+    lng += dLng;
+    coords.push({ lat: lat / 1e5, lng: lng / 1e5 });
+  }
+  return coords;
+}

package/src/types/Effect.tsx

@@ -17,9 +17,12 @@ import type { Effect as EffectStream } from "../schema/index";
 export function EffectWrapper({
   stream,
   children,
+  contained,
 }: {
   stream: EffectStream;
   children: React.ReactNode;
+  /** Fill the parent box instead of the whole canvas (map overlay children). */
+  contained?: boolean;
 }) {
   const frame = useCurrentFrame();
   const { fps, width, height } = useVideoConfig();
@@ -78,7 +81,15 @@ export function EffectWrapper({
 
   return (
     <div
-      style={Object.assign({ width, height, position: "absolute" as const, inset: 0 }, ...styles)}
+      style={Object.assign(
+        {
+          width: contained ? "100%" : width,
+          height: contained ? "100%" : height,
+          position: "absolute" as const,
+          inset: 0,
+        },
+        ...styles,
+      )}
       className="effect"
     >
       {children}