diff --git a/docs/catalog/blocks/spain-map.mdx b/docs/catalog/blocks/spain-map.mdx
new file mode 100644
index 000000000..5184aaacf
--- /dev/null
+++ b/docs/catalog/blocks/spain-map.mdx
@@ -0,0 +1,44 @@
+---
+title: "Spain Map"
+description: "Animated Spain choropleth by autonomous community with staggered reveals and gradient legend"
+---
+
+# Spain Map
+
+Animated Spain choropleth by autonomous community with staggered reveals and gradient legend — D3 conic conformal projection with GSAP timeline. GDP per capita data with warm red-to-amber color scale.
+
+`data` `map` `geography` `spain` `europe` `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/spain-map.mp4?v=1779081476" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/spain-map.png" autoPlay muted loop playsInline />
+
+## Install
+
+<CodeGroup>
+
+```bash Terminal
+npx hyperframes add spain-map
+```
+
+</CodeGroup>
+
+## Details
+
+| Property | Value |
+| --- | --- |
+| Type | Block |
+| Dimensions | 1920×1080 |
+| Duration | 12s |
+
+## Files
+
+| File | Target | Type |
+| --- | --- | --- |
+| `spain-map.html` | `compositions/spain-map.html` | hyperframes:composition |
+
+## Usage
+
+After installing, add the block to your host composition:
+
+```html
+<div data-composition-id="spain-map" data-composition-src="compositions/spain-map.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-bubble.mdx b/docs/catalog/blocks/us-map-bubble.mdx
new file mode 100644
index 000000000..d2815bbec
--- /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?v=1779081476" 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..55db2c216
--- /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?v=1779081476" 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..bbff7409f
--- /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?v=1779081476" 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..26ff07d02
--- /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-v1779081660.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..a3ba2d5e4
--- /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?v=1779081476" 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..30d555412 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -188,6 +188,17 @@
               "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",
+              "catalog/blocks/spain-map"
+            ]
+          },
           {
             "group": "Data",
             "pages": [
diff --git a/docs/public/catalog-index.json b/docs/public/catalog-index.json
index 764193bcf..fa4d31679 100644
--- a/docs/public/catalog-index.json
+++ b/docs/public/catalog-index.json
@@ -544,6 +544,22 @@
     "href": "/catalog/components/shimmer-sweep",
     "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/shimmer-sweep.png"
   },
+  {
+    "name": "spain-map",
+    "type": "block",
+    "title": "Spain Map",
+    "description": "Animated Spain choropleth by autonomous community with staggered reveals and gradient legend — D3 conic conformal projection",
+    "tags": [
+      "data",
+      "map",
+      "geography",
+      "spain",
+      "europe",
+      "choropleth"
+    ],
+    "href": "/catalog/blocks/spain-map",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/spain-map.png"
+  },
   {
     "name": "spotify-card",
     "type": "block",
@@ -777,6 +793,70 @@
     "href": "/catalog/blocks/ui-3d-reveal",
     "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/ui-3d-reveal.png"
   },
+  {
+    "name": "us-map",
+    "type": "block",
+    "title": "US Map",
+    "description": "Animated US choropleth map with staggered state reveals, value labels, and gradient legend — pure inline SVG with GSAP",
+    "tags": [
+      "data",
+      "map",
+      "geography",
+      "usa",
+      "choropleth"
+    ],
+    "href": "/catalog/blocks/us-map",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map.png"
+  },
+  {
+    "name": "us-map-bubble",
+    "type": "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"
+    ],
+    "href": "/catalog/blocks/us-map-bubble",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-bubble.png"
+  },
+  {
+    "name": "us-map-flow",
+    "type": "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"
+    ],
+    "href": "/catalog/blocks/us-map-flow",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-flow.png"
+  },
+  {
+    "name": "us-map-hex",
+    "type": "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"
+    ],
+    "href": "/catalog/blocks/us-map-hex",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/us-map-hex.png"
+  },
   {
     "name": "vfx-iphone-device",
     "type": "block",
@@ -911,6 +991,21 @@
     "href": "/catalog/blocks/whip-pan",
     "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/whip-pan.png"
   },
