dsh-remotion 0.2.0 → 0.3.0

package/skills/remotion-maps/techniques/maptiler/references/map-explainer-architecture.md

@@ -0,0 +1,129 @@
+# Map Explainer — architecture reference
+
+Deep detail behind `TECHNIQUE.md`: the timing model, the river reveal + electric head, the per-country
+sequence, and label projection. The supplied values are examples, not a production style system.
+The custom-geometry example is `../assets/RiverReveal.tsx` +
+`../assets/CountryLabel.tsx` +
+`../assets/tokens.ts`. Provider-vector setup is in
+`../assets/MapTilerVectorElement.ts`; choose between
+the two modes with `data-sources.md`.
+
+## 1. The render harness (per frame)
+
+Init the MapTiler map once (ref guard). On `load`: strip clutter (see `geo-prep.md`), add sources/layers,
+wait for `once('idle') → continueRender`. Per frame:
+
+```
+delayRender → setData/setPaintProperty → map.once('idle', continueRender) → triggerRepaint
+```
+
+`preserveDrawingBuffer:true` so Remotion's screenshot captures the canvas. Render `--gl=angle`.
+For an animated camera, read `render-stability.md`: the MapTiler renderer remains static and a CSS plate
+transform supplies the camera choreography.
+
+## 2. Timing model — time-based; beat length derived from the sequences
+
+Everything keys off **seconds** (`t = frame / fps`), not reveal-units. The river draws over a window;
+each country **triggers when the river reaches it** and runs a fixed sequence. The beat is exactly as
+long as the sequences need.
+
+```ts
+const RIVER_START = 0.3, RIVER_END = 8.0;            // river draws over this window
+const BORDER_S = 2.5, FILL_S = 1.0, LABEL_S = 0.7;   // per-country sequence (constant durations)
+const trigger = (c) => RIVER_START + META[c].stop * (RIVER_END - RIVER_START);  // river-arrival time
+// beat length = max over c of (trigger(c) + BORDER_S + FILL_S + LABEL_S) + tail
+const reveal = interpolate(t, [RIVER_START, RIVER_END], [0,1], { ...clamp, easing: Easing.bezier(0.645, 0.045, 0.355, 1) });
+```
+
+**Constant durations matter:** drive the border draw by _time since trigger_, not a slice of the reveal —
+otherwise complex or long borders flash by in a fraction of a second.
+
+## 3. Provider-vector animation
+
+MapTiler Planet elements can be animated directly in place. Filter an exact `source-layer` feature,
+initialize its paint in the hidden or neutral state, then update paint properties from the Remotion frame.
+This works for line, fill, circle, and symbol layers without copying provider geometry into the project.
+
+Do not assume tiled geometry has a global order. Provider features are split at tile boundaries: opacity,
+colour, width, blur, radius, fill, and feature-state changes are reliable; semantic start-to-end line
+draws are not. Bake ordered GeoJSON when the direction of the draw carries meaning.
+
+## 4. Custom line animation — reveal + electric draw-head
+
+The "electricity" is a **white-hot head** leading the draw — the last few % of the drawn line in its own
+bright + glow layers, faded out once the river completes.
+
+```ts
+const riverDrawnKm = lineKm * reveal;
+map.getSource("river").setData(turf.lineSliceAlong(line, 0, Math.max(0.001, riverDrawnKm)));
+const headKm = lineKm * 0.03;
+map.getSource("river-head").setData(turf.lineSliceAlong(line, Math.max(0, riverDrawnKm - headKm), Math.max(0.001, riverDrawnKm)));
+let headFade = 0;
+if (reveal > 0.002 && reveal < 0.999) headFade = 1;
+else if (reveal >= 0.999) headFade = 1 - clamp01((t - RIVER_END) / 0.5);  // fade out at the mouth
+map.setPaintProperty("river-headglow", "line-opacity", 0.85 * headFade);
+map.setPaintProperty("river-head", "line-opacity", headFade);
+```
+
+Layers, bottom→top: `river-glow` (electric blue `#49C6FF`, w11, op0.32, blur6) → `river-line`
+(icy core `#E8F7FF`, w3) → `river-headglow` (`rgba(120,225,255,.95)`, w16, blur9) → `river-head`
+(white `#FFFFFF`, w4.5). **No dark casing** — the bright icy core reads over every fill on its own.
+
+## 5. Country animation — border draws → fill blooms → label rises
+
+Triggered by river arrival, each country runs three sequential phases. The border is a **darker shade**
+of the country colour (the electricity is on the river, not here).
+
+```ts
+const lt = t - trigger(c);                                   // local seconds since trigger
+// 1) complete source border draws on over a constant BORDER_S, multi-segment-safe
+const bp = interpolate(clamp01(lt / BORDER_S), [0,1], [0,1], { easing: Easing.bezier(0.645, 0.045, 0.355, 1) });
+map.getSource(`trail-${c}`).setData(sliceBorder(DRAW[c], 0, DRAW[c].total * bp));   // COUNTRY_DARK line
+// 2) fill blooms in (opacity overshoots, then settles) after the border completes
+const fp = clamp01((lt - BORDER_S) / FILL_S);
+const fo = interpolate(fp, [0, 0.6, 1], [0, FILL_OPACITY * 1.25, FILL_OPACITY], { ...clamp, easing: Easing.bezier(0.3333333333333333, 1, 0.6666666666666666, 1) });
+map.setPaintProperty(`fill-${c}`, "fill-opacity", fp <= 0 ? 0 : fo);
+// 3) label rises in after the fill
+const lp = clamp01((lt - BORDER_S - FILL_S) / LABEL_S);
+```
+
+`sliceBorder(d, fromKm, toKm)` reveals a portion of a complete (possibly multi-segment) border as a
+MultiLineString, slicing each segment by cumulative length — no joins across gaps and no viewport crop:
+
+```ts
+const sliceBorder = (d, fromKm, toKm) => {
+  const out = [];
+  for (let i = 0; i < d.segLines.length; i++) {
+    const start = d.cum[i], end = start + d.segLen[i];
+    const a = Math.max(fromKm, start), b = Math.min(toKm, end);
+    if (b - a <= 0.0008) continue;
+    out.push(turf.lineSliceAlong(d.segLines[i], a - start, b - start).geometry.coordinates);
+  }
+  return { type:"Feature", properties:{}, geometry:{ type:"MultiLineString", coordinates: out } };
+};
+```
+
+Choose fill, border, and river colours in the production's local token file. The bundled token values are
+examples only; do not carry a source project's palette into another production.
+
+## 6. Labels — HTML overlay, projected each frame
+
+Labels are React, not map symbols (full typography control). `CountryLabel` is an example accent-rule,
+rise-and-fade treatment; select the typeface and final values in the production.
+Positioned by projecting the anchor to screen pixels **every frame**, stored in state:
+
+```ts
+const p = map.project(META[c].anchor);   // lngLat → screen px (respects the live camera)
+pos[c] = { x: p.x, y: p.y, reveal: lp };
+setLabels(pos);                          // re-render the overlay; effect deps exclude `labels`
+```
+
+`CountryLabel` shows the mechanics: uppercase region name, short accent divider, rise/fade entrance,
+and `pointerEvents:none`. Select font, weight, size, spacing, contrast, and colour from the production's
+own type and palette system.
+
+## 7. Camera — fixed map plate for any movement
+
+Read `render-stability.md`. Do not use per-frame `map.jumpTo()` for a moving 2D shot; it can shimmer in
+headless renders even on satellite imagery. Interpolate the intended camera for the CSS plate transform,
+while keeping the MapTiler renderer static.

