fix: preserve original rel attribute on sub-composition link extraction

Store {href, rel, crossorigin} from source <link> elements instead of
re-deriving rel from a URL substring heuristic. Fixes preview-vs-render
parity: a stylesheet link whose href lacks ".css" or "css2?" was
emitted as preconnect in the compiled output, silently dropping the font.

Also documents that caption components ship with transparent backgrounds
intentionally — users add contrast layers in the host composition.

packages/core/src/compiler/htmlBundler.ts

@@ -685,7 +685,7 @@ export async function bundleToSingleHtml(
   const compStyleChunks: string[] = [...subCompResult.styles];
   const compScriptChunks: string[] = [...subCompResult.scripts];
   const compExternalScriptSrcs: string[] = [...subCompResult.externalScriptSrcs];
-  const compExternalLinkHrefs: string[] = [...subCompResult.externalLinkHrefs];
+  const compExternalLinks = [...subCompResult.externalLinks];
   const compVariablesByComp: Record<string, Record<string, unknown>> = {
     ...subCompResult.variablesByComp,
   };
@@ -812,14 +812,12 @@ export async function bundleToSingleHtml(
     }
   }
 
-  for (const href of compExternalLinkHrefs) {
+  for (const link of compExternalLinks) {
-    if (!document.querySelector(`link[href="${href}"]`)) {
+    if (!document.querySelector(`link[href="${link.href}"]`)) {
       const linkEl = document.createElement("link");
-      linkEl.setAttribute(
+      linkEl.setAttribute("rel", link.rel);
-        "rel",
+      linkEl.setAttribute("href", link.href);
-        href.includes(".css") || href.includes("css2?") ? "stylesheet" : "preconnect",
+      if (link.crossorigin != null) linkEl.setAttribute("crossorigin", link.crossorigin);
-      );
-      linkEl.setAttribute("href", href);
       document.head.appendChild(linkEl);
     }
   }

packages/core/src/compiler/inlineSubCompositions.ts

@@ -97,7 +97,7 @@ export interface InlineSubCompositionsResult {
   styles: string[];
   scripts: string[];
   externalScriptSrcs: string[];
-  externalLinkHrefs: string[];
+  externalLinks: { href: string; rel: string; crossorigin?: string }[];
   variablesByComp: Record<string, Record<string, unknown>>;
 }
 
@@ -150,7 +150,8 @@ export function inlineSubCompositions(
   const styles: string[] = [];
   const scripts: string[] = [];
   const externalScriptSrcs: string[] = [];
-  const externalLinkHrefs: string[] = [];
+  const externalLinks: { href: string; rel: string; crossorigin?: string }[] = [];
+  const seenLinkHrefs = new Set<string>();
   const variablesByComp: Record<string, Record<string, unknown>> = {};
 
   for (const hostEl of hosts) {
@@ -227,8 +228,13 @@ export function inlineSubCompositions(
         ...compDoc.head.querySelectorAll('link[rel="stylesheet"], link[rel="preconnect"]'),
       ]) {
         const href = (link.getAttribute("href") || "").trim();
-        if (href && !externalLinkHrefs.includes(href)) {
+        if (href && !seenLinkHrefs.has(href)) {
-          externalLinkHrefs.push(href);
+          seenLinkHrefs.add(href);
+          const rel = (link.getAttribute("rel") || "").trim();
+          const crossorigin = link.hasAttribute("crossorigin")
+            ? link.getAttribute("crossorigin") || ""
+            : undefined;
+          externalLinks.push({ href, rel, crossorigin });
         }
       }
     }
@@ -335,5 +341,5 @@ export function inlineSubCompositions(
     hostEl.removeAttribute("data-composition-src");
   }
 
-  return { styles, scripts, externalScriptSrcs, externalLinkHrefs, variablesByComp };
+  return { styles, scripts, externalScriptSrcs, externalLinks, variablesByComp };
 }

packages/producer/src/services/htmlCompiler.ts

@@ -612,15 +612,13 @@ function inlineSubCompositions(
     }
   }
 
-  if (result.externalLinkHrefs.length && head) {
+  if (result.externalLinks.length && head) {
-    for (const href of result.externalLinkHrefs) {
+    for (const link of result.externalLinks) {
-      if (document.querySelector(`link[href="${href}"]`)) continue;
+      if (document.querySelector(`link[href="${link.href}"]`)) continue;
       const el = document.createElement("link");
-      el.setAttribute(
+      el.setAttribute("rel", link.rel);
-        "rel",
+      el.setAttribute("href", link.href);
-        href.includes(".css") || href.includes("css2?") ? "stylesheet" : "preconnect",
+      if (link.crossorigin != null) el.setAttribute("crossorigin", link.crossorigin);
-      );
-      el.setAttribute("href", href);
       head.appendChild(el);
     }
   }

skills/hyperframes/references/captions.md

@@ -146,6 +146,8 @@ npx hyperframes add caption-highlight         # install a specific one
 
 Browse all with previews: [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog)
 
+Caption components ship with transparent backgrounds — they're pure overlays. If the underlying video is bright or busy, add a contrast layer (e.g. a semi-transparent dark div) in the host composition beneath the caption sub-composition, not inside the component itself.
+
 ## Further References
 
 - [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation