@lalalic/markcut 2.9.0 → 3.1.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

@@ -133,7 +133,7 @@ export type Image = z.infer<typeof image>;
 export const component = base.extend({
   type: z.literal("component").default("component"),
   jsx: z.string().describe("usage JSX expression compiled at runtime; tag names resolved from imports"),
-  data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe("extra variables (e.g. from ~~~md source code fences) available in JSX scope"),
+  data: z.record(z.string(), z.unknown()).optional().describe("extra variables (e.g. from ~~~md source code fences) available in JSX scope"),
 });
 export type Component = z.infer<typeof component>;
 
@@ -143,6 +143,7 @@ export type Component = z.infer<typeof component>;
 export const effect = base.extend({
   type: z.literal("effect").default("effect"),
   animation: z.string().optional().describe("builtin keyframe name or 'custom'"),
+  animationDurationSeconds: z.number().optional().describe("animation duration (separate from wrapper durationInSeconds which getDurationInSeconds may overwrite)"),
   animationTimingFunction: z
     .enum(["linear", "ease", "ease-in", "ease-out", "ease-in-out"])
     .optional(),
@@ -211,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(),
@@ -220,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),
@@ -232,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>;

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/Component.tsx

@@ -72,7 +72,30 @@ export function ComponentLeaf({ stream }: { stream: Component }) {
     [stream.data, components, eventState],
   );
 
-  if (!stream.jsx) return null;
+  if (!stream.jsx) {
+    // Event-only stub: no JSX to render, but may fire events on `on`.
+    // Still needs EventAwareComponent for useFrameEvents to register
+    // and fire at the right frame.
+    const start = stream.start ?? 0;
+    const end = stream.end ?? start + (stream.duration ?? 1);
+    const durFrames = Math.max(1, Math.floor(fps * (end - start)));
+    return (
+      <Sequence
+        durationInFrames={durFrames}
+        from={Math.floor(fps * start)}
+        layout="none"
+      >
+        <EventAwareComponent
+          jsx=""
+          components={components}
+          data={bindings}
+          action={{ start, end }}
+          durFrames={durFrames}
+          on={stream.on}
+        />
+      </Sequence>
+    );
+  }
 
   const start = stream.start ?? 0;
   const end = stream.end ?? start + (stream.duration ?? 1);
@@ -118,6 +141,9 @@ function EventAwareComponent({
   // Fire events at the right frame for this node's timeline
   useFrameEvents(on, durFrames);
 
+  // If no JSX, this is an event-only stub — nothing to render
+  if (!jsx) return null;
+
   return (
     <TweenedJsxParser
       jsx={jsx}

package/src/types/Effect.tsx

@@ -34,17 +34,24 @@ export function EffectWrapper({
     const durationInFrames = end - start;
     if (durationInFrames <= 0) return [] as Record<string, string>[];
 
+    // Use animationDurationSeconds for animation timing when available
+    // (set by wrapWithEffects for background nodes where end is set to parent
+    //  duration but the animation spec duration is preserved separately).
+    const animDurationSec = stream.animationDurationSeconds ?? stream.durationInSeconds ?? (durationInFrames / fps);
+    const animDurationFrames = Math.ceil(animDurationSec * fps);
+
     const animation = stream.animation;
     const timingFn = stream.animationTimingFunction;
     const iterCount = stream.animationIterationCount ?? 1;
     const style = (cssJS(stream.style) ?? {}) as Record<string, string>;
 
-    // Handle iteration count: loop the animation within the span
+    // Handle iteration count: loop the animation within the span.
+    // The animation period is animDurationFrames (not the full span duration).
     let currentFrame = frame;
-    if (iterCount > 0 && durationInFrames > 0) {
-      const iteration = Math.floor((frame - start) / durationInFrames);
+    if (iterCount > 0 && animDurationFrames > 0) {
+      const iteration = Math.floor((frame - start) / animDurationFrames);
       if (iteration < iterCount) {
-        currentFrame = start + ((frame - start) % durationInFrames);
+        currentFrame = start + ((frame - start) % animDurationFrames);
       }
     }
 
@@ -56,7 +63,7 @@ export function EffectWrapper({
         if (config) {
           const animStyle = interpolateKeyframes(config, actionFrame, {
             fps,
-            durationInSeconds: durationInFrames / fps,
+            durationInSeconds: animDurationSec,
             timingFunction: timingFn,
           });
           if (animStyle) Object.assign(style, animStyle);
@@ -65,7 +72,7 @@ export function EffectWrapper({
     }
 
     return Object.keys(style).length > 0 ? [style] : [];
-  }, [frame, fps, startSec, endSec, stream.animation, stream.animationTimingFunction, stream.animationIterationCount, stream.customKeyframes, stream.style]);
+  }, [frame, fps, startSec, endSec, stream.animation, stream.animationTimingFunction, stream.animationIterationCount, stream.customKeyframes, stream.style, stream.animationDurationSeconds, stream.durationInSeconds]);
 
   if (styles.length === 0) return <>{children}</>;
 

package/src/types/Folder.tsx

@@ -62,7 +62,7 @@ export function FolderLeaf({ stream }: { stream: FolderStream }) {
   // Background children are rendered outside the series (parallel overlays),
   // so TransitionSeries doesn't reject the <Loop> wrapper.
   const bgChildren = visibleChildren.filter((c) => c.isBackground);
-  const seriesChildren = isSeries ? visibleChildren.filter((c) => !c.isBackground) : visibleChildren;
+  const seriesChildren = visibleChildren.filter((c) => !c.isBackground);
 
   // When all non-background series children are audio, skip transitions to
   // avoid audio overlap (both audio tracks play simultaneously during a fade).