package/skills/remotion-maps/techniques/maptiler/references/map-geo-prep.md

@@ -0,0 +1,85 @@
+# Map Explainer — basemap & geo prep
+
+How the basemap is cleaned and how `../scripts/prep-geo.mjs` bakes the per-country data the component reads.
+
+## Basemap styling — strip the clutter
+
+On `load`, remove the basemap's labels and inner admin borders so only your geography reads:
+
+```ts
+for (const l of m.getStyle().layers as any[])
+  if (l.type === "symbol" || /other border/i.test(l.id)) m.removeLayer(l.id);
+```
+
+- `type === "symbol"` → every place/water/road **label** (the "MapTiler labels"). Gone.
+- Inner admin-border layer IDs vary by style. Inspect the loaded style, remove state/province/district
+  layers as needed, and retain only the context borders the production requires.
+- Logo/attribution: `maptilerLogo:false` + `attributionControl:false` aren't always enough — also hide
+  via CSS in the component:
+  ```tsx
+  <style>
+    {`
+      .maplibregl-ctrl-bottom-left,
+      .maplibregl-ctrl-bottom-right,
+      .maplibregl-ctrl-attrib,
+      .maptiler-logo {
+        display: none !important;
+      }
+    `}
+  </style>
+  ```
+
+## `../scripts/prep-geo.mjs` → outputs
+
+Reads a routed river GeoJSON + country polygon GeoJSONs; writes:
+
+- **River line** — simplified for a smooth draw. For a braided river, route one source→mouth path through
+  the network first: greedy endpoint-chaining bounces between parallel channels. → `src/geo/river-flow.json`.
+- **`public/geo/borders.geojson`** — each country's polygon tagged `{country: name}` (one source,
+  filtered per country for the fills).
+- **`src/geo/country-meta.json`** — per country `{ stop, anchor, border }`.
+
+### `stop` — when a country lights up
+
+Walk the river points; first point inside a country (`turf.booleanPointInPolygon`) = the arc-length
+fraction where the river **enters** it. Drives the trigger time. The headwaters country = 0.
+
+### `anchor` — label centre via pole of inaccessibility
+
+The most-interior point of the country (clipped to a per-country **story bbox** so a big country
+centres in the relevant region, not its far bulge), then a small operator **nudge**. Pole = grid-sample
+inside the polygon, keep the point with max distance to the boundary. **Centroids get pulled to edges —
+don't use them.**
+
+```js
+const pole = (poly) => {
+  const bb = turf.bbox(poly), edge = turf.polygonToLine(poly), N = 46;
+  let best = null, bestD = -1;
+  for (let i = 0; i <= N; i++) for (let j = 0; j <= N; j++) {
+    const p = turf.point([bb[0]+(bb[2]-bb[0])*i/N, bb[1]+(bb[3]-bb[1])*j/N]);
+    if (!turf.booleanPointInPolygon(p, poly)) continue;
+    const d = turf.pointToLineDistance(p, edge);
+    if (d > bestD) { bestD = d; best = p.geometry.coordinates; }
+  }
+  return best;
+};
+const ANCHOR_BBOX = { china:[82,27,96,32], india:[76,14,99,31], bangladesh:[86,20,93,27] };  // story regions
+const NUDGE = { china:[0,0.6], india:[-1.0,0], bangladesh:[0,-0.6] };                          // operator-directed
+```
+
+### `border` — complete source geometry
+
+Preserve every exterior ring from the named country source. Never clip a country or bilateral border to
+the framed bbox and never discard an off-screen segment: the geometry may leave the frame naturally.
+The renderer handles a MultiLineString by cumulative length, so it remains one timed reveal without
+inventing joins across gaps.
+
+## Tuning the geo prep for a new scenario
+
+| Want                              | Knob                                                                 |
+| --------------------------------- | -------------------------------------------------------------------- |
+| Which countries                   | the country list in `prep-geo.mjs` (+ supply their polygon GeoJSONs) |
+| Label centred in the right region | `ANCHOR_BBOX[country]` (the story bbox)                              |
+| Nudge a label                     | `NUDGE[country]` (lng, lat offset)                                   |
+| What border is drawn              | the complete named source geometry; never the visible extent         |
+| When each lights up               | derived from `stop` — depends on the river geometry                  |

package/skills/remotion-maps/techniques/maptiler/references/render-stability.md

@@ -0,0 +1,64 @@
+# Moving Map Render Stability
+
+Read this reference before building a moving 2D MapTiler scene or diagnosing a wavering Remotion render.
+
+## Symptom and cause
+
+If basemap detail shimmers or jitters during a pan/zoom, the likely cause is per-frame `map.jumpTo()`.
+Headless MapTiler capture can resample both vector hillshade and satellite imagery differently frame to
+frame. Tile retries, easing changes, and label changes do not solve that renderer effect.
+
+## Required pattern: fixed map plate
+
+For any 2D pan/zoom:
+
+1. Render the MapTiler canvas once at the largest required zoom in an oversized container. Size it from the camera route and keep each dimension below the browser's reliable WebGL render-buffer limit (commonly 4096 px). Do **not** blindly use 3×: a 1920×1080 composition becomes 5760 px wide and Chromium may silently downsample it, causing visible pixelation during the CSS zoom.
+2. Keep the map's camera static.
+3. For each frame, calculate the approved target centre/zoom, then move the canvas with CSS `translate` + `scale`.
+4. Apply the same transform to every projected HTML overlay.
+5. Continue to animate GeoJSON data and paint properties imperatively; only the renderer camera is frozen.
+
+Keep pitch and bearing constant. Use a 3D engine such as Cesium for genuine changing pitch/bearing or a terrain flythrough.
+
+```ts
+const baseZoom = Math.max(start.zoom, end.zoom);
+const map = new maptilersdk.Map({
+  container,
+  style,
+  center: end.center,
+  zoom: baseZoom,
+  pitch: end.pitch ?? 0,
+  bearing: end.bearing ?? 0,
+  interactive: false,
+  fadeDuration: 0,
+  canvasContextAttributes: {preserveDrawingBuffer: true},
+});
+
+// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
+const projected = map.project(camera.center);
+const scale = 2 ** (camera.zoom - baseZoom);
+const plate = {
+  transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
+  transformOrigin: "0 0",
+};
+
+// Convert label projection with exactly the same plate transform.
+const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
+const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;
+```
+
+### Plate sizing and sharpness
+
+- Render at the maximum zoom reached by **any** camera waypoint, including intermediate or hold cameras. The CSS scale should never exceed `1`; otherwise the plate is being enlarged.
+- Centre the frozen map on the midpoint of the camera route's geographic extent, not automatically on the final camera. This minimizes required overscan.
+- Keep the largest canvas dimension at or below 4096 px unless the actual render environment has been tested with a larger `MAX_RENDERBUFFER_SIZE`.
+- For 1920×1080, a 3840×2160 plate is a safe default. For 1080×1920, use approximately 2700×3840 when the route needs extra horizontal pan room.
+- If the route cannot fit within that plate at the required zoom, split the shot into two fixed plates with a deliberate editorial transition. Do not trade sharpness for one enormous canvas.
+- Distinguish failure modes: repeating shimmer means the live renderer is moving; steadily soft tiles during a CSS push means the fixed plate is underspecified, internally downsampled, or being scaled above `1`.
+
+## Verification
+
+- Render a short MP4, not only a Studio preview.
+- Inspect static terrain texture and satellite detail while the camera moves.
+- If any underlying map detail wavers, use the fixed map plate. Do not approve it as a minor preview artefact.
+- Render WebGL with `--gl=angle`, `preserveDrawingBuffer:true`, and conservative concurrency (`1`) while validating.

