dsh-remotion 0.2.0 → 0.3.0

package/skills/remotion-best-practices/remotion-maps/techniques/maptiler/assets/sample-data/yarlung-flow.json

@@ -0,0 +1,605 @@
+[
+	[84.144, 29.565],
+	[84.171, 29.577],
+	[84.22500000000001, 29.559],
+	[84.246, 29.541],
+	[84.297, 29.544],
+	[84.321, 29.532],
+	[84.411, 29.544],
+	[84.426, 29.529],
+	[84.45, 29.535],
+	[84.468, 29.523],
+	[84.492, 29.523],
+	[84.531, 29.490000000000002],
+	[84.507, 29.466],
+	[84.501, 29.445],
+	[84.513, 29.385],
+	[84.495, 29.379],
+	[84.483, 29.361],
+	[84.486, 29.34],
+	[84.519, 29.316],
+	[84.51, 29.292],
+	[84.522, 29.286],
+	[84.525, 29.265],
+	[84.57600000000001, 29.253],
+	[84.58800000000001, 29.259],
+	[84.60300000000001, 29.247],
+	[84.615, 29.265],
+	[84.63, 29.268],
+	[84.624, 29.283],
+	[84.651, 29.286],
+	[84.669, 29.259],
+	[84.732, 29.25],
+	[84.741, 29.235],
+	[84.771, 29.25],
+	[84.777, 29.241],
+	[84.843, 29.223],
+	[84.864, 29.232],
+	[84.879, 29.202],
+	[84.9, 29.199],
+	[84.909, 29.181],
+	[84.933, 29.184],
+	[84.96900000000001, 29.163],
+	[85.023, 29.187],
+	[85.071, 29.259],
+	[85.122, 29.274],
+	[85.167, 29.322],
+	[85.185, 29.310000000000002],
+	[85.26, 29.319],
+	[85.284, 29.301000000000002],
+	[85.34400000000001, 29.289],
+	[85.35600000000001, 29.265],
+	[85.413, 29.262],
+	[85.431, 29.271],
+	[85.449, 29.247],
+	[85.464, 29.244],
+	[85.521, 29.25],
+	[85.551, 29.265],
+	[85.611, 29.235],
+	[85.617, 29.193],
+	[85.662, 29.172],
+	[85.686, 29.172],
+	[85.69500000000001, 29.184],
+	[85.71600000000001, 29.172],
+	[85.72800000000001, 29.187],
+	[85.764, 29.181],
+	[85.761, 29.193],
+	[85.776, 29.202],
+	[85.788, 29.196],
+	[85.797, 29.22],
+	[85.809, 29.211000000000002],
+	[85.848, 29.211000000000002],
+	[85.863, 29.193],
+	[85.881, 29.193],
+	[85.917, 29.172],
+	[85.968, 29.175],
+	[86.004, 29.163],
+	[86.09400000000001, 29.175],
+	[86.10000000000001, 29.166],
+	[86.133, 29.172],
+	[86.148, 29.166],
+	[86.193, 29.178],
+	[86.223, 29.202],
+	[86.268, 29.193],
+	[86.295, 29.208000000000002],
+	[86.34, 29.205000000000002],
+	[86.412, 29.217000000000002],
+	[86.427, 29.211000000000002],
+	[86.43, 29.199],
+	[86.47800000000001, 29.196],
+	[86.496, 29.22],
+	[86.514, 29.211000000000002],
+	[86.52, 29.235],
+	[86.529, 29.238],
+	[86.535, 29.217000000000002],
+	[86.559, 29.196],
+	[86.607, 29.202],
+	[86.616, 29.184],
+	[86.658, 29.193],
+	[86.67, 29.205000000000002],
+	[86.682, 29.199],
+	[86.7, 29.208000000000002],
+	[86.736, 29.205000000000002],
+	[86.778, 29.187],
+	[86.805, 29.196],
+	[86.82300000000001, 29.184],
+	[86.84100000000001, 29.19],
+	[86.901, 29.181],
+	[86.949, 29.163],
+	[87.027, 29.172],
+	[87.039, 29.148],
+	[87.063, 29.136],
+	[87.084, 29.142],
+	[87.12, 29.175],
+	[87.162, 29.142],
+	[87.21000000000001, 29.142],
+	[87.237, 29.157],
+	[87.249, 29.136],
+	[87.297, 29.127],
+	[87.303, 29.115000000000002],
+	[87.366, 29.121000000000002],
+	[87.459, 29.097],
+	[87.486, 29.115000000000002],
+	[87.546, 29.109],
+	[87.56700000000001, 29.121000000000002],
+	[87.59400000000001, 29.121000000000002],
+	[87.60600000000001, 29.133],
+	[87.654, 29.139],
+	[87.666, 29.13],
+	[87.684, 29.133],
+	[87.687, 29.157],
+	[87.669, 29.181],
+	[87.675, 29.205000000000002],
+	[87.705, 29.217000000000002],
+	[87.714, 29.235],
+	[87.732, 29.238],
+	[87.732, 29.253],
+	[87.756, 29.283],
+	[87.753, 29.301000000000002],
+	[87.789, 29.304000000000002],
+	[87.795, 29.328],
+	[87.81, 29.337],
+	[87.849, 29.331],
+	[87.87, 29.349],
+	[87.906, 29.343],
+	[87.924, 29.349],
+	[87.97800000000001, 29.388],
+	[87.996, 29.376],
+	[88.014, 29.379],
+	[88.017, 29.37],
+	[88.125, 29.367],
+	[88.137, 29.337],
+	[88.161, 29.331],
+	[88.176, 29.337],
+	[88.188, 29.325],
+	[88.2, 29.328],
+	[88.221, 29.367],
+	[88.245, 29.367],
+	[88.287, 29.349],
+	[88.299, 29.358],
+	[88.365, 29.316],
+	[88.41, 29.322],
+	[88.422, 29.316],
+	[88.443, 29.325],
+	[88.458, 29.349],
+	[88.503, 29.361],
+	[88.536, 29.334],
+	[88.563, 29.328],
+	[88.596, 29.349],
+	[88.629, 29.346],
+	[88.641, 29.334],
+	[88.671, 29.34],
+	[88.71000000000001, 29.331],
+	[88.72800000000001, 29.343],
+	[88.791, 29.337],
+	[88.818, 29.352],
+	[88.86, 29.319],
+	[88.884, 29.334],
+	[88.908, 29.316],
+	[88.923, 29.331],
+	[88.962, 29.328],
+	[88.971, 29.349],
+	[89.007, 29.361],
+	[89.019, 29.352],
+	[89.034, 29.358],
+	[89.08500000000001, 29.322],
+	[89.136, 29.316],
+	[89.16, 29.343],
+	[89.181, 29.337],
+	[89.211, 29.349],
+	[89.235, 29.379],
+	[89.253, 29.373],
+	[89.265, 29.385],
+	[89.289, 29.385],
+	[89.307, 29.376],
+	[89.349, 29.379],
+	[89.397, 29.358],
+	[89.45100000000001, 29.355],
+	[89.46000000000001, 29.334],
+	[89.58, 29.358],
+	[89.595, 29.346],
+	[89.61, 29.355],
+	[89.631, 29.346],
+	[89.661, 29.349],
+	[89.679, 29.364],
+	[89.757, 29.295],
+	[89.787, 29.292],
+	[89.808, 29.310000000000002],
+	[89.85300000000001, 29.322],
+	[89.931, 29.319],
+	[89.985, 29.343],
+	[90.015, 29.337],
+	[90.072, 29.352],
+	[90.156, 29.355],
+	[90.168, 29.346],
+	[90.20100000000001, 29.349],
+	[90.22500000000001, 29.331],
+	[90.273, 29.337],
+	[90.276, 29.328],
+	[90.342, 29.313],
+	[90.378, 29.295],
+	[90.435, 29.241],
+	[90.477, 29.256],
+	[90.492, 29.25],
+	[90.51, 29.256],
+	[90.522, 29.247],
+	[90.54, 29.262],
+	[90.621, 29.277],
+	[90.642, 29.301000000000002],
+	[90.663, 29.298000000000002],
+	[90.681, 29.313],
+	[90.684, 29.328],
+	[90.705, 29.34],
+	[90.729, 29.328],
+	[90.747, 29.337],
+	[90.765, 29.328],
+	[90.768, 29.310000000000002],
+	[90.756, 29.295],
+	[90.771, 29.277],
+	[90.855, 29.283],
+	[90.897, 29.319],
+	[90.933, 29.310000000000002],
+	[90.95100000000001, 29.295],
+	[90.993, 29.322],
+	[91.035, 29.295],
+	[91.065, 29.316],
+	[91.116, 29.325],
+	[91.131, 29.313],
+	[91.173, 29.325],
+	[91.194, 29.286],
+	[91.233, 29.274],
+	[91.296, 29.289],
+	[91.308, 29.277],
+	[91.34700000000001, 29.28],
+	[91.374, 29.292],
+	[91.395, 29.28],
+	[91.449, 29.286],
+	[91.479, 29.268],
+	[91.512, 29.28],
+	[91.533, 29.271],
+	[91.554, 29.289],
+	[91.587, 29.292],
+	[91.602, 29.271],
+	[91.62, 29.265],
+	[91.659, 29.271],
+	[91.674, 29.259],
+	[91.71000000000001, 29.268],
+	[91.74, 29.259],
+	[91.782, 29.274],
+	[91.839, 29.268],
+	[91.869, 29.283],
+	[91.98, 29.262],
+	[92.007, 29.232],
+	[92.07000000000001, 29.289],
+	[92.115, 29.283],
+	[92.154, 29.289],
+	[92.196, 29.244],
+	[92.22, 29.253],
+	[92.235, 29.244],
+	[92.277, 29.244],
+	[92.295, 29.229],
+	[92.319, 29.226],
+	[92.376, 29.226],
+	[92.397, 29.241],
+	[92.406, 29.262],
+	[92.433, 29.25],
+	[92.46600000000001, 29.253],
+	[92.529, 29.172],
+	[92.529, 29.133],
+	[92.553, 29.148],
+	[92.598, 29.145],
+	[92.589, 29.121000000000002],
+	[92.61, 29.097],
+	[92.619, 29.115000000000002],
+	[92.658, 29.121000000000002],
+	[92.685, 29.139],
+	[92.697, 29.127],
+	[92.676, 29.112000000000002],
+	[92.679, 29.103],
+	[92.709, 29.109],
+	[92.739, 29.067],
+	[92.772, 29.091],
+	[92.775, 29.073],
+	[92.796, 29.082],
+	[92.808, 29.061],
+	[92.82000000000001, 29.067],
+	[92.82300000000001, 29.082],
+	[92.82900000000001, 29.076],
+	[92.85300000000001, 29.082],
+	[92.85600000000001, 29.073],
+	[92.88, 29.073],
+	[92.904, 29.058],
+	[92.934, 29.067],
+	[92.952, 29.049],
+	[92.973, 29.061],
+	[92.988, 29.043],
+	[92.997, 29.049],
+	[93.066, 29.043],
+	[93.081, 29.094],
+	[93.117, 29.115000000000002],
+	[93.123, 29.136],
+	[93.138, 29.139],
+	[93.15, 29.127],
+	[93.147, 29.094],
+	[93.165, 29.064],
+	[93.165, 29.043],
+	[93.153, 29.037],
+	[93.153, 29.025000000000002],
+	[93.162, 29.016000000000002],
+	[93.21300000000001, 29.025000000000002],
+	[93.22800000000001, 29.019000000000002],
+	[93.23100000000001, 29.001],
+	[93.261, 28.992],
+	[93.285, 29.001],
+	[93.312, 28.998],
+	[93.315, 29.016000000000002],
+	[93.348, 29.046],
+	[93.375, 29.052],
+	[93.393, 29.094],
+	[93.429, 29.109],
+	[93.447, 29.106],
+	[93.438, 29.13],
+	[93.48, 29.175],
+	[93.492, 29.163],
+	[93.54, 29.178],
+	[93.57000000000001, 29.166],
+	[93.627, 29.172],
+	[93.63, 29.151],
+	[93.645, 29.145],
+	[93.675, 29.151],
+	[93.681, 29.163],
+	[93.699, 29.16],
+	[93.702, 29.142],
+	[93.735, 29.127],
+	[93.75, 29.136],
+	[93.75, 29.148],
+	[93.78, 29.154],
+	[93.789, 29.124000000000002],
+	[93.825, 29.118000000000002],
+	[93.834, 29.124000000000002],
+	[93.831, 29.142],
+	[93.894, 29.13],
+	[93.912, 29.145],
+	[93.903, 29.166],
+	[93.909, 29.178],
+	[93.94500000000001, 29.184],
+	[93.95400000000001, 29.196],
+	[94.017, 29.193],
+	[94.035, 29.205000000000002],
+	[94.176, 29.196],
+	[94.251, 29.262],
+	[94.305, 29.271],
+	[94.302, 29.292],
+	[94.33200000000001, 29.316],
+	[94.35000000000001, 29.316],
+	[94.389, 29.337],
+	[94.401, 29.361],
+	[94.419, 29.37],
+	[94.434, 29.406000000000002],
+	[94.542, 29.448],
+	[94.581, 29.481],
+	[94.656, 29.490000000000002],
+	[94.70700000000001, 29.463],
+	[94.818, 29.493000000000002],
+	[94.875, 29.541],
+	[94.923, 29.61],
+	[94.926, 29.622],
+	[94.887, 29.634],
+	[94.917, 29.67],
+	[94.893, 29.697],
+	[94.905, 29.715],
+	[94.956, 29.757],
+	[95.124, 29.763],
+	[95.124, 29.781000000000002],
+	[95.09100000000001, 29.814],
+	[95.11200000000001, 29.868000000000002],
+	[95.13, 29.88],
+	[95.175, 29.895],
+	[95.196, 29.892],
+	[95.223, 29.868000000000002],
+	[95.286, 29.868000000000002],
+	[95.304, 29.856],
+	[95.307, 29.838],
+	[95.283, 29.82],
+	[95.289, 29.811],
+	[95.385, 29.772000000000002],
+	[95.379, 29.718],
+	[95.397, 29.688000000000002],
+	[95.388, 29.595],
+	[95.403, 29.562],
+	[95.427, 29.538],
+	[95.43900000000001, 29.478],
+	[95.43, 29.451],
+	[95.313, 29.331],
+	[95.256, 29.289],
+	[95.202, 29.28],
+	[95.04, 29.175],
+	[95.001, 29.169],
+	[95.004, 29.139],
+	[94.908, 29.052],
+	[94.902, 29.016000000000002],
+	[94.869, 28.998],
+	[94.839, 28.956],
+	[94.788, 28.935000000000002],
+	[94.773, 28.854],
+	[94.794, 28.824],
+	[94.914, 28.821],
+	[94.923, 28.812],
+	[94.911, 28.794],
+	[94.92, 28.752],
+	[94.977, 28.713],
+	[94.983, 28.674],
+	[94.998, 28.683],
+	[95.031, 28.617],
+	[95.09700000000001, 28.539],
+	[95.10300000000001, 28.506],
+	[95.09100000000001, 28.455000000000002],
+	[95.09700000000001, 28.419],
+	[95.013, 28.326],
+	[94.992, 28.287],
+	[94.992, 28.242],
+	[95.019, 28.215],
+	[95.031, 28.173000000000002],
+	[95.06700000000001, 28.155],
+	[95.145, 28.149],
+	[95.211, 28.179000000000002],
+	[95.277, 28.155],
+	[95.292, 28.116],
+	[95.316, 28.089000000000002],
+	[95.355, 28.071],
+	[95.379, 28.071],
+	[95.385, 28.059],
+	[95.382, 27.951],
+	[95.4, 27.936],
+	[95.412, 27.882],
+	[95.379, 27.843],
+	[95.349, 27.837],
+	[95.325, 27.810000000000002],
+	[95.325, 27.78],
+	[95.298, 27.762],
+	[95.289, 27.717000000000002],
+	[95.253, 27.657],
+	[95.211, 27.666],
+	[95.151, 27.624000000000002],
+	[95.139, 27.63],
+	[95.10300000000001, 27.609],
+	[94.992, 27.6],
+	[94.944, 27.57],
+	[94.917, 27.573],
+	[94.869, 27.504],
+	[94.803, 27.495],
+	[94.803, 27.48],
+	[94.785, 27.471],
+	[94.794, 27.456],
+	[94.767, 27.435000000000002],
+	[94.767, 27.414],
+	[94.73100000000001, 27.402],
+	[94.71900000000001, 27.372],
+	[94.69800000000001, 27.36],
+	[94.69800000000001, 27.333000000000002],
+	[94.683, 27.324],
+	[94.677, 27.294],
+	[94.635, 27.291],
+	[94.629, 27.273],
+	[94.602, 27.255],
+	[94.596, 27.231],
+	[94.584, 27.228],
+	[94.587, 27.177],
+	[94.596, 27.162],
+	[94.584, 27.147000000000002],
+	[94.566, 27.150000000000002],
+	[94.554, 27.102],
+	[94.518, 27.105],
+	[94.449, 27.060000000000002],
+	[94.44, 27.018],
+	[94.407, 26.985],
+	[94.35900000000001, 26.97],
+	[94.287, 26.919],
+	[94.197, 26.925],
+	[94.164, 26.898],
+	[94.146, 26.865000000000002],
+	[94.125, 26.856],
+	[94.113, 26.868000000000002],
+	[94.134, 26.907],
+	[94.113, 26.913],
+	[94.077, 26.886],
+	[93.927, 26.832],
+	[93.864, 26.766000000000002],
+	[93.753, 26.733],
+	[93.657, 26.715],
+	[93.618, 26.724],
+	[93.56700000000001, 26.751],
+	[93.441, 26.769000000000002],
+	[93.411, 26.76],
+	[93.369, 26.718],
+	[93.288, 26.742],
+	[93.249, 26.724],
+	[93.183, 26.673000000000002],
+	[93.12, 26.646],
+	[93.087, 26.655],
+	[93.018, 26.646],
+	[92.898, 26.655],
+	[92.883, 26.652],
+	[92.874, 26.625],
+	[92.83500000000001, 26.607],
+	[92.733, 26.613],
+	[92.676, 26.601],
+	[92.658, 26.592000000000002],
+	[92.616, 26.523],
+	[92.595, 26.517],
+	[92.508, 26.517],
+	[92.43, 26.535],
+	[92.391, 26.532],
+	[92.244, 26.472],
+	[92.229, 26.442],
+	[92.202, 26.454],
+	[92.172, 26.442],
+	[92.124, 26.403000000000002],
+	[92.06700000000001, 26.373],
+	[92.07000000000001, 26.325],
+	[92.058, 26.304000000000002],
+	[91.971, 26.271],
+	[91.932, 26.271],
+	[91.899, 26.241],
+	[91.878, 26.235],
+	[91.854, 26.241],
+	[91.665, 26.166],
+	[91.608, 26.172],
+	[91.542, 26.145],
+	[91.497, 26.139],
+	[91.377, 26.172],
+	[91.287, 26.166],
+	[91.197, 26.202],
+	[91.134, 26.214000000000002],
+	[91.062, 26.187],
+	[90.96300000000001, 26.175],
+	[90.888, 26.136],
+	[90.849, 26.13],
+	[90.807, 26.154],
+	[90.741, 26.163],
+	[90.681, 26.19],
+	[90.58200000000001, 26.205000000000002],
+	[90.507, 26.229],
+	[90.474, 26.226],
+	[90.435, 26.178],
+	[90.402, 26.16],
+	[90.345, 26.148],
+	[90.309, 26.124],
+	[90.22500000000001, 26.106],
+	[90.177, 26.076],
+	[89.955, 26.01],
+	[89.904, 25.941],
+	[89.84700000000001, 25.89],
+	[89.81400000000001, 25.815],
+	[89.736, 25.692],
+	[89.724, 25.632],
+	[89.697, 25.572],
+	[89.709, 25.482],
+	[89.697, 25.398],
+	[89.67, 25.323],
+	[89.7, 25.266000000000002],
+	[89.703, 25.242],
+	[89.685, 25.2],
+	[89.661, 25.173000000000002],
+	[89.625, 25.074],
+	[89.613, 24.96],
+	[89.613, 24.936],
+	[89.658, 24.87],
+	[89.673, 24.792],
+	[89.706, 24.75],
+	[89.769, 24.549],
+	[89.748, 24.372],
+	[89.754, 24.282],
+	[89.733, 24.225],
+	[89.742, 24.201],
+	[89.739, 24.123],
+	[89.697, 24.015],
+	[89.7, 23.958000000000002],
+	[89.727, 23.883],
+	[89.787, 23.796],
+	[89.85600000000001, 23.748],
+	[89.919, 23.664],
+	[89.985, 23.643],
+	[90.144, 23.544],
+	[90.249, 23.463]
+]

