From 278bc712d7b40d03cd3bfa6a705cf64e2f709c34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 24 Sep 2026 23:44:04 -0400
Subject: [PATCH] fix(core): a mounted composition's import map and module
 scripts run as such (#4446)

* feat(core): a composition's script can load its own files with __hyperframes.assetUrl

* test(core): a template composition inside a mounted file resolves assets from that file

* docs: assetUrl is for paths beside the composition, not project-root paths

* docs: say assetUrl misses a project-root path

* fix(core): a mounted composition's import map and module scripts run as such

* refactor(core): scope a mounted module script under the same condition as a classic one

* fix(core): a mounted module script loaded by src stays a module

* fix(core): a mounted import map keeps the trailing slash of a prefix address

* chore(core): keep the module-script helpers' comment share at the base
---
 .../src/compiler/compositionScoping.test.ts   |  21 ++++
 .../core/src/compiler/compositionScoping.ts   |  38 ++++---
 packages/core/src/compiler/externalScripts.ts |   3 +
 .../core/src/compiler/htmlBundler.test.ts     |  49 +++++++++
 packages/core/src/compiler/htmlBundler.ts     |   6 +-
 packages/core/src/compiler/importMaps.test.ts |  55 ++++++++++
 packages/core/src/compiler/importMaps.ts      | 102 ++++++++++++++++++
 packages/core/src/compiler/index.ts           |   1 +
 .../src/compiler/inlineSubCompositions.ts     |  40 ++++++-
 .../src/runtime/compositionLoader.test.ts     |  24 +++++
 .../core/src/runtime/compositionLoader.ts     |  20 +++-
 .../htmlCompiler.moduleScripts.test.ts        |  66 ++++++++++++
 .../producer/src/services/htmlCompiler.ts     |   8 ++
 13 files changed, 414 insertions(+), 19 deletions(-)
 create mode 100644 packages/core/src/compiler/importMaps.test.ts
 create mode 100644 packages/core/src/compiler/importMaps.ts
 create mode 100644 packages/producer/src/services/htmlCompiler.moduleScripts.test.ts

diff --git a/packages/core/src/compiler/compositionScoping.test.ts b/packages/core/src/compiler/compositionScoping.test.ts
index 2449f21349..b5bb34fc25 100644
--- a/packages/core/src/compiler/compositionScoping.test.ts
+++ b/packages/core/src/compiler/compositionScoping.test.ts
@@ -4,6 +4,7 @@ import {
   buildVariablesByCompScript,
   scopeCssToComposition,
   wrapInlineScriptWithErrorBoundary,
+  scopedModulePrelude,
   wrapScopedCompositionScript,
 } from "./compositionScoping";
 
@@ -165,6 +166,26 @@ body { margin: 0; }
     expect(fakeWindow.__captured).toEqual({ title: "Pro", price: "$29" });
   });
 
