From 471b4efb4b382cc308bcec0f33b5883653b698e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 20 May 2026 01:55:17 -0400
Subject: [PATCH] feat: data-timeline-locked + fix font loss in
 sub-compositions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Timeline locking:
- Add data-timeline-locked attribute support — fully disables move,
  trim-start, and trim-end in Studio for clips that carry this attr
- Runtime propagates the attribute from inner composition root to host
  element so component authors control it from their HTML
- All 15 caption components in the registry now carry the attribute

Font fix:
- Extract <link rel="stylesheet"> and <link rel="preconnect"> from
  sub-composition <head> alongside existing <style>/<script> extraction
- Fixes caption components (and any sub-comp using Google Fonts via
  <link> tags) losing their font-family when loaded as sub-compositions
- Applied in both runtime (compositionLoader) and compiler
  (inlineSubCompositions) paths
---
 packages/core/src/compiler/htmlBundler.ts     | 13 +++++++++++
 .../src/compiler/inlineSubCompositions.ts     | 12 +++++++++-
 .../core/src/runtime/compositionLoader.ts     | 22 +++++++++++++++++++
 .../producer/src/services/htmlCompiler.ts     | 13 +++++++++++
 .../player/components/timelineEditing.test.ts | 16 ++++++++++++++
 .../src/player/components/timelineEditing.ts  |  3 ++-
 packages/studio/src/player/lib/timelineDOM.ts |  4 ++++
 .../studio/src/player/store/playerStore.ts    |  2 ++
 .../caption-clip-wipe/caption-clip-wipe.html  |  2 +-
 .../caption-editorial-emphasis.html           |  2 +-
 .../caption-emoji-pop/caption-emoji-pop.html  |  2 +-
 .../caption-glitch-rgb.html                   |  2 +-
 .../caption-gradient-fill.html                |  2 +-
 .../caption-highlight/caption-highlight.html  |  2 +-
 .../caption-kinetic-slam.html                 |  2 +-
 .../caption-matrix-decode.html                |  2 +-
 .../caption-neon-accent.html                  |  2 +-
 .../caption-neon-glow/caption-neon-glow.html  |  2 +-
 .../caption-parallax-layers.html              |  2 +-
 .../caption-particle-burst.html               |  2 +-
 .../caption-pill-karaoke.html                 |  2 +-
 .../caption-texture/caption-texture.html      |  2 +-
 .../caption-weight-shift.html                 |  2 +-
 23 files changed, 98 insertions(+), 17 deletions(-)
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index 3bae137bf..c21e1e5a2 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -685,6 +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 compVariablesByComp: Record<string, Record<string, unknown>> = {
     ...subCompResult.variablesByComp,
   };
@@ -811,6 +812,18 @@ export async function bundleToSingleHtml(
     }
   }
 