package/skills/remotion-best-practices/remotion-maps/techniques/maptiler/assets/tokens.ts

@@ -0,0 +1,34 @@
+// Example tokens only. Replace every visual value with production-local tokens.
+export const COLORS = {
+	bg: '#101315',
+	// Electric water — a near-white icy core with a blue glow and a white-hot draw-head (the "electricity"
+	// travels along the river as it draws on). No dark casing.
+	river: '#E8F7FF', // bright icy core
+	riverGlow: 'rgba(73,198,255,0.5)', // electric-blue glow
+	riverHead: '#FFFFFF', // white-hot leading head
+	riverHeadGlow: 'rgba(120,225,255,0.95)',
+	border: '#f5f2ed', // neutral cream country borders/labels over the colored fills
+	cream: '#f5f0eb',
+} as const;
+
+// Example progressive fill tokens. Rename these keys and replace values for each production.
+export const COUNTRY = {
+	china: '#D4A853',
+	india: '#5B8A8A',
+	bangladesh: '#C07B57',
+} as const;
+// Darker shade of each country colour — the settled border line (the bright COUNTRY colour is the
+// glowing draw-head that leads the animation).
+export const COUNTRY_DARK = {
+	china: '#9A7530',
+	india: '#3C5C5C',
+	bangladesh: '#855239',
+} as const;
+export const FILL_OPACITY = 0.5;
+
+export const VIDEO = {width: 1920, height: 1080, fps: 30} as const;
+
+// Beat durations (seconds → frames at VIDEO.fps)
+export const DUR = {
+	mapExplainer: 12 * VIDEO.fps,
+} as const;

