takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/remotion/rules/maplibre.md

@@ -0,0 +1,458 @@
+---
+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`.

package/assets/.agent/skills/remotion/rules/measuring-dom-nodes.md

@@ -32,4 +32,3 @@ export const MyComponent = () => {
   return <div ref={ref}>Content to measure</div>;
 };
 ```
-

package/assets/.agent/skills/remotion/rules/measuring-text.md

@@ -12,10 +12,7 @@ metadata:
 Install @remotion/layout-utils if it is not already installed:
 
 ```bash
-npx remotion add @remotion/layout-utils # If project uses npm
-bunx remotion add @remotion/layout-utils # If project uses bun
-yarn remotion add @remotion/layout-utils # If project uses yarn
-pnpm exec remotion add @remotion/layout-utils # If project uses pnpm
+npx remotion add @remotion/layout-utils
 ```
 
 ## Measuring text dimensions
@@ -104,7 +101,7 @@ waitUntilDone().then(() => {
     fontFamily,
     fontSize: 32,
   });
-})
+});
 ```
 
 **Use validateFontIsLoaded:** Catch font loading issues early:

package/assets/.agent/skills/remotion/rules/parameters.md

@@ -7,38 +7,38 @@ metadata:
 
 To make a video parametrizable, a Zod schema can be added to a composition.
 
-First, `zod` must be installed - it must be exactly version `3.22.3`.
+First, `zod` must be installed .
 
 Search the project for lockfiles and run the correct command depending on the package manager:
 
 If `package-lock.json` is found, use the following command:
 
 ```bash
-npm i zod@3.22.3
+npm i zod
 ```
 
 If `bun.lockb` is found, use the following command:
 
 ```bash
-bun i zod@3.22.3
+bun i zod
 ```
 
 If `yarn.lock` is found, use the following command:
 
 ```bash
-yarn add zod@3.22.3
+yarn add zod
 ```
 
 If `pnpm-lock.yaml` is found, use the following command:
 
 ```bash
-pnpm i zod@3.22.3
+pnpm i zod
 ```
 
 Then, a Zod schema can be defined alongside the component:
 
 ```tsx title="src/MyComposition.tsx"
-import {z} from 'zod';
+import { z } from "zod";
 
 export const MyCompositionSchema = z.object({
   title: z.string(),
@@ -56,11 +56,22 @@ const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
 In the root file, the schema can be passed to the composition:
 
 ```tsx title="src/Root.tsx"
-import {Composition} from 'remotion';
-import {MycComponent, MyCompositionSchema} from './MyComposition';
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
 
 export const RemotionRoot = () => {
-  return <Composition id="MyComposition" component={MyComponent} durationInFrames={100} fps={30} width={1080} height={1080} defaultProps={{title: 'Hello World'}} schema={MyCompositionSchema} />;
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComponent}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ title: "Hello World" }}
+      schema={MyCompositionSchema}
+    />
+  );
 };
 ```
 
@@ -86,7 +97,7 @@ pnpm exec remotion add @remotion/zod-types # If project uses pnpm
 Then import `zColor` from `@remotion/zod-types`:
 
 ```tsx
-import {zColor} from '@remotion/zod-types';
+import { zColor } from "@remotion/zod-types";
 ```
 
 Then use it in the schema:

package/assets/.agent/skills/remotion/rules/sequencing.md

@@ -10,14 +10,40 @@ Use `<Sequence>` to delay when an element appears in the timeline.
 ```tsx
 import { Sequence } from "remotion";
 
-const {fps} = useVideoConfig();
-
-<Sequence from={1 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
-  <Title />
-</Sequence>
-<Sequence from={2 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
-  <Subtitle />
-</Sequence>
+export const Title = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+    extrapolateLeft: "clamp",
+    easing: Easing.bezier(0.16, 1, 0.3, 1),
+  });
+
+  return <div style={{ opacity }}>Title</div>;
+};
+
+export const Subtitle = () => {
+  return <div>Subtitle</div>;
+};
+
+const Main = () => {
+  const {fps} = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      <Sequence>
+        <Background />
+      </Sequence>
+      <Sequence from={1 * fps} durationInFrames={2 * fps} layout="none">
+        <Title />
+      </Sequence>
+      <Sequence from={2 * fps} durationInFrames={2 * fps} layout="none">
+        <Subtitle />
+      </Sequence>
+    </AbsoluteFill>
+  );
+}
 ```
 
 This will by default wrap the component in an absolute fill element.  
@@ -45,7 +71,7 @@ Always premount any `<Sequence>`!
 Use `<Series>` when elements should play one after another without overlap.
 
 ```tsx
-import {Series} from 'remotion';
+import { Series } from "remotion";
 
 <Series>
   <Series.Sequence durationInFrames={45}>

package/assets/.agent/skills/remotion/rules/sfx.md

@@ -0,0 +1,51 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+  tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `<Audio>` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+<Audio src={"https://remotion.media/whoosh.wav"} />;
+```
+
+The following sound effects are available:
+
+- `https://remotion.media/whoosh.wav`
+- `https://remotion.media/whip.wav`
+- `https://remotion.media/page-turn.wav`
+- `https://remotion.media/switch.wav`
+- `https://remotion.media/mouse-click.wav`
+- `https://remotion.media/shutter-modern.wav`
+- `https://remotion.media/shutter-old.wav`
+- `https://remotion.media/ding.wav`
+- `https://remotion.media/bruh.wav`
+- `https://remotion.media/vine-boom.wav`
+- `https://remotion.media/windows-xp-error.wav`
+- `https://remotion.media/fah.wav`
+- `https://remotion.media/spongebob-fail.wav`
+- `https://remotion.media/omg-hell-nah.wav`
+- `https://remotion.media/price-is-right-fail.wav`
+- `https://remotion.media/romance-meme.wav`
+- `https://remotion.media/bone-crack.wav`
+- `https://remotion.media/anime-wow.wav`
+- `https://remotion.media/yippee.wav`
+- `https://remotion.media/loading-lag.wav`
+- `https://remotion.media/wilhelm-scream.wav`
+- `https://remotion.media/mac-quack.wav`
+- `https://remotion.media/skedaddle.wav`
+- `https://remotion.media/snapchat-notification.wav`
+- `https://remotion.media/nelly-ahh.wav`
+- `https://remotion.media/sanctuary-guardian-what.wav`
+- `https://remotion.media/minecraft-hurt.wav`
+- `https://remotion.media/oh-my-god-vine.wav`
+- `https://remotion.media/illuminati-confirmed.wav`
+- `https://remotion.media/dramatic-boomer.wav`
+- `https://remotion.media/triggered.wav`
+- `https://remotion.media/record-scratch.wav`
+
+For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.