+  it("gives a mounted module script its composition's own __hyperframes", () => {
+    const { document } = parseHTML(`<div></div>`);
+    Object.defineProperty(document, "baseURI", { value: "https://p.test/preview/" });
+    const fakeWindow = {
+      document,
+      __hfVariablesByComp: { blk: { title: "Hi" }, other: { title: "No" } },
+      __hyperframes: { assetUrl: () => "TOP-LEVEL", getVariables: () => ({}), fitTextFontSize: 1 },
+    };
+    const scoped = new Function(
+      "window",
+      `${scopedModulePrelude("blk", "compositions/blk/blk.html")}return __hyperframes;`,
+    )(fakeWindow);
+
+    expect(scoped.assetUrl("assets/env.hdr")).toBe(
+      "https://p.test/preview/compositions/blk/assets/env.hdr",
+    );
+    expect(scoped.getVariables()).toEqual({ title: "Hi" });
+    expect(scoped.fitTextFontSize).toBe(1);
+  });
+
   it("resolves __hyperframes.assetUrl against the mounted composition's own file", () => {
     const run = (compositionSrc?: string) => {
       const { document } = parseHTML(`<div data-composition-id="blk"></div>`);
diff --git a/packages/core/src/compiler/compositionScoping.ts b/packages/core/src/compiler/compositionScoping.ts
index 133f861e9a..f463fefca0 100644
--- a/packages/core/src/compiler/compositionScoping.ts
+++ b/packages/core/src/compiler/compositionScoping.ts
@@ -276,6 +276,30 @@ function jsonScriptLiteral(value: unknown): string {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
 
+const SCOPED_HYPERFRAMES_EXPRESSION = `!__hfBaseHyperframes
+    ? __hfBaseHyperframes
+    : Object.assign({}, __hfBaseHyperframes, {
+        assetUrl: function(path) {
+          var page = window.document.baseURI;
+          return new URL(path, __hfCompositionSrc ? new URL(__hfCompositionSrc, page) : page).href;
+        },
+        getVariables: function() {
+          var byComp = window.__hfVariablesByComp;
+          var scoped = byComp && __hfTimelineCompId ? byComp[__hfTimelineCompId] : null;
+          return scoped ? Object.assign({}, scoped) : {};
+        },
+      })`;
+
+export function scopedModulePrelude(
+  timelineCompositionId: string,
+  compositionSrc?: string | null,
+): string {
+  return `const __hyperframes = (function(__hfBaseHyperframes, __hfTimelineCompId, __hfCompositionSrc) {
+  return ${SCOPED_HYPERFRAMES_EXPRESSION};
+})(window.__hyperframes, ${jsonScriptLiteral(timelineCompositionId)}, ${jsonScriptLiteral(compositionSrc?.trim() || null)});
+`;
+}
+
 export function wrapScopedCompositionScript(
   source: string,
   compositionId: string,
@@ -611,19 +635,7 @@ export function wrapScopedCompositionScript(
         },
       });
   var __hfBaseHyperframes = window.__hyperframes;
-  var __hfScopedHyperframes = !__hfBaseHyperframes
-    ? __hfBaseHyperframes
-    : Object.assign({}, __hfBaseHyperframes, {
-        assetUrl: function(path) {
-          var page = window.document.baseURI;
-          return new URL(path, __hfCompositionSrc ? new URL(__hfCompositionSrc, page) : page).href;
-        },
-        getVariables: function() {
-          var byComp = window.__hfVariablesByComp;
-          var scoped = byComp && __hfTimelineCompId ? byComp[__hfTimelineCompId] : null;
-          return scoped ? Object.assign({}, scoped) : {};
-        },
-      });
+  var __hfScopedHyperframes = ${SCOPED_HYPERFRAMES_EXPRESSION};
   var __hfRun = function() {
     try {
       (function(document, gsap, window, __hyperframes) {
diff --git a/packages/core/src/compiler/externalScripts.ts b/packages/core/src/compiler/externalScripts.ts
index 796a5f46c6..3b440ba6cf 100644
--- a/packages/core/src/compiler/externalScripts.ts
+++ b/packages/core/src/compiler/externalScripts.ts
@@ -1,12 +1,14 @@
 export interface ExternalScriptAttributes {
   integrity?: string;
   crossorigin?: string;
+  type?: "module";
 }
 
 export function readExternalScriptAttributes(el: Element): ExternalScriptAttributes {
   const attributes: ExternalScriptAttributes = {};
   if (el.hasAttribute("integrity")) attributes.integrity = el.getAttribute("integrity") || "";
   if (el.hasAttribute("crossorigin")) attributes.crossorigin = el.getAttribute("crossorigin") || "";
+  if ((el.getAttribute("type") || "").trim().toLowerCase() === "module") attributes.type = "module";
   return attributes;
 }
 
@@ -40,6 +42,7 @@ export function ensureExternalScriptTag(
     if (integrity) el.setAttribute("integrity", integrity);
     if (attributes.crossorigin !== undefined)
       el.setAttribute("crossorigin", attributes.crossorigin);
+    if (attributes.type) el.setAttribute("type", attributes.type);
   }
   if (!existing.length) {
     const el = elements[0]!;
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index e5432c615c..d092ea3dd6 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -198,6 +198,55 @@ describe("bundleToSingleHtml", () => {
     expect(bundled).toContain('var __hfCompositionSrc = "compositions/blk/blk.html";');
   });
 
+  it("keeps a mounted file's import map and module script as such, bound to that file", async () => {
+    const dir = makeTempProject({
+      "index.html": `<!doctype html>
+<html><head></head><body>
+  <div id="root" data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="blk-host" data-composition-id="blk" data-composition-src="compositions/blk/blk.html"
+      data-start="0" data-duration="5"></div>
+  </div>
+</body></html>`,
+      "compositions/blk/assets/three.js": "export const REVISION = 1;",
+      "compositions/blk/assets/addons/env.js": "export const ENV = 1;",
+      "compositions/blk/assets/scene.js": 'import * as THREE from "three"; export const SCENE = 1;',
+      "compositions/blk/blk.html": `<div data-composition-id="blk" data-width="1920" data-height="1080">
+  <script type="module" src="./assets/scene.js"></script>
+  <script type="module" src="https://cdn.test/mod.js"></script>
+  <script type="importmap">{ "imports": { "three": "./assets/three.js", "three/addons/": "./assets/addons/", "cdn": "https://cdn.test/x.js" } }</script>
+  <script type="module">import * as THREE from "three"; window.__url = __hyperframes.assetUrl("assets/leaf.webp");</script>
+  <script>window.__classic = 1;</script>
+</div>`,
+    });
+
+    const { document } = parseHTML(await bundleToSingleHtml(dir));
+    const importMaps = [...document.querySelectorAll('script[type="importmap"]')];
+    const modules = [...document.querySelectorAll('script[type="module"]')];
+    const classic = [...document.querySelectorAll("script:not([type])")].map((s) => s.textContent);
+
+    expect(importMaps).toHaveLength(1);
+    expect(JSON.parse(importMaps[0]!.textContent || "")).toEqual({
+      imports: {
+        three: "./compositions/blk/assets/three.js",
+        "three/addons/": "./compositions/blk/assets/addons/",
+        cdn: "https://cdn.test/x.js",
+      },
+    });
+    expect(modules.map((m) => m.getAttribute("src")).filter(Boolean)).toEqual([
+      "compositions/blk/assets/scene.js",
+      "https://cdn.test/mod.js",
+    ]);
+    const inline = modules.filter((m) => !m.hasAttribute("src"));
+    expect(inline).toHaveLength(1);
+    expect(inline[0]!.textContent).toMatch(/^const __hyperframes = /);
+    expect(inline[0]!.textContent).toContain('"compositions/blk/blk.html"');
+    expect(inline[0]!.textContent).toContain('import * as THREE from "three";');
+    expect(classic.join("")).not.toContain("SCENE");
+    expect(classic.join("")).toContain(".__classic = 1;");
+    expect(classic.join("")).not.toContain('"imports"');
+    expect(classic.join("")).not.toContain("import * as THREE");
+  });
+
   it("binds a <template> composition authored in a mounted file to that file", async () => {
     const dir = makeTempProject({
       "index.html": `<!doctype html>
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index 3560e25f98..d80c7448dd 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -4,6 +4,7 @@ import {
   readExternalScriptAttributes,
   type ExternalScriptAttributes,
 } from "./externalScripts";
+import { emitMountedModuleScripts } from "./importMaps";
 import { markFlattenedInnerRoot } from "../runtime/flattenedRoot";
 export { FLATTENED_INNER_ROOT_STRIP_ATTRS } from "../runtime/flattenedRoot";
 import { parseHostVariableValues, warnUnknownEnumValues } from "../runtime/getVariables";
@@ -846,7 +847,7 @@ function hoistExternalScript(
   }
   if (seenSrcs.has(src)) return;
   seenSrcs.add(src);
-  if (!isNonRelativeUrl(src) && !isAbsolute(src)) {
+  if (!isNonRelativeUrl(src) && !isAbsolute(src) && attributes.type !== "module") {
     const jsPath = resolveWithinProject(projectDir, src);
     const js = jsPath ? safeReadFile(jsPath) : null;
     if (js != null) {
@@ -1023,7 +1024,7 @@ export async function bundleToSingleHtml(
     }
     if (seenCompScriptSrcs.has(extSrc)) continue;
     seenCompScriptSrcs.add(extSrc);
-    if (isRelativeUrl(extSrc)) {
+    if (isRelativeUrl(extSrc) && scriptItem.type !== "module") {
       const jsPath = resolveEntryPath(extSrc);
       const js = jsPath ? safeReadFile(jsPath) : null;
       if (js != null) {
@@ -1214,6 +1215,7 @@ export async function bundleToSingleHtml(
     );
     document.body.appendChild(compScript);
   }
+  emitMountedModuleScripts(document, subCompResult.importMaps, subCompResult.moduleScripts);
 
   emitRootCompositionVariableStyles(document, compVariablesByComp);
 
diff --git a/packages/core/src/compiler/importMaps.test.ts b/packages/core/src/compiler/importMaps.test.ts
new file mode 100644
index 0000000000..fd846445a9
--- /dev/null
+++ b/packages/core/src/compiler/importMaps.test.ts
@@ -0,0 +1,55 @@
+import { parseHTML } from "linkedom";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mergeImportMapsIntoDocument, parseImportMap } from "./importMaps";
+
+afterEach(() => vi.restoreAllMocks());
+
+const pageWith = (head: string) =>
+  parseHTML(`<!doctype html><html><head>${head}</head><body></body></html>`).document;
+const mapOf = (doc: Document) =>
+  JSON.parse(doc.querySelector('script[type="importmap"]')?.textContent || "null");
+
+describe("parseImportMap", () => {
+  it("rebases imports and scopes, and rejects what the browser would reject", () => {
+    const rebase = (url: string) => `R(${url})`;
+    expect(
+      parseImportMap(`{"imports":{"a":"./a.js"},"scopes":{"./s/":{"b":"./b.js"}}}`, rebase),
+    ).toEqual({ imports: { a: "R(./a.js)" }, scopes: { "R(./s/)": { b: "R(./b.js)" } } });
+    expect(parseImportMap("{ not json", rebase)).toBeNull();
+    expect(parseImportMap("null", rebase)).toBeNull();
+  });
+});
+
+describe("mergeImportMapsIntoDocument", () => {
+  it("creates the page's one import map ahead of every script when it has none", () => {
+    const doc = pageWith(`<script type="module" src="x.js"></script>`);
+    mergeImportMapsIntoDocument(doc, [{ imports: { three: "./t.js" } }]);
+    expect(doc.head.firstElementChild?.getAttribute("type")).toBe("importmap");
+    expect(mapOf(doc)).toEqual({ imports: { three: "./t.js" } });
+  });
+
+  it("keeps the first mapping of a specifier and warns about a conflicting one", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const doc = pageWith(
+      `<script type="importmap">{"imports":{"three":"./page.js"},"integrity":{"./page.js":"sha384-x"}}</script>`,
+    );
+    mergeImportMapsIntoDocument(doc, [
+      { imports: { three: "./mounted.js", gsap: "./g.js" }, scopes: { "./s/": { a: "./a.js" } } },
+      { imports: { gsap: "./g.js" }, scopes: { "./s/": { a: "./other.js" } } },
+    ]);
+    expect(doc.querySelectorAll('script[type="importmap"]')).toHaveLength(1);
+    expect(mapOf(doc)).toEqual({
+      imports: { three: "./page.js", gsap: "./g.js" },
+      scopes: { "./s/": { a: "./a.js" } },
+      integrity: { "./page.js": "sha384-x" },
+    });
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(String(warn.mock.calls[0]?.[0])).toContain('"three"');
+  });
+
+  it("leaves the page alone when no mounted file declares a map", () => {
+    const doc = pageWith("");
+    mergeImportMapsIntoDocument(doc, []);
+    expect(doc.querySelector('script[type="importmap"]')).toBeNull();
+  });
+});
diff --git a/packages/core/src/compiler/importMaps.ts b/packages/core/src/compiler/importMaps.ts
new file mode 100644
index 0000000000..2dd87ffd64
--- /dev/null
+++ b/packages/core/src/compiler/importMaps.ts
@@ -0,0 +1,102 @@
+/** The subset of an import map a composition can declare. */
+export interface ImportMap {
+  imports?: Record<string, string>;
+  scopes?: Record<string, Record<string, string>>;
+}
+
+const rebaseEntries = (
+  entries: Record<string, string> | undefined,
+  rebase: (url: string) => string,
+): Record<string, string> | undefined =>
+  entries &&
+  Object.fromEntries(Object.entries(entries).map(([specifier, url]) => [specifier, rebase(url)]));
+
+/**
+ * Parses a mounted composition's import map, rebasing each address the way its `src`/`href`
+ * attributes are rebased. Returns null for a map the browser would reject too.
+ */
+export function parseImportMap(json: string, rebase: (url: string) => string): ImportMap | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const { imports, scopes } = parsed as ImportMap;
+  return {
+    imports: rebaseEntries(imports, rebase),
+    scopes:
+      scopes &&
+      Object.fromEntries(
+        Object.entries(scopes).map(([prefix, entries]) => [
+          rebase(prefix),
+          rebaseEntries(entries, rebase) ?? {},
+        ]),
+      ),
+  };
+}
+
+function mergeEntries(
+  into: Record<string, string>,
+  from: Record<string, string> | undefined,
+  where: string,
+): void {
+  for (const [specifier, url] of Object.entries(from ?? {})) {
+    if (!(specifier in into)) into[specifier] = url;
+    else if (into[specifier] !== url) {
+      console.warn(
+        `[HyperFrames] import map conflict for "${specifier}"${where}: keeping ${into[specifier]}, ignoring ${url}.`,
+      );
+    }
+  }
+}
+
+/**
+ * A page has one import map, and it must precede every module script. Mounted compositions'
+ * maps merge into the page's own (created at the top of <head> if absent); the first mapping
+ * of a specifier wins and a conflicting later one is dropped with a warning.
+ */
+export function mergeImportMapsIntoDocument(doc: Document, maps: ImportMap[]): void {
+  if (maps.length === 0) return;
+  let el = doc.querySelector('script[type="importmap"]');
+  let page: ImportMap & Record<string, unknown> = {};
+  try {
+    page = el ? JSON.parse(el.textContent || "{}") : {};
+  } catch {
+    console.warn("[HyperFrames] the page's import map is not valid JSON; replacing it.");
+  }
+  const imports = { ...page.imports };
+  const scopes = { ...page.scopes };
+  for (const map of maps) {
+    mergeEntries(imports, map.imports, "");
+    for (const [prefix, entries] of Object.entries(map.scopes ?? {})) {
+      mergeEntries((scopes[prefix] ??= {}), entries, ` in scope ${prefix}`);
+    }
+  }
+  if (!el) {
+    el = doc.createElement("script");
+    el.setAttribute("type", "importmap");
+    doc.head.prepend(el);
+  }
+  el.textContent = JSON.stringify({
+    ...page,
+    imports,
+    ...(Object.keys(scopes).length ? { scopes } : {}),
+  }).replace(/</g, "\\u003c");
+}
+
+/** Emits what inlineSubCompositions collected from mounted files' module and import-map scripts. */
+export function emitMountedModuleScripts(
+  doc: Document,
+  importMaps: ImportMap[],
+  moduleScripts: string[],
+): void {
+  mergeImportMapsIntoDocument(doc, importMaps);
+  for (const content of moduleScripts) {
+    const el = doc.createElement("script");
+    el.setAttribute("type", "module");
+    el.textContent = content;
+    doc.body.appendChild(el);
+  }
+}
diff --git a/packages/core/src/compiler/index.ts b/packages/core/src/compiler/index.ts
index a6efa13ec4..af8bca17b3 100644
--- a/packages/core/src/compiler/index.ts
+++ b/packages/core/src/compiler/index.ts
@@ -100,3 +100,4 @@ export {
 } from "./mediaRenderIds";
 
 export { ensureExternalScriptTag } from "./externalScripts";
+export { emitMountedModuleScripts } from "./importMaps";
diff --git a/packages/core/src/compiler/inlineSubCompositions.ts b/packages/core/src/compiler/inlineSubCompositions.ts
index c4ca5a1714..8f1d295307 100644
--- a/packages/core/src/compiler/inlineSubCompositions.ts
+++ b/packages/core/src/compiler/inlineSubCompositions.ts
@@ -1,4 +1,5 @@
 import { readExternalScriptAttributes, type ExternalScriptAttributes } from "./externalScripts";
+import { parseImportMap, type ImportMap } from "./importMaps";
 /**
  * Shared sub-composition inlining logic.
  *
@@ -20,6 +21,7 @@ import { warnUnknownEnumValues } from "../runtime/getVariables";
 import {
   scopeCssToComposition,
   wrapInlineScriptWithErrorBoundary,
+  scopedModulePrelude,
   wrapScopedCompositionScript,
 } from "./compositionScoping";
 import {
@@ -142,6 +144,10 @@ export interface InlineSubCompositionsResult {
   >;
   externalLinks: { href: string; rel: string; crossorigin?: string }[];
   variablesByComp: Record<string, Record<string, unknown>>;
+  /** Mounted files' import maps, addresses rebased; emit with `emitMountedModuleScripts`. */
+  importMaps: ImportMap[];
+  /** Mounted files' inline module scripts, each already carrying its scoped `__hyperframes`. */
+  moduleScripts: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -197,6 +203,8 @@ export function inlineSubCompositions(
   const scripts: string[] = [];
   const externalScriptSrcs: string[] = [];
   const scriptItems: InlineSubCompositionsResult["scriptItems"] = [];
+  const importMaps: ImportMap[] = [];
+  const moduleScripts: string[] = [];
   const externalLinks: { href: string; rel: string; crossorigin?: string }[] = [];
   const seenLinkHrefs = new Set<string>();
   const variablesByComp: Record<string, Record<string, unknown>> = {};
@@ -340,7 +348,26 @@ export function inlineSubCompositions(
     // discarded on render while the mount path executed it.
     for (const scriptEl of plan.scriptSources) {
       const externalSrc = resolveSubAssetPath(scriptEl.getAttribute("src"));
-      if (externalSrc) {
+      const type = (scriptEl.getAttribute("type") || "").trim().toLowerCase();
+      if (type === "importmap") {
+        const map = parseImportMap(scriptEl.textContent || "", (url) => {
+          // The rebase drops a leading "./" and a trailing "/"; an import map address needs both.
+          const authored = url.trim();
+          const rebased = resolveSubAssetPath(authored);
+          if (rebased === authored) return rebased;
+          const urlLike = /^(\/|\.\.?\/|[a-z][a-z\d+.-]*:)/i.test(rebased)
+            ? rebased
+            : `./${rebased}`;
+          return authored.endsWith("/") && !urlLike.endsWith("/") ? `${urlLike}/` : urlLike;
+        });
+        if (map) importMaps.push(map);
+        else console.warn(`[HyperFrames] ${src}: import map is not valid JSON, so it is skipped.`);
+      } else if (type === "module" && !externalSrc) {
+        const prelude = scriptCompositionId
+          ? scopedModulePrelude(runtimeCompId || scopeCompId || scriptCompositionId, src)
+          : "";
+        moduleScripts.push(prelude + (scriptEl.textContent || ""));
+      } else if (externalSrc) {
         if (!externalScriptSrcs.includes(externalSrc)) {
           externalScriptSrcs.push(externalSrc);
         }
@@ -461,5 +488,14 @@ export function inlineSubCompositions(
     }
   }
 
-  return { styles, scripts, externalScriptSrcs, scriptItems, externalLinks, variablesByComp };
+  return {
+    styles,
+    scripts,
+    externalScriptSrcs,
+    scriptItems,
+    externalLinks,
+    variablesByComp,
+    importMaps,
+    moduleScripts,
+  };
 }
diff --git a/packages/core/src/runtime/compositionLoader.test.ts b/packages/core/src/runtime/compositionLoader.test.ts
index 4c95ebe19f..dc7a476252 100644
--- a/packages/core/src/runtime/compositionLoader.test.ts
+++ b/packages/core/src/runtime/compositionLoader.test.ts
@@ -54,6 +54,30 @@ describe("loadExternalCompositions", () => {
     );
   });
 
+  it("injects a fetched composition's import map and module script bound to its own URL", async () => {
+    const host = document.createElement("div");
+    host.setAttribute("data-composition-src", "https://example.com/blocks/blk/blk.html");
+    host.setAttribute("data-composition-id", "blk");
+    document.body.appendChild(host);
+    const compositionHtml =
+      `<div data-composition-id="blk">` +
+      `<script type="importmap">{ "imports": { "three": "./lib/three.js" } }</scr` +
+      `ipt><script type="module">import "three"; window.__url = __hyperframes.assetUrl("a.png");</scr` +
+      `ipt></div>`;
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(compositionHtml, { status: 200 }));
+
+    const injectedScripts: HTMLScriptElement[] = [];
+    await loadExternalCompositions({ ...defaultParams, injectedScripts });
+
+    const importMap = injectedScripts.find((script) => script.type === "importmap");
+    const moduleScript = injectedScripts.find((script) => script.type === "module");
+    expect(JSON.parse(importMap?.textContent || "")).toEqual({
+      imports: { three: "https://example.com/blocks/blk/lib/three.js" },
+    });
+    expect(moduleScript?.textContent).toMatch(/^const __hyperframes = /);
+    expect(moduleScript?.textContent).toContain('"https://example.com/blocks/blk/blk.html"');
+  });
+
   it("fetches and mounts external composition HTML", async () => {
     const host = document.createElement("div");
     host.setAttribute("data-composition-src", "https://example.com/comp.html");
diff --git a/packages/core/src/runtime/compositionLoader.ts b/packages/core/src/runtime/compositionLoader.ts
index c53b877c4f..0fa30800c1 100644
--- a/packages/core/src/runtime/compositionLoader.ts
+++ b/packages/core/src/runtime/compositionLoader.ts
@@ -2,7 +2,12 @@ import {
   planCompositionAssembly,
   EXTRACTED_COMPOSITION_ASSET_SELECTOR,
 } from "../compiler/compositionAssembly";
-import { scopeCssToComposition, wrapScopedCompositionScript } from "../compiler/compositionScoping";
+import {
+  scopeCssToComposition,
+  scopedModulePrelude,
+  wrapScopedCompositionScript,
+} from "../compiler/compositionScoping";
+import { parseImportMap } from "../compiler/importMaps";
 import { markFlattenedInnerRoot } from "./flattenedRoot";
 import {
   applyCssVariables,
@@ -556,8 +561,19 @@ async function mountCompositionContent(params: {
     injectedScript.async = false;
     if (scriptPayload.kind === "external") {
       injectedScript.src = scriptPayload.src;
+    } else if (scriptPayload.type.toLowerCase() === "importmap") {
+      const map = parseImportMap(scriptPayload.content, (url) =>
+        resolveScriptSourceUrl(url, params.compositionUrl),
+      );
+      injectedScript.textContent = map ? JSON.stringify(map) : scriptPayload.content;
     } else if (scriptPayload.type.toLowerCase() === "module") {
-      injectedScript.textContent = scriptPayload.content;
+      const prelude = scriptPayload.scopeCompositionId
+        ? scopedModulePrelude(
+            runtimeScopeCompositionId || scriptPayload.scopeCompositionId,
+            params.compositionUrl?.href,
+          )
+        : "";
+      injectedScript.textContent = prelude + scriptPayload.content;
     } else if (scriptPayload.scopeCompositionId) {
       injectedScript.textContent = wrapScopedCompositionScript(
         scriptPayload.content,
diff --git a/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts b/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts
new file mode 100644
index 0000000000..c8be300d6d
--- /dev/null
+++ b/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts
@@ -0,0 +1,66 @@
+// @vitest-environment node
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseHTML } from "linkedom";
+import { afterEach, describe, expect, it } from "vitest";
+import { compileForRender } from "./htmlCompiler.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function project(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "hf-module-scripts-"));
+  tempDirs.push(dir);
+  for (const [relative, content] of Object.entries(files)) {
+    const path = join(dir, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+  return dir;
+}
+
+describe("compileForRender mounted module scripts", () => {
+  it("keeps a mounted file's import map and module script as such, bound to that file", async () => {
+    const dir = project({
+      "index.html": `<!doctype html>
+<html><body>
+  <div data-composition-id="root" data-width="320" data-height="180">
+    <div data-composition-id="blk" data-composition-src="compositions/blk/blk.html"
+      data-start="0" data-duration="2"></div>
+  </div>
+</body></html>`,
+      "compositions/blk/assets/three.js": "export const REVISION = 1;",
+      "compositions/blk/assets/scene.js": 'import * as THREE from "three"; export const SCENE = 1;',
+      "compositions/blk/blk.html": `<div data-composition-id="blk" data-width="320" data-height="180">
+  <script type="module" src="./assets/scene.js"></script>
+  <script type="importmap">{ "imports": { "three": "./assets/three.js" } }</script>
+  <script type="module">import * as THREE from "three"; window.__url = __hyperframes.assetUrl("assets/leaf.webp");</script>
+</div>`,
+    });
+    const { html } = await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
+      allowSystemFontCapture: false,
+    });
+    const { document } = parseHTML(html);
+    const importMap = document.querySelector('script[type="importmap"]');
+    const modules = [...document.querySelectorAll('script[type="module"]')];
+    const classic = [...document.querySelectorAll("script:not([type])")].map((s) => s.textContent);
+
+    expect(JSON.parse(importMap?.textContent || "null")).toEqual({
+      imports: { three: "./compositions/blk/assets/three.js" },
+    });
+    expect(modules.map((m) => m.getAttribute("src")).filter(Boolean)).toEqual([
+      "compositions/blk/assets/scene.js",
+    ]);
+    const inline = modules.filter((m) => !m.hasAttribute("src"));
+    expect(inline).toHaveLength(1);
+    expect(inline[0]!.textContent).toMatch(/^const __hyperframes = /);
+    expect(inline[0]!.textContent).toContain('"compositions/blk/blk.html"');
+    expect(classic.join("")).not.toContain("SCENE");
+    expect(classic.join("")).not.toContain('"imports"');
+    expect(classic.join("")).not.toContain("import * as THREE");
+  });
+});
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 0d997502aa..bb0cfc3f94 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -41,6 +41,7 @@ import {
   buildVariablesByCompScript,
   inlineSubCompositions as inlineSubCompositionsShared,
   ensureExternalScriptTag,
+  emitMountedModuleScripts,
   prepareFlattenedInnerRoot,
   emitRootCompositionVariableStyles,
   readDeclaredDefaults,
@@ -1097,6 +1098,13 @@ function inlineSubCompositions(
     }
     flushInline();
   }
+  if (body) {
+    emitMountedModuleScripts(
+      document as unknown as Document,
+      result.importMaps,
+      result.moduleScripts,
+    );
+  }
 
   // Compile-time CSS custom properties (mirrors the preview bundler): root
   // declarers plus one scoped rule per sub-composition host, so var(--slug)