package/skills/remotion-best-practices/remotion-maps/techniques/maptiler/references/map-data-sources.md

@@ -0,0 +1,91 @@
+# Map element data sources
+
+Choose the source independently for every story element. A single map can—and often should—mix
+provider vectors with custom geodata.
+
+## Decision rule
+
+Use a MapTiler Planet vector layer when the feature already exists there, its attributes support an
+editorially precise filter, and provider geometry is acceptable for the claim. Use custom GeoJSON when
+the feature is absent, proposed, historical, disputed, corrected, privately sourced, or needs ordered
+geometry for a deterministic draw.
+
+| Requirement                                                                 | MapTiler vector layer | Custom GeoJSON                              |
+| --------------------------------------------------------------------------- | --------------------- | ------------------------------------------- |
+| Roads, waterways, water, boundaries, land cover, or other standard context  | Prefer                | Use only when provider data is insufficient |
+| Basemap-consistent geometry without a duplicate local dataset               | Prefer                | No                                          |
+| Proposed, historical, classified, corrected, or production-specific element | No                    | Prefer                                      |
+| Fade, colour, width, radius, blur, or fill-opacity animation                | Yes                   | Yes                                         |
+| Feature-state highlight when a stable feature ID exists                     | Yes                   | Yes                                         |
+| Deterministic source-to-end line draw or perimeter draw                     | Bake first            | Prefer                                      |
+| Geometry editing, morphing, clipping, or exact sequencing                   | No                    | Prefer                                      |
+
+Provider alignment is not proof of correctness. Inspect the attributes and geometry against the
+editorial source before presenting a provider feature as evidence.
+
+## MapTiler vector mode
+
+MapTiler Planet is a vector tile source. Add it once, then build story layers with a
+`source-layer` and an exact attribute filter. Read the current MapTiler Planet schema before choosing
+layer names or fields.
+
+Common layer categories include `waterway`, `water`, `transportation`, `boundary`, `landcover`, and
+`poi`; availability, fields, and zoom ranges vary by schema version.
+
+```ts
+import {addMapTilerVectorElement, setVectorElementPaint} from "./MapTilerVectorElement";
+
+addMapTilerVectorElement(map, process.env.REMOTION_MAPTILER_KEY!, {
+  id: "story-river",
+  sourceLayer: "waterway",
+  type: "line",
+  filter: [
+    "all",
+    ["==", ["get", "class"], "river"],
+    ["==", ["coalesce", ["get", "name_en"], ["get", "name"]], "Yarlung Tsangpo"],
+  ],
+  layout: {"line-cap": "round", "line-join": "round"},
+  paint: {
+    "line-color": "#E8F7FF",
+    "line-width": 3,
+    "line-opacity": 0,
+  },
+});
+
+setVectorElementPaint(map, "story-river", {
+  "line-opacity": reveal,
+  "line-width": 2 + reveal * 2,
+});
+```
+
+Animate provider features by changing paint properties from the Remotion frame: opacity, colour,
+width, blur, fill opacity, circle radius, or symbol opacity. Use feature state only when the source
+provides stable IDs and the selection remains deterministic across tiles.
+
+Do not treat a tiled line as one ordered path. Vector tiles split features at tile boundaries, so a
+source-to-mouth or start-to-end draw has no reliable global order. If that motion carries meaning,
+extract and verify the complete feature, order it once, save it as GeoJSON, and use the custom mode.
+
+## Custom geodata mode
+
+Use the bundled `../assets/RiverReveal.tsx` and `../scripts/prep-geo.mjs` pattern for custom GeoJSON. This mode owns
+the exact geometry and can slice it by distance, calculate entry triggers, draw complete borders, and
+produce deterministic sequences.
+
+Custom mode is mandatory when:
+
+- the feature is not in the provider dataset;
+- the story uses a proposed route, planned tunnel, historical boundary, disputed interpretation, or
+  non-public dataset;
+- provider geometry was editorially corrected;
+- motion must travel through the geometry in a verified order;
+- a complete off-screen boundary matters and a viewport query would silently crop it.
+
+## Hybrid mode
+
+Use provider vectors for ordinary contextual features and custom GeoJSON for the specific claim. For
+example: MapTiler waterways and roads as aligned context; a custom proposed tunnel, dam site, disputed
+boundary, or verified evacuation area as the highlighted evidence.
+
+Keep provider and custom layers visually distinct when they carry different evidentiary weight. Record
+the source and effective date of every custom layer in the production notes.