+  for (const href of compExternalLinkHrefs) {
+    if (!document.querySelector(`link[href="${href}"]`)) {
+      const linkEl = document.createElement("link");
+      linkEl.setAttribute(
+        "rel",
+        href.includes(".css") || href.includes("css2?") ? "stylesheet" : "preconnect",
+      );
+      linkEl.setAttribute("href", href);
+      document.head.appendChild(linkEl);
+    }
+  }
+
   if (compStyleChunks.length) {
     const style = document.createElement("style");
     style.textContent = compStyleChunks.join("\n\n");
diff --git a/packages/core/src/compiler/inlineSubCompositions.ts b/packages/core/src/compiler/inlineSubCompositions.ts
index 3ff1a437a..2740f0f41 100644
--- a/packages/core/src/compiler/inlineSubCompositions.ts
+++ b/packages/core/src/compiler/inlineSubCompositions.ts
@@ -97,6 +97,7 @@ export interface InlineSubCompositionsResult {
   styles: string[];
   scripts: string[];
   externalScriptSrcs: string[];
+  externalLinkHrefs: string[];
   variablesByComp: Record<string, Record<string, unknown>>;
 }
 
@@ -149,6 +150,7 @@ export function inlineSubCompositions(
   const styles: string[] = [];
   const scripts: string[] = [];
   const externalScriptSrcs: string[] = [];
+  const externalLinkHrefs: string[] = [];
   const variablesByComp: Record<string, Record<string, unknown>> = {};
 
   for (const hostEl of hosts) {
@@ -221,6 +223,14 @@ export function inlineSubCompositions(
           externalScriptSrcs.push(externalSrc);
         }
       }
+      for (const link of [
+        ...compDoc.head.querySelectorAll('link[rel="stylesheet"], link[rel="preconnect"]'),
+      ]) {
+        const href = (link.getAttribute("href") || "").trim();
+        if (href && !externalLinkHrefs.includes(href)) {
+          externalLinkHrefs.push(href);
+        }
+      }
     }
 
     // Extract styles from content
@@ -325,5 +335,5 @@ export function inlineSubCompositions(
     hostEl.removeAttribute("data-composition-src");
   }
 
-  return { styles, scripts, externalScriptSrcs, variablesByComp };
+  return { styles, scripts, externalScriptSrcs, externalLinkHrefs, variablesByComp };
 }
