From dba158dfc163df7d49be988945602ff8f7fa8b55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sun, 17 May 2026 23:16:41 -0400
Subject: [PATCH] feat(registry): add maps section with 4 new map blocks + docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New blocks: world-map (D3 Natural Earth choropleth), us-map-bubble
(proportional city markers), us-map-hex (hexagonal tile grid),
us-map-flow (animated connection arcs between cities).

All blocks share the same dark theme and are composable — layer
bubble or flow on top of the choropleth via track indexes.

Adds "Maps" section to the catalog docs with MDX pages for all 5
map blocks (including the us-map from the previous commit).
---
 docs/catalog/blocks/us-map-bubble.mdx         |  44 ++
 docs/catalog/blocks/us-map-flow.mdx           |  44 ++
 docs/catalog/blocks/us-map-hex.mdx            |  44 ++
 docs/catalog/blocks/us-map.mdx                |  53 ++
 docs/catalog/blocks/world-map.mdx             |  44 ++
 docs/docs.json                                |  10 +
 .../blocks/us-map-bubble/registry-item.json   |  20 +
 .../blocks/us-map-bubble/us-map-bubble.html   | 477 +++++++++++++++
 .../blocks/us-map-flow/registry-item.json     |  17 +
 registry/blocks/us-map-flow/us-map-flow.html  | 429 ++++++++++++++
 registry/blocks/us-map-hex/registry-item.json |  17 +
 registry/blocks/us-map-hex/us-map-hex.html    | 559 ++++++++++++++++++
 registry/blocks/world-map/registry-item.json  |  17 +
 registry/blocks/world-map/world-map.html      | 443 ++++++++++++++
 registry/registry.json                        |  16 +
 15 files changed, 2234 insertions(+)
 create mode 100644 docs/catalog/blocks/us-map-bubble.mdx
 create mode 100644 docs/catalog/blocks/us-map-flow.mdx
 create mode 100644 docs/catalog/blocks/us-map-hex.mdx
 create mode 100644 docs/catalog/blocks/us-map.mdx
 create mode 100644 docs/catalog/blocks/world-map.mdx
 create mode 100644 registry/blocks/us-map-bubble/registry-item.json
 create mode 100644 registry/blocks/us-map-bubble/us-map-bubble.html
 create mode 100644 registry/blocks/us-map-flow/registry-item.json
 create mode 100644 registry/blocks/us-map-flow/us-map-flow.html
 create mode 100644 registry/blocks/us-map-hex/registry-item.json
 create mode 100644 registry/blocks/us-map-hex/us-map-hex.html
 create mode 100644 registry/blocks/world-map/registry-item.json
 create mode 100644 registry/blocks/world-map/world-map.html

diff --git a/docs/catalog/blocks/us-map-bubble.mdx b/docs/catalog/blocks/us-map-bubble.mdx
new file mode 100644
index 000000000..39d36c715
--- /dev/null
+++ b/docs/catalog/blocks/us-map-bubble.mdx
@@ -0,0 +1,44 @@
+---
+title: "US Bubble Map"
+description: "Animated US bubble map with proportional city markers, value callouts, and connection lines"
+---
+
+# US Bubble Map
+
+Animated US bubble map with proportional city markers, value callouts, and connection lines — composable with `us-map` for layered data visualizations.
+
+`data` `map` `geography` `usa` `bubble` `cities`
+
+<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-bubble.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-bubble.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add us-map-bubble
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 12s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `us-map-bubble.html` | `compositions/us-map-bubble.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="us-map-bubble" data-composition-src="compositions/us-map-bubble.html" data-start="0" data-duration="12" data-track-index="1" data-width="1920" data-height="1080"></div>
+```
diff --git a/docs/catalog/blocks/us-map-flow.mdx b/docs/catalog/blocks/us-map-flow.mdx
new file mode 100644
index 000000000..56d3db42b
--- /dev/null
+++ b/docs/catalog/blocks/us-map-flow.mdx
@@ -0,0 +1,44 @@
+---
+title: "US Flow Map"
+description: "Animated connection arcs between US cities over a base map — composable origin-destination flow visualization"
+---
+
+# US Flow Map
+
+Animated connection arcs between US cities over a base map — composable origin-destination flow visualization with traveling particles and GSAP-drawn Bezier arcs.
+
+`data` `map` `geography` `usa` `flow` `connections` `arcs`
+
+<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-flow.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-flow.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add us-map-flow
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 12s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `us-map-flow.html` | `compositions/us-map-flow.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="us-map-flow" data-composition-src="compositions/us-map-flow.html" data-start="0" data-duration="12" data-track-index="1" data-width="1920" data-height="1080"></div>
+```
diff --git a/docs/catalog/blocks/us-map-hex.mdx b/docs/catalog/blocks/us-map-hex.mdx
new file mode 100644
index 000000000..8a1b2aed1
--- /dev/null
+++ b/docs/catalog/blocks/us-map-hex.mdx
@@ -0,0 +1,44 @@
+---
+title: "US Hex Grid Map"
+description: "Animated hexagonal tile grid map — each state as an equal-weight hex with data fill and abbreviation label"
+---
+
+# US Hex Grid Map
+
+Animated hexagonal tile grid map — each state as an equal-weight hex with data fill and abbreviation label. No external dependencies beyond GSAP.
+
+`data` `map` `geography` `usa` `hexgrid` `tilegrid`
+
+<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-hex.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-hex.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add us-map-hex
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 10s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `us-map-hex.html` | `compositions/us-map-hex.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="us-map-hex" data-composition-src="compositions/us-map-hex.html" data-start="0" data-duration="10" data-track-index="1" data-width="1920" data-height="1080"></div>
+```
diff --git a/docs/catalog/blocks/us-map.mdx b/docs/catalog/blocks/us-map.mdx
new file mode 100644
index 000000000..62f6fd53e
--- /dev/null
+++ b/docs/catalog/blocks/us-map.mdx
@@ -0,0 +1,53 @@
+---
+title: "US Map"
+description: "Animated US choropleth map with staggered state reveals, value labels, and gradient legend"
+---
+
+# US Map
+
+Animated US choropleth map with staggered state reveals, value labels, and gradient legend — D3 geoAlbersUsa projection with GSAP timeline.
+
+`data` `map` `geography` `usa` `choropleth`
+
+<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add us-map
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 12s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `us-map.html` | `compositions/us-map.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="us-map" data-composition-src="compositions/us-map.html" data-start="0" data-duration="12" data-track-index="1" data-width="1920" data-height="1080"></div>
+```
+
+## Composability
+
+Layer `us-map-bubble` or `us-map-flow` on top of this block as a higher track index to combine choropleth + bubble or flow visualizations:
+
+```html
+<div data-composition-id="us-map" data-composition-src="compositions/us-map.html" data-start="0" data-duration="12" data-track-index="1" data-width="1920" data-height="1080"></div>
+<div data-composition-id="us-map-bubble" data-composition-src="compositions/us-map-bubble.html" data-start="0" data-duration="12" data-track-index="2" data-width="1920" data-height="1080"></div>
+```
diff --git a/docs/catalog/blocks/world-map.mdx b/docs/catalog/blocks/world-map.mdx
new file mode 100644
index 000000000..957cf817a
--- /dev/null
+++ b/docs/catalog/blocks/world-map.mdx
@@ -0,0 +1,44 @@
+---
+title: "World Map"
+description: "Animated world choropleth with country-by-country reveal — D3 Natural Earth projection"
+---
+
+# World Map
+
+Animated world choropleth with country-by-country reveal, gradient legend, and highlight pulses on top GDP countries — D3 Natural Earth projection with GSAP timeline.
+
+`data` `map` `geography` `world` `choropleth`
+
+<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/world-map.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/world-map.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add world-map
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 14s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `world-map.html` | `compositions/world-map.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="world-map" data-composition-src="compositions/world-map.html" data-start="0" data-duration="14" data-track-index="1" data-width="1920" data-height="1080"></div>
+```
diff --git a/docs/docs.json b/docs/docs.json
index 563b51b3d..f71db04b8 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -188,6 +188,16 @@
               "catalog/blocks/vpn-youtube-spot"
             ]
           },
+          {
+            "group": "Maps",
+            "pages": [
+              "catalog/blocks/us-map",
+              "catalog/blocks/us-map-bubble",
+              "catalog/blocks/us-map-hex",
+              "catalog/blocks/us-map-flow",
+              "catalog/blocks/world-map"
+            ]
+          },
           {
             "group": "Data",
             "pages": [
diff --git a/registry/blocks/us-map-bubble/registry-item.json b/registry/blocks/us-map-bubble/registry-item.json
new file mode 100644
index 000000000..0fd5c14bc
--- /dev/null
+++ b/registry/blocks/us-map-bubble/registry-item.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "us-map-bubble",
+  "type": "hyperframes:block",
+  "title": "US Bubble Map",
+  "description": "Animated US bubble map with proportional city markers, value callouts, and connection lines — composable with us-map",
+  "tags": ["data", "map", "geography", "usa", "bubble", "cities"],
+  "dimensions": {
+    "width": 1920,
+    "height": 1080
+  },
+  "duration": 12,
+  "files": [
+    {
+      "path": "us-map-bubble.html",
+      "target": "compositions/us-map-bubble.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/us-map-bubble/us-map-bubble.html b/registry/blocks/us-map-bubble/us-map-bubble.html
new file mode 100644
index 000000000..943269a94
--- /dev/null
+++ b/registry/blocks/us-map-bubble/us-map-bubble.html
@@ -0,0 +1,477 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>US Bubble Map</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/topojson-client@3.1.0/dist/topojson-client.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background-color: #0f172a;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="us-map-bubble"
+      data-composition-id="us-map-bubble"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="12"
+    >
+      <div class="map-container">
+        <div class="header">
+          <h1 class="headline">Top 20 US Cities by Population</h1>
+          <p class="subtitle">Proportional bubble markers by metropolitan population</p>
+        </div>
+
+        <svg class="map-svg" viewBox="0 0 1400 820" preserveAspectRatio="xMidYMid meet">
+          <g class="states-group"></g>
+          <g class="connections-group"></g>
+          <g class="bubbles-group"></g>
+          <g class="callouts-group"></g>
+        </svg>
+
+        <div class="source">Source: U.S. Census Bureau, 2024</div>
+      </div>
+
+      <style>
+        #us-map-bubble {
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(145deg, #0f172a 0%, #1e293b 100%);
+          font-family: "Inter", sans-serif;
+          color: #e2e8f0;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          overflow: hidden;
+        }
+
+        #us-map-bubble .map-container {
+          width: 1700px;
+          height: 950px;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          position: relative;
+        }
+
+        #us-map-bubble .header {
+          text-align: center;
+          margin-bottom: 20px;
+        }
+
+        #us-map-bubble .headline {
+          font-size: 52px;
+          font-weight: 700;
+          letter-spacing: -0.02em;
+          color: #f8fafc;
+          clip-path: inset(0 100% 0 0);
+        }
+
+        #us-map-bubble .subtitle {
+          font-size: 20px;
+          font-weight: 300;
+          color: #94a3b8;
+          margin-top: 8px;
+          opacity: 0;
+        }
+
+        #us-map-bubble .map-svg {
+          width: 1500px;
+          height: 750px;
+          overflow: visible;
+        }
+
+        #us-map-bubble .state-path {
+          fill: #1e293b;
+          stroke: #334155;
+          stroke-width: 0.5;
+          opacity: 0;
+        }
+
+        #us-map-bubble .city-bubble {
+          fill: rgba(59, 130, 246, 0.6);
+          stroke: #ffffff;
+          stroke-width: 1;
+          transform-origin: center center;
+          transform: scale(0);
+        }
+
+        #us-map-bubble .city-pulse {
+          fill: none;
+          stroke: rgba(59, 130, 246, 0.4);
+          stroke-width: 2;
+          opacity: 0;
+        }
+
+        #us-map-bubble .callout-group {
+          opacity: 0;
+        }
+
+        #us-map-bubble .callout-line {
+          stroke: rgba(148, 163, 184, 0.5);
+          stroke-width: 1;
+          fill: none;
+        }
+
+        #us-map-bubble .callout-name {
+          font-size: 13px;
+          font-weight: 600;
+          fill: #f8fafc;
+        }
+
+        #us-map-bubble .callout-value {
+          font-size: 11px;
+          font-weight: 400;
+          fill: #94a3b8;
+        }
+
+        #us-map-bubble .connection-line {
+          stroke: rgba(59, 130, 246, 0.3);
+          stroke-width: 1;
+          fill: none;
+          stroke-dasharray: 6 4;
+        }
+
+        #us-map-bubble .source {
+          position: absolute;
+          bottom: 0;
+          right: 40px;
+          font-size: 12px;
+          color: #475569;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          var US_TOPO_URL = "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json";
+
+          var cities = [
+            { name: "New York", lat: 40.7128, lon: -74.006, pop: 8300000 },
+            { name: "Los Angeles", lat: 34.0522, lon: -118.2437, pop: 3900000 },
+            { name: "Chicago", lat: 41.8781, lon: -87.6298, pop: 2700000 },
+            { name: "Houston", lat: 29.7604, lon: -95.3698, pop: 2300000 },
+            { name: "Phoenix", lat: 33.4484, lon: -112.074, pop: 1600000 },
+            { name: "Philadelphia", lat: 39.9526, lon: -75.1652, pop: 1600000 },
+            { name: "San Antonio", lat: 29.4241, lon: -98.4936, pop: 1400000 },
+            { name: "San Diego", lat: 32.7157, lon: -117.1611, pop: 1400000 },
+            { name: "Dallas", lat: 32.7767, lon: -96.797, pop: 1300000 },
+            { name: "Jacksonville", lat: 30.3322, lon: -81.6557, pop: 950000 },
+            { name: "Austin", lat: 30.2672, lon: -97.7431, pop: 960000 },
+            { name: "San Jose", lat: 37.3382, lon: -121.8863, pop: 1000000 },
+            { name: "Fort Worth", lat: 32.7555, lon: -97.3308, pop: 930000 },
+            { name: "Columbus", lat: 39.9612, lon: -82.9988, pop: 910000 },
+            { name: "Charlotte", lat: 35.2271, lon: -80.8431, pop: 870000 },
+            { name: "Indianapolis", lat: 39.7684, lon: -86.1581, pop: 880000 },
+            { name: "San Francisco", lat: 37.7749, lon: -122.4194, pop: 870000 },
+            { name: "Seattle", lat: 47.6062, lon: -122.3321, pop: 740000 },
+            { name: "Denver", lat: 39.7392, lon: -104.9903, pop: 710000 },
+            { name: "Nashville", lat: 36.1627, lon: -86.7816, pop: 690000 },
+          ];
+
+          var radiusScale = d3.scaleSqrt().domain([500000, 8500000]).range([6, 45]);
+
+          var svg = document.querySelector("#us-map-bubble .map-svg");
+          var statesGroup = svg.querySelector(".states-group");
+          var bubblesGroup = svg.querySelector(".bubbles-group");
+          var calloutsGroup = svg.querySelector(".callouts-group");
+          var connectionsGroup = svg.querySelector(".connections-group");
+          var tl = gsap.timeline({ paused: true });
+
+          function formatPop(n) {
+            if (n >= 1000000) {
+              return (n / 1000000).toFixed(1) + "M";
+            }
+            return (n / 1000).toFixed(0) + "K";
+          }
+
+          fetch(US_TOPO_URL)
+            .then(function (r) {
+              return r.json();
+            })
+            .then(function (us) {
+              var states = topojson.feature(us, us.objects.states).features;
+              var projection = d3.geoAlbersUsa().fitSize([1380, 800], {
+                type: "FeatureCollection",
+                features: states,
+              });
+              var path = d3.geoPath().projection(projection);
+
+              states.forEach(function (feature) {
+                var d = path(feature);
+                if (!d) return;
+
+                var el = document.createElementNS("http://www.w3.org/2000/svg", "path");
+                el.setAttribute("d", d);
+                el.setAttribute("class", "state-path");
+                statesGroup.appendChild(el);
+              });
+
+              var projectedCities = [];
+              cities.forEach(function (city) {
+                var coords = projection([city.lon, city.lat]);
+                if (!coords) return;
+                projectedCities.push({
+                  name: city.name,
+                  pop: city.pop,
+                  x: coords[0],
+                  y: coords[1],
+                  r: radiusScale(city.pop),
+                });
+              });
+
+              projectedCities.sort(function (a, b) {
+                return b.pop - a.pop;
+              });
+
+              var nycCoords = null;
+              projectedCities.forEach(function (city) {
+                if (city.name === "New York") {
+                  nycCoords = { x: city.x, y: city.y };
+                }
+              });
+
+              var connectionTargets = ["Los Angeles", "Chicago", "Houston", "Phoenix"];
+              connectionTargets.forEach(function (targetName) {
+                if (!nycCoords) return;
+                var target = null;
+                projectedCities.forEach(function (c) {
+                  if (c.name === targetName) target = c;
+                });
+                if (!target) return;
+
+                var midX = (nycCoords.x + target.x) / 2;
+                var midY = Math.min(nycCoords.y, target.y) - 60;
+
+                var pathD =
+                  "M " +
+                  nycCoords.x +
+                  " " +
+                  nycCoords.y +
+                  " Q " +
+                  midX +
+                  " " +
+                  midY +
+                  " " +
+                  target.x +
+                  " " +
+                  target.y;
+
+                var line = document.createElementNS("http://www.w3.org/2000/svg", "path");
+                line.setAttribute("d", pathD);
+                line.setAttribute("class", "connection-line");
+                connectionsGroup.appendChild(line);
+
+                var length = line.getTotalLength();
+                line.style.strokeDasharray = length;
+                line.style.strokeDashoffset = length;
+              });
+
+              projectedCities.forEach(function (city) {
+                var circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+                circle.setAttribute("cx", city.x);
+                circle.setAttribute("cy", city.y);
+                circle.setAttribute("r", city.r);
+                circle.setAttribute("class", "city-bubble");
+                circle.setAttribute("data-city", city.name);
+                bubblesGroup.appendChild(circle);
+              });
+
+              var pulseCircle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+              if (nycCoords) {
+                pulseCircle.setAttribute("cx", nycCoords.x);
+                pulseCircle.setAttribute("cy", nycCoords.y);
+                pulseCircle.setAttribute("r", radiusScale(8300000));
+                pulseCircle.setAttribute("class", "city-pulse");
+                bubblesGroup.appendChild(pulseCircle);
+              }
+
+              var top5 = projectedCities.slice(0, 5);
+              top5.forEach(function (city, i) {
+                var g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+                g.setAttribute("class", "callout-group");
+
+                var offsetX = city.r + 12;
+                var offsetY = -8;
+
+                if (city.name === "Los Angeles" || city.name === "San Francisco") {
+                  offsetX = -(city.r + 80);
+                }
+
+                var calloutLine = document.createElementNS("http://www.w3.org/2000/svg", "line");
+                calloutLine.setAttribute("x1", city.x);
+                calloutLine.setAttribute("y1", city.y);
+                calloutLine.setAttribute("x2", city.x + offsetX);
+                calloutLine.setAttribute("y2", city.y + offsetY);
+                calloutLine.setAttribute("class", "callout-line");
+                g.appendChild(calloutLine);
+
+                var nameText = document.createElementNS("http://www.w3.org/2000/svg", "text");
+                nameText.setAttribute("x", city.x + offsetX + (offsetX > 0 ? 6 : -6));
+                nameText.setAttribute("y", city.y + offsetY - 2);
+                nameText.setAttribute("class", "callout-name");
+                if (offsetX < 0) {
+                  nameText.setAttribute("text-anchor", "end");
+                }
+                nameText.textContent = city.name;
+                g.appendChild(nameText);
+
+                var valueText = document.createElementNS("http://www.w3.org/2000/svg", "text");
+                valueText.setAttribute("x", city.x + offsetX + (offsetX > 0 ? 6 : -6));
+                valueText.setAttribute("y", city.y + offsetY + 14);
+                valueText.setAttribute("class", "callout-value");
+                if (offsetX < 0) {
+                  valueText.setAttribute("text-anchor", "end");
+                }
+                valueText.textContent = formatPop(city.pop) + " residents";
+                g.appendChild(valueText);
+
+                calloutsGroup.appendChild(g);
+              });
+
+              buildTimeline(projectedCities, pulseCircle);
+            });
+
+          function buildTimeline(projectedCities, pulseCircle) {
+            var statePaths = statesGroup.querySelectorAll(".state-path");
+            var bubbles = bubblesGroup.querySelectorAll(".city-bubble");
+            var callouts = calloutsGroup.querySelectorAll(".callout-group");
+            var connections = connectionsGroup.querySelectorAll(".connection-line");
+
+            tl.to(
+              "#us-map-bubble .headline",
+              {
+                clipPath: "inset(0 0% 0 0)",
+                duration: 1.0,
+                ease: "power2.inOut",
+              },
+              0,
+            );
+
+            tl.to(
+              "#us-map-bubble .subtitle",
+              {
+                opacity: 1,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              0.4,
+            );
+
+            tl.to(
+              statePaths,
+              {
+                opacity: 0.8,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              0.8,
+            );
+
+            tl.to(
+              bubbles,
+              {
+                scale: 1,
+                duration: 0.5,
+                stagger: {
+                  each: 0.08,
+                  from: "start",
+                },
+                ease: "back.out(1.7)",
+              },
+              1.5,
+            );
+
+            tl.set(callouts, { x: 20 }, 3.9);
+
+            tl.to(
+              callouts,
+              {
+                opacity: 1,
+                x: 0,
+                duration: 0.6,
+                stagger: 0.3,
+                ease: "power2.out",
+              },
+              4.0,
+            );
+
+            connections.forEach(function (line) {
+              tl.to(
+                line,
+                {
+                  strokeDashoffset: 0,
+                  duration: 1.2,
+                  ease: "power2.inOut",
+                },
+                6.0,
+              );
+            });
+
+            if (pulseCircle) {
+              tl.to(
+                pulseCircle,
+                {
+                  opacity: 1,
+                  duration: 0.01,
+                },
+                8.0,
+              );
+
+              tl.fromTo(
+                pulseCircle,
+                {
+                  attr: { r: radiusScale(8300000) },
+                  opacity: 0.6,
+                },
+                {
+                  attr: { r: radiusScale(8300000) + 30 },
+                  opacity: 0,
+                  duration: 1.5,
+                  repeat: 2,
+                  ease: "power2.out",
+                },
+                8.0,
+              );
+            }
+
+            tl.to(
+              "#us-map-bubble .source",
+              {
+                opacity: 1,
+                duration: 0.5,
+                ease: "power2.out",
+              },
+              5.5,
+            );
+
+            window.__timelines = window.__timelines || {};
+            window.__timelines["us-map-bubble"] = tl;
+          }
+        })();
+      </script>
+    </div>
+  </body>
+</html>
diff --git a/registry/blocks/us-map-flow/registry-item.json b/registry/blocks/us-map-flow/registry-item.json
new file mode 100644
index 000000000..9c82cdb6e
--- /dev/null
+++ b/registry/blocks/us-map-flow/registry-item.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "us-map-flow",
+  "type": "hyperframes:block",
+  "title": "US Flow Map",
+  "description": "Animated connection arcs between US cities over a base map — composable origin-destination flow visualization",
+  "tags": ["data", "map", "geography", "usa", "flow", "connections", "arcs"],
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 12,
+  "files": [
+    {
+      "path": "us-map-flow.html",
+      "target": "compositions/us-map-flow.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/us-map-flow/us-map-flow.html b/registry/blocks/us-map-flow/us-map-flow.html
new file mode 100644
index 000000000..1805d7c3a
--- /dev/null
+++ b/registry/blocks/us-map-flow/us-map-flow.html
@@ -0,0 +1,429 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>US Flow Map</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/topojson-client@3.1.0/dist/topojson-client.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #0f172a;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="us-map-flow"
+      data-composition-id="us-map-flow"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="12"
+    >
+      <div class="flow-header">
+        <h1 class="flow-headline">Interstate Flow Connections</h1>
+        <p class="flow-subtitle">Relative volume of major city-to-city corridors</p>
+      </div>
+
+      <svg class="flow-svg" viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid meet">
+        <defs>
+          <filter id="arc-glow">
+            <feGaussianBlur stdDeviation="3" result="blur" />
+            <feMerge>
+              <feMergeNode in="blur" />
+              <feMergeNode in="SourceGraphic" />
+            </feMerge>
+          </filter>
+          <filter id="dot-glow">
+            <feGaussianBlur stdDeviation="4" result="blur" />
+            <feMerge>
+              <feMergeNode in="blur" />
+              <feMergeNode in="SourceGraphic" />
+            </feMerge>
+          </filter>
+        </defs>
+        <g class="states-group"></g>
+        <g class="arcs-group"></g>
+        <g class="traveling-dots-group"></g>
+        <g class="city-dots-group"></g>
+        <g class="city-labels-group"></g>
+      </svg>
+
+      <div class="flow-source">Source: Illustrative data</div>
+
+      <style>
+        #us-map-flow {
+          position: relative;
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(145deg, #0f172a 0%, #1e293b 100%);
+          font-family: "Inter", sans-serif;
+          color: #ffffff;
+          overflow: hidden;
+        }
+
+        #us-map-flow .flow-header {
+          position: absolute;
+          top: 40px;
+          left: 60px;
+          z-index: 2;
+        }
+
+        #us-map-flow .flow-headline {
+          font-size: 48px;
+          font-weight: 700;
+          color: #f8fafc;
+          letter-spacing: -0.02em;
+          clip-path: inset(0 100% 0 0);
+        }
+
+        #us-map-flow .flow-subtitle {
+          font-size: 22px;
+          font-weight: 300;
+          color: #94a3b8;
+          margin-top: 8px;
+          opacity: 0;
+        }
+
+        #us-map-flow .flow-svg {
+          position: absolute;
+          top: 0;
+          left: 0;
+          width: 1920px;
+          height: 1080px;
+        }
+
+        #us-map-flow .state-path {
+          fill: #1e293b;
+          stroke: #334155;
+          stroke-width: 0.5;
+          opacity: 0;
+        }
+
+        #us-map-flow .arc-path {
+          fill: none;
+          stroke: #3b82f6;
+          filter: url(#arc-glow);
+          stroke-linecap: round;
+        }
+
+        #us-map-flow .city-dot {
+          fill: #ffffff;
+          filter: url(#dot-glow);
+          opacity: 0;
+        }
+
+        #us-map-flow .city-label {
+          fill: #cbd5e1;
+          font-family: "Inter", sans-serif;
+          font-size: 13px;
+          font-weight: 500;
+          opacity: 0;
+        }
+
+        #us-map-flow .traveling-dot {
+          fill: #60a5fa;
+          opacity: 0;
+        }
+
+        #us-map-flow .flow-source {
+          position: absolute;
+          bottom: 30px;
+          right: 60px;
+          font-size: 14px;
+          font-weight: 400;
+          color: #475569;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          var NS = "http://www.w3.org/2000/svg";
+          var root = document.getElementById("us-map-flow");
+          var svg = root.querySelector(".flow-svg");
+          var statesGroup = svg.querySelector(".states-group");
+          var arcsGroup = svg.querySelector(".arcs-group");
+          var travelingDotsGroup = svg.querySelector(".traveling-dots-group");
+          var cityDotsGroup = svg.querySelector(".city-dots-group");
+          var cityLabelsGroup = svg.querySelector(".city-labels-group");
+
+          var tl = gsap.timeline({ paused: true });
+
+          /* --- City data: name → [longitude, latitude] (D3 uses [lon, lat]) --- */
+          var cities = {
+            "San Francisco": [-122.4194, 37.7749],
+            "New York": [-74.006, 40.7128],
+            "Los Angeles": [-118.2437, 34.0522],
+            Chicago: [-87.6298, 41.8781],
+            Seattle: [-122.3321, 47.6062],
+            Austin: [-97.7431, 30.2672],
+            Miami: [-80.1918, 25.7617],
+            Denver: [-104.9903, 39.7392],
+            Houston: [-95.3698, 29.7604],
+            Atlanta: [-84.388, 33.749],
+            Boston: [-71.0589, 42.3601],
+            Dallas: [-96.797, 32.7767],
+          };
+
+          /* --- Flow connections --- */
+          var flows = [
+            { from: "San Francisco", to: "New York", volume: 100 },
+            { from: "Los Angeles", to: "Chicago", volume: 85 },
+            { from: "Seattle", to: "Austin", volume: 70 },
+            { from: "New York", to: "Miami", volume: 90 },
+            { from: "Chicago", to: "Denver", volume: 65 },
+            { from: "Houston", to: "Atlanta", volume: 75 },
+            { from: "Boston", to: "San Francisco", volume: 80 },
+            { from: "Denver", to: "Los Angeles", volume: 60 },
+            { from: "Atlanta", to: "Dallas", volume: 55 },
+            { from: "Miami", to: "New York", volume: 50 },
+            { from: "Austin", to: "Seattle", volume: 45 },
+            { from: "Dallas", to: "Chicago", volume: 40 },
+          ];
+
+          var maxVolume = 100;
+          var minWidth = 1.5;
+          var maxWidth = 4;
+
+          /* --- Projection centered on continental US --- */
+          var projection = d3.geoAlbersUsa().scale(1300).translate([960, 560]);
+
+          var pathGen = d3.geoPath().projection(projection);
+
+          /* --- Project city positions --- */
+          var projected = {};
+          var cityNames = Object.keys(cities);
+          cityNames.forEach(function (name) {
+            var p = projection(cities[name]);
+            if (p) {
+              projected[name] = { x: p[0], y: p[1] };
+            }
+          });
+
+          /* --- Unique city list for dots/labels (only those that project) --- */
+          var visibleCities = Object.keys(projected);
+
+          /* --- Build arc path string (quadratic bezier curving upward) --- */
+          function buildArcPath(fromName, toName) {
+            var p1 = projected[fromName];
+            var p2 = projected[toName];
+            if (!p1 || !p2) return null;
+            var x1 = p1.x;
+            var y1 = p1.y;
+            var x2 = p2.x;
+            var y2 = p2.y;
+            var midX = (x1 + x2) / 2;
+            var midY = Math.min(y1, y2) - Math.abs(x2 - x1) * 0.15;
+            return "M" + x1 + "," + y1 + " Q" + midX + "," + midY + " " + x2 + "," + y2;
+          }
+
+          /* --- Load topology and render states --- */
+          d3.json("https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json").then(function (us) {
+            var states = topojson.feature(us, us.objects.states).features;
+
+            states.forEach(function (feature) {
+              var d = pathGen(feature);
+              if (!d) return;
+              var path = document.createElementNS(NS, "path");
+              path.setAttribute("d", d);
+              path.setAttribute("class", "state-path");
+              statesGroup.appendChild(path);
+            });
+
+            /* --- Create arc paths --- */
+            var arcPaths = [];
+            flows.forEach(function (flow) {
+              var d = buildArcPath(flow.from, flow.to);
+              if (!d) return;
+
+              var strokeW = minWidth + (flow.volume / maxVolume) * (maxWidth - minWidth);
+              var arcOpacity = 0.4 + (flow.volume / maxVolume) * 0.6;
+
+              var path = document.createElementNS(NS, "path");
+              path.setAttribute("d", d);
+              path.setAttribute("class", "arc-path");
+              path.setAttribute("stroke-width", strokeW);
+              path.style.opacity = arcOpacity;
+              arcsGroup.appendChild(path);
+
+              var len = path.getTotalLength();
+              path.style.strokeDasharray = len;
+              path.style.strokeDashoffset = len;
+
+              arcPaths.push({ el: path, length: len });
+            });
+
+            /* --- Create city dots --- */
+            visibleCities.forEach(function (name) {
+              var p = projected[name];
+              var circle = document.createElementNS(NS, "circle");
+              circle.setAttribute("cx", p.x);
+              circle.setAttribute("cy", p.y);
+              circle.setAttribute("r", 5);
+              circle.setAttribute("class", "city-dot");
+              cityDotsGroup.appendChild(circle);
+            });
+
+            /* --- Create city labels with offset --- */
+            visibleCities.forEach(function (name) {
+              var p = projected[name];
+              var text = document.createElementNS(NS, "text");
+              text.setAttribute("x", p.x + 10);
+              text.setAttribute("y", p.y - 10);
+              text.setAttribute("class", "city-label");
+              text.textContent = name;
+              cityLabelsGroup.appendChild(text);
+            });
+
+            /* --- Create traveling dots (one per arc) --- */
+            var travelingDots = [];
+            arcPaths.forEach(function () {
+              var dot = document.createElementNS(NS, "circle");
+              dot.setAttribute("r", 3);
+              dot.setAttribute("class", "traveling-dot");
+              travelingDotsGroup.appendChild(dot);
+              travelingDots.push(dot);
+            });
+
+            /* ===== GSAP TIMELINE ===== */
+
+            /* 0s: headline clip-path wipe */
+            tl.to(
+              "#us-map-flow .flow-headline",
+              {
+                clipPath: "inset(0 0% 0 0)",
+                duration: 1,
+                ease: "power2.inOut",
+              },
+              0,
+            );
+
+            /* 0.3s: subtitle fade */
+            tl.to(
+              "#us-map-flow .flow-subtitle",
+              {
+                opacity: 1,
+                duration: 0.5,
+                ease: "power2.out",
+              },
+              0.3,
+            );
+
+            /* 0.6s: states fade in */
+            tl.to(
+              "#us-map-flow .state-path",
+              {
+                opacity: 1,
+                duration: 0.8,
+                ease: "power2.out",
+              },
+              0.6,
+            );
+
+            /* 1.5s: city dots pop in */
+            tl.to(
+              "#us-map-flow .city-dot",
+              {
+                opacity: 1,
+                scale: 1,
+                transformOrigin: "center center",
+                duration: 0.4,
+                stagger: 0.05,
+                ease: "back.out(1.7)",
+              },
+              1.5,
+            );
+
+            /* 2.5s: city labels fade in */
+            tl.to(
+              "#us-map-flow .city-label",
+              {
+                opacity: 1,
+                duration: 0.3,
+                stagger: 0.05,
+                ease: "power2.out",
+              },
+              2.5,
+            );
+
+            /* 3.5s: arcs draw sequentially */
+            arcPaths.forEach(function (arc, i) {
+              tl.to(
+                arc.el,
+                {
+                  strokeDashoffset: 0,
+                  duration: 1,
+                  ease: "power2.inOut",
+                },
+                3.5 + i * 0.2,
+              );
+            });
+
+            /* 7.0s: traveling dots animate along paths */
+            arcPaths.forEach(function (arc, i) {
+              var dot = travelingDots[i];
+              var pathEl = arc.el;
+              var pathLength = arc.length;
+
+              tl.set(dot, { opacity: 0.9 }, 7.0 + i * 0.1);
+
+              var progress = { value: 0 };
+              tl.to(
+                progress,
+                {
+                  value: 1,
+                  duration: 1.5,
+                  ease: "power1.inOut",
+                  onUpdate: function () {
+                    var pt = pathEl.getPointAtLength(progress.value * pathLength);
+                    dot.setAttribute("cx", pt.x);
+                    dot.setAttribute("cy", pt.y);
+                  },
+                  onComplete: function () {
+                    gsap.to(dot, { opacity: 0, duration: 0.3 });
+                  },
+                },
+                7.0 + i * 0.1,
+              );
+            });
+
+            /* 9.0s: source fade in */
+            tl.to(
+              "#us-map-flow .flow-source",
+              {
+                opacity: 1,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              9.0,
+            );
+
+            /* Register timeline */
+            window.__timelines = window.__timelines || {};
+            window.__timelines["us-map-flow"] = tl;
+          });
+        })();
+      </script>
+    </div>
+  </body>
+</html>
diff --git a/registry/blocks/us-map-hex/registry-item.json b/registry/blocks/us-map-hex/registry-item.json
new file mode 100644
index 000000000..c7877d8b9
--- /dev/null
+++ b/registry/blocks/us-map-hex/registry-item.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "us-map-hex",
+  "type": "hyperframes:block",
+  "title": "US Hex Grid Map",
+  "description": "Animated hexagonal tile grid map — each state as an equal-weight hex with data fill and abbreviation label",
+  "tags": ["data", "map", "geography", "usa", "hexgrid", "tilegrid"],
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 10,
+  "files": [
+    {
+      "path": "us-map-hex.html",
+      "target": "compositions/us-map-hex.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/us-map-hex/us-map-hex.html b/registry/blocks/us-map-hex/us-map-hex.html
new file mode 100644
index 000000000..3d8ec4faf
--- /dev/null
+++ b/registry/blocks/us-map-hex/us-map-hex.html
@@ -0,0 +1,559 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>US Hex Grid Map</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: linear-gradient(145deg, #0f172a 0%, #1e293b 100%);
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="us-map-hex"
+      data-composition-id="us-map-hex"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="10"
+    >
+      <div class="map-header">
+        <h1 class="map-headline">Median Household Income by State</h1>
+        <p class="map-subtitle">American Community Survey, 2024</p>
+      </div>
+
+      <svg class="hex-svg" viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid meet">
+        <g class="hex-grid"></g>
+        <g class="hex-labels"></g>
+      </svg>
+
+      <div class="map-legend">
+        <div class="legend-label legend-low">$52k</div>
+        <div class="legend-bar"></div>
+        <div class="legend-label legend-high">$107k</div>
+      </div>
+
+      <div class="map-source">Source: U.S. Census Bureau, American Community Survey 2024</div>
+
+      <style>
+        #us-map-hex {
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(145deg, #0f172a 0%, #1e293b 100%);
+          font-family: "Inter", sans-serif;
+          color: #f8fafc;
+          position: relative;
+          overflow: hidden;
+        }
+
+        #us-map-hex .map-header {
+          position: absolute;
+          top: 48px;
+          left: 80px;
+          z-index: 2;
+        }
+
+        #us-map-hex .map-headline {
+          font-size: 48px;
+          font-weight: 700;
+          letter-spacing: -0.02em;
+          color: #f8fafc;
+          clip-path: inset(0 100% 0 0);
+          white-space: nowrap;
+        }
+
+        #us-map-hex .map-subtitle {
+          font-size: 20px;
+          font-weight: 400;
+          color: #94a3b8;
+          margin-top: 8px;
+          opacity: 0;
+        }
+
+        #us-map-hex .hex-svg {
+          position: absolute;
+          top: 0;
+          left: 0;
+          width: 1920px;
+          height: 1080px;
+        }
+
+        #us-map-hex .hex-poly {
+          stroke: #0f172a;
+          stroke-width: 2;
+          opacity: 0;
+        }
+
+        #us-map-hex .hex-text {
+          font-family: "Inter", sans-serif;
+          font-size: 14px;
+          font-weight: 600;
+          fill: #0f172a;
+          text-anchor: middle;
+          dominant-baseline: central;
+          pointer-events: none;
+          opacity: 0;
+        }
+
+        #us-map-hex .hex-text.light-text {
+          fill: #fef3c7;
+        }
+
+        #us-map-hex .map-legend {
+          position: absolute;
+          bottom: 80px;
+          left: 80px;
+          display: flex;
+          align-items: center;
+          gap: 12px;
+          opacity: 0;
+        }
+
+        #us-map-hex .legend-bar {
+          width: 240px;
+          height: 16px;
+          border-radius: 4px;
+          background: linear-gradient(90deg, #451a03 0%, #f59e0b 50%, #fef3c7 100%);
+        }
+
+        #us-map-hex .legend-label {
+          font-size: 14px;
+          font-weight: 500;
+          color: #94a3b8;
+        }
+
+        #us-map-hex .map-source {
+          position: absolute;
+          bottom: 48px;
+          left: 80px;
+          font-size: 12px;
+          color: #475569;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          var NS = "http://www.w3.org/2000/svg";
+          var hexGrid = document.querySelector("#us-map-hex .hex-grid");
+          var hexLabels = document.querySelector("#us-map-hex .hex-labels");
+
+          /* --- State grid positions (col, row) --- */
+          var positions = {
+            ME: [10, 0],
+            VT: [9, 1],
+            NH: [10, 1],
+            WA: [0, 2],
+            MT: [1, 2],
+            ND: [2, 2],
+            MN: [3, 2],
+            WI: [4, 2],
+            MI: [7, 2],
+            NY: [8, 2],
+            MA: [9, 2],
+            RI: [10, 2],
+            ID: [0, 3],
+            WY: [1, 3],
+            SD: [2, 3],
+            IA: [3, 3],
+            IL: [4, 3],
+            IN: [5, 3],
+            OH: [6, 3],
+            PA: [7, 3],
+            NJ: [8, 3],
+            CT: [9, 3],
+            OR: [0, 4],
+            NV: [1, 4],
+            CO: [2, 4],
+            NE: [3, 4],
+            MO: [4, 4],
+            KY: [5, 4],
+            WV: [6, 4],
+            VA: [7, 4],
+            MD: [8, 4],
+            DE: [9, 4],
+            CA: [0, 5],
+            UT: [1, 5],
+            NM: [2, 5],
+            KS: [3, 5],
+            AR: [4, 5],
+            TN: [5, 5],
+            NC: [6, 5],
+            SC: [7, 5],
+            DC: [8, 5],
+            AZ: [1, 6],
+            OK: [3, 6],
+            LA: [4, 6],
+            MS: [5, 6],
+            AL: [6, 6],
+            GA: [7, 6],
+            HI: [0, 7],
+            TX: [3, 7],
+            FL: [7, 7],
+            AK: [0, 8],
+          };
+
+          /* --- Median household income (2024 ACS, rounded to nearest $1k) --- */
+          var income = {
+            MD: 106998,
+            NJ: 101778,
+            MA: 101079,
+            CT: 92545,
+            HI: 91010,
+            NH: 90845,
+            WA: 90325,
+            CA: 89648,
+            CO: 87598,
+            VA: 87249,
+            UT: 86833,
+            MN: 84313,
+            AK: 83601,
+            NY: 81386,
+            RI: 81370,
+            IL: 79253,
+            OR: 76632,
+            DE: 75932,
+            WI: 72458,
+            NV: 71646,
+            VT: 71560,
+            PA: 71610,
+            ND: 71017,
+            NE: 70654,
+            TX: 70813,
+            AZ: 70821,
+            ID: 69973,
+            MT: 68091,
+            GA: 67992,
+            ME: 67587,
+            FL: 67917,
+            IA: 67684,
+            WY: 67249,
+            SD: 66894,
+            MI: 66986,
+            IN: 65834,
+            OH: 64018,
+            MO: 63594,
+            KS: 66354,
+            NC: 65070,
+            TN: 63426,
+            SC: 62064,
+            OK: 60438,
+            KY: 57584,
+            NM: 58257,
+            AL: 57563,
+            LA: 55728,
+            WV: 52520,
+            AR: 53289,
+            MS: 52434,
+            DC: 101722,
+          };
+
+          /* --- Color interpolation --- */
+          var incomeValues = [];
+          var stateKeys = Object.keys(income);
+          for (var i = 0; i < stateKeys.length; i++) {
+            incomeValues.push(income[stateKeys[i]]);
+          }
+          var minIncome = Math.min.apply(null, incomeValues);
+          var maxIncome = Math.max.apply(null, incomeValues);
+
+          function lerp(a, b, t) {
+            return a + (b - a) * t;
+          }
+
+          function hexToRgb(hex) {
+            var r = parseInt(hex.substring(1, 3), 16);
+            var g = parseInt(hex.substring(3, 5), 16);
+            var b = parseInt(hex.substring(5, 7), 16);
+            return [r, g, b];
+          }
+
+          var colorLow = hexToRgb("#451a03");
+          var colorMid = hexToRgb("#f59e0b");
+          var colorHigh = hexToRgb("#fef3c7");
+
+          function getColor(val) {
+            var t = (val - minIncome) / (maxIncome - minIncome);
+            var r, g, b;
+            if (t < 0.5) {
+              var t2 = t / 0.5;
+              r = Math.round(lerp(colorLow[0], colorMid[0], t2));
+              g = Math.round(lerp(colorLow[1], colorMid[1], t2));
+              b = Math.round(lerp(colorLow[2], colorMid[2], t2));
+            } else {
+              var t2 = (t - 0.5) / 0.5;
+              r = Math.round(lerp(colorMid[0], colorHigh[0], t2));
+              g = Math.round(lerp(colorMid[1], colorHigh[1], t2));
+              b = Math.round(lerp(colorMid[2], colorHigh[2], t2));
+            }
+            return "rgb(" + r + "," + g + "," + b + ")";
+          }
+
+          /* Determine if text should be light on dark hex */
+          function isLightText(val) {
+            var t = (val - minIncome) / (maxIncome - minIncome);
+            return t < 0.35;
+          }
+
+          /* --- Hex geometry (flat-top) --- */
+          var hexW = 80;
+          var hexS = hexW / 2;
+          var hexH = hexS * Math.sqrt(3);
+          var startX = 480;
+          var startY = 200;
+
+          function hexCenter(col, row) {
+            var cx = startX + col * (hexW * 0.75);
+            var cy = startY + row * hexH;
+            if (row % 2 === 1) {
+              cx += hexW * 0.375;
+            }
+            return [cx, cy];
+          }
+
+          function hexPoints(cx, cy) {
+            var pts = [
+              [cx - hexS, cy],
+              [cx - hexS / 2, cy - hexH / 2],
+              [cx + hexS / 2, cy - hexH / 2],
+              [cx + hexS, cy],
+              [cx + hexS / 2, cy + hexH / 2],
+              [cx - hexS / 2, cy + hexH / 2],
+            ];
+            var strs = [];
+            for (var i = 0; i < pts.length; i++) {
+              strs.push(pts[i][0].toFixed(2) + "," + pts[i][1].toFixed(2));
+            }
+            return strs.join(" ");
+          }
+
+          /* --- Compute center of all hexes for stagger distance --- */
+          var allCenters = [];
+          var allStates = Object.keys(positions);
+          for (var i = 0; i < allStates.length; i++) {
+            var pos = positions[allStates[i]];
+            var center = hexCenter(pos[0], pos[1]);
+            allCenters.push(center);
+          }
+          var avgCx = 0;
+          var avgCy = 0;
+          for (var i = 0; i < allCenters.length; i++) {
+            avgCx += allCenters[i][0];
+            avgCy += allCenters[i][1];
+          }
+          avgCx /= allCenters.length;
+          avgCy /= allCenters.length;
+
+          /* --- Create hex elements --- */
+          var hexPolys = [];
+          var hexTexts = [];
+          var distances = [];
+
+          for (var i = 0; i < allStates.length; i++) {
+            var st = allStates[i];
+            var pos = positions[st];
+            var center = hexCenter(pos[0], pos[1]);
+            var cx = center[0];
+            var cy = center[1];
+
+            var poly = document.createElementNS(NS, "polygon");
+            poly.setAttribute("points", hexPoints(cx, cy));
+            poly.setAttribute("fill", getColor(income[st]));
+            poly.setAttribute("class", "hex-poly");
+            poly.setAttribute("data-state", st);
+            hexGrid.appendChild(poly);
+            hexPolys.push(poly);
+
+            var text = document.createElementNS(NS, "text");
+            text.setAttribute("x", cx);
+            text.setAttribute("y", cy);
+            var textClass = "hex-text";
+            if (isLightText(income[st])) {
+              textClass += " light-text";
+            }
+            text.setAttribute("class", textClass);
+            text.textContent = st;
+            hexLabels.appendChild(text);
+            hexTexts.push(text);
+
+            var dx = cx - avgCx;
+            var dy = cy - avgCy;
+            distances.push(Math.sqrt(dx * dx + dy * dy));
+          }
+
+          /* --- Sort indices by distance from center (for stagger) --- */
+          var sortedIndices = [];
+          for (var i = 0; i < allStates.length; i++) {
+            sortedIndices.push(i);
+          }
+          sortedIndices.sort(function (a, b) {
+            return distances[a] - distances[b];
+          });
+
+          var sortedPolys = [];
+          var sortedTexts = [];
+          for (var i = 0; i < sortedIndices.length; i++) {
+            sortedPolys.push(hexPolys[sortedIndices[i]]);
+            sortedTexts.push(hexTexts[sortedIndices[i]]);
+          }
+
+          /* --- GSAP Timeline --- */
+          var tl = gsap.timeline({ paused: true });
+
+          /* 0s: headline wipe */
+          tl.to(
+            "#us-map-hex .map-headline",
+            {
+              clipPath: "inset(0 0% 0 0)",
+              duration: 1,
+              ease: "power2.inOut",
+            },
+            0,
+          );
+
+          /* 0.3s: subtitle fade */
+          tl.to(
+            "#us-map-hex .map-subtitle",
+            {
+              opacity: 1,
+              duration: 0.5,
+              ease: "power2.out",
+            },
+            0.3,
+          );
+
+          /* 0.8s: hexagons stagger in from center outward */
+          tl.fromTo(
+            sortedPolys,
+            {
+              opacity: 0,
+              scale: 0,
+              transformOrigin: "50% 50%",
+            },
+            {
+              opacity: 1,
+              scale: 1,
+              duration: 0.4,
+              stagger: 0.03,
+              ease: "back.out(1.4)",
+            },
+            0.8,
+          );
+
+          /* 3.5s: state labels fade in */
+          tl.fromTo(
+            sortedTexts,
+            { opacity: 0 },
+            {
+              opacity: 1,
+              duration: 0.3,
+              stagger: 0.02,
+              ease: "power2.out",
+            },
+            3.5,
+          );
+
+          /* 5.0s: legend fade */
+          tl.to(
+            "#us-map-hex .map-legend",
+            {
+              opacity: 1,
+              duration: 0.6,
+              ease: "power2.out",
+            },
+            5.0,
+          );
+
+          /* 5.5s: source fade */
+          tl.to(
+            "#us-map-hex .map-source",
+            {
+              opacity: 1,
+              duration: 0.5,
+              ease: "power2.out",
+            },
+            5.5,
+          );
+
+          /* 6.0s: top 5 income states pulse */
+          var topStates = ["MD", "NJ", "MA", "CT", "HI"];
+          var topPolys = [];
+          for (var i = 0; i < topStates.length; i++) {
+            for (var j = 0; j < allStates.length; j++) {
+              if (allStates[j] === topStates[i]) {
+                topPolys.push(hexPolys[j]);
+                break;
+              }
+            }
+          }
+
+          tl.to(
+            topPolys,
+            {
+              filter: "brightness(1.4)",
+              duration: 0.4,
+              stagger: 0.08,
+              ease: "power2.out",
+            },
+            6.0,
+          );
+
+          tl.to(
+            topPolys,
+            {
+              filter: "brightness(1)",
+              duration: 0.4,
+              stagger: 0.08,
+              ease: "power2.in",
+            },
+            6.8,
+          );
+
+          tl.to(
+            topPolys,
+            {
+              filter: "brightness(1.3)",
+              duration: 0.3,
+              stagger: 0.06,
+              ease: "power2.out",
+            },
+            7.4,
+          );
+
+          tl.to(
+            topPolys,
+            {
+              filter: "brightness(1)",
+              duration: 0.5,
+              stagger: 0.06,
+              ease: "power2.in",
+            },
+            8.0,
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["us-map-hex"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
diff --git a/registry/blocks/world-map/registry-item.json b/registry/blocks/world-map/registry-item.json
new file mode 100644
index 000000000..9a248d98f
--- /dev/null
+++ b/registry/blocks/world-map/registry-item.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "world-map",
+  "type": "hyperframes:block",
+  "title": "World Map",
+  "description": "Animated world choropleth with country-by-country reveal, tooltip labels, and rotating globe inset — D3 Natural Earth projection",
+  "tags": ["data", "map", "geography", "world", "choropleth"],
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 14,
+  "files": [
+    {
+      "path": "world-map.html",
+      "target": "compositions/world-map.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/world-map/world-map.html b/registry/blocks/world-map/world-map.html
new file mode 100644
index 000000000..5732d21f7
--- /dev/null
+++ b/registry/blocks/world-map/world-map.html
@@ -0,0 +1,443 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>World Map</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=block"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/topojson-client@3.1.0/dist/topojson-client.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #0f172a;
+      }
+
+      #world-map {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        background: linear-gradient(145deg, #0f172a 0%, #1e293b 100%);
+        font-family: "Inter", sans-serif;
+        color: #f0fdfa;
+        overflow: hidden;
+      }
+
+      #world-map .headline {
+        position: absolute;
+        top: 48px;
+        left: 80px;
+        font-size: 52px;
+        font-weight: 700;
+        letter-spacing: -0.02em;
+        color: #f0fdfa;
+        clip-path: inset(0 100% 0 0);
+      }
+
+      #world-map .subtitle {
+        position: absolute;
+        top: 114px;
+        left: 80px;
+        font-size: 22px;
+        font-weight: 300;
+        color: #94a3b8;
+        opacity: 0;
+      }
+
+      #world-map .map-container {
+        position: absolute;
+        top: 170px;
+        left: 80px;
+        width: 1380px;
+        height: 700px;
+      }
+
+      #world-map .map-container svg {
+        width: 1380px;
+        height: 700px;
+      }
+
+      #world-map .country-path {
+        stroke: #1e293b;
+        stroke-width: 0.6;
+        opacity: 0;
+        cursor: default;
+      }
+
+      #world-map .ocean {
+        fill: none;
+      }
+
+      #world-map .graticule {
+        fill: none;
+        stroke: #1e293b;
+        stroke-width: 0.3;
+        stroke-opacity: 0.4;
+      }
+
+      #world-map .legend-group {
+        position: absolute;
+        bottom: 80px;
+        right: 80px;
+        display: flex;
+        flex-direction: column;
+        align-items: flex-end;
+        gap: 8px;
+        opacity: 0;
+      }
+
+      #world-map .legend-bar {
+        width: 280px;
+        height: 14px;
+        border-radius: 7px;
+      }
+
+      #world-map .legend-labels {
+        display: flex;
+        justify-content: space-between;
+        width: 280px;
+        font-size: 13px;
+        font-weight: 500;
+        color: #94a3b8;
+      }
+
+      #world-map .source {
+        position: absolute;
+        bottom: 36px;
+        left: 80px;
+        font-size: 13px;
+        font-weight: 400;
+        color: #475569;
+        opacity: 0;
+      }
+
+      #world-map .tooltip {
+        position: absolute;
+        pointer-events: none;
+        background: rgba(15, 23, 42, 0.92);
+        border: 1px solid #334155;
+        border-radius: 8px;
+        padding: 10px 16px;
+        font-size: 14px;
+        font-weight: 500;
+        color: #f0fdfa;
+        white-space: nowrap;
+        opacity: 0;
+        transform: translateY(4px);
+        backdrop-filter: blur(8px);
+        z-index: 10;
+      }
+
+      #world-map .tooltip .tt-value {
+        color: #22d3ee;
+        font-weight: 600;
+        margin-left: 6px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="world-map"
+      data-composition-id="world-map"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="14"
+    >
+      <h1 class="headline">Global GDP per Capita</h1>
+      <p class="subtitle">Nominal GDP per capita, 2024 IMF estimates</p>
+
+      <div class="map-container">
+        <svg id="world-map-svg"></svg>
+      </div>
+
+      <div class="legend-group">
+        <div
+          class="legend-bar"
+          style="background: linear-gradient(90deg, #064e3b 0%, #0d9488 33%, #22d3ee 66%, #f0fdfa 100%)"
+        ></div>
+        <div class="legend-labels">
+          <span>Low</span>
+          <span>High</span>
+        </div>
+      </div>
+
+      <p class="source">Source: International Monetary Fund</p>
+
+      <div class="tooltip"></div>
+    </div>
+
+    <script>
+      (function () {
+        /* ── GDP per capita data (2024 IMF estimates, USD) ── */
+        /* Keys are ISO 3166-1 numeric codes as strings (3-digit, zero-padded) */
+        var gdpData = {
+          "840": { name: "United States", gdp: 85373 },
+          "156": { name: "China", gdp: 13136 },
+          "356": { name: "India", gdp: 2731 },
+          "276": { name: "Germany", gdp: 54291 },
+          "826": { name: "United Kingdom", gdp: 48913 },
+          "250": { name: "France", gdp: 44408 },
+          "392": { name: "Japan", gdp: 33950 },
+          "076": { name: "Brazil", gdp: 10412 },
+          "036": { name: "Australia", gdp: 65366 },
+          "124": { name: "Canada", gdp: 54866 },
+          "643": { name: "Russia", gdp: 14403 },
+          "410": { name: "South Korea", gdp: 33147 },
+          "484": { name: "Mexico", gdp: 13434 },
+          "360": { name: "Indonesia", gdp: 5108 },
+          "566": { name: "Nigeria", gdp: 1621 },
+          "710": { name: "South Africa", gdp: 6190 },
+          "818": { name: "Egypt", gdp: 4295 },
+          "792": { name: "Turkey", gdp: 13110 },
+          "682": { name: "Saudi Arabia", gdp: 32270 },
+          "764": { name: "Thailand", gdp: 7647 },
+          "704": { name: "Vietnam", gdp: 4623 },
+          "616": { name: "Poland", gdp: 22393 },
+          "752": { name: "Sweden", gdp: 59324 },
+          "578": { name: "Norway", gdp: 94660 },
+          "756": { name: "Switzerland", gdp: 105669 },
+          "032": { name: "Argentina", gdp: 13709 },
+          "170": { name: "Colombia", gdp: 7230 },
+          "404": { name: "Kenya", gdp: 2198 },
+          "586": { name: "Pakistan", gdp: 1658 },
+          "050": { name: "Bangladesh", gdp: 2688 }
+        };
+
+        /* Top 5 GDP countries for highlight pulse */
+        var top5Codes = ["756", "578", "840", "036", "752"];
+
+        /* GDP range for color scale */
+        var gdpValues = [];
+        var codes = Object.keys(gdpData);
+        for (var i = 0; i < codes.length; i++) {
+          gdpValues.push(gdpData[codes[i]].gdp);
+        }
+        var minGdp = Math.min.apply(null, gdpValues);
+        var maxGdp = Math.max.apply(null, gdpValues);
+
+        /* Color interpolation: green → teal → cyan → white */
+        var colorStops = [
+          { r: 6, g: 78, b: 59 },
+          { r: 13, g: 148, b: 136 },
+          { r: 34, g: 211, b: 238 },
+          { r: 240, g: 253, b: 250 }
+        ];
+
+        function gdpToColor(value) {
+          var t = (value - minGdp) / (maxGdp - minGdp);
+          t = Math.max(0, Math.min(1, t));
+          var scaledT = t * (colorStops.length - 1);
+          var idx = Math.floor(scaledT);
+          if (idx >= colorStops.length - 1) idx = colorStops.length - 2;
+          var localT = scaledT - idx;
+          var c0 = colorStops[idx];
+          var c1 = colorStops[idx + 1];
+          var r = Math.round(c0.r + (c1.r - c0.r) * localT);
+          var g = Math.round(c0.g + (c1.g - c0.g) * localT);
+          var b = Math.round(c0.b + (c1.b - c0.b) * localT);
+          return "rgb(" + r + "," + g + "," + b + ")";
+        }
+
+        /* Default fill for countries without data */
+        var defaultFill = "#1e293b";
+
+        /* ── Build the map ── */
+        var svg = d3
+          .select("#world-map-svg")
+          .attr("viewBox", "0 0 1380 700")
+          .attr("preserveAspectRatio", "xMidYMid meet");
+
+        var projection = d3
+          .geoNaturalEarth1()
+          .fitSize([1380, 700], { type: "Sphere" });
+
+        var pathGenerator = d3.geoPath().projection(projection);
+
+        /* Graticule */
+        var graticule = d3.geoGraticule10();
+        svg
+          .append("path")
+          .datum(graticule)
+          .attr("class", "graticule")
+          .attr("d", pathGenerator);
+
+        /* Tooltip element */
+        var tooltipEl = document.querySelector("#world-map .tooltip");
+
+        /* Fetch topology and render countries */
+        d3.json(
+          "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json"
+        ).then(function (world) {
+          var countries = topojson.feature(
+            world,
+            world.objects.countries
+          ).features;
+
+          svg
+            .selectAll(".country-path")
+            .data(countries)
+            .enter()
+            .append("path")
+            .attr("class", "country-path")
+            .attr("d", pathGenerator)
+            .attr("data-country", function (d) {
+              return String(d.id).padStart(3, "0");
+            })
+            .attr("fill", function (d) {
+              var code = String(d.id).padStart(3, "0");
+              if (gdpData[code]) {
+                return gdpToColor(gdpData[code].gdp);
+              }
+              return defaultFill;
+            })
+            .on("mouseenter", function (event, d) {
+              var code = String(d.id).padStart(3, "0");
+              if (gdpData[code]) {
+                var entry = gdpData[code];
+                tooltipEl.innerHTML =
+                  entry.name +
+                  '<span class="tt-value">$' +
+                  entry.gdp.toLocaleString() +
+                  "</span>";
+                tooltipEl.style.opacity = "1";
+                tooltipEl.style.transform = "translateY(0)";
+              }
+            })
+            .on("mousemove", function (event) {
+              var container = document.querySelector("#world-map");
+              var rect = container.getBoundingClientRect();
+              var x = event.clientX - rect.left + 16;
+              var y = event.clientY - rect.top - 40;
+              tooltipEl.style.left = x + "px";
+              tooltipEl.style.top = y + "px";
+            })
+            .on("mouseleave", function () {
+              tooltipEl.style.opacity = "0";
+              tooltipEl.style.transform = "translateY(4px)";
+            });
+
+          /* ── GSAP Timeline ── */
+          buildTimeline();
+        });
+
+        function buildTimeline() {
+          var tl = gsap.timeline({ paused: true });
+
+          /* 0s: Headline clip-path wipe reveal (1s) */
+          tl.to(
+            "#world-map .headline",
+            {
+              clipPath: "inset(0 0% 0 0)",
+              duration: 1,
+              ease: "power3.inOut"
+            },
+            0
+          );
+
+          /* 0.4s: Subtitle fade in (0.6s) */
+          tl.to(
+            "#world-map .subtitle",
+            {
+              opacity: 1,
+              duration: 0.6,
+              ease: "power2.out"
+            },
+            0.4
+          );
+
+          /* 1.0s: Countries stagger reveal */
+          tl.to(
+            "#world-map .country-path",
+            {
+              opacity: 1,
+              duration: 0.3,
+              stagger: {
+                each: 0.02,
+                from: "random"
+              },
+              ease: "power1.out"
+            },
+            1.0
+          );
+
+          /* 4.0s: Legend fade in */
+          tl.to(
+            "#world-map .legend-group",
+            {
+              opacity: 1,
+              duration: 0.6,
+              ease: "power2.out"
+            },
+            4.0
+          );
+
+          /* 4.5s: Source fade in */
+          tl.to(
+            "#world-map .source",
+            {
+              opacity: 1,
+              duration: 0.5,
+              ease: "power2.out"
+            },
+            4.5
+          );
+
+          /* 5.0s: Highlight pulse on top 5 GDP countries */
+          for (var i = 0; i < top5Codes.length; i++) {
+            var selector =
+              '#world-map [data-country="' + top5Codes[i] + '"]';
+
+            /* Pulse up: brightness + white stroke */
+            tl.to(
+              selector,
+              {
+                filter: "brightness(1.5)",
+                stroke: "#ffffff",
+                strokeWidth: 1.8,
+                duration: 0.4,
+                ease: "power2.out"
+              },
+              5.0 + i * 0.15
+            );
+
+            /* Pulse back to normal */
+            tl.to(
+              selector,
+              {
+                filter: "brightness(1)",
+                stroke: "#1e293b",
+                strokeWidth: 0.6,
+                duration: 0.6,
+                ease: "power2.inOut"
+              },
+              5.0 + i * 0.15 + 0.4
+            );
+          }
+
+          /* Register timeline */
+          if (!window.__timelines) {
+            window.__timelines = {};
+          }
+          window.__timelines["world-map"] = tl;
+        }
+      })();
+    </script>
+  </body>
+</html>
diff --git a/registry/registry.json b/registry/registry.json
index 5dff678fa..e60bc3483 100644
--- a/registry/registry.json
+++ b/registry/registry.json
@@ -43,6 +43,22 @@
       "name": "us-map",
       "type": "hyperframes:block"
     },
+    {
+      "name": "us-map-bubble",
+      "type": "hyperframes:block"
+    },
+    {
+      "name": "us-map-hex",
+      "type": "hyperframes:block"
+    },
+    {
+      "name": "us-map-flow",
+      "type": "hyperframes:block"
+    },
+    {
+      "name": "world-map",
+      "type": "hyperframes:block"
+    },
     {
       "name": "flowchart",
       "type": "hyperframes:block"