@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/example-Root.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import {Composition} from 'remotion';
+import {CesiumFlythrough, type CesiumFlythroughProps} from './CesiumFlythrough';
+import cityPath from './city-path.json';
+
+export const RemotionRoot: React.FC = () => (
+	<>
+		<Composition
+			id="LandscapeFlyover"
+			component={CesiumFlythrough}
+			defaultProps={{mode: 'landscape'} satisfies CesiumFlythroughProps}
+			durationInFrames={24 * 30}
+			fps={30}
+			width={1920}
+			height={1080}
+		/>
+		<Composition
+			id="CityFlyover"
+			component={CesiumFlythrough}
+			defaultProps={
+				{
+					mode: 'city',
+					path: cityPath as [number, number][],
+					altitudeStart: 700,
+					altitudeEnd: 500,
+					lookAheadKm: 0.7,
+					travelKm: 4.5,
+					pitchFromNadir: 72,
+					verticalExaggeration: 1,
+					maximumScreenSpaceError: 6,
+				} satisfies CesiumFlythroughProps
+			}
+			durationInFrames={18 * 30}
+			fps={30}
+			width={1920}
+			height={1080}
+		/>
+	</>
+);

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/flight-path.ts

@@ -0,0 +1,35 @@
+export type LngLat = [number, number];
+
+// Chaikin corner cutting turns a sparse route into a continuous curve. Repeated passes round
+// direction changes into deliberate swerves instead of left-right heading bumps.
+export const smoothFlightPath = (source: LngLat[], passes = 3): LngLat[] => {
+	if (source.length < 2)
+		throw new Error('Flyover path needs at least two points');
+
+	// Keep adjacent longitudes continuous for routes that cross the antimeridian.
+	const unwrapped: LngLat[] = [source[0]];
+	for (let index = 1; index < source.length; index++) {
+		const [lng, lat] = source[index];
+		const previous = unwrapped[index - 1][0];
+		let adjusted = lng;
+		while (adjusted - previous > 180) adjusted -= 360;
+		while (adjusted - previous < -180) adjusted += 360;
+		unwrapped.push([adjusted, lat]);
+	}
+
+	let curve = unwrapped;
+	for (let pass = 0; pass < Math.max(0, passes); pass++) {
+		const next: LngLat[] = [curve[0]];
+		for (let i = 0; i < curve.length - 1; i++) {
+			const a = curve[i];
+			const b = curve[i + 1];
+			next.push(
+				[a[0] * 0.75 + b[0] * 0.25, a[1] * 0.75 + b[1] * 0.25],
+				[a[0] * 0.25 + b[0] * 0.75, a[1] * 0.25 + b[1] * 0.75],
+			);
+		}
+		next.push(curve[curve.length - 1]);
+		curve = next;
+	}
+	return curve;
+};

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/sample-river.geojson