diff --git a/packages/core/src/runtime/compositionLoader.ts b/packages/core/src/runtime/compositionLoader.ts
index abc0e3b33..bb335694a 100644
--- a/packages/core/src/runtime/compositionLoader.ts
+++ b/packages/core/src/runtime/compositionLoader.ts
@@ -262,6 +262,8 @@ async function mountCompositionContent(params: {
   headStyles?: HTMLStyleElement[];
   /** Extra <script> elements from the parsed document <head> (non-template sub-compositions). */
   headScripts?: HTMLScriptElement[];
+  /** Extra <link> elements from the parsed document <head> (font stylesheets, preconnects). */
+  headLinks?: HTMLLinkElement[];
   /**
    * Defaults extracted from the sub-composition's own
    * `<html data-composition-variables="...">` attribute. Layered under the
@@ -297,6 +299,15 @@ async function mountCompositionContent(params: {
     ? `[data-composition-id="${CSS.escape(runtimeScopeCompositionId)}"]`
     : undefined;
 
+  if (params.headLinks) {
+    for (const link of params.headLinks) {
+      const href = link.getAttribute("href") || "";
+      if (!href) continue;
+      if (document.head.querySelector(`link[href="${CSS.escape(href)}"]`)) continue;
+      document.head.appendChild(link.cloneNode(true));
+    }
+  }
+
   // Inject <head> styles from non-template sub-compositions first (they define
   // element styles like backgrounds and positioning that the composition needs).
   if (params.headStyles) {
@@ -395,6 +406,9 @@ async function mountCompositionContent(params: {
     if (heightRaw) params.host.setAttribute("data-height", heightRaw);
     if (widthPx && params.host instanceof HTMLElement) params.host.style.width = widthPx;
     if (heightPx && params.host instanceof HTMLElement) params.host.style.height = heightPx;
+    if (innerRoot.hasAttribute("data-timeline-locked")) {
+      params.host.setAttribute("data-timeline-locked", "");
+    }
     params.host.appendChild(prepareFlattenedInnerRoot(innerRoot));
   } else if (params.hasTemplate) {
     params.host.appendChild(document.importNode(contentNode, true));
@@ -581,6 +595,13 @@ export async function loadExternalCompositions(
         const headScripts = !template
           ? Array.from(doc.head.querySelectorAll<HTMLScriptElement>("script"))
           : undefined;
+        const headLinks = !template
+          ? Array.from(
+              doc.head.querySelectorAll<HTMLLinkElement>(
+                'link[rel="stylesheet"], link[rel="preconnect"]',
+              ),
+            )
+          : undefined;
         await mountCompositionContent({
           host,
           authoredCompositionId,
@@ -595,6 +616,7 @@ export async function loadExternalCompositions(
           parseDimensionPx: params.parseDimensionPx,
           headStyles,
           headScripts,
+          headLinks,
           declaredVariableDefaults: readDeclaredDefaults(doc.documentElement),
           onDiagnostic: params.onDiagnostic,
         });
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 5894a3e58..b68ecd68d 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -612,6 +612,19 @@ function inlineSubCompositions(
     }
   }
 
+  if (result.externalLinkHrefs.length && head) {
+    for (const href of result.externalLinkHrefs) {
+      if (document.querySelector(`link[href="${href}"]`)) continue;
+      const el = document.createElement("link");
+      el.setAttribute(
+        "rel",
+        href.includes(".css") || href.includes("css2?") ? "stylesheet" : "preconnect",
+      );
+      el.setAttribute("href", href);
+      head.appendChild(el);
+    }
+  }
+
   // Append collected styles to <head>
   if (result.styles.length && head) {
     const styleEl = document.createElement("style");
diff --git a/packages/studio/src/player/components/timelineEditing.test.ts b/packages/studio/src/player/components/timelineEditing.test.ts
index 1e945c19b..720847048 100644
--- a/packages/studio/src/player/components/timelineEditing.test.ts
+++ b/packages/studio/src/player/components/timelineEditing.test.ts
@@ -263,6 +263,22 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
+  it("locks all timeline edits for clips with data-timeline-locked", () => {
+    expect(
+      getTimelineEditCapabilities({
+        tag: "div",
+        duration: 8,
+        selector: '[data-composition-id="caption-highlight"]',
+        compositionSrc: "compositions/components/caption-highlight.html",
+        timelineLocked: true,
+      }),
+    ).toEqual({
+      canMove: false,
+      canTrimStart: false,
+      canTrimEnd: false,
+    });
+  });
+
   it("allows full editing of explicitly authored generic elements", () => {
     expect(
       getTimelineEditCapabilities({
diff --git a/packages/studio/src/player/components/timelineEditing.ts b/packages/studio/src/player/components/timelineEditing.ts
index f837cb40b..1c3ef3593 100644
--- a/packages/studio/src/player/components/timelineEditing.ts
+++ b/packages/studio/src/player/components/timelineEditing.ts
@@ -211,8 +211,9 @@ export function getTimelineEditCapabilities(input: {
   playbackStartAttr?: "media-start" | "playback-start";
   sourceDuration?: number;
   timingSource?: "authored" | "implicit";
+  timelineLocked?: boolean;
 }): TimelineEditCapabilities {
-  if (input.timingSource === "implicit") {
+  if (input.timingSource === "implicit" || input.timelineLocked) {
     return {
       canMove: false,
       canTrimStart: false,
diff --git a/packages/studio/src/player/lib/timelineDOM.ts b/packages/studio/src/player/lib/timelineDOM.ts
index 5fc6fbb66..963832359 100644
--- a/packages/studio/src/player/lib/timelineDOM.ts
+++ b/packages/studio/src/player/lib/timelineDOM.ts
@@ -280,6 +280,10 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       applyMediaMetadataFromElement(entry, el);
     }
 
+    if (el.hasAttribute("data-timeline-locked")) {
+      entry.timelineLocked = true;
+    }
+
     // Sub-compositions
     const compSrc =
       el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");
diff --git a/packages/studio/src/player/store/playerStore.ts b/packages/studio/src/player/store/playerStore.ts
index 414283dc7..fdbf18925 100644
--- a/packages/studio/src/player/store/playerStore.ts
+++ b/packages/studio/src/player/store/playerStore.ts
@@ -26,6 +26,8 @@ export interface TimelineElement {
   compositionSrc?: string;
   /** Whether this row came from authored clip timing or Studio's full-duration layer fallback. */
   timingSource?: "authored" | "implicit";
+  /** Set by data-timeline-locked on the host element — disables move and trim in Studio. */
+  timelineLocked?: boolean;
 }
 
 export type ZoomMode = "fit" | "manual";
diff --git a/registry/components/caption-clip-wipe/caption-clip-wipe.html b/registry/components/caption-clip-wipe/caption-clip-wipe.html
index a519dbfe8..12aee72af 100644
--- a/registry/components/caption-clip-wipe/caption-clip-wipe.html
+++ b/registry/components/caption-clip-wipe/caption-clip-wipe.html
@@ -83,7 +83,7 @@
   <body>
     <div
       id="clip-wipe"
-      data-composition-id="caption-clip-wipe"
+      data-composition-id="caption-clip-wipe" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-editorial-emphasis/caption-editorial-emphasis.html b/registry/components/caption-editorial-emphasis/caption-editorial-emphasis.html
index 85067766d..ef63d346b 100644
--- a/registry/components/caption-editorial-emphasis/caption-editorial-emphasis.html
+++ b/registry/components/caption-editorial-emphasis/caption-editorial-emphasis.html
@@ -123,7 +123,7 @@
   <body>
     <div
       id="editorial-emphasis"
-      data-composition-id="caption-editorial-emphasis"
+      data-composition-id="caption-editorial-emphasis" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-emoji-pop/caption-emoji-pop.html b/registry/components/caption-emoji-pop/caption-emoji-pop.html
index 64ac88ec5..edea14a96 100644
--- a/registry/components/caption-emoji-pop/caption-emoji-pop.html
+++ b/registry/components/caption-emoji-pop/caption-emoji-pop.html
@@ -119,7 +119,7 @@
   <body>
     <div
       id="emoji-pop"
-      data-composition-id="caption-emoji-pop"
+      data-composition-id="caption-emoji-pop" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-glitch-rgb/caption-glitch-rgb.html b/registry/components/caption-glitch-rgb/caption-glitch-rgb.html
index 0cff82ec3..a694808b0 100644
--- a/registry/components/caption-glitch-rgb/caption-glitch-rgb.html
+++ b/registry/components/caption-glitch-rgb/caption-glitch-rgb.html
@@ -103,7 +103,7 @@
   <body>
     <div
       id="caption-glitch-rgb"
-      data-composition-id="caption-glitch-rgb"
+      data-composition-id="caption-glitch-rgb" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-gradient-fill/caption-gradient-fill.html b/registry/components/caption-gradient-fill/caption-gradient-fill.html
index 6ea07aa97..0dd542376 100644
--- a/registry/components/caption-gradient-fill/caption-gradient-fill.html
+++ b/registry/components/caption-gradient-fill/caption-gradient-fill.html
@@ -71,7 +71,7 @@
   <body>
     <div
       id="gradient-fill"
-      data-composition-id="caption-gradient-fill"
+      data-composition-id="caption-gradient-fill" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-highlight/caption-highlight.html b/registry/components/caption-highlight/caption-highlight.html
index 2236c8b89..2a53beb2c 100644
--- a/registry/components/caption-highlight/caption-highlight.html
+++ b/registry/components/caption-highlight/caption-highlight.html
@@ -102,7 +102,7 @@
   <body>
     <div
       id="highlight"
-      data-composition-id="caption-highlight"
+      data-composition-id="caption-highlight" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-kinetic-slam/caption-kinetic-slam.html b/registry/components/caption-kinetic-slam/caption-kinetic-slam.html
index a3d4d7314..6331699a5 100644
--- a/registry/components/caption-kinetic-slam/caption-kinetic-slam.html
+++ b/registry/components/caption-kinetic-slam/caption-kinetic-slam.html
@@ -70,7 +70,7 @@
   <body>
     <div
       id="kinetic-slam"
-      data-composition-id="caption-kinetic-slam"
+      data-composition-id="caption-kinetic-slam" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-matrix-decode/caption-matrix-decode.html b/registry/components/caption-matrix-decode/caption-matrix-decode.html
index 11ac39f60..cccad7e16 100644
--- a/registry/components/caption-matrix-decode/caption-matrix-decode.html
+++ b/registry/components/caption-matrix-decode/caption-matrix-decode.html
@@ -91,7 +91,7 @@
   <body>
     <div
       id="matrix-decode"
-      data-composition-id="caption-matrix-decode"
+      data-composition-id="caption-matrix-decode" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-neon-accent/caption-neon-accent.html b/registry/components/caption-neon-accent/caption-neon-accent.html
index 3f9e294aa..cbb6e79e7 100644
--- a/registry/components/caption-neon-accent/caption-neon-accent.html
+++ b/registry/components/caption-neon-accent/caption-neon-accent.html
@@ -119,7 +119,7 @@
   <body>
     <div
       id="neon-accent"
-      data-composition-id="caption-neon-accent"
+      data-composition-id="caption-neon-accent" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-neon-glow/caption-neon-glow.html b/registry/components/caption-neon-glow/caption-neon-glow.html
index 0416d344f..a75180f0b 100644
--- a/registry/components/caption-neon-glow/caption-neon-glow.html
+++ b/registry/components/caption-neon-glow/caption-neon-glow.html
@@ -82,7 +82,7 @@
   <body>
     <div
       id="neon-glow"
-      data-composition-id="caption-neon-glow"
+      data-composition-id="caption-neon-glow" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-parallax-layers/caption-parallax-layers.html b/registry/components/caption-parallax-layers/caption-parallax-layers.html
index 5a18a8822..6857580e1 100644
--- a/registry/components/caption-parallax-layers/caption-parallax-layers.html
+++ b/registry/components/caption-parallax-layers/caption-parallax-layers.html
@@ -147,7 +147,7 @@
   <body>
     <div
       id="parallax-layers"
-      data-composition-id="caption-parallax-layers"
+      data-composition-id="caption-parallax-layers" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-particle-burst/caption-particle-burst.html b/registry/components/caption-particle-burst/caption-particle-burst.html
index b0a4306e4..0683ec18b 100644
--- a/registry/components/caption-particle-burst/caption-particle-burst.html
+++ b/registry/components/caption-particle-burst/caption-particle-burst.html
@@ -93,7 +93,7 @@
   <body>
     <div
       id="particle-burst"
-      data-composition-id="caption-particle-burst"
+      data-composition-id="caption-particle-burst" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-pill-karaoke/caption-pill-karaoke.html b/registry/components/caption-pill-karaoke/caption-pill-karaoke.html
index 664825959..c9e3e71e9 100644
--- a/registry/components/caption-pill-karaoke/caption-pill-karaoke.html
+++ b/registry/components/caption-pill-karaoke/caption-pill-karaoke.html
@@ -125,7 +125,7 @@
   <body>
     <div
       id="pill-karaoke"
-      data-composition-id="caption-pill-karaoke"
+      data-composition-id="caption-pill-karaoke" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-texture/caption-texture.html b/registry/components/caption-texture/caption-texture.html
index 7c082dfcf..2332fd943 100644
--- a/registry/components/caption-texture/caption-texture.html
+++ b/registry/components/caption-texture/caption-texture.html
@@ -96,7 +96,7 @@
   <body>
     <div
       id="caption-texture"
-      data-composition-id="caption-texture"
+      data-composition-id="caption-texture" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
diff --git a/registry/components/caption-weight-shift/caption-weight-shift.html b/registry/components/caption-weight-shift/caption-weight-shift.html
index 1eb03870d..8b3d7f659 100644
--- a/registry/components/caption-weight-shift/caption-weight-shift.html
+++ b/registry/components/caption-weight-shift/caption-weight-shift.html
@@ -111,7 +111,7 @@
   <body>
     <div
       id="weight-shift"
-      data-composition-id="caption-weight-shift"
+      data-composition-id="caption-weight-shift" data-timeline-locked
       data-start="0"
       data-duration="8"
       data-fps="30"
