chore: import upstream snapshot with attribution

skills/motion-graphics/categories/maps/bake-basemap.mjs

@@ -0,0 +1,273 @@
+// bake-basemap.mjs — canonical basemap-lane helper for the `maps` skill.
+//
+// WHAT IT DOES (and why baking at all): drives MapLibre in headless Chrome to record ONLY the
+// real-imagery basemap as an MP4 (camera zoom→hold), and projects each requested country's border
+// to SCREEN coordinates at the held view. The HF composition then plays the MP4 on track 0 and
+// animates a *live* SVG overlay (border draw-on, colour-block / flag fills, labels, pins) from the
+// exported `coords.json`. Borders/fills are NOT baked into the video — they stay editable in HF.
+//
+// Why bake the imagery at all (this is the real reason, not "smoothness"): HF forbids render-time
+// network and requires deterministic output. Live raster tiles re-fetch every render and can change
+// → non-deterministic. Baking FREEZES the imagery into pixels = deterministic + offline-reproducible.
+// (Exposing the engine's per-frame `onBeforeCapture` hook would let MapLibre run live and smooth, but
+// it would NOT remove the need to freeze tiles for determinism — so this bake step stays relevant.)
+//
+// PARAMETRIC — drive everything by env. Example (Brazil + Argentina on satellite):
+//   NAME=br-ar STYLE=satellite COUNTRIES="Brazil:#22d3ee,Argentina:#f59e0b" \
+//   CENTER="-60,-25" ZSTART=2.4 ZEND=3.4 FPS=30 DUR=5 node bake-basemap.mjs
+// Then encode frames-<NAME>/f%04d.png → <NAME>.mp4 (all-intra: -g 1) and feed <NAME>-coords.json
+// to the HF composition.
+import puppeteer from "puppeteer-core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { mkdirSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// --- resolve Chrome dynamically (no hardcoded machine path) ---
+function resolveChrome() {
+  if (process.env.CHROME && existsSync(process.env.CHROME)) return process.env.CHROME;
+  const exe = process.platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell";
+  const base = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
+  if (existsSync(base)) {
+    for (const v of readdirSync(base).sort().reverse()) {
+      // lexical sort; any working binary is fine
+      try {
+        for (const inner of readdirSync(join(base, v))) {
+          const bin = join(base, v, inner, exe);
+          if (existsSync(bin)) return bin;
+        }
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  for (const c of [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+  ])
+    if (existsSync(c)) return c;
+  throw new Error(
+    "Chrome not found. Set CHROME=/path/to/chrome-headless-shell, or install one:\n" +
+      "  npx puppeteer browsers install chrome-headless-shell",
+  );
+}
+
+// --- params (all overridable by env) ---
+const NAME = process.env.NAME || "basemap";
+const STYLE = process.env.STYLE || "satellite"; // satellite | dark | light | raw {z}/{x}/{y} template
+const CENTER = (process.env.CENTER || "2.6,46.6").split(",").map(Number);
+const ZSTART = +(process.env.ZSTART || 4.2);
+const ZEND = +(process.env.ZEND || 5.4);
+const PITCH = +(process.env.PITCH || 0);
+const BEARING = +(process.env.BEARING || 0);
+const FPS = +(process.env.FPS || 30),
+  DUR = +(process.env.DUR || 5),
+  N = Math.max(1, Math.round(FPS * DUR));
+const HOLD = +(process.env.HOLD || 0.5); // p∈[0,1] at which the zoom finishes; camera holds after
+const MARGIN = (process.env.KEEPMARGIN || "16,13").split(",").map(Number); // [lon°,lat°] keep-box around each country's mainland
+// COUNTRIES="Name:#hex,Name:#hex" — borders to project (optional; omit for a pure zoom-to / pin shot)
+const COUNTRIES = (process.env.COUNTRIES || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean)
+  .map((s) => {
+    const [name, color] = s.split(":");
+    return { name, color: color || "#38bdf8" };
+  });
+
+// fail fast on bad numeric env — otherwise NaN silently bakes zero/garbage frames and still prints "done"
+for (const [k, v] of Object.entries({
+  "CENTER.lng": CENTER[0],
+  "CENTER.lat": CENTER[1],
+  ZSTART,
+  ZEND,
+  PITCH,
+  BEARING,
+  FPS,
+  DUR,
+  HOLD,
+}))
+  if (!Number.isFinite(v))
+    throw new Error(
+      `bad numeric env: ${k}=${v} — check CENTER="lng,lat" / ZSTART / ZEND / FPS / DUR`,
+    );
+
+// IMPORTANT: tileSize:256 matches Esri/CARTO raster endpoints. MapLibre's INTERNAL world width is
+// 512·2^zoom regardless — a 512px (@2x/retina/vector) tile source needs tileSize:512 or every zoom
+// level is off by one. Keep 256 for these raster sources.
+const TILES =
+  {
+    satellite:
+      "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
+    dark: "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
+    light: "https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
+  }[STYLE] || STYLE; // STYLE may also be a raw {z}/{x}/{y} template
+
+const OUT = process.env.OUT || process.cwd(); // artifacts → workspace (cwd), NOT the installed skill dir
+const framesDir = join(OUT, "frames-" + NAME);
+mkdirSync(framesDir, { recursive: true });
+
+// Deps PINNED exact (mutable @5/@2 majors would drift the bake over time).
+const PAGE = `<!doctype html><html><head>
+<link href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/topojson-client@3.1.0/dist/topojson-client.min.js"></script>
+<style>*{margin:0}html,body{width:1920px;height:1080px;overflow:hidden;background:#05070d}#map{width:1920px;height:1080px}.maplibregl-control-container{display:none!important}</style>
+</head><body><div id="map"></div><script>
+var CENTER=${JSON.stringify(CENTER)}, ZSTART=${ZSTART}, ZEND=${ZEND}, PITCH=${PITCH}, BEARING=${BEARING}, HOLD=${HOLD};
+var MARGIN=${JSON.stringify(MARGIN)}, WANT=${JSON.stringify(COUNTRIES)};
+var map=new maplibregl.Map({container:"map",style:{version:8,projection:{type:"mercator"},
+  sources:{s:{type:"raster",tiles:[${JSON.stringify(TILES)}],tileSize:256,maxzoom:19}},
+  layers:[{id:"bg",type:"background",paint:{"background-color":"#05070d"}},{id:"s",type:"raster",source:"s"}]},
+  center:CENTER,zoom:ZSTART,pitch:0,bearing:0,interactive:false,attributionControl:false,fadeDuration:0,preserveDrawingBuffer:true,maxTileCacheSize:6000});
+function ease(x){return x<0.5?4*x*x*x:1-Math.pow(-2*x+2,3)/2;} // easeInOutCubic (= Remotion interpolate+Easing)
+function camAt(p){ var t=ease(Math.min(1,p/HOLD)); return {center:CENTER, zoom:ZSTART+(ZEND-ZSTART)*t, pitch:PITCH*t, bearing:BEARING*t}; }
+function ringCentroid(r){ var sx=0,sy=0; for(var k=0;k<r.length;k++){sx+=r[k][0];sy+=r[k][1];} return [sx/r.length, sy/r.length]; }
+// Keep the polygons in a lon/lat box around the country's MAINLAND (the vertex-richest polygon),
+// dropping far-flung overseas territories that would blow up the bbox. Generalizes per subject —
+// no continent-specific constant. Keeps near islands (Corsica, Sicily); drops Guiana, Alaska, Hawaii.
+function mainland(f){
+  if(!f) return f;
+  if(f.geometry.type!=="MultiPolygon"){ f.__anchorRing=f.geometry.coordinates[0]; return f; } // Polygon: outer ring
+  var polys=f.geometry.coordinates, anchor=polys[0], amax=-1;
+  polys.forEach(function(poly){ if(poly[0].length>amax){amax=poly[0].length;anchor=poly;} });
+  var ac=ringCentroid(anchor[0]);
+  var kept=polys.filter(function(poly){ var c=ringCentroid(poly[0]); return Math.abs(c[0]-ac[0])<=MARGIN[0] && Math.abs(c[1]-ac[1])<=MARGIN[1]; });
+  var nf={type:"Feature",properties:f.properties,geometry:{type:"MultiPolygon",coordinates:kept}}; nf.__anchorRing=anchor[0]; return nf;
+}
+function lonSpan(f){ var mn=1e9,mx=-1e9; (f.geometry.type==="Polygon"?[f.geometry.coordinates]:f.geometry.coordinates).forEach(function(poly){poly[0].forEach(function(c){if(c[0]<mn)mn=c[0];if(c[0]>mx)mx=c[0];});}); return mx-mn; }
+// ANTIMERIDIAN unwrap (Russia/Fiji/NZ): make all lon contiguous around the camera-center ref so a
+// feature touching ±180° doesn't smear when map.project() runs per-vertex (mercatorX is linear and
+// accepts out-of-range lon, so 181 sits just east of center, not far-west at -179). Mutates in place;
+// __anchorRing shares the same arrays so it's covered.
+function unwrapLon(f, ref){ if(!f) return; function fix(r){ for(var i=0;i<r.length;i++){ var lon=r[i][0]; while(lon-ref>180)lon-=360; while(lon-ref<-180)lon+=360; r[i][0]=lon; } }
+  var g=f.geometry; if(g.type==="Polygon") g.coordinates.forEach(fix); else g.coordinates.forEach(function(poly){ poly.forEach(fix); }); }
+var FEATS=[]; window.__warn=[];
+window.__ready=new Promise(function(res){ map.on("load", function(){
+  if(!WANT.length){ res(); return; }
+  fetch("https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json").then(function(r){return r.json();}).then(function(w){
+    var fc=topojson.feature(w,w.objects.countries);
+    WANT.forEach(function(want){
+      var f=fc.features.filter(function(x){return x.properties.name===want.name;})[0];
+      if(!f){ window.__warn.push("country not found in world-atlas: "+want.name); return; }
+      f=mainland(f);
+      unwrapLon(f, CENTER[0]); // antimeridian: unwrap lons around the camera ref (CENTER must be near the subject) before projecting
+      if(lonSpan(f)>180) window.__warn.push(want.name+" spans >180° lon even after unwrap — projection may still smear.");
+      FEATS.push({name:want.name, color:want.color, f:f});
+    });
+    res();
+  });
+});});
+window.__setCam=function(p){ map.jumpTo(camAt(p)); };
+// returns true if the idle event did NOT fire within ms (i.e. tiles may be incomplete)
+// returns true only if tiles are GENUINELY not loaded at timeout — CARTO/Esri idle is flaky and
+// often never fires even when every tile is painted, so check areTilesLoaded() before crying timeout.
+window.__waitIdle=function(ms){ return new Promise(function(res){ var done=false; function fin(t){if(done)return;done=true;res(t);} map.once("idle",function(){fin(false);}); setTimeout(function(){ fin(!map.areTilesLoaded()); }, ms||9000); }); };
+function featurePath(f){ function ring(r){ return r.map(function(c,i){ var p=map.project(c); return (i?"L":"M")+p.x.toFixed(1)+" "+p.y.toFixed(1); }).join(" ")+"Z"; }
+  var g=f.geometry,d=""; if(g.type==="Polygon") g.coordinates.forEach(function(r){d+=ring(r);}); else g.coordinates.forEach(function(poly){poly.forEach(function(r){d+=ring(r);});}); return d; }
+function bboxOf(f){ var mnx=1e9,mny=1e9,mxx=-1e9,mxy=-1e9;
+  function eat(r){ r.forEach(function(c){ var p=map.project(c); if(p.x<mnx)mnx=p.x; if(p.y<mny)mny=p.y; if(p.x>mxx)mxx=p.x; if(p.y>mxy)mxy=p.y; }); }
+  var g=f.geometry; if(g.type==="Polygon")g.coordinates.forEach(eat); else g.coordinates.forEach(function(poly){poly.forEach(eat);});
+  return {x:+mnx.toFixed(1),y:+mny.toFixed(1),w:+(mxx-mnx).toFixed(1),h:+(mxy-mny).toFixed(1)}; }
+window.__project=function(){ return {
+  view:{center:CENTER, zoom:ZEND, pitch:PITCH, bearing:BEARING},
+  countries: FEATS.map(function(e){ var lc=ringCentroid(e.f.__anchorRing); var lp=map.project(lc);
+    return { name:e.name, color:e.color, d:featurePath(e.f), bbox:bboxOf(e.f), label:{x:+lp.x.toFixed(1),y:+lp.y.toFixed(1)} }; }),
+}; };
+</script></body></html>`;
+
+// --no-sandbox is intentional: trusted Source-time bake, headless, often root/CI; deps are version-pinned above.
+const browser = await puppeteer.launch({
+  executablePath: resolveChrome(),
+  headless: true,
+  args: [
+    "--no-sandbox",
+    "--hide-scrollbars",
+    "--use-gl=angle",
+    "--use-angle=swiftshader",
+    "--enable-unsafe-swiftshader",
+    "--enable-webgl",
+    "--window-size=1920,1080",
+  ],
+});
+try {
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1920, height: 1080, deviceScaleFactor: 1 });
+  await page.setContent(PAGE, { waitUntil: "load" });
+  await page.evaluate(() => window.__ready);
+  for (const w of await page.evaluate(() => window.__warn)) console.warn(`[${NAME}] WARN: ${w}`);
+  console.log(
+    `[${NAME}] ready (${STYLE}); baking ${N} frames, zoom ${ZSTART}→${ZEND} hold@p=${HOLD}, ${COUNTRIES.length} border(s)`,
+  );
+  let coords = null;
+  const timeouts = [];
+  for (let i = 0; i < N; i++) {
+    const p = N === 1 ? 1 : i / (N - 1);
+    await page.evaluate((pp) => window.__setCam(pp), p);
+    const timedOut = await page.evaluate((ms) => window.__waitIdle(ms), 9000);
+    if (timedOut) {
+      timeouts.push(i);
+      console.warn(`[${NAME}] idle TIMEOUT at frame ${i} — tiles may be incomplete`);
+    }
+    await page.screenshot({
+      path: join(framesDir, `f${String(i).padStart(4, "0")}.png`),
+      clip: { x: 0, y: 0, width: 1920, height: 1080 },
+      optimizeForSpeed: true,
+    });
+    if (p >= HOLD && !coords && COUNTRIES.length)
+      coords = await page.evaluate(() => window.__project()); // capture at first hold frame
+    if (i % 20 === 0 || i === N - 1) console.log(`  [${NAME}] ${i + 1}/${N}`);
+  }
+  // encode frames → all-intra MP4 (every frame seekable for HF); fall back to printing the command if ffmpeg is absent
+  const mp4 = join(OUT, NAME + ".mp4"),
+    pat = join(framesDir, "f%04d.png");
+  const ff = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-framerate",
+      String(FPS),
+      "-i",
+      pat,
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-g",
+      "1",
+      "-crf",
+      "16",
+      "-movflags",
+      "+faststart",
+      mp4,
+    ],
+    { stdio: "ignore" },
+  );
+  if (ff.status === 0) console.log(`[${NAME}] encoded → ${mp4}`);
+  else
+    console.warn(
+      `[${NAME}] ffmpeg unavailable (status ${ff.status}) — encode manually:\n  ffmpeg -y -framerate ${FPS} -i ${pat} -c:v libx264 -pix_fmt yuv420p -g 1 -crf 16 -movflags +faststart ${mp4}`,
+    );
+  if (coords) {
+    writeFileSync(join(OUT, NAME + "-coords.json"), JSON.stringify(coords));
+    console.log(
+      `[${NAME}] coords written: ${coords.countries.map((c) => c.name + "(" + c.d.length + "ch)").join(", ")}`,
+    );
+  }
+  if (timeouts.length) {
+    // FAIL LOUD: the asset exists but is suspect — don't let a half-loaded bake pass silently
+    console.error(
+      `[${NAME}] ${timeouts.length}/${N} frame(s) hit the idle timeout (frames ${timeouts.slice(0, 8).join(",")}${timeouts.length > 8 ? "…" : ""}). The basemap MP4 may have INCOMPLETE tiles. Re-run with a slower zoom / larger timeout / check the tile server.`,
+    );
+    process.exitCode = 1;
+  } else {
+    console.log(`[${NAME}] done — all ${N} frames reached map idle (complete tiles).`);
+  }
+} finally {
+  await browser.close();
+}