@@ -0,0 +1,215 @@
+{
+	"type": "FeatureCollection",
+	"features": [
+		{
+			"type": "Feature",
+			"properties": {"name": "Yarlung Tsangpo (OSM, gorge way)"},
+			"geometry": {
+				"type": "LineString",
+				"coordinates": [
+					[94.8794306, 29.5453548],
+					[94.880058, 29.5500259],
+					[94.8804545, 29.5529773],
+					[94.8872806, 29.559007],
+					[94.8902386, 29.5645817],
+					[94.8945618, 29.5651505],
+					[94.8985437, 29.5703839],
+					[94.8978611, 29.5758448],
+					[94.9077237, 29.5843086],
+					[94.9107706, 29.5872382],
+					[94.9136749, 29.5879042],
+					[94.9208424, 29.5864253],
+					[94.9243692, 29.5890419],
+					[94.9243692, 29.5945028],
+					[94.9268508, 29.597544],
+					[94.9331942, 29.6000111],
+					[94.9350913, 29.6024165],
+					[94.9359736, 29.6042869],
+					[94.9354367, 29.6064452],
+					[94.9350634, 29.608155],
+					[94.9343462, 29.6094434],
+					[94.9295695, 29.6113703],
+					[94.9288061, 29.6124782],
+					[94.9268721, 29.6194181],
+					[94.9273809, 29.6276608],
+					[94.9274409, 29.6286334],
+					[94.9263783, 29.6303683],
+					[94.9250518, 29.6304537],
+					[94.922744, 29.6299103],
+					[94.9170292, 29.6256472],
+					[94.9144757, 29.6243553],
+					[94.9115439, 29.6243318],
+					[94.9008302, 29.6273853],
+					[94.8972905, 29.6276085],
+					[94.8897112, 29.6252949],
+					[94.8827398, 29.6253184],
+					[94.8806998, 29.6268686],
+					[94.8777241, 29.6317051],
+					[94.8768493, 29.6342436],
+					[94.8768641, 29.6346894],
+					[94.8769277, 29.6365972],
+					[94.8775677, 29.6391137],
+					[94.8804943, 29.6418187],
+					[94.8821969, 29.6438716],
+					[94.8877263, 29.6456718],
+					[94.8903366, 29.6468971],
+					[94.8959561, 29.6481151],
+					[94.9032857, 29.6528729],
+					[94.9113869, 29.6568592],
+					[94.9162734, 29.6587881],
+					[94.9182022, 29.6625172],
+					[94.9203882, 29.670104],
+					[94.9197453, 29.6744761],
+					[94.9192644, 29.6754058],
+					[94.9178164, 29.6782052],
+					[94.915116, 29.6816771],
+					[94.9094581, 29.6810342],
+					[94.9043145, 29.6796197],
+					[94.9018712, 29.6806484],
+					[94.8976278, 29.6812914],
+					[94.8909411, 29.6856634],
+					[94.8896552, 29.6890068],
+					[94.892227, 29.6990368],
+					[94.8978849, 29.704952],
+					[94.9017426, 29.7100956],
+					[94.9061206, 29.7112788],
+					[94.9065005, 29.7113815],
+					[94.9225743, 29.7192255],
+					[94.9264023, 29.7212652],
+					[94.9267629, 29.7213678],
+					[94.9341474, 29.723469],
+					[94.9360823, 29.7245705],
+					[94.9357152, 29.7273333],
+					[94.9344915, 29.7289804],
+					[94.9323502, 29.7303263],
+					[94.9298621, 29.73339],
+					[94.9294542, 29.734665],
+					[94.9298213, 29.7382244],
+					[94.9306755, 29.739157],
+					[94.9340021, 29.7439794],
+					[94.9355331, 29.7464083],
+					[94.9364901, 29.7488664],
+					[94.9372115, 29.749423],
+					[94.937775, 29.7498579],
+					[94.939019, 29.7500527],
+					[94.9407117, 29.7501944],
+					[94.9429346, 29.7513629],
+					[94.947778, 29.7543307],
+					[94.9541921, 29.755984],
+					[94.9574551, 29.7555414],
+					[94.9603715, 29.7553644],
+					[94.9629516, 29.755488],
+					[94.9676317, 29.757489],
+					[94.9709355, 29.7587814],
+					[94.9737019, 29.7603278],
+					[94.9738572, 29.7603796],
+					[94.9844009, 29.7638941],
+					[94.9852725, 29.7649069],
+					[94.9861359, 29.7675568],
+					[94.9898232, 29.7694497],
+					[94.9917263, 29.7691954],
+					[94.9966421, 29.7688099],
+					[95.0005707, 29.7670075],
+					[95.0007566, 29.7668999],
+					[95.0028203, 29.7657056],
+					[95.0080406, 29.7614995],
+					[95.0092963, 29.7609572],
+					[95.0138378, 29.7589957],
+					[95.0160159, 29.7574362],
+					[95.0194618, 29.7553902],
+					[95.0222306, 29.7524106],
+					[95.024336, 29.7498815],
+					[95.0273932, 29.7487547],
+					[95.0324981, 29.7493557],
+					[95.0339552, 29.7496724],
+					[95.0346257, 29.7499916],
+					[95.035882, 29.7507411],
+					[95.0375964, 29.7530966],
+					[95.0386203, 29.754818],
+					[95.0383895, 29.7567272],
+					[95.038166, 29.7590432],
+					[95.0395792, 29.7618349],
+					[95.0411334, 29.7631575],
+					[95.0420532, 29.7639402],
+					[95.0467825, 29.7661735],
+					[95.0495101, 29.7673453],
+					[95.0510063, 29.7681933],
+					[95.0516577, 29.7683919],
+					[95.0560621, 29.7692331],
+					[95.0577259, 29.7690047],
+					[95.0588453, 29.7684695],
+					[95.0650773, 29.767807],
+					[95.0705737, 29.761782],
+					[95.0720258, 29.7599696],
+					[95.0736121, 29.7540856],
+					[95.0754147, 29.751782],
+					[95.0758224, 29.751042],
+					[95.0760619, 29.750314],
+					[95.0759483, 29.7495284],
+					[95.0751984, 29.7480135],
+					[95.0728911, 29.7466988],
+					[95.0724585, 29.7445327],
+					[95.0732804, 29.7429802],
+					[95.0734102, 29.740789],
+					[95.0731362, 29.7386729],
+					[95.0744382, 29.7374902],
+					[95.075294, 29.7367129],
+					[95.079535, 29.7361346],
+					[95.081745, 29.736994],
+					[95.083005, 29.737484],
+					[95.0833905, 29.7430745],
+					[95.0844421, 29.7452715],
+					[95.0871532, 29.7473749],
+					[95.0918361, 29.7499864],
+					[95.0931923, 29.7511573],
+					[95.0943202, 29.7514189],
+					[95.0965266, 29.7510558],
+					[95.0991656, 29.7494408],
+					[95.1029871, 29.7472998],
+					[95.1038668, 29.7453591],
+					[95.1063039, 29.7417406],
+					[95.1084814, 29.741365],
+					[95.111726, 29.7426671],
+					[95.1138489, 29.7452914],
+					[95.1152135, 29.7465013],
+					[95.1154175, 29.7473556],
+					[95.1158661, 29.7480506],
+					[95.1167533, 29.7482586],
+					[95.1179004, 29.7491572],
+					[95.119434, 29.7515181],
+					[95.1195997, 29.7517319],
+					[95.1214023, 29.7535598],
+					[95.1239692, 29.754987],
+					[95.1260602, 29.7556005],
+					[95.1284973, 29.7561388],
+					[95.1311663, 29.7559002],
+					[95.1323477, 29.7559385],
+					[95.1344757, 29.7564723],
+					[95.1350155, 29.7583672],
+					[95.1382746, 29.7617848],
+					[95.1400377, 29.7646815],
+					[95.1410982, 29.7654339],
+					[95.1437689, 29.7649144],
+					[95.1469991, 29.7640131],
+					[95.1503617, 29.7622343],
+					[95.1506908, 29.7620602],
+					[95.1532721, 29.7600322],
+					[95.1565312, 29.7590432],
+					[95.1584059, 29.7594063],
+					[95.1589059, 29.7599317],
+					[95.1595043, 29.7612399],
+					[95.1611602, 29.7632119],
+					[95.1635565, 29.7646136],
+					[95.1700434, 29.7649144],
+					[95.1730828, 29.7644136],
+					[95.1748094, 29.7636814],
+					[95.1765005, 29.7628339],
+					[95.1794885, 29.7589784],
+					[95.1830673, 29.7576787],
+					[95.1848212, 29.7580682],
+					[95.1869103, 29.7594603]
+				]
+			}
+		}
+	]
+}

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-data-sources.md

@@ -0,0 +1,43 @@
+# Flyover data sources
+
+## Landscape
+
+Use MapTiler for both layers:
+
+- `terrain-quantized-mesh-v2`: elevation encoded as Cesium quantized-mesh terrain.
+- `satellite-v2`: raster satellite imagery draped on that mesh.
+
+CesiumJS renders the layers; it does not supply the data. Set `REMOTION_MAPTILER_KEY`.
+
+Create a key:
+
+- https://cloud.maptiler.com/account/keys/
+
+Official documentation:
+
+- https://docs.maptiler.com/cesium/
+- https://docs.maptiler.com/schema-raster/terrain-3d/
+
+## City
+
+Use Google Photorealistic 3D Tiles. Google supplies one high-resolution 3D mesh already textured
+with imagery. Disable the Cesium globe and do not add MapTiler terrain or satellite beneath it. Set
+`REMOTION_GOOGLE_MAPS_API_KEY`.
+
+Create and configure a key:
+
+- https://developers.google.com/maps/documentation/tile/get-api-key
+
+Enable the Map Tiles API in a billing-enabled Google Cloud project and restrict the key to that API.
+The application restriction must permit the local headless Remotion request.
+
+Official documentation:
+
+- https://developers.google.com/maps/documentation/tile/3d-tiles
+- https://developers.google.com/maps/documentation/tile/policies
+
+## Why not extruded buildings
+
+OSM-, Overture- and vector-tile building products primarily provide footprints, approximate heights
+and optional roof attributes. They are useful for analytical or stylized maps, but they do not
+provide the textured architecture required for a cinematic city flyover.

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-flyover-architecture.md

@@ -0,0 +1,128 @@
+# 3D Flyover — architecture reference
+
+Deep detail behind `TECHNIQUE.md`: provider loading, the camera-path pipeline, per-frame camera math, and
+the proven terrain values. Both landscape and city modes have been forward-tested through Remotion.
+
+## 1. Provider initialization
+
+Create the Viewer with `baseLayer: false`, UI widgets disabled, and
+`contextOptions.webgl.preserveDrawingBuffer: true`. Never hide the credit display.
+
+### Landscape
+
+Add MapTiler `satellite-v2` with `UrlTemplateImageryProvider`, then load
+`terrain-quantized-mesh-v2` with `CesiumTerrainProvider.fromUrl({requestVertexNormals: true})`.
+MapTiler supplies both datasets; no Cesium ion token is required.
+
+### City
+
+Do not add MapTiler. Hide the globe, then add:
+
+```ts
+viewer.scene.globe.show = false;
+const tileset = await Cesium.Cesium3DTileset.fromUrl(
+  `https://tile.googleapis.com/v1/3dtiles/root.json?key=${GOOGLE_KEY}`,
+  {showCreditsOnScreen: true, maximumScreenSpaceError: 4},
+);
+viewer.scene.primitives.add(tileset);
+```
+
+Lower `maximumScreenSpaceError` improves refinement at substantial download/render cost. Start at
+`4` for a hero landmark and `6–8` for wider urban shots. Enforce the Google 30-second promotional
+video ceiling in the component.
+
+Load Cesium from the CDN after setting `window.CESIUM_BASE_URL`; the tested version is `1.143`.
+
+## 2. The camera path — structure & generation
+
+Four properties matter, in order:
+
+1. **Continuous curvature** — the camera must flow through curves, never "fly straight, snap to a new
+   heading, fly straight." The component applies three passes of **Chaikin corner cutting** to every
+   supplied path. Each pass replaces a segment with quarter and three-quarter points, rounding a
+   corner into a curve. Three passes are the default; four is softer, two is tighter.
+2. **Constant ground speed** — precompute cumulative distance along the rounded curve and interpolate
+   by arc length. Do not animate by source-point index; unequal source spacing creates speed bumps.
+3. **Minimized amplitude** — for detailed landscape centerlines, dampen the prepared path toward its
+   straight start→end chord by a fixed fraction `DAMP` (0 = dead straight, 1 = full river). This is
+   the single swerve-amplitude knob.
+4. **Enough length** — `PATHKM ≥ TRAVEL_KM + 2·LOOK_AHEAD_KM` so the look-ahead aim never clamps.
+
+`../scripts/prep-cesium-path.mjs` does: clip a window of the source centerline → resample to even
+arc-length spacing (0.1 km) → moving-average smooth (±2.8 km window, 2 passes) → dampen toward the chord
+(`DAMP=0.45`). Validate with the heading-delta probe it prints — deltas should be small and change
+_gradually_ (water-wars: `3,0,-1,-3,-4,1,7,9,5,-5,-12,-7,…`). Big jumps = corners = bad.
+
+The component then applies Chaikin smoothing to this prepared route, or directly to a short
+hand-authored city route. Keep city control points sparse and intentional; smoothing cannot rescue a
+zig-zagging route that crosses the subject repeatedly.
+
+**Source data:** OSM via Overpass (~0.3 km vertex spacing) — Natural Earth is too coarse for inner
+gorges. overpass-api.de is often busy → mirror `overpass.kumi.systems`.
+
+## 3. Camera animation per frame (position, heading, pitch, bank)
+
+Walk the path by **arc length** (precompute cumulative distances once). Every frame:
+
+- **Position** = the point at `dCam` km along the path, altitude `lerp(ALT_START, ALT_END, prog)`.
+- **Heading** = bearing from the camera point to a **real point `LOOK_AHEAD_KM` further along the same
+  path**. A far aim averages wiggle → smooth heading; on a curved path it leads into the bend, so the
+  heading turns gently with the path. (A local-tangent aim spins the camera at every kink — don't.)
+- **Pitch** = constant. We keep a MapLibre-style param `PITCH_FROM_NADIR` (90 = horizon), then convert:
+  **Cesium pitch = `-(90 - PITCH_FROM_NADIR)`** (Cesium: 0 = horizon, -90 = straight down). 76° → -14°.
+- **Bank (roll)** = lean _into_ the turn — the helicopter tell. Measure turn rate as the bearing change
+  between `aim` and a point `2·LOOK_AHEAD_KM` ahead; `roll = clamp(dH · BANK_GAIN, ±MAX_BANK)`. Because
+  the path is smooth, `dH` changes gradually → the bank eases in and out, never jerks.
+
+```ts
+const setCamera = (C, viewer, prog) => {
+  const dCam = Math.min(TRAVEL_KM, PATHKM - LOOK_AHEAD_KM * 2) * prog;
+  const cam  = alongPath(dCam);                    // arc-length point
+  const aim  = alongPath(dCam + LOOK_AHEAD_KM);     // heading target (real point on the path)
+  const aim2 = alongPath(dCam + LOOK_AHEAD_KM * 2); // turn-rate probe → bank
+  const heading = bearing(cam, aim);
+  let dH = bearing(aim, aim2) - heading; while (dH > Math.PI) dH -= 2*Math.PI; while (dH < -Math.PI) dH += 2*Math.PI;
+  viewer.camera.setView({
+    destination: C.Cartesian3.fromDegrees(cam[0], cam[1], lerp(ALT_START, ALT_END, prog)),
+    orientation: { heading, pitch: C.Math.toRadians(-(90 - PITCH_FROM_NADIR)), roll: clamp(dH * BANK_GAIN, -MAX_BANK, MAX_BANK) },
+  });
+};
+```
+
+> **Cesium vs MapLibre conventions (gotcha):** Cesium heading is radians, 0 = north, clockwise. Pitch
+> 0 = horizon, negative = down (MapLibre is the inverse). Roll positive = bank right; tune the sign by eye.
+
+## 4. The feel — proven water-wars values
+
+| Param                    | Value                  | Meaning                                                                              |
+| ------------------------ | ---------------------- | ------------------------------------------------------------------------------------ |
+| `TRAVEL_KM`              | 13                     | How far the camera travels. **Speed = `TRAVEL_KM / durationSeconds`.**               |
+| duration                 | 24 s (720 f @30)       | 13 km / 24 s ≈ **0.54 km/s** — a slow, peaceful glide. 8 s felt "extremely rushed".  |
+| `ALT_START → ALT_END`    | 4600 → 4300 m ASL      | Absolute (terrain-independent). Inside the corridor walls → fly _through_, not over. |
+| `LOOK_AHEAD_KM`          | 1.5                    | Heading smoothness vs responsiveness.                                                |
+| `PITCH_FROM_NADIR`       | 76°                    | Stare-ahead down the corridor (90 = level). → Cesium -14°.                           |
+| `MAX_BANK` / `BANK_GAIN` | 0.13 rad (~7.5°) / 0.6 | Helicopter lean into turns.                                                          |
+| `verticalExaggeration`   | 1.1                    | Subtle terrain drama.                                                                |
+| `DAMP` (prep)            | 0.45                   | Swerve amount: higher = weavier, lower = straighter.                                 |
+
+**A slow camera renders fast.** At 0.54 km/s the camera moves ~18 m/frame, so tiles stay cached and each
+`settle()` returns almost immediately; the 720-frame render completed in one pass (no chunk-rendering).
+
+## 5. The complete component
+
+The full, runnable component is `../assets/CesiumFlythrough.tsx` — read it directly. Its shape:
+
+- `loadCesium()` — inject `CESIUM_BASE_URL` + the CDN `Cesium.js`, resolve when loaded.
+- init effect — build the Viewer (§1), `setCamera(…, 0)`, `await settle(viewer)`, `continueRender`.
+- `settle(viewer)` — loop `viewer.render()` until `globe.tilesLoaded` for landscapes or
+  `tileset.tilesLoaded` for cities is stable for ~8 ticks (cap ~600).
+- per-frame effect — `delayRender({timeoutInMilliseconds: 60000})` → `setCamera(prog)` → `settle()` → `continueRender`.
+
+## 6. Render
+
+```bash
+bunx remotion still   src/index.ts <Comp> out.png --frame=N --gl=angle --timeout=180000   # validate framing/bank first
+bunx remotion render  src/index.ts <Comp> out.mp4  --gl=angle --concurrency=1 --timeout=180000
+```
+
+`--gl=angle` is mandatory. Use `--concurrency=1`; `settle()` already serializes tile loading.

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-troubleshooting.md

@@ -0,0 +1,57 @@
+# 3D Flyover — troubleshooting
+
+## The headless dead-end (why we render through Remotion)
+
+Cesium's globe **will not draw in a standalone headless Playwright/Chromium** harness. Verified on
+Apple M4 (ANGLE Metal active, WebGL working): the skybox/stars render, but the globe surface produces
+**zero draw commands** (`scene.frameState.commandList.length === 0`), `globe.tilesLoaded` never goes
+true, and frames come back as the black starfield. No network failures; `sampleTerrainMostDetailed`
+succeeds (terrain data is reachable). Dead-ends tried, all failed:
+
+- default render loop, manual `scene.render()`, manual `viewer.render()`, headed mode (context-destroyed).
+
+**What works:** render Cesium **through Remotion** — same headless Chrome, but driven by Remotion's frame
+loop with these four non-negotiables:
+
+1. `useDefaultRenderLoop = false` — drive frames by hand.
+2. Per frame call **`viewer.render()`**, NOT `scene.render()`. `viewer.render()` does the full frame
+   (`initializeFrame` → tile streaming → render); `scene.render()` skips frame-init, so tiles never
+   advance and the globe never appears. **This is the single most important line.**
+3. `contextOptions: { webgl: { preserveDrawingBuffer: true } }` so Remotion's screenshot captures pixels.
+4. Gate init + every frame with `delayRender(…, {timeoutInMilliseconds})` — tile loading can exceed Remotion's
+   default; use 60–120 s.
+
+The standalone `flythrough.html` / `render.mjs` / `probe.mjs` from the original spike are kept only as the
+record of this dead-end. The canonical render path is the Remotion component
+(`../assets/CesiumFlythrough.tsx`).
+
+## Symptom → fix
+
+| Symptom                                                   | Cause                                                                                                         | Fix                                                                                                 |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Frames are black with stars                               | Globe not drawing (headless Playwright, or `scene.render()` used)                                             | Render through Remotion; use `viewer.render()`; `useDefaultRenderLoop=false`.                       |
+| Screenshots blank/transparent                             | No `preserveDrawingBuffer`                                                                                    | `contextOptions:{ webgl:{ preserveDrawingBuffer:true } }`.                                          |
+| "delayRender timed out"                                   | Cold tiles exceed the default                                                                                 | `delayRender(…, {timeoutInMilliseconds: 120000})` + `--timeout=180000`.                             |
+| Globe is a dark/navy sphere                               | Imagery layer didn't attach                                                                                   | `baseLayer:false` then `viewer.imageryLayers.addImageryProvider(...)`.                              |
+| High-pitch frame shows a void/starfield above the horizon | No atmosphere                                                                                                 | `viewer.scene.skyAtmosphere.show = true`.                                                           |
+| 403 on tiles in headless                                  | Domain-locked MapTiler key                                                                                    | Use an **unrestricted** key.                                                                        |
+| Google root tileset returns 403                           | Map Tiles API disabled, billing absent, wrong key, or application restriction blocks local headless rendering | Enable Map Tiles API and billing; restrict the key to that API while allowing the Remotion request. |
+| Google scene shows a duplicate/competing surface          | MapTiler or the Cesium globe is still enabled                                                                 | Do not add MapTiler; set `viewer.scene.globe.show=false`.                                           |
+| Google mesh remains coarse                                | Screen-space error is too high or the capture starts before refinement                                        | Lower `maximumScreenSpaceError`; settle on `tileset.tilesLoaded`.                                   |
+| WebGL unavailable / software renderer                     | Missing GL flag                                                                                               | Render with `--gl=angle`.                                                                           |
+| Camera looks at sky / ground, not terrain                 | Pitch sign / convention                                                                                       | Cesium pitch 0 = horizon, negative = down (inverse of MapLibre); `-(90 - PITCH_FROM_NADIR)`.        |
+| Aim/turn-probe clamps near the end                        | Path too short                                                                                                | `PATHKM ≥ TRAVEL_KM + 2·LOOK_AHEAD_KM`; raise `WINDOW_KM` in prep.                                  |
+| Path feels like straight-then-corner                      | Douglas-Peucker simplification                                                                                | Use resample → moving-average smooth (see architecture §2), not `turf.simplify`.                    |
+| Camera bumps left and right instead of swerving           | Sparse route vertices are still being followed as straight segments                                           | Keep `pathSmoothingPasses={3}`; use sparse intentional control points and arc-length movement.      |
+
+## Gotchas checklist
+
+- **`viewer.render()`, never `scene.render()`** per frame. The single biggest trap.
+- Cesium loads from **CDN**; set `window.CESIUM_BASE_URL` _before_ injecting the script.
+- `preserveDrawingBuffer: true` or screenshots are blank.
+- `delayRender` uses `timeoutInMilliseconds`; set it to at least 60,000.
+- Terrain: `baseLayer:false`, then add MapTiler imagery.
+- Google: no MapTiler, hide the globe, retain `showCreditsOnScreen:true`.
+- Always `skyAtmosphere.show = true`.
+- Validate the path's heading-delta probe and render one **still** (framing + bank) before the full mp4.
+- Cesium pitch/roll conventions are inverted vs MapLibre.

package/templates/default/.opencode/skills/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs

@@ -0,0 +1,161 @@
+// Camera-path generator for the Cesium flythrough. Turns a river/route centerline GeoJSON into a LONG,
+// CONTINUOUSLY-curving camera path so the camera banks through smooth flowing curves (no
+// straight-then-corner). Method: clip → resample to even spacing → moving-average smooth (inherently
+// continuous curvature) → dampen lateral deviation toward the straight chord (dials swerve amplitude).
+// No Douglas-Peucker (that concentrates curvature at sparse control points → corners).
+//
+// RUN (out of the box, against the shipped sample):
+//   node prep-cesium-path.mjs
+//     → reads  assets/sample-river.geojson   (override: node prep-cesium-path.mjs <input.geojson> <output.json>)
+//     → writes assets/cesium-path.json        (then import that JSON in CesiumFlythrough.tsx, or copy it
+//                                               into your Remotion project's src/geo/ and adjust the import)
+//
+// ADAPT for a new location: change START (a point ON your centerline where the corridor opens),
+// WINDOW_KM, and DAMP/SMOOTH below. Input must be a single LineString feature (features[0].geometry).
+
+import {readFileSync, writeFileSync, mkdirSync} from 'fs';
+import {dirname, resolve} from 'path';
+import {fileURLToPath} from 'url';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const IN = process.argv[2] || resolve(__dir, '../assets/sample-river.geojson');
+const OUT = process.argv[3] || resolve(__dir, '../assets/cesium-path.json');
+const havKm = (a, b) => {
+	const R = 6371,
+		r = Math.PI / 180,
+		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));
+};
+
+const gorge = JSON.parse(readFileSync(IN, 'utf8')).features[0].geometry
+	.coordinates;
+
+// ADAPT: clip ~24 km of river from the reach where the flythrough opens. START must be a point ON the
+// centerline (the script snaps to the nearest vertex). The sample's opening is the Yarlung gorge:
+const START = [94.968, 29.757];
+let s0 = 0,
+	best = Infinity;
+gorge.forEach((p, i) => {
+	const d = havKm(p, START);
+	if (d < best) {
+		best = d;
+		s0 = i;
+	}
+});
+const WINDOW_KM = 30; // clip to ~end of gorge data; smoothing+dampening shrink it to the usable corridor
+const clip = [];
+for (let i = s0, acc = 0; i < gorge.length; i++) {
+	if (i > s0) acc += havKm(gorge[i - 1], gorge[i]);
+	if (acc > WINDOW_KM) break;
+	clip.push(gorge[i]);
+}
+
+// Resample to even arc-length spacing so curvature is distributed evenly along the path.
+const STEP_KM = 0.1;
+const resample = (coords) => {
+	const out = [coords[0].slice()];
+	let carry = 0,
+		from = coords[0];
+	for (let i = 1; i < coords.length; i++) {
+		let segLen = havKm(from, coords[i]);
+		while (carry + segLen >= STEP_KM) {
+			const t = (STEP_KM - carry) / segLen;
+			const np = [
+				from[0] + (coords[i][0] - from[0]) * t,
+				from[1] + (coords[i][1] - from[1]) * t,
+			];
+			out.push(np);
+			from = np;
+			segLen = havKm(from, coords[i]);
+			carry = 0;
+		}
+		carry += segLen;
+		from = coords[i];
+	}
+	return out;
+};
+
+// Moving-average smoothing — inherently continuous (no kinks). Window in points; repeat for extra glass.
+const smoothMA = (coords, w, passes) => {
+	let c = coords;
+	for (let p = 0; p < passes; p++) {
+		c = c.map((_, i) => {
+			let sx = 0,
+				sy = 0,
+				n = 0;
+			for (
+				let j = Math.max(0, i - w);
+				j <= Math.min(c.length - 1, i + w);
+				j++
+			) {
+				sx += c[j][0];
+				sy += c[j][1];
+				n++;
+			}
+			return [sx / n, sy / n];
+		});
+	}
+	return c;
+};
+
+const SMOOTH_W = 28; // ±2.8 km window — turns meanders into smooth flowing curves
+const SMOOTH_PASSES = 2;
+const DAMP = 0.45; // keep 45% of the (already-smooth) deviation → gentle, continuous swerve
+
+const even = resample(clip);
+const sm = smoothMA(even, SMOOTH_W, SMOOTH_PASSES);
+
+const lat0 = (sm[0][1] * Math.PI) / 180;
+const kx = 111.32 * Math.cos(lat0),
+	ky = 110.57;
+const toXY = (p) => [(p[0] - sm[0][0]) * kx, (p[1] - sm[0][1]) * ky];
+const toLL = (xy) => [sm[0][0] + xy[0] / kx, sm[0][1] + xy[1] / ky];
+const A = toXY(sm[0]),
+	B = toXY(sm[sm.length - 1]);
+const AB = [B[0] - A[0], B[1] - A[1]],
+	len2 = AB[0] ** 2 + AB[1] ** 2;
+const path = sm.map((p) => {
+	const P = toXY(p);
+	const t = ((P[0] - A[0]) * AB[0] + (P[1] - A[1]) * AB[1]) / len2;
+	const proj = [A[0] + t * AB[0], A[1] + t * AB[1]];
+	return toLL([
+		proj[0] + (P[0] - proj[0]) * DAMP,
+		proj[1] + (P[1] - proj[1]) * DAMP,
+	]);
+});
+
+mkdirSync(dirname(OUT), {recursive: true});
+writeFileSync(OUT, JSON.stringify(path));
+
+let len = 0;
+for (let i = 1; i < path.length; i++) len += havKm(path[i - 1], path[i]);
+console.log(
+	`cesium-path: clip ${clip.length} → resample ${even.length} → smooth → ${path.length} pts · ${len.toFixed(1)} km`,
+);
+const bear = (a, b) => {
+	const r = Math.PI / 180;
+	const y = Math.sin((b[0] - a[0]) * r) * Math.cos(b[1] * r);
+	const x =
+		Math.cos(a[1] * r) * Math.sin(b[1] * r) -
+		Math.sin(a[1] * r) * Math.cos(b[1] * r) * Math.cos((b[0] - a[0]) * r);
+	return (Math.atan2(y, x) * 180) / Math.PI;
+};
+// heading sampled every ~1.5 km — should change gradually & continuously (no big jumps = no corners)
+const stepPts = Math.round(1.5 / STEP_KM);
+let prev = null,
+	hs = [];
+for (let i = 0; i + stepPts < path.length; i += stepPts) {
+	const h = bear(path[i], path[i + stepPts]);
+	if (prev !== null) {
+		let d = h - prev;
+		while (d > 180) d -= 360;
+		while (d < -180) d += 360;
+		hs.push(d.toFixed(0));
+	}
+	prev = h;
+}
+console.log(`  heading deltas every 1.5km (deg): ${hs.join(', ')}`);