@oriro/orirocli 0.1.9 → 0.1.11

package/skills/craft/remotion-best-practices/rules/maplibre.md

@@ -1,441 +1,441 @@
----
-name: maps
-description: Make deterministic Remotion map animations with MapLibre GL JS and Turf. Use for animated routes, flyovers, map markers, labels, and camera movement.
-metadata:
-  tags: map, map animation, maplibre, turf, geojson, route animation
----
-
-Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
-
-## Core rules
-
-- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
-- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
-- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
-- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
-- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
-- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
-- Use standard MapLibre style JSON URLs and layer/source APIs.
-- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
-
-Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
-
-```ts
-const zurich: [number, number] = [8.5417, 47.3769];
-const newYork: [number, number] = [-74.006, 40.7128];
-```
-
-## Prerequisites
-
-Install MapLibre and Turf with the project's package manager.
-
-```bash
-npm i maplibre-gl @turf/turf
-```
-
-```bash
-bun i maplibre-gl @turf/turf
-```
-
-```bash
-yarn add maplibre-gl @turf/turf
-```
-
-```bash
-pnpm i maplibre-gl @turf/turf
-```
-
-Import the MapLibre CSS once in the component or an app-level stylesheet:
-
-```ts
-import "maplibre-gl/dist/maplibre-gl.css";
-```
-
-## Basic map example
-
-```tsx
-import { useEffect, useRef, useState } from "react";
-import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-
-const zurich: [number, number] = [8.5417, 47.3769];
-
-export const MyComposition = () => {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const { delayRender, continueRender } = useDelayRender();
-  const { width, height } = useVideoConfig();
-  const [loadingHandle] = useState(() => delayRender("Loading map"));
-
-  useEffect(() => {
-    if (!containerRef.current) {
-      return;
-    }
-
-    const mapInstance = new maplibregl.Map({
-      container: containerRef.current,
-      style: "https://demotiles.maplibre.org/style.json",
-      center: zurich,
-      zoom: 7,
-      interactive: false,
-      attributionControl: false,
-      fadeDuration: 0,
-      canvasContextAttributes: {
-        preserveDrawingBuffer: true,
-      },
-    });
-
-    mapInstance.on("load", () => {
-      mapInstance.jumpTo({ center: zurich, zoom: 7 });
-      mapInstance.once("idle", () => {
-        continueRender(loadingHandle);
-      });
-    });
-  }, [continueRender, loadingHandle]);
-
-  return (
-    <AbsoluteFill>
-      <div ref={containerRef} style={{ width, height, position: "absolute" }} />
-    </AbsoluteFill>
-  );
-};
-```
-
-Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
-
-## Animated flight route example
-
-This example shows the recommended pattern for route animations:
-
-- Turf creates the route and markers.
-- Turf slices the route for line reveal animation.
-- The camera has a separate route from the target route.
-- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
-- Frame 0 is prepared before `continueRender()`.
-
-```tsx
-import * as turf from "@turf/turf";
-import { useEffect, useRef, useState } from "react";
-import {
-  AbsoluteFill,
-  Easing,
-  interpolate,
-  useCurrentFrame,
-  useDelayRender,
-  useVideoConfig,
-} from "remotion";
-import maplibregl, { type GeoJSONSource, type Map } from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-
-const zurich: [number, number] = [8.5417, 47.3769];
-const newYork: [number, number] = [-74.006, 40.7128];
-
-const greatCircleLine = (from: [number, number], to: [number, number]) => {
-  const route = turf.greatCircle(from, to, { npoints: 100 });
-
-  if (route.geometry.type === "LineString") {
-    return turf.lineString(route.geometry.coordinates);
-  }
-
-  // Great-circle routes crossing the antimeridian can become MultiLineString.
-  // Keep the example valid by choosing the longest segment.
-  const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
-    return segment.length > longest.length ? segment : longest;
-  });
-
-  return turf.lineString(longestSegment);
-};
-
-const targetRoute = greatCircleLine(zurich, newYork);
-const targetRouteDistance = turf.length(targetRoute);
-
-const cameraRoute = greatCircleLine(zurich, newYork);
-const cameraRouteDistance = turf.length(cameraRoute);
-
-const cityMarkers = turf.featureCollection([
-  turf.point(zurich, { name: "Zurich" }),
-  turf.point(newYork, { name: "New York" }),
-]);
-
-const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
-
-const distanceAlong = (totalDistance: number, progress: number) => {
-  // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
-  return Math.max(0.001, totalDistance * clampProgress(progress));
-};
-
-const getPartialTargetRoute = (progress: number) => {
-  return turf.lineSliceAlong(targetRoute, 0, distanceAlong(targetRouteDistance, progress));
-};
-
-const getCameraOptions = (
-  map: Map,
-  progress: number,
-  cameraAltitudeMeters: number,
-  cameraLatitudeOffset: number,
-) => {
-  const target = turf.along(targetRoute, distanceAlong(targetRouteDistance, progress)).geometry
-    .coordinates;
-  const camera = turf.along(cameraRoute, distanceAlong(cameraRouteDistance, progress)).geometry
-    .coordinates;
-
-  return map.calculateCameraOptionsFromTo(
-    new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
-    cameraAltitudeMeters,
-    new maplibregl.LngLat(target[0], target[1]),
-  );
-};
-
-export const MyComposition = () => {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const frame = useCurrentFrame();
-  const { delayRender, continueRender } = useDelayRender();
-  const { durationInFrames, height, width } = useVideoConfig();
-  const [map, setMap] = useState<Map | null>(null);
-  const [loadingHandle] = useState(() => delayRender("Loading MapLibre map"));
-
-  useEffect(() => {
-    if (!containerRef.current) {
-      return;
-    }
-
-    const mapInstance = new maplibregl.Map({
-      container: containerRef.current,
-      style: "https://demotiles.maplibre.org/style.json",
-      center: zurich,
-      zoom: 7,
-      interactive: false,
-      attributionControl: false,
-      fadeDuration: 0,
-      canvasContextAttributes: {
-        preserveDrawingBuffer: true,
-      },
-    });
-
-    mapInstance.on("load", () => {
-      mapInstance.addSource("trace", {
-        type: "geojson",
-        data: getPartialTargetRoute(0),
-      });
-
-      mapInstance.addLayer({
-        id: "trace-line",
-        type: "line",
-        source: "trace",
-        layout: {
-          "line-cap": "round",
-          "line-join": "round",
-        },
-        paint: {
-          "line-color": "#111111",
-          "line-width": 7,
-        },
-      });
-
-      mapInstance.addSource("city-markers", {
-        type: "geojson",
-        data: cityMarkers,
-      });
-
-      mapInstance.addLayer({
-        id: "city-marker-dots",
-        type: "circle",
-        source: "city-markers",
-        paint: {
-          "circle-color": "#f03b20",
-          "circle-radius": 12,
-          "circle-stroke-color": "#ffffff",
-          "circle-stroke-width": 4,
-        },
-      });
-
-      mapInstance.addLayer({
-        id: "city-marker-labels",
-        type: "symbol",
-        source: "city-markers",
-        layout: {
-          "text-allow-overlap": true,
-          "text-anchor": "top",
-          "text-field": ["get", "name"],
-          "text-offset": [0, 0.9],
-          "text-size": 28,
-        },
-        paint: {
-          "text-color": "#111111",
-          "text-halo-color": "#ffffff",
-          "text-halo-width": 3,
-        },
-      });
-
-      mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
-      mapInstance.once("idle", () => {
-        setMap(mapInstance);
-        continueRender(loadingHandle);
-      });
-    });
-  }, [continueRender, loadingHandle]);
-
-  useEffect(() => {
-    if (!map) {
-      return;
-    }
-
-    const handle = delayRender("Rendering MapLibre frame");
-    const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
-      extrapolateLeft: "clamp",
-      extrapolateRight: "clamp",
-    });
-    const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
-      extrapolateLeft: "clamp",
-      extrapolateRight: "clamp",
-      easing: Easing.inOut(Easing.cubic),
-    });
-    const cameraAltitudeMeters = interpolate(
-      timelineProgress,
-      [0, 0.28, 0.74, 1],
-      [180000, 2200000, 2200000, 180000],
-      {
-        extrapolateLeft: "clamp",
-        extrapolateRight: "clamp",
-        easing: Easing.inOut(Easing.cubic),
-      },
-    );
-    const cameraLatitudeOffset = interpolate(
-      timelineProgress,
-      [0, 0.28, 0.74, 1],
-      [1.1, 8, 8, 1.1],
-      {
-        extrapolateLeft: "clamp",
-        extrapolateRight: "clamp",
-        easing: Easing.inOut(Easing.cubic),
-      },
-    );
-    const trace = map.getSource("trace") as GeoJSONSource | undefined;
-
-    trace?.setData(getPartialTargetRoute(travelProgress));
-    map.jumpTo(getCameraOptions(map, travelProgress, cameraAltitudeMeters, cameraLatitudeOffset));
-
-    map.once("idle", () => continueRender(handle));
-    // Force an idle event even if the camera parameters are unchanged from the previous frame.
-    map.triggerRepaint();
-  }, [continueRender, delayRender, durationInFrames, frame, map]);
-
-  return (
-    <AbsoluteFill style={{ backgroundColor: "#e8eef3" }}>
-      <div ref={containerRef} style={{ height, position: "absolute", width }} />
-    </AbsoluteFill>
-  );
-};
-```
-
-## Camera guidance
-
-Use MapLibre's camera helper for camera movement:
-
-```ts
-map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
-```
-
-A good pattern is to keep two concepts separate:
-
-- `targetRoute`: where the animated line is and where the camera looks.
-- `cameraRoute`: where the camera moves.
-
-Then use Turf to read positions from both routes for the same progress value:
-
-```ts
-const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
-const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
-
-map.jumpTo(
-  map.calculateCameraOptionsFromTo(
-    new maplibregl.LngLat(camera[0], camera[1]),
-    cameraAltitudeMeters,
-    new maplibregl.LngLat(target[0], target[1]),
-  ),
-);
-```
-
-For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
-
-## Lines
-
-Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
-
-For geodesic flight routes, use Turf:
-
-```ts
-const line = greatCircleLine(start, end);
-const distance = turf.length(line);
-const partialLine = turf.lineSliceAlong(
-  line,
-  0,
-  // Keep the route non-empty at progress 0.
-  Math.max(0.001, distance * progress),
-);
-```
-
-For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
-
-## Markers and labels
-
-Use map-native GeoJSON layers for markers and labels:
-
-```tsx
-mapInstance.addSource("markers", {
-  type: "geojson",
-  data: turf.featureCollection([turf.point([-118.2437, 34.0522], { name: "Los Angeles" })]),
-});
-
-mapInstance.addLayer({
-  id: "marker-dots",
-  type: "circle",
-  source: "markers",
-  paint: {
-    "circle-color": "#f03b20",
-    "circle-radius": 12,
-    "circle-stroke-color": "#ffffff",
-    "circle-stroke-width": 4,
-  },
-});
-
-mapInstance.addLayer({
-  id: "marker-labels",
-  type: "symbol",
-  source: "markers",
-  layout: {
-    "text-allow-overlap": true,
-    "text-anchor": "top",
-    "text-field": ["get", "name"],
-    "text-offset": [0, 0.9],
-    "text-size": 28,
-  },
-  paint: {
-    "text-color": "#111111",
-    "text-halo-color": "#ffffff",
-    "text-halo-width": 3,
-  },
-});
-```
-
-Make marker sizes and label font sizes large enough for the composition resolution.
-
-## Styles
-
-Default to the stock MapLibre demo style:
-
-```ts
-style: "https://demotiles.maplibre.org/style.json";
-```
-
-If the user requests another style, use any valid MapLibre style JSON URL.
-
-## Rendering
-
-For WebGL map renders, prefer single concurrency and ANGLE:
-
-```bash
-bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
-```
-
-Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
+---
+name: maps
+description: Make deterministic Remotion map animations with MapLibre GL JS and Turf. Use for animated routes, flyovers, map markers, labels, and camera movement.
+metadata:
+  tags: map, map animation, maplibre, turf, geojson, route animation
+---
+
+Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use standard MapLibre style JSON URLs and layer/source APIs.
+- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
+
+Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install MapLibre and Turf with the project's package manager.
+
+```bash
+npm i maplibre-gl @turf/turf
+```
+
+```bash
+bun i maplibre-gl @turf/turf
+```
+
+```bash
+yarn add maplibre-gl @turf/turf
+```
+
+```bash
+pnpm i maplibre-gl @turf/turf
+```
+
+Import the MapLibre CSS once in the component or an app-level stylesheet:
+
+```ts
+import "maplibre-gl/dist/maplibre-gl.css";
+```
+
+## Basic map example
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+export const MyComposition = () => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const { delayRender, continueRender } = useDelayRender();
+  const { width, height } = useVideoConfig();
+  const [loadingHandle] = useState(() => delayRender("Loading map"));
+
+  useEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+
+    const mapInstance = new maplibregl.Map({
+      container: containerRef.current,
+      style: "https://demotiles.maplibre.org/style.json",
+      center: zurich,
+      zoom: 7,
+      interactive: false,
+      attributionControl: false,
+      fadeDuration: 0,
+      canvasContextAttributes: {
+        preserveDrawingBuffer: true,
+      },
+    });
+
+    mapInstance.on("load", () => {
+      mapInstance.jumpTo({ center: zurich, zoom: 7 });
+      mapInstance.once("idle", () => {
+        continueRender(loadingHandle);
+      });
+    });
+  }, [continueRender, loadingHandle]);
+
+  return (
+    <AbsoluteFill>
+      <div ref={containerRef} style={{ width, height, position: "absolute" }} />
+    </AbsoluteFill>
+  );
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- The camera has a separate route from the target route.
+- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from "@turf/turf";
+import { useEffect, useRef, useState } from "react";
+import {
+  AbsoluteFill,
+  Easing,
+  interpolate,
+  useCurrentFrame,
+  useDelayRender,
+  useVideoConfig,
+} from "remotion";
+import maplibregl, { type GeoJSONSource, type Map } from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+  const route = turf.greatCircle(from, to, { npoints: 100 });
+
+  if (route.geometry.type === "LineString") {
+    return turf.lineString(route.geometry.coordinates);
+  }
+
+  // Great-circle routes crossing the antimeridian can become MultiLineString.
+  // Keep the example valid by choosing the longest segment.
+  const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+    return segment.length > longest.length ? segment : longest;
+  });
+
+  return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cameraRoute = greatCircleLine(zurich, newYork);
+const cameraRouteDistance = turf.length(cameraRoute);
+
+const cityMarkers = turf.featureCollection([
+  turf.point(zurich, { name: "Zurich" }),
+  turf.point(newYork, { name: "New York" }),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+  // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+  return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+  return turf.lineSliceAlong(targetRoute, 0, distanceAlong(targetRouteDistance, progress));
+};
+
+const getCameraOptions = (
+  map: Map,
+  progress: number,
+  cameraAltitudeMeters: number,
+  cameraLatitudeOffset: number,
+) => {
+  const target = turf.along(targetRoute, distanceAlong(targetRouteDistance, progress)).geometry
+    .coordinates;
+  const camera = turf.along(cameraRoute, distanceAlong(cameraRouteDistance, progress)).geometry
+    .coordinates;
+
+  return map.calculateCameraOptionsFromTo(
+    new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
+    cameraAltitudeMeters,
+    new maplibregl.LngLat(target[0], target[1]),
+  );
+};
+
+export const MyComposition = () => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const frame = useCurrentFrame();
+  const { delayRender, continueRender } = useDelayRender();
+  const { durationInFrames, height, width } = useVideoConfig();
+  const [map, setMap] = useState<Map | null>(null);
+  const [loadingHandle] = useState(() => delayRender("Loading MapLibre map"));
+
+  useEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+
+    const mapInstance = new maplibregl.Map({
+      container: containerRef.current,
+      style: "https://demotiles.maplibre.org/style.json",
+      center: zurich,
+      zoom: 7,
+      interactive: false,
+      attributionControl: false,
+      fadeDuration: 0,
+      canvasContextAttributes: {
+        preserveDrawingBuffer: true,
+      },
+    });
+
+    mapInstance.on("load", () => {
+      mapInstance.addSource("trace", {
+        type: "geojson",
+        data: getPartialTargetRoute(0),
+      });
+
+      mapInstance.addLayer({
+        id: "trace-line",
+        type: "line",
+        source: "trace",
+        layout: {
+          "line-cap": "round",
+          "line-join": "round",
+        },
+        paint: {
+          "line-color": "#111111",
+          "line-width": 7,
+        },
+      });
+
+      mapInstance.addSource("city-markers", {
+        type: "geojson",
+        data: cityMarkers,
+      });
+
+      mapInstance.addLayer({
+        id: "city-marker-dots",
+        type: "circle",
+        source: "city-markers",
+        paint: {
+          "circle-color": "#f03b20",
+          "circle-radius": 12,
+          "circle-stroke-color": "#ffffff",
+          "circle-stroke-width": 4,
+        },
+      });
+
+      mapInstance.addLayer({
+        id: "city-marker-labels",
+        type: "symbol",
+        source: "city-markers",
+        layout: {
+          "text-allow-overlap": true,
+          "text-anchor": "top",
+          "text-field": ["get", "name"],
+          "text-offset": [0, 0.9],
+          "text-size": 28,
+        },
+        paint: {
+          "text-color": "#111111",
+          "text-halo-color": "#ffffff",
+          "text-halo-width": 3,
+        },
+      });
+
+      mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
+      mapInstance.once("idle", () => {
+        setMap(mapInstance);
+        continueRender(loadingHandle);
+      });
+    });
+  }, [continueRender, loadingHandle]);
+
+  useEffect(() => {
+    if (!map) {
+      return;
+    }
+
+    const handle = delayRender("Rendering MapLibre frame");
+    const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+      extrapolateLeft: "clamp",
+      extrapolateRight: "clamp",
+    });
+    const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+      extrapolateLeft: "clamp",
+      extrapolateRight: "clamp",
+      easing: Easing.inOut(Easing.cubic),
+    });
+    const cameraAltitudeMeters = interpolate(
+      timelineProgress,
+      [0, 0.28, 0.74, 1],
+      [180000, 2200000, 2200000, 180000],
+      {
+        extrapolateLeft: "clamp",
+        extrapolateRight: "clamp",
+        easing: Easing.inOut(Easing.cubic),
+      },
+    );
+    const cameraLatitudeOffset = interpolate(
+      timelineProgress,
+      [0, 0.28, 0.74, 1],
+      [1.1, 8, 8, 1.1],
+      {
+        extrapolateLeft: "clamp",
+        extrapolateRight: "clamp",
+        easing: Easing.inOut(Easing.cubic),
+      },
+    );
+    const trace = map.getSource("trace") as GeoJSONSource | undefined;
+
+    trace?.setData(getPartialTargetRoute(travelProgress));
+    map.jumpTo(getCameraOptions(map, travelProgress, cameraAltitudeMeters, cameraLatitudeOffset));
+
+    map.once("idle", () => continueRender(handle));
+    // Force an idle event even if the camera parameters are unchanged from the previous frame.
+    map.triggerRepaint();
+  }, [continueRender, delayRender, durationInFrames, frame, map]);
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: "#e8eef3" }}>
+      <div ref={containerRef} style={{ height, position: "absolute", width }} />
+    </AbsoluteFill>
+  );
+};
+```
+
+## Camera guidance
+
+Use MapLibre's camera helper for camera movement:
+
+```ts
+map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
+```
+
+A good pattern is to keep two concepts separate:
+
+- `targetRoute`: where the animated line is and where the camera looks.
+- `cameraRoute`: where the camera moves.
+
+Then use Turf to read positions from both routes for the same progress value:
+
+```ts
+const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
+const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
+
+map.jumpTo(
+  map.calculateCameraOptionsFromTo(
+    new maplibregl.LngLat(camera[0], camera[1]),
+    cameraAltitudeMeters,
+    new maplibregl.LngLat(target[0], target[1]),
+  ),
+);
+```
+
+For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+  line,
+  0,
+  // Keep the route non-empty at progress 0.
+  Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource("markers", {
+  type: "geojson",
+  data: turf.featureCollection([turf.point([-118.2437, 34.0522], { name: "Los Angeles" })]),
+});
+
+mapInstance.addLayer({
+  id: "marker-dots",
+  type: "circle",
+  source: "markers",
+  paint: {
+    "circle-color": "#f03b20",
+    "circle-radius": 12,
+    "circle-stroke-color": "#ffffff",
+    "circle-stroke-width": 4,
+  },
+});
+
+mapInstance.addLayer({
+  id: "marker-labels",
+  type: "symbol",
+  source: "markers",
+  layout: {
+    "text-allow-overlap": true,
+    "text-anchor": "top",
+    "text-field": ["get", "name"],
+    "text-offset": [0, 0.9],
+    "text-size": 28,
+  },
+  paint: {
+    "text-color": "#111111",
+    "text-halo-color": "#ffffff",
+    "text-halo-width": 3,
+  },
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to the stock MapLibre demo style:
+
+```ts
+style: "https://demotiles.maplibre.org/style.json";
+```
+
+If the user requests another style, use any valid MapLibre style JSON URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.