+  {
+    "name": "world-map",
+    "type": "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"
+    ],
+    "href": "/catalog/blocks/world-map",
+    "preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/world-map.png"
+  },
   {
     "name": "x-post",
     "type": "block",
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index a17050dc9..3bae137bf 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -368,7 +368,7 @@ function parseHostVariableValues(host: Element): Record<string, unknown> {
   return parsed as Record<string, unknown>;
 }
 
-const FLATTENED_INNER_ROOT_STRIP_ATTRS = [
+export const FLATTENED_INNER_ROOT_STRIP_ATTRS = [
   "data-composition-id",
   "data-composition-file",
   "data-start",
@@ -381,7 +381,7 @@ const FLATTENED_INNER_ROOT_STRIP_ATTRS = [
   "data-hf-authored-end",
 ];
 
-function prepareFlattenedInnerRoot(innerRoot: Element): Element {
+export function prepareFlattenedInnerRoot(innerRoot: Element): Element {
   const prepared = innerRoot.cloneNode(true) as Element;
   const authoredRootId = prepared.getAttribute("id")?.trim();
   for (const attrName of FLATTENED_INNER_ROOT_STRIP_ATTRS) {
diff --git a/packages/core/src/compiler/index.ts b/packages/core/src/compiler/index.ts
index 85d66afea..e173ba890 100644
--- a/packages/core/src/compiler/index.ts
+++ b/packages/core/src/compiler/index.ts
@@ -15,7 +15,12 @@ export {
 export { compileHtml, type MediaDurationProber } from "./htmlCompiler";
 
 // HTML bundler (Node.js — requires fs, linkedom, esbuild)
-export { bundleToSingleHtml, type BundleOptions } from "./htmlBundler";
+export {
+  bundleToSingleHtml,
+  type BundleOptions,
+  prepareFlattenedInnerRoot,
+  FLATTENED_INNER_ROOT_STRIP_ATTRS,
+} from "./htmlBundler";
 
 export {
   RUNTIME_BOOTSTRAP_ATTR,
diff --git a/packages/core/src/lint/rules/adapters.ts b/packages/core/src/lint/rules/adapters.ts
index 50be06e1f..c6d61fb99 100644
--- a/packages/core/src/lint/rules/adapters.ts
+++ b/packages/core/src/lint/rules/adapters.ts
@@ -37,8 +37,16 @@ export const adapterRules: Array<(ctx: LintContext) => HyperframeLintFinding[]>
 
     const usesThree = allScriptTexts.some((t) => /\bTHREE\./.test(t));
     const hasThreeScript = allScriptSrcs.some((src) => /three/i.test(src));
+    const hasThreeImportMap = allScriptTexts.some(
+      (t) =>
+        /["']three["']/.test(t) &&
+        /importmap/.test(scripts.find((s) => s.content === t)?.attrs || ""),
+    );
+    const hasThreeModuleImport = allScriptTexts.some(
+      (t) => /\bimport\b.*['"]three['"]/.test(t) || /\bfrom\s+['"]three['"]/.test(t),
+    );
 
-    if (!usesThree || hasThreeScript) return [];
+    if (!usesThree || hasThreeScript || hasThreeImportMap || hasThreeModuleImport) return [];
     return [
       {
         code: "missing_three_script",
diff --git a/packages/core/src/lint/rules/core.ts b/packages/core/src/lint/rules/core.ts
index b4991d234..273eb340b 100644
--- a/packages/core/src/lint/rules/core.ts
+++ b/packages/core/src/lint/rules/core.ts
@@ -157,7 +157,11 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
     const findings: HyperframeLintFinding[] = [];
     for (const script of scripts) {
       const attrs = script.attrs || "";
-      if (/\bsrc\s*=/.test(attrs) || /\btype\s*=\s*["']application\/json["']/.test(attrs)) continue;
+      if (
+        /\bsrc\s*=/.test(attrs) ||
+        /\btype\s*=\s*["'](?:application\/json|importmap|module)["']/.test(attrs)
+      )
+        continue;
       const syntaxError = getInlineScriptSyntaxError(script.content);
       if (!syntaxError) continue;
       findings.push({
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 5c677959e..01036dc84 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -964,6 +964,11 @@ export function initSandboxRuntimeModular(): void {
     return true;
   };
 
+  (window as Window & { __hfForceTimelineRebind?: () => void }).__hfForceTimelineRebind = () => {
+    childrenBound = false;
+    bindRootTimelineIfAvailable();
+  };
+
   const emitRootStageLayoutDiagnostics = () => {
     const rootNode = resolveRootCompositionElement();
     if (!(rootNode instanceof HTMLElement)) {
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index e945063a2..62b3729e7 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -349,6 +349,54 @@ async function pollPageExpression(
   return Boolean(await page.evaluate(expression));
 }
 
+async function pollSubCompositionTimelines(
+  page: Page,
+  timeoutMs: number,
+  intervalMs: number = 150,
+): Promise<void> {
+  const expression = `(function() {
+    var hosts = document.querySelectorAll("[data-composition-id]");
+    if (hosts.length === 0) return true;
+    var timelines = window.__timelines || {};
+    for (var i = 0; i < hosts.length; i++) {
+      var id = hosts[i].getAttribute("data-composition-id");
+      if (!id) continue;
+      if (!timelines[id]) return false;
+    }
+    return true;
+  })()`;
+  const timelinesBeforePoll = Number(
+    await page.evaluate(`Object.keys(window.__timelines || {}).length`),
+  );
+  const ready = await pollPageExpression(page, expression, timeoutMs, intervalMs);
+  const timelinesAfterPoll = Number(
+    await page.evaluate(`Object.keys(window.__timelines || {}).length`),
+  );
+  if (ready && timelinesAfterPoll > timelinesBeforePoll) {
+    await page.evaluate(`(function() {
+      if (typeof window.__hfForceTimelineRebind === "function") {
+        window.__hfForceTimelineRebind();
+      }
+    })()`);
+  }
+  if (!ready) {
+    const missing = await page.evaluate(`(function() {
+      var hosts = document.querySelectorAll("[data-composition-id]");
+      var timelines = window.__timelines || {};
+      var m = [];
+      for (var i = 0; i < hosts.length; i++) {
+        var id = hosts[i].getAttribute("data-composition-id");
+        if (id && !timelines[id]) m.push(id);
+      }
+      return m.join(", ");
+    })()`);
+    console.warn(
+      `[FrameCapture] Sub-composition timelines not registered after ${timeoutMs}ms: ${missing}. ` +
+        `Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes.`,
+    );
+  }
+}
+
 async function pollVideosReady(
   page: Page,
   skipIds: readonly string[],
@@ -360,7 +408,16 @@ async function pollVideosReady(
       await page.evaluate((skipIdList: readonly string[]) => {
         const skip = new Set(skipIdList);
         const vids = Array.from(document.querySelectorAll("video")).filter((v) => !skip.has(v.id));
-        return vids.length === 0 || vids.every((v) => (v as HTMLVideoElement).readyState >= 2);
+        return (
+          vids.length === 0 ||
+          vids.every((v) => {
+            const ve = v as HTMLVideoElement;
+            if (ve.readyState >= 2) return true;
+            if (ve.error) return true;
+            if (ve.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) return true;
+            return false;
+          })
+        );
       }, skipIds),
     );
   };
@@ -499,6 +556,8 @@ export async function initializeSession(session: CaptureSession): Promise<void>
       );
     }
 
+    await pollSubCompositionTimelines(page, pageReadyTimeout);
+
     await applyVideoMetadataHints(page, session.options.videoMetadataHints);
 
     // Wait for all video elements to have decoded their CURRENT frame, not
@@ -519,8 +578,17 @@ export async function initializeSession(session: CaptureSession): Promise<void>
       pageReadyTimeout,
     );
     if (!videosReady) {
-      throw new Error(
-        `[FrameCapture] video first frame not decoded after ${pageReadyTimeout}ms. Video elements must reach readyState >= 2 (HAVE_CURRENT_DATA) before capture starts.`,
+      const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
+        const skip = new Set(skipIdList);
+        return Array.from(document.querySelectorAll("video"))
+          .filter((v) => !skip.has(v.id))
+          .filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
+          .map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
+          .join(", ");
+      }, session.options.skipReadinessVideoIds ?? []);
+      console.warn(
+        `[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
+          `Continuing render — affected videos will appear as blank/black frames.`,
       );
     }
 
@@ -615,14 +683,30 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     );
   }
 
+  await pollSubCompositionTimelines(page, pageReadyTimeout);
+
   await applyVideoMetadataHints(page, session.options.videoMetadataHints);
 
   // Same readyState contract as the screenshot path above (>= 2 / HAVE_CURRENT_DATA).
-  await pollVideosReady(
+  const bfVideosReady = await pollVideosReady(
     page,
     session.options.skipReadinessVideoIds ?? [],
     session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout,
   );
+  if (!bfVideosReady) {
+    const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
+      const skip = new Set(skipIdList);
+      return Array.from(document.querySelectorAll("video"))
+        .filter((v) => !skip.has(v.id))
+        .filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
+        .map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
+        .join(", ");
+    }, session.options.skipReadinessVideoIds ?? []);
+    console.warn(
+      `[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
+        `Continuing render — affected videos will appear as blank/black frames.`,
+    );
+  }
 
   // Font check (no rAF dependency — uses fonts.ready API directly)
   await page.evaluate(`document.fonts?.ready`);
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
index 67681df04..ef32c2ef2 100644
--- a/packages/engine/src/services/videoFrameExtractor.ts
+++ b/packages/engine/src/services/videoFrameExtractor.ts
@@ -512,8 +512,10 @@ export function resolveProjectRelativeSrc(
   baseDir: string,
   compiledDir?: string,
 ): string {
-  const fromCompiled = compiledDir ? join(compiledDir, src) : null;
-  const fromBase = join(baseDir, src);
+  const qIdx = src.indexOf("?");
+  const cleanSrc = qIdx >= 0 ? src.slice(0, qIdx) : src;
+  const fromCompiled = compiledDir ? join(compiledDir, cleanSrc) : null;
+  const fromBase = join(baseDir, cleanSrc);
   const candidates: string[] = [];
   if (fromCompiled) candidates.push(fromCompiled);
   candidates.push(fromBase);
@@ -528,7 +530,7 @@ export function resolveProjectRelativeSrc(
     // then strip any remaining leading `..` segments. Stripping `..` from the
     // raw input would leave dangling siblings (`assets/../../assets/foo`
     // would become `assets/assets/foo` instead of `assets/foo`).
-    const normalized = posix.normalize(src.replace(/\\/g, "/"));
+    const normalized = posix.normalize(cleanSrc.replace(/\\/g, "/"));
     const stripped = normalized.replace(/^(\.\.\/)+/, "");
     if (stripped && stripped !== src && !stripped.startsWith("..")) {
       if (compiledDir) candidates.push(join(compiledDir, stripped));
diff --git a/packages/producer/node_modules/.bin/esbuild b/packages/producer/node_modules/.bin/esbuild
deleted file mode 120000
index 00d2d93cd..000000000
--- a/packages/producer/node_modules/.bin/esbuild
+++ /dev/null
@@ -1 +0,0 @@
-../../../../node_modules/.bun/@esbuild+darwin-arm64@0.27.7/node_modules/@esbuild/darwin-arm64/bin/esbuild
\ No newline at end of file
diff --git a/packages/producer/node_modules/@types/node b/packages/producer/node_modules/@types/node
deleted file mode 120000
index 454f1340f..000000000
--- a/packages/producer/node_modules/@types/node
+++ /dev/null
@@ -1 +0,0 @@
-../../../../node_modules/.bun/@types+node@22.19.19/node_modules/@types/node
\ No newline at end of file
diff --git a/packages/producer/node_modules/esbuild b/packages/producer/node_modules/esbuild
deleted file mode 120000
index 2bb1f6fa5..000000000
--- a/packages/producer/node_modules/esbuild
+++ /dev/null
@@ -1 +0,0 @@
-../../../node_modules/.bun/esbuild@0.27.7/node_modules/esbuild
\ No newline at end of file
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 533e04c7e..4b9362404 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -578,6 +578,18 @@ function inlineSubCompositions(
     },
   );
 
+  // Set data-hf-authored-id on host elements so the scoped script proxy
+  // can rewrite #id selectors (e.g. #us-map → [data-hf-authored-id="us-map"]).
+  // Unlike flattenInnerRoot (which changes DOM structure and breaks baselines),
+  // this preserves the existing innerHTML-based inlining while enabling the
+  // authored-id selector contract.
+  for (const hostEl of hosts) {
+    const compId = hostEl.getAttribute("data-composition-id");
+    if (compId && !hostEl.getAttribute("data-hf-authored-id")) {
+      hostEl.setAttribute("data-hf-authored-id", compId);
+    }
+  }
+
   // Producer-specific: set explicit pixel dimensions on host elements so
   // children using width/height: 100% resolve correctly. The runtime does
   // this automatically but compiled HTML needs it inline.
diff --git a/registry/blocks/spain-map/registry-item.json b/registry/blocks/spain-map/registry-item.json
new file mode 100644
index 000000000..8329e66a4
--- /dev/null
+++ b/registry/blocks/spain-map/registry-item.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "spain-map",
+  "type": "hyperframes:block",
+  "title": "Spain Map",
+  "description": "Animated Spain choropleth by autonomous community with staggered reveals and gradient legend — D3 conic conformal projection",
+  "tags": ["data", "map", "geography", "spain", "europe", "choropleth"],
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 12,
+  "files": [
+    {
+      "path": "spain-map.html",
+      "target": "compositions/spain-map.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/spain-map/spain-map.html b/registry/blocks/spain-map/spain-map.html
new file mode 100644
index 000000000..28e52d495
--- /dev/null
+++ b/registry/blocks/spain-map/spain-map.html
@@ -0,0 +1,393 @@
+<!doctype html>
+<html lang="es">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Spain 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="spain-map"
+      data-composition-id="spain-map"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="12"
+    >
+      <div class="map-container">
+        <div class="header">
+          <h1 class="headline">PIB per c&aacute;pita por Comunidad Aut&oacute;noma</h1>
+          <p class="subtitle">Producto Interior Bruto per c&aacute;pita, estimaci&oacute;n 2024</p>
+        </div>
+
+        <svg class="map-svg" viewBox="0 0 1400 820" preserveAspectRatio="xMidYMid meet">
+          <g class="regions-group"></g>
+          <g class="labels-group"></g>
+        </svg>
+
+        <div class="legend">
+          <span class="legend-label legend-low">Bajo</span>
+          <div class="legend-bar"></div>
+          <span class="legend-label legend-high">Alto</span>
+        </div>
+
+        <div class="source">Fuente: Instituto Nacional de Estad&iacute;stica</div>
+      </div>
+
+      <style>
+        #spain-map {
+          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;
+        }
+
+        #spain-map .map-container {
+          width: 1700px;
+          height: 950px;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          position: relative;
+        }
+
+        #spain-map .header {
+          text-align: center;
+          margin-bottom: 20px;
+        }
+
+        #spain-map .headline {
+          font-size: 48px;
+          font-weight: 700;
+          letter-spacing: -0.02em;
+          color: #f8fafc;
+          clip-path: inset(0 100% 0 0);
+        }
+
+        #spain-map .subtitle {
+          font-size: 20px;
+          font-weight: 300;
+          color: #94a3b8;
+          margin-top: 8px;
+          opacity: 0;
+        }
+
+        #spain-map .map-svg {
+          width: 1500px;
+          height: 750px;
+          overflow: visible;
+        }
+
+        #spain-map .region-path {
+          stroke: #1e293b;
+          stroke-width: 0.8;
+          opacity: 0;
+          cursor: default;
+        }
+
+        #spain-map .region-label {
+          font-size: 11px;
+          font-weight: 500;
+          fill: #f8fafc;
+          text-anchor: middle;
+          dominant-baseline: central;
+          opacity: 0;
+          pointer-events: none;
+        }
+
+        #spain-map .legend {
+          display: flex;
+          align-items: center;
+          gap: 12px;
+          margin-top: 16px;
+          opacity: 0;
+        }
+
+        #spain-map .legend-bar {
+          width: 300px;
+          height: 12px;
+          border-radius: 6px;
+          background: linear-gradient(90deg, #7f1d1d, #dc2626, #fbbf24);
+        }
+
+        #spain-map .legend-label {
+          font-size: 14px;
+          font-weight: 500;
+          color: #94a3b8;
+        }
+
+        #spain-map .source {
+          position: absolute;
+          bottom: 0;
+          right: 40px;
+          font-size: 12px;
+          color: #475569;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          var SPAIN_TOPO_URL =
+            "https://cdn.jsdelivr.net/npm/es-atlas@0.6.0/es/autonomous_regions.json";
+
+          var data = {
+            "01": { name: "Andalucía", abbr: "AND", gdp: 20200 },
+            "02": { name: "Aragón", abbr: "ARA", gdp: 30500 },
+            "03": { name: "Asturias", abbr: "AST", gdp: 24100 },
+            "04": { name: "Illes Balears", abbr: "BAL", gdp: 28900 },
+            "05": { name: "Canarias", abbr: "CAN", gdp: 21500 },
+            "06": { name: "Cantabria", abbr: "CNT", gdp: 25200 },
+            "07": { name: "Castilla y León", abbr: "CYL", gdp: 25800 },
+            "08": { name: "Castilla-La Mancha", abbr: "CLM", gdp: 21400 },
+            "09": { name: "Catalunya", abbr: "CAT", gdp: 33700 },
+            10: { name: "Comunitat Valenciana", abbr: "VAL", gdp: 23800 },
+            11: { name: "Extremadura", abbr: "EXT", gdp: 19200 },
+            12: { name: "Galicia", abbr: "GAL", gdp: 24500 },
+            13: { name: "Comunidad de Madrid", abbr: "MAD", gdp: 38100 },
+            14: { name: "Región de Murcia", abbr: "MUR", gdp: 22100 },
+            15: { name: "Navarra", abbr: "NAV", gdp: 35200 },
+            16: { name: "País Vasco", abbr: "PVA", gdp: 36800 },
+            17: { name: "La Rioja", abbr: "RIO", gdp: 29800 },
+            18: { name: "Ceuta", abbr: "CEU", gdp: 21000 },
+            19: { name: "Melilla", abbr: "MEL", gdp: 19500 },
+          };
+
+          var nameMap = {};
+          for (var key in data) {
+            nameMap[data[key].name.toLowerCase()] = key;
+          }
+
+          var minGdp = 19200;
+          var maxGdp = 38100;
+
+          function gdpToColor(gdp) {
+            var t = Math.min(Math.max((gdp - minGdp) / (maxGdp - minGdp), 0), 1);
+            if (t < 0.5) {
+              var s = t / 0.5;
+              return lerpColor([127, 29, 29], [220, 38, 38], s);
+            } else {
+              var s2 = (t - 0.5) / 0.5;
+              return lerpColor([220, 38, 38], [251, 191, 36], s2);
+            }
+          }
+
+          function lerpColor(a, b, t) {
+            var r = Math.round(a[0] + (b[0] - a[0]) * t);
+            var g = Math.round(a[1] + (b[1] - a[1]) * t);
+            var bl = Math.round(a[2] + (b[2] - a[2]) * t);
+            return "rgb(" + r + "," + g + "," + bl + ")";
+          }
+
+          function findData(feature) {
+            var id = String(feature.id).padStart(2, "0");
+            if (data[id]) return data[id];
+            var fname = (feature.properties && feature.properties.name) || "";
+            var fnameLower = fname.toLowerCase();
+            for (var k in data) {
+              var dname = data[k].name.toLowerCase();
+              if (fnameLower.indexOf(dname) >= 0 || dname.indexOf(fnameLower) >= 0) {
+                return data[k];
+              }
+            }
+            return null;
+          }
+
+          var svg = document.querySelector("#spain-map .map-svg");
+          var regionsGroup = svg.querySelector(".regions-group");
+          var labelsGroup = svg.querySelector(".labels-group");
+          var tl = gsap.timeline({ paused: true });
+
+          fetch(SPAIN_TOPO_URL)
+            .then(function (r) {
+              return r.json();
+            })
+            .then(function (es) {
+              var featureCollection = topojson.feature(es, es.objects.autonomous_regions);
+              var features = featureCollection.features;
+
+              var projection = d3
+                .geoConicConformal()
+                .center([0, 39.5])
+                .rotate([3.5, 0])
+                .fitSize([1200, 750], featureCollection);
+              var path = d3.geoPath().projection(projection);
+
+              var sortedFeatures = features
+                .filter(function (f) {
+                  return findData(f) !== null;
+                })
+                .sort(function (a, b) {
+                  return findData(a).gdp - findData(b).gdp;
+                });
+
+              sortedFeatures.forEach(function (feature) {
+                var info = findData(feature);
+                if (!info) return;
+
+                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", "region-path");
+                el.setAttribute("data-region", info.abbr);
+                el.setAttribute("data-gdp", String(info.gdp));
+                el.style.fill = gdpToColor(info.gdp);
+                regionsGroup.appendChild(el);
+
+                var centroid = path.centroid(feature);
+                if (centroid[0] && centroid[1]) {
+                  var label = document.createElementNS("http://www.w3.org/2000/svg", "text");
+                  label.setAttribute("x", String(centroid[0]));
+                  label.setAttribute("y", String(centroid[1]));
+                  label.setAttribute("class", "region-label");
+                  label.textContent = info.abbr;
+                  labelsGroup.appendChild(label);
+                }
+              });
+
+              buildTimeline();
+            });
+
+          function buildTimeline() {
+            var regionPaths = regionsGroup.querySelectorAll(".region-path");
+            var regionLabels = labelsGroup.querySelectorAll(".region-label");
+
+            tl.to(
+              "#spain-map .headline",
+              {
+                clipPath: "inset(0 0% 0 0)",
+                duration: 1.0,
+                ease: "power2.inOut",
+              },
+              0,
+            );
+
+            tl.to(
+              "#spain-map .subtitle",
+              {
+                opacity: 1,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              0.4,
+            );
+
+            tl.to(
+              regionPaths,
+              {
+                opacity: 1,
+                scale: 1,
+                duration: 0.4,
+                stagger: {
+                  each: 0.08,
+                  from: "center",
+                },
+                ease: "back.out(1.4)",
+              },
+              1.0,
+            );
+
+            tl.to(
+              regionLabels,
+              {
+                opacity: 1,
+                duration: 0.3,
+                stagger: {
+                  each: 0.05,
+                  from: "center",
+                },
+                ease: "power2.out",
+              },
+              4.0,
+            );
+
+            tl.to(
+              "#spain-map .legend",
+              {
+                opacity: 1,
+                y: 0,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              5.5,
+            );
+
+            tl.to(
+              "#spain-map .source",
+              {
+                opacity: 1,
+                duration: 0.5,
+                ease: "power2.out",
+              },
+              6.0,
+            );
+
+            var highlightRegions = ["MAD", "PVA", "NAV"];
+            highlightRegions.forEach(function (abbr, i) {
+              var el = regionsGroup.querySelector('[data-region="' + abbr + '"]');
+              if (!el) return;
+
+              tl.to(
+                el,
+                {
+                  filter: "brightness(1.5) drop-shadow(0 0 8px rgba(255,255,255,0.4))",
+                  stroke: "#f8fafc",
+                  strokeWidth: 2.5,
+                  duration: 0.5,
+                  ease: "power2.out",
+                },
+                6.5 + i * 0.8,
+              );
+
+              tl.to(
+                el,
+                {
+                  filter: "brightness(1) drop-shadow(0 0 0px rgba(255,255,255,0))",
+                  stroke: "#1e293b",
+                  strokeWidth: 0.8,
+                  duration: 0.5,
+                  ease: "power2.in",
+                },
+                7.0 + i * 0.8,
+              );
+            });
+
+            window.__timelines = window.__timelines || {};
+            window.__timelines["spain-map"] = tl;
+          }
+        })();
+      </script>
+    </div>
+  </body>
+</html>
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/us-map/registry-item.json b/registry/blocks/us-map/registry-item.json
new file mode 100644
index 000000000..b842ce50d
--- /dev/null
+++ b/registry/blocks/us-map/registry-item.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "us-map",
+  "type": "hyperframes:block",
+  "title": "US Map",
+  "description": "Animated US choropleth map with staggered state reveals, value labels, and gradient legend — pure inline SVG with GSAP",
+  "tags": ["data", "map", "geography", "usa", "choropleth"],
+  "dimensions": {
+    "width": 1920,
+    "height": 1080
+  },
+  "duration": 12,
+  "files": [
+    {
+      "path": "us-map.html",
+      "target": "compositions/us-map.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
diff --git a/registry/blocks/us-map/us-map.html b/registry/blocks/us-map/us-map.html
new file mode 100644
index 000000000..3a8c59a3b
--- /dev/null
+++ b/registry/blocks/us-map/us-map.html
@@ -0,0 +1,402 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>US 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"
+      data-composition-id="us-map"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="12"
+    >
+      <div class="map-container">
+        <div class="header">
+          <h1 class="headline">Population Density by State</h1>
+          <p class="subtitle">Residents per square mile, 2024 Census estimates</p>
+        </div>
+
+        <svg class="map-svg" viewBox="0 0 1400 820" preserveAspectRatio="xMidYMid meet">
+          <g class="states-group"></g>
+          <g class="labels-group"></g>
+        </svg>
+
+        <div class="legend">
+          <span class="legend-label legend-low">Low</span>
+          <div class="legend-bar"></div>
+          <span class="legend-label legend-high">High</span>
+        </div>
+
+        <div class="source">Source: U.S. Census Bureau</div>
+      </div>
+
+      <style>
+        #us-map {
+          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 .map-container {
+          width: 1700px;
+          height: 950px;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          position: relative;
+        }
+
+        #us-map .header {
+          text-align: center;
+          margin-bottom: 20px;
+        }
+
+        #us-map .headline {
+          font-size: 52px;
+          font-weight: 700;
+          letter-spacing: -0.02em;
+          color: #f8fafc;
+          clip-path: inset(0 100% 0 0);
+        }
+
+        #us-map .subtitle {
+          font-size: 20px;
+          font-weight: 300;
+          color: #94a3b8;
+          margin-top: 8px;
+          opacity: 0;
+        }
+
+        #us-map .map-svg {
+          width: 1500px;
+          height: 750px;
+          overflow: visible;
+        }
+
+        #us-map .state-path {
+          stroke: #1e293b;
+          stroke-width: 1.2;
+          opacity: 0;
+          cursor: default;
+        }
+
+        #us-map .state-label {
+          font-size: 10px;
+          font-weight: 500;
+          fill: #f8fafc;
+          text-anchor: middle;
+          dominant-baseline: central;
+          opacity: 0;
+          pointer-events: none;
+          text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
+        }
+
+        #us-map .legend {
+          display: flex;
+          align-items: center;
+          gap: 12px;
+          margin-top: 16px;
+          opacity: 0;
+        }
+
+        #us-map .legend-bar {
+          width: 300px;
+          height: 12px;
+          border-radius: 6px;
+          background: linear-gradient(90deg, #1e3a5f, #2563eb, #7c3aed, #ec4899);
+        }
+
+        #us-map .legend-label {
+          font-size: 14px;
+          font-weight: 500;
+          color: #94a3b8;
+        }
+
+        #us-map .source {
+          position: absolute;
+          bottom: 0;
+          right: 40px;
+          font-size: 12px;
+          color: #475569;
+          opacity: 0;
+        }
+      </style>
+
+      <script>
+        (function () {
+          const US_TOPO_URL = "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json";
+
+          const stateData = {
+            "01": { name: "Alabama", abbr: "AL", density: 99.2 },
+            "02": { name: "Alaska", abbr: "AK", density: 1.3 },
+            "04": { name: "Arizona", abbr: "AZ", density: 63.5 },
+            "05": { name: "Arkansas", abbr: "AR", density: 58.1 },
+            "06": { name: "California", abbr: "CA", density: 253.9 },
+            "08": { name: "Colorado", abbr: "CO", density: 56.5 },
+            "09": { name: "Connecticut", abbr: "CT", density: 738.1 },
+            10: { name: "Delaware", abbr: "DE", density: 508.0 },
+            12: { name: "Florida", abbr: "FL", density: 410.5 },
+            13: { name: "Georgia", abbr: "GA", density: 185.6 },
+            15: { name: "Hawaii", abbr: "HI", density: 226.6 },
+            16: { name: "Idaho", abbr: "ID", density: 22.8 },
+            17: { name: "Illinois", abbr: "IL", density: 228.2 },
+            18: { name: "Indiana", abbr: "IN", density: 186.7 },
+            19: { name: "Iowa", abbr: "IA", density: 57.1 },
+            20: { name: "Kansas", abbr: "KS", density: 35.9 },
+            21: { name: "Kentucky", abbr: "KY", density: 113.2 },
+            22: { name: "Louisiana", abbr: "LA", density: 107.7 },
+            23: { name: "Maine", abbr: "ME", density: 43.8 },
+            24: { name: "Maryland", abbr: "MD", density: 636.1 },
+            25: { name: "Massachusetts", abbr: "MA", density: 901.2 },
+            26: { name: "Michigan", abbr: "MI", density: 176.4 },
+            27: { name: "Minnesota", abbr: "MN", density: 71.7 },
+            28: { name: "Mississippi", abbr: "MS", density: 63.5 },
+            29: { name: "Missouri", abbr: "MO", density: 89.5 },
+            30: { name: "Montana", abbr: "MT", density: 7.6 },
+            31: { name: "Nebraska", abbr: "NE", density: 25.3 },
+            32: { name: "Nevada", abbr: "NV", density: 28.3 },
+            33: { name: "New Hampshire", abbr: "NH", density: 153.2 },
+            34: { name: "New Jersey", abbr: "NJ", density: 1263.0 },
+            35: { name: "New Mexico", abbr: "NM", density: 17.4 },
+            36: { name: "New York", abbr: "NY", density: 415.3 },
+            37: { name: "North Carolina", abbr: "NC", density: 214.7 },
+            38: { name: "North Dakota", abbr: "ND", density: 11.3 },
+            39: { name: "Ohio", abbr: "OH", density: 288.8 },
+            40: { name: "Oklahoma", abbr: "OK", density: 57.7 },
+            41: { name: "Oregon", abbr: "OR", density: 43.9 },
+            42: { name: "Pennsylvania", abbr: "PA", density: 286.1 },
+            44: { name: "Rhode Island", abbr: "RI", density: 1061.4 },
+            45: { name: "South Carolina", abbr: "SC", density: 170.2 },
+            46: { name: "South Dakota", abbr: "SD", density: 12.2 },
+            47: { name: "Tennessee", abbr: "TN", density: 167.0 },
+            48: { name: "Texas", abbr: "TX", density: 112.8 },
+            49: { name: "Utah", abbr: "UT", density: 40.3 },
+            50: { name: "Vermont", abbr: "VT", density: 68.0 },
+            51: { name: "Virginia", abbr: "VA", density: 218.6 },
+            53: { name: "Washington", abbr: "WA", density: 115.9 },
+            54: { name: "West Virginia", abbr: "WV", density: 74.6 },
+            55: { name: "Wisconsin", abbr: "WI", density: 108.8 },
+            56: { name: "Wyoming", abbr: "WY", density: 5.8 },
+          };
+
+          const maxDensity = 500;
+
+          function densityToColor(d) {
+            const t = Math.min(d / maxDensity, 1);
+            if (t < 0.33) {
+              const s = t / 0.33;
+              return lerpColor([30, 58, 95], [37, 99, 235], s);
+            } else if (t < 0.66) {
+              const s = (t - 0.33) / 0.33;
+              return lerpColor([37, 99, 235], [124, 58, 237], s);
+            } else {
+              const s = (t - 0.66) / 0.34;
+              return lerpColor([124, 58, 237], [236, 72, 153], s);
+            }
+          }
+
+          function lerpColor(a, b, t) {
+            const r = Math.round(a[0] + (b[0] - a[0]) * t);
+            const g = Math.round(a[1] + (b[1] - a[1]) * t);
+            const bl = Math.round(a[2] + (b[2] - a[2]) * t);
+            return "rgb(" + r + "," + g + "," + bl + ")";
+          }
+
+          const svg = document.querySelector("#us-map .map-svg");
+          const statesGroup = svg.querySelector(".states-group");
+          const labelsGroup = svg.querySelector(".labels-group");
+          const tl = gsap.timeline({ paused: true });
+
+          fetch(US_TOPO_URL)
+            .then((r) => r.json())
+            .then((us) => {
+              const states = topojson.feature(us, us.objects.states).features;
+              const projection = d3
+                .geoAlbersUsa()
+                .fitSize([1380, 800], { type: "FeatureCollection", features: states });
+              const path = d3.geoPath().projection(projection);
+
+              const sortedStates = states
+                .filter((f) => stateData[String(f.id).padStart(2, "0")])
+                .sort((a, b) => {
+                  const aData = stateData[String(a.id).padStart(2, "0")];
+                  const bData = stateData[String(b.id).padStart(2, "0")];
+                  return aData.density - bData.density;
+                });
+
+              sortedStates.forEach((feature) => {
+                const fips = String(feature.id).padStart(2, "0");
+                const info = stateData[fips];
+                if (!info) return;
+
+                const d = path(feature);
+                if (!d) return;
+
+                const el = document.createElementNS("http://www.w3.org/2000/svg", "path");
+                el.setAttribute("d", d);
+                el.setAttribute("class", "state-path");
+                el.setAttribute("data-state", info.abbr);
+                el.setAttribute("data-density", info.density);
+                el.style.fill = densityToColor(info.density);
+                statesGroup.appendChild(el);
+
+                const centroid = path.centroid(feature);
+                if (centroid[0] && centroid[1]) {
+                  const label = document.createElementNS("http://www.w3.org/2000/svg", "text");
+                  label.setAttribute("x", centroid[0]);
+                  label.setAttribute("y", centroid[1]);
+                  label.setAttribute("class", "state-label");
+                  label.textContent = info.abbr;
+                  labelsGroup.appendChild(label);
+                }
+              });
+
+              buildTimeline();
+            });
+
+          function buildTimeline() {
+            const statePaths = statesGroup.querySelectorAll(".state-path");
+            const stateLabels = labelsGroup.querySelectorAll(".state-label");
+
+            tl.to(
+              "#us-map .headline",
+              {
+                clipPath: "inset(0 0% 0 0)",
+                duration: 1.0,
+                ease: "power2.inOut",
+              },
+              0,
+            );
+
+            tl.to(
+              "#us-map .subtitle",
+              {
+                opacity: 1,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              0.4,
+            );
+
+            tl.to(
+              statePaths,
+              {
+                opacity: 1,
+                scale: 1,
+                duration: 0.4,
+                stagger: {
+                  each: 0.06,
+                  from: "center",
+                },
+                ease: "back.out(1.4)",
+              },
+              1.0,
+            );
+
+            tl.to(
+              stateLabels,
+              {
+                opacity: 1,
+                duration: 0.3,
+                stagger: {
+                  each: 0.04,
+                  from: "center",
+                },
+                ease: "power2.out",
+              },
+              3.5,
+            );
+
+            tl.to(
+              "#us-map .legend",
+              {
+                opacity: 1,
+                y: 0,
+                duration: 0.6,
+                ease: "power2.out",
+              },
+              5.0,
+            );
+
+            tl.to(
+              "#us-map .source",
+              {
+                opacity: 1,
+                duration: 0.5,
+                ease: "power2.out",
+              },
+              5.5,
+            );
+
+            const highlightStates = ["CA", "NY", "TX", "FL", "NJ"];
+            highlightStates.forEach((abbr, i) => {
+              const el = statesGroup.querySelector('[data-state="' + abbr + '"]');
+              if (!el) return;
+
+              tl.to(
+                el,
+                {
+                  filter: "brightness(1.6) drop-shadow(0 0 8px rgba(255,255,255,0.4))",
+                  stroke: "#f8fafc",
+                  strokeWidth: 2.5,
+                  duration: 0.5,
+                  ease: "power2.out",
+                },
+                6.5 + i * 0.8,
+              );
+
+              tl.to(
+                el,
+                {
+                  filter: "brightness(1) drop-shadow(0 0 0px rgba(255,255,255,0))",
+                  stroke: "#1e293b",
+                  strokeWidth: 1.2,
+                  duration: 0.5,
+                  ease: "power2.in",
+                },
+                7.0 + i * 0.8,
+              );
+            });
+
+            window.__timelines = window.__timelines || {};
+            window.__timelines["us-map"] = 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..4e451c217
--- /dev/null
+++ b/registry/blocks/world-map/world-map.html
@@ -0,0 +1,435 @@
+<!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: "center",
+              },
+              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 26c8ffd02..0fb114096 100644
--- a/registry/registry.json
+++ b/registry/registry.json
@@ -39,6 +39,30 @@
       "name": "data-chart",
       "type": "hyperframes:block"
     },
+    {
+      "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": "spain-map",
+      "type": "hyperframes:block"
+    },
     {
       "name": "flowchart",
       "type": "hyperframes:block"