package/skills/remotion-maps/techniques/maptiler/scripts/prep-geo.mjs

@@ -0,0 +1,202 @@
+// Geo prep for the map-explainer. Bakes the data the component reads:
+//   out/river-flow.json    -> the river draw-on line   (→ copy to your Remotion project's src/geo/)
+//   out/country-meta.json  -> per-country { stop, anchor, border }   (→ src/geo/)
+//   out/borders.geojson    -> country polygons, each tagged {country}  (→ public/geo/  — loaded via staticFile)
+//
+// RUN:  node prep-geo.mjs        (needs YOUR geodata — see CONFIG; the source polygons are too large to ship,
+//                                 so the skill ships the OUTPUTS in assets/sample-data/ instead.)
+//
+// RIVER INPUT MUST BE ONE CLEAN LINESTRING, source → mouth (features[0].geometry is a LineString). If your
+// OSM river comes as many ways / braided channels, ROUTE it into a single line FIRST — a graph
+// shortest-path from source node to mouth node. Do NOT greedily chain by nearest endpoint: it bounces
+// between parallel channels. (That routing step is a prerequisite, not part of this script.)
+
+import {readFileSync, writeFileSync, mkdirSync} from 'fs';
+import {dirname, resolve} from 'path';
+import {fileURLToPath} from 'url';
+
+if (process.argv.includes('--help')) {
+	console.log(
+		'Configure COUNTRIES, RIVER, BORDER, label bounds, and output paths in this script, then run: bun scripts/prep-geo.mjs',
+	);
+	process.exit(0);
+}
+
+const turf = await import('@turf/turf');
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dir, '..');
+const geo = resolve(root, '../geodata'); // ADAPT: where your input GeoJSON lives
+const read = (p) => JSON.parse(readFileSync(p, 'utf8'));
+
+// ===== CONFIG — edit for your river + countries =====
+const COUNTRIES = ['china', 'india', 'bangladesh']; // ORDERED headwaters → mouth; first = source (stop 0)
+const RIVER = resolve(geo, 'focus-rivers/yarlung-brahmaputra-full-osm.geojson'); // a single clean source→mouth LineString
+const BORDER = (name) => resolve(geo, `project-borders/${name}.geojson`); // one polygon file per country, named <country>.geojson
+const FRAME_BBOX = [76, 14, 104, 33.5]; // [W,S,E,N] visible extent — fallback for label anchoring only
+const ANCHOR_BBOX = {
+	china: [82, 27, 96, 32],
+	india: [76, 14, 99, 31],
+	bangladesh: [86, 20, 93, 27],
+}; // [W,S,E,N] per-country label "story region"
+const NUDGE = {china: [0, 0.6], india: [-1.0, 0], bangladesh: [0, -0.6]}; // [lng,lat] label nudge
+const RIVER_SIMPLIFY_TOL = 0.006; // degrees — smooths the draw-on (bigger = simpler)
+const OUT_RIVER = resolve(root, 'out/river-flow.json');
+const OUT_META = resolve(root, 'out/country-meta.json');
+const OUT_BORDERS = resolve(root, 'out/borders.geojson');
+// =====================================================
+
+const havKm = (a, b) => {
+	const R = 6371,
+		r = Math.PI / 180;
+	const dLat = (b[1] - a[1]) * r,
+		dLng = (b[0] - a[0]) * r;
+	const h =
+		Math.sin(dLat / 2) ** 2 +
+		Math.cos(a[1] * r) * Math.cos(b[1] * r) * Math.sin(dLng / 2) ** 2;
+	return 2 * R * Math.asin(Math.sqrt(h));
+};
+
+// --- River draw-on line: take the clean routed LineString, strip a dangling final hop, simplify so the
+// wide-zoom draw-on reads as one smooth thread (no bezier — meander overshoot on a long river). ---
+const routed = read(RIVER).features[0].geometry.coordinates;
+let end = routed.length;
+while (end > 2 && havKm(routed[end - 2], routed[end - 1]) > 15) end--; // drop a final cross-braid jump if present
+const flow = turf.simplify(turf.lineString(routed.slice(0, end)), {
+	tolerance: RIVER_SIMPLIFY_TOL,
+	highQuality: true,
+}).geometry.coordinates;
+
+// --- Borders + country fills (one source, filtered per country in the component) ---
+const borders = {type: 'FeatureCollection', features: []};
+const polys = {};
+for (const name of COUNTRIES) {
+	const fc = read(BORDER(name));
+	polys[name] = fc;
+	for (const f of fc.features) {
+		f.properties = {...(f.properties || {}), country: name};
+		borders.features.push(f);
+	}
+}
+
+// --- Reveal stops: arc-length fraction of `flow` where the river first ENTERS each country. The first
+// country (headwaters) is the source, so its stop is 0; the rest are computed. ---
+const flowKm = turf.length(turf.lineString(flow));
+const insideCountry = (pt, name) =>
+	polys[name].features.some((f) => turf.booleanPointInPolygon(pt, f));
+const stops = {};
+COUNTRIES.forEach((c, i) => {
+	stops[c] = i === 0 ? 0 : 1;
+}); // 0 = headwaters; 1 = sentinel until entered
+let acc = 0;
+for (let i = 0; i < flow.length; i++) {
+	if (i > 0) acc += havKm(flow[i - 1], flow[i]);
+	const frac = acc / (flowKm || 1);
+	const pt = turf.point(flow[i]);
+	for (const c of COUNTRIES)
+		if (stops[c] === 1 && insideCountry(pt, c)) stops[c] = frac;
+}
+
+// --- Per-country meta: anchor = pole of inaccessibility of the visible landmass (centred, away from
+// borders/edges) within the country's story region + a NUDGE; border = every exterior ring from the
+// complete named source. Never crop a country or bilateral boundary to the viewport. ---
+const biggestPoly = (geom) => {
+	const rings =
+		geom.type === 'MultiPolygon' ? geom.coordinates : [geom.coordinates];
+	let best = null,
+		bestA = -1;
+	for (const c of rings) {
+		const p = turf.polygon(c);
+		const a = turf.area(p);
+		if (a > bestA) {
+			bestA = a;
+			best = p;
+		}
+	}
+	return best;
+};
+const largestPolygon = (fc) => {
+	let best = null,
+		bestA = -1;
+	for (const f of fc.features) {
+		const p = biggestPoly(f.geometry),
+			a = turf.area(p);
+		if (a > bestA) {
+			bestA = a;
+			best = p;
+		}
+	}
+	return best;
+};
+const completeExteriorSegments = (fc) => {
+	const segments = [];
+	for (const feature of fc.features) {
+		const polygons =
+			feature.geometry.type === 'MultiPolygon'
+				? feature.geometry.coordinates
+				: [feature.geometry.coordinates];
+		for (const polygon of polygons)
+			if (polygon[0]?.length > 1) segments.push(polygon[0]);
+	}
+	return segments;
+};
+const poleOfInaccessibility = (poly) => {
+	const bb = turf.bbox(poly),
+		boundary = turf.polygonToLine(poly),
+		N = 46;
+	let best = null,
+		bestD = -1;
+	for (let i = 0; i <= N; i++)
+		for (let j = 0; j <= N; j++) {
+			const lng = bb[0] + ((bb[2] - bb[0]) * i) / N,
+				lat = bb[1] + ((bb[3] - bb[1]) * j) / N;
+			const pt = turf.point([lng, lat]);
+			if (!turf.booleanPointInPolygon(pt, poly)) continue;
+			const d = turf.pointToLineDistance(pt, boundary);
+			if (d > bestD) {
+				bestD = d;
+				best = [lng, lat];
+			}
+		}
+	return best;
+};
+const countryMeta = {};
+for (const name of COUNTRIES) {
+	const poly = largestPolygon(polys[name]);
+	const storyRegion = biggestPoly(
+		turf.bboxClip(poly, ANCHOR_BBOX[name] || FRAME_BBOX).geometry,
+	);
+	const pole = poleOfInaccessibility(storyRegion);
+	const segs = completeExteriorSegments(polys[name]);
+	const nudge = NUDGE[name] || [0, 0];
+	countryMeta[name] = {
+		stop: stops[name],
+		anchor: [pole[0] + nudge[0], pole[1] + nudge[1]],
+		border: segs,
+	};
+}
+
+mkdirSync(dirname(OUT_RIVER), {recursive: true});
+writeFileSync(OUT_RIVER, JSON.stringify(flow));
+writeFileSync(OUT_META, JSON.stringify(countryMeta));
+writeFileSync(OUT_BORDERS, JSON.stringify(borders));
+console.log(
+	'river:',
+	flow.length,
+	'pts ·',
+	flowKm.toFixed(0),
+	'km · entry stops',
+	JSON.stringify(stops),
+);
+for (const n of COUNTRIES) {
+	const km = countryMeta[n].border.reduce(
+		(s, seg) => s + turf.length(turf.lineString(seg)),
+		0,
+	);
+	console.log(
+		`  ${n}: anchor ${countryMeta[n].anchor.map((v) => v.toFixed(2)).join(',')} · border ${km.toFixed(0)} km`,
+	);
+}
+console.log(
+	"\nNext: copy out/river-flow.json + out/country-meta.json → your project's src/geo/ ; out/borders.geojson → public/geo/",
+);

package/skills/remotion-maps/techniques/static-map/TECHNIQUE.md

@@ -0,0 +1,37 @@
+---
+name: remotion-maps-static
+description: Create a deterministic static locator map in Remotion when neither the camera nor geographic data animates.
+---
+
+# Static map
+
+Use a static image when the map only provides location context. This is the smallest, fastest, and
+most deterministic map technique.
+
+## Build
+
+1. Export or request a map image at the composition's final aspect ratio and at least its rendered
+   pixel dimensions.
+2. Store the image in the Remotion project's `public/` directory.
+3. Render it with `CanvasImage` and `staticFile()`.
+4. Add labels or markers as ordinary Remotion elements if they remain fixed.
+
+```tsx
+import React from 'react';
+import {AbsoluteFill, CanvasImage, staticFile} from 'remotion';
+
+export const StaticMap: React.FC = () => {
+	return (
+	  <>
+  		<CanvasImage
+  			src={staticFile('locator-map.png')}
+  			style={{width: '100%', height: '100%', objectFit: 'cover'}}
+  		/>
+		</>
+	);
+};
+```
+
+## Overlays and Interactivity
+
+Follow [Remotion Interactivity](../../../remotion-interactivity/SKILL.md) best practices and [Remotion Markup Best practices](../../../remotion-markup/SKILL.md) for elements.

package/skills/remotion-markup/3d.md

@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>;
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>;
+```