skills/motion-graphics/categories/maps/module.md

@@ -0,0 +1,61 @@
+# maps — category module
+
+Geographic motion: highlight regions, connect places, zoom to a location. **First decision: does the shot need a real basemap** (satellite/street/terrain imagery, globe, or zoom to a real address)? That picks the lane.
+
+## Plan (Director)
+
+Set `content.lane` first:
+
+- **vector** (default) — stylized region shapes, no real imagery. Native + live in HF, cheap. `asset_needs: []`.
+- **basemap** — needs real satellite/dark tiles, globe, or zoom-to-real-place. `asset_needs: [{ type: "map-bake", … }]`. **Bake the imagery in Source**: HF forbids render-time network and requires determinism, so live tiles (which re-fetch and can change per render) can't be the imagery layer — baking freezes it (and is smooth as a bonus). See Basemap lane + Determinism.
+
+`content`: `{ lane, shot: highlight|flow|choropleth|labels|flag|pin-rollout|zoom-to, regions[], points[], basemap: satellite|dark, palette, headline, overlays: [label|pin|callout-card] }`.
+
+`overlays` are independent of `shot` and work in both lanes. **`callout-card`** = a pinned card (flag chip + stat + progress bar) — this is the "documentary popup" (top #13); compose it on any zoom-to/highlight shot rather than treating it as its own shot.
+
+## Vocabulary / leans on
+
+**Vector lane** (D3 + TopoJSON — reuse the existing map family, don't duplicate):
+
+- Reuse: `us-map` (+bubble/hex/flow), `world-map`, `spain-map`.
+- **Hand-author** these (NOT in the catalog — build per the signatures below, don't expect an `add`): `geo-highlight` (N countries colored + labels + border pulse), `geo-flow` (world arcs / hub network), `flag-borders` (flag clipped to a country), `pin-rollout` (cities pulse in sequence + counter).
+- Signature: country fill-in stagger · pin drop + pulse ring · arc `stroke-dashoffset` draw-on + flyer · choropleth color reveal · **viewBox** zoom.
+
+**Basemap lane** (MapLibre, baked in Source — validated pipeline, `bake-basemap.mjs`, fully env-parametric — runs for any country, not just the prototypes):
+
+- **Bake** `bake-basemap.mjs` (puppeteer + MapLibre; env-driven: `NAME STYLE COUNTRIES CENTER ZSTART ZEND PITCH BEARING FPS DUR`): drive the camera **zoom→hold** (`easeInOutCubic`) and **`await map.once('idle')` before every frame** so each frame has complete tiles (Remotion `delayRender` technique → no tile pop). The helper resolves Chrome itself, pins deps exactly, derives the overseas-territory filter per subject, and **fails loud on idle-timeout** (suspect frames → non-zero exit). _External deps: the pinned CDN libs (maplibre/topojson/world-atlas) + the Esri/CARTO tile endpoints are third-party — re-verify availability + ToS on any version bump._ `preserveDrawingBuffer:true`, `fadeDuration:0`. The helper then **encodes the frames to an all-intra MP4 itself** (`ffmpeg -framerate FPS -i f%04d.png -c:v libx264 -g 1 -pix_fmt yuv420p`) and writes everything to **`$OUT` (default `cwd`)**, not the skill dir → `<NAME>.mp4` + `<NAME>-coords.json`.
+- **Export geo→screen** at the hold view: `map.project()` each requested country → `<NAME>-coords.json` = `{ view, countries: [{ name, color, d (SVG path), bbox, label }] }`. The camera holds static after the zoom, so these paths stay pixel-aligned. `label` is an **approximate** anchor (vertex-average of the mainland ring — for concave countries nudge per Legibility). Consume `coords.countries[i]`; the `smooth-frde2`/`smooth-flag` example dirs predate this helper and use a flat `{fr,de,…}` shape, so adapt their wiring.
+- **Builder**: `<video>` basemap on track 0 + an **SVG overlay** that, during the hold, animates country **borders (`stroke-dashoffset` draw-on)** + **fills (colour-block reveal)** + labels/pins/cards — all geo-aligned via `coords.json`. This reproduces the Hera "satellite + animated coloured borders/callouts" look.
+  - The same projected path also doubles as an SVG **`clipPath`**: clip a **flag (or any texture) into the real border** for _flag-in-borders_ — a richer fill than flat colour, over real map context (validated: France tricolor over a dark basemap, `smooth-flag`). Export the feature's screen **bbox** alongside its path so the flag stripes/texture can be sized to the country.
+- **Stretch / data gaps** (extend `bake-basemap.mjs` as needed — the eval agents did): a **globe intro** ("start from the globe") = MapLibre `projection:{type:'globe'}` for the opening phase, easing to mercator at the target (the helper defaults to mercator). **Sub-national** regions (states/provinces) aren't in world-atlas (country-only) → use a Natural Earth **admin-1** TopoJSON, or project centroids as pins (`pin-rollout`).
+
+## Build (reuse-first)
+
+Vector: `npx hyperframes add <block>` → edit regions/data/palette in place. Basemap: baked `map.mp4` as track-0 `<video>`, bind overlays to anchors.
+
+**Restraint (no cheese — this is the #1 way auto-built maps go wrong):** every animated element must serve the message — region, connector, label, pin, camera. **NO decorative ambient glows, background light blobs, floating particles, lens flares, or gratuitous bloom.** Motion = a continuous camera move (viewBox push/zoom) + purposeful, overlapping element reveals — not a light show. Palette: color must **carry meaning** — a data scale (choropleth), categorical fills that distinguish regions (political map), or 1–2 accents for the subjects (highlighted countries / route) over neutral everything-else. Don't add color as **decoration** (a country amber just for contrast, a glow for "energy"). The frame should read like a clean broadcast map, not a screensaver.
+
+**Legibility (hard rule):** offset labels from the highlighted shape and from each other; clamp to the safe area; a callout pill must not sit on another label or a border (the eval surfaced a DE/PL "Oder–Neisse" pill overlapping the POLAND label). A key element stays readable ≥~0.3s.
+
+**Attribution (hard rule):** real basemap imagery carries usage terms — bake a credit element into the composition whenever a basemap is on screen (Esri satellite → "Esri, Maxar, Earthstar Geographics"; CARTO → "© CARTO, © OpenStreetMap"). A small low-corner label (see `smooth-jp`). Non-negotiable for anything published.
+
+**Determinism (hard rules — each one bit us in the prototypes):**
+
+- Drive everything from the seek clock; **never `tl.call`** for stateful updates (counters, text) → proxy tween + `onUpdate` (tl.call freezes the timeline under HF seek).
+- SVG zoom = animate **viewBox** (don't hand-compute group transform origins).
+- Centered overlays (cards/labels using `transform: translate(-50%,…)` to center): animate **opacity only**, or wrap in an outer centered div — GSAP animating `y`/`scale` overwrites the whole transform and kills the centering.
+- Country geometry: filter to the polygon(s) **in a lon/lat box around the subject** — world-atlas bundles overseas territories that blow up the bbox (France + Guiana). Keep near islands (Corsica, Sicily), drop far ones. (`bake-basemap.mjs` anchors on the vertex-richest polygon ± `KEEPMARGIN` — no continent-specific constant.)
+- **Tile world-scale**: MapLibre's internal world width is `512·2^zoom` regardless of the raster `tileSize`. Esri/CARTO raster → `tileSize:256` (correct); a 512px / @2x / retina / vector source needs `tileSize:512` or every zoom level is off by one (this silently over-zoomed a bake once — France overflowed the frame top-to-bottom).
+- **Antimeridian**: a feature crossing ±180° (Russia, Fiji, NZ) smears under per-vertex `map.project()`. `bake-basemap.mjs` **unwraps longitudes around the camera-center ref** before projecting, which handles it; it still warns if a feature spans >180° even after unwrap.
+- **Smoothness = per-frame complete tiles + eased camera.** In the bake, `await map.once('idle')` before each screenshot (= Remotion `delayRender`) and ease the camera with `easeInOutCubic` (= interpolate+Easing). `preserveDrawingBuffer:true`, `fadeDuration:0`, large `maxTileCacheSize`.
+- **Overlay alignment**: project feature borders at a **held** camera and only animate the overlay during the hold — a moving camera + a fixed projected path drift apart.
+- **Pre-hold hidden state**: an overlay revealed _at_ the hold must be `gsap.set` to its hidden state at build time (`scaleX:0`, full `stroke-dashoffset`, `opacity:0`) — a bare `fromTo` does **not** apply its "from" until the tween starts, so the element otherwise shows at its natural (visible, mispositioned) state during the zoom-in.
+- **Why bake at all** (the real reason — not just smoothness): baking freezes the imagery into **deterministic** pixels. Live raster tiles re-fetch every render and can change, and render-time network is forbidden. MapLibre _does_ render live in HF (just janky: tiles pop, deep zooms outrun loading); exposing the engine's per-frame `onBeforeCapture` hook (it exists — `frameCapture.ts:~1250`) would make live **smooth** — but it would **not** remove the need to freeze tiles for **determinism + offline reproducibility**. So `onBeforeCapture` would replace the _smoothness_ role of baking, not the _freeze_ role.
+
+## Out of scope
+
+3D photorealistic landmarks (Cesium territory) · per-country / per-template blocks (parametrize instead) · charts (→ `charts`). (In-engine _live_ MapLibre is possible but janky today — bake instead; revisit if the engine gains a per-frame ready hook.)
+
+## Register
+
+`director.md` classifier line (the lane fork) + `catalog-map.md` `maps/geo` row (add the basemap lane). Phase pipeline untouched.