@hyperframes/studio 0.8.193 → 0.8.195

package/dist/index.html

@@ -14,7 +14,7 @@
         document.documentElement.dataset.theme = "paper";
       }
     </script>
-    <script type="module" crossorigin src="/assets/index-Ca-mgTnS.js"></script>
+    <script type="module" crossorigin src="/assets/index-Dkt4c1MV.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CYbvOVp-.css">
   </head>
   <body>

package/dist/index.js

@@ -17608,7 +17608,7 @@ async function writeProjectFilesWithHistoryInQueue({
 
 // src/utils/gsapSoftReload.ts
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR as COLOR_GRADING_SOURCE_HIDDEN_ATTR2 } from "@hyperframes/core/color-grading";
-import { motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
+import { GSAP_BASE_URL_META, motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
 
 // src/utils/authoredSource.ts
 import { ensureHfIds, isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
@@ -17870,6 +17870,12 @@ function fileDocs(ownFile, written, nestedFiles) {
 
 // src/utils/gsapSoftReload.ts
 var pendingReadyRetry = null;
+function previewMotionPathUrl(doc, version) {
+  const baseUrl = doc.head.querySelector(
+    `meta[name="${GSAP_BASE_URL_META}"]`
+  )?.content;
+  return motionPathPluginUrl(version, baseUrl);
+}
 function ensureMotionPathPluginLoaded(iframe) {
   if (pendingReadyRetry) window.removeEventListener("message", pendingReadyRetry);
   pendingReadyRetry = null;
@@ -17900,7 +17906,7 @@ function ensureMotionPathPluginLoaded(iframe) {
   try {
     win.__hfMotionPathPluginLoading = true;
     const pluginScript = doc.createElement("script");
-    pluginScript.src = motionPathPluginUrl(win.gsap?.version);
+    pluginScript.src = previewMotionPathUrl(doc, win.gsap?.version);
     const finalize = () => {
       win.__hfMotionPathPluginLoading = false;
       try {
@@ -18086,7 +18092,7 @@ function applySoftReload(iframe, scriptText, options = {}) {
       }
       win.__hfMotionPathPluginLoading = true;
       const pluginScript = doc.createElement("script");
-      pluginScript.src = motionPathPluginUrl(win.gsap?.version);
+      pluginScript.src = previewMotionPathUrl(doc, win.gsap?.version);
       pluginScript.onload = () => {
         win.__hfMotionPathPluginLoading = false;
         executeScript();
@@ -43350,6 +43356,7 @@ import { useCallback as useCallback61 } from "react";
 
 // src/components/editor/useLayerRevealOverride.ts
 import { useCallback as useCallback60, useEffect as useEffect56, useRef as useRef73 } from "react";
+import { revealClip } from "@hyperframes/core/runtime/clip-reveal";
 var LAYER_REVEAL_LIFT_Z = "2147483000";
 var LAYER_REVEAL_PENDING_COMMIT_ATTR = "data-hf-studio-reveal-pending-commit";
 var revealCommitSequence = 0;
@@ -43430,9 +43437,10 @@ function rollbackLayerRevealCommit(element, ownership) {
   }
 }
 function restoreIfOurs(el, property, applied, prior) {
-  if (applied == null) return;
-  if (el.style.getPropertyValue(property) !== applied) return;
+  if (applied == null) return false;
+  if (el.style.getPropertyValue(property) !== applied) return false;
   restoreInline(el, property, prior);
+  return true;
 }
 function readHideSignals(el, win) {
   const computed = win.getComputedStyle(el);
@@ -43450,20 +43458,21 @@ function revealNode(el, win, needs) {
     opacity: el.style.opacity
   };
   const applied = {};
+  let putMarkBack;
   if (needs.display) {
     el.style.removeProperty("display");
     if (win.getComputedStyle(el).display === "none") el.style.display = "block";
     applied.display = el.style.display;
   }
   if (needs.visibility) {
-    el.style.visibility = "visible";
+    putMarkBack = revealClip(el);
     applied.visibility = "visible";
   }
   if (needs.opacity) {
     el.style.opacity = "1";
     applied.opacity = "1";
   }
-  return { element: el, priors, applied };
+  return { element: el, priors, applied, putMarkBack };
 }
 function revealHiddenChain(element) {
   const doc = element.ownerDocument;
@@ -43532,10 +43541,11 @@ function useLayerRevealOverride({
     const state = stateRef.current;
     stateRef.current = null;
     if (!state) return;
-    for (const { element, priors, applied } of state.nodes) {
+    for (const { element, priors, applied, putMarkBack } of state.nodes) {
       if (!element.isConnected) continue;
       restoreIfOurs(element, "display", applied.display, priors.display);
-      restoreIfOurs(element, "visibility", applied.visibility, priors.visibility);
+      if (restoreIfOurs(element, "visibility", applied.visibility, priors.visibility))
+        putMarkBack?.();
       restoreIfOurs(element, "opacity", applied.opacity, priors.opacity);
     }
     if (state.lift && state.base.isConnected) restoreLiftedElement(state.base, state.lift);
@@ -90880,6 +90890,7 @@ var StudioHeader = memo46(function StudioHeader2({
 import { useState as useState136, useCallback as useCallback164, useRef as useRef169, useEffect as useEffect136 } from "react";
 
 // src/hooks/useGestureRecording.ts
+import { revealClip as revealClip2 } from "@hyperframes/core/runtime/clip-reveal";
 import { useCallback as useCallback163, useEffect as useEffect135, useRef as useRef168, useState as useState135 } from "react";
 function readBasePosition(element, iframeEl) {
   let baseOpacity = 1;
@@ -90920,7 +90931,8 @@ function connectGsapRuntime(element, iframeEl, elementEndTime) {
         startTime: win.__player?.getTime() ?? 0,
         maxSeekTime: elementEndTime != null && elementEndTime < tlDuration ? elementEndTime : tlDuration,
         savedVisibility: element.style.visibility,
-        savedTranslate: element.style.getPropertyValue("translate")
+        savedTranslate: element.style.getPropertyValue("translate"),
+        putMarkBack: null
       };
     }
   } catch {
@@ -90932,7 +90944,8 @@ function applyRuntimePreview(runtime, time, properties) {
   runtime.timeline.seek(seekTime);
   runtime.element.style.setProperty("translate", "none");
   runtime.gsap.set(runtime.element, { ...properties });
-  runtime.element.style.visibility = "visible";
+  const putMarkBack = revealClip2(runtime.element);
+  runtime.putMarkBack ??= putMarkBack;
   liveTime.notify(seekTime);
   usePlayerStore.getState().setCurrentTime(seekTime);
 }
@@ -91008,6 +91021,7 @@ function releaseRuntimePreview(r) {
   if (!runtime) return;
   const { element, savedVisibility, savedTranslate } = runtime;
   element.style.visibility = savedVisibility;
+  runtime.putMarkBack?.();
   element.style.setProperty("translate", savedTranslate || "");
   try {
     runtime.gsap.set(runtime.element, {
@@ -98684,7 +98698,7 @@ function levelOf(settings) {
   return settings.shutterDeg > STRONG_ABOVE ? "strong" : "subtle";
 }
 function patchForLevel(level) {
-  return level === "off" ? { enabled: false } : { enabled: true, ...LEVEL_SETTINGS[level] };
+  return level === "off" ? { enabled: false, events: false } : { enabled: true, events: true, ...LEVEL_SETTINGS[level] };
 }
 
 // src/components/panels/MotionBlurPanel.tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.193",
+  "version": "0.8.195",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.193",
-    "@hyperframes/sdk": "0.8.193",
-    "@hyperframes/core": "0.8.193",
-    "@hyperframes/shader-transitions": "0.8.193",
-    "@hyperframes/studio-server": "0.8.193",
-    "@hyperframes/player": "0.8.193"
+    "@hyperframes/core": "0.8.195",
+    "@hyperframes/parsers": "0.8.195",
+    "@hyperframes/sdk": "0.8.195",
+    "@hyperframes/player": "0.8.195",
+    "@hyperframes/shader-transitions": "0.8.195",
+    "@hyperframes/studio-server": "0.8.195"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.193"
+    "@hyperframes/producer": "0.8.195"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/useLayerRevealOverride.test.ts

@@ -18,6 +18,7 @@ import {
   readTimelineElementZIndex,
 } from "../../player/lib/timelineElementHelpers";
 import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
+import { CLIP_HIDDEN_ATTR } from "@hyperframes/core/runtime/clip-reveal";
 
 installReactActEnvironment();
 
@@ -149,6 +150,33 @@ describe("useLayerRevealOverride — delayed reveal ownership", () => {
     act(() => root.unmount());
   });
 
+  it("lifts the runtime's hidden-clip mark with the visibility it forces, and puts both back", () => {
+    const host = document.createElement("div");
+    const clip = makeEl("2", "absolute");
+    clip.style.visibility = "hidden";
+    clip.setAttribute(CLIP_HIDDEN_ATTR, "");
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    let scheduleReveal: ((element: HTMLElement, delayMs: number) => void) | undefined;
+
+    function Harness({ isPlaying }: { isPlaying: boolean }) {
+      ({ scheduleReveal } = useLayerRevealOverride({ isPlaying, selectedElement: clip }));
+      return null;
+    }
+
+    act(() => root.render(React.createElement(Harness, { isPlaying: false })));
+    act(() => scheduleReveal!(clip, 0));
+    act(() => vi.advanceTimersByTime(0));
+    expect([clip.style.visibility, clip.hasAttribute(CLIP_HIDDEN_ATTR)]).toEqual([
+      "visible",
+      false,
+    ]);
+
+    act(() => root.render(React.createElement(Harness, { isPlaying: true })));
+    expect([clip.style.visibility, clip.hasAttribute(CLIP_HIDDEN_ATTR)]).toEqual(["hidden", true]);
+    act(() => root.unmount());
+  });
+
   it("revalidates the current selection before a delayed reveal runs", () => {
     const host = document.createElement("div");
     const selected = makeEl("2", "absolute");

package/src/components/editor/useLayerRevealOverride.ts

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef } from "react";
+import { revealClip } from "@hyperframes/core/runtime/clip-reveal";
 import {
   LAYER_REVEAL_PRIOR_POSITION_ATTR,
   LAYER_REVEAL_PRIOR_Z_ATTR,
@@ -15,6 +16,7 @@ interface RevealedNode {
   priors: { display: string; visibility: string; opacity: string };
   /** Values THIS override wrote — restore only while they are still in place. */
   applied: { display?: string; visibility?: string; opacity?: string };
+  putMarkBack?: () => void;
 }
 
 interface RevealLift {
@@ -158,10 +160,11 @@ function restoreIfOurs(
   property: "display" | "visibility" | "opacity",
   applied: string | undefined,
   prior: string,
-): void {
-  if (applied == null) return;
-  if (el.style.getPropertyValue(property) !== applied) return;
+): boolean {
+  if (applied == null) return false;
+  if (el.style.getPropertyValue(property) !== applied) return false;
   restoreInline(el, property, prior);
+  return true;
 }
 
 /** What hides this node at the current frame, per computed style. */
@@ -187,6 +190,7 @@ function revealNode(
     opacity: el.style.opacity,
   };
   const applied: RevealedNode["applied"] = {};
+  let putMarkBack: RevealedNode["putMarkBack"];
   if (needs.display) {
     // Prefer whatever the stylesheet says once the inline hide is lifted;
     // only force block when the sheet itself hides it.
@@ -195,14 +199,14 @@ function revealNode(
     applied.display = el.style.display;
   }
   if (needs.visibility) {
-    el.style.visibility = "visible";
+    putMarkBack = revealClip(el);
     applied.visibility = "visible";
   }
   if (needs.opacity) {
     el.style.opacity = "1";
     applied.opacity = "1";
   }
-  return { element: el, priors, applied };
+  return { element: el, priors, applied, putMarkBack };
 }
 
 /** Walk `element` → body, force-revealing every hiding node; returns the touched nodes. */
@@ -317,10 +321,11 @@ export function useLayerRevealOverride({
     const state = stateRef.current;
     stateRef.current = null;
     if (!state) return;
-    for (const { element, priors, applied } of state.nodes) {
+    for (const { element, priors, applied, putMarkBack } of state.nodes) {
       if (!element.isConnected) continue;
       restoreIfOurs(element, "display", applied.display, priors.display);
-      restoreIfOurs(element, "visibility", applied.visibility, priors.visibility);
+      if (restoreIfOurs(element, "visibility", applied.visibility, priors.visibility))
+        putMarkBack?.();
       restoreIfOurs(element, "opacity", applied.opacity, priors.opacity);
     }
     if (state.lift && state.base.isConnected) restoreLiftedElement(state.base, state.lift);

package/src/components/panels/MotionBlurPanel.test.tsx

@@ -130,20 +130,29 @@ describe("MotionBlurPanel", () => {
     expect(html).toContain('data-motion-blur-samples="64"');
   });
 
-  it("Off removes data-motion-blur and leaves every other setting on the root", async () => {
+  it("Off removes data-motion-blur and its events, and leaves the other settings on the root", async () => {
     const host = await mount(
       ' data-motion-blur="on" data-motion-blur-shutter="720" data-motion-blur-samples="64" data-motion-blur-tier="filter" data-motion-blur-events="on"',
     );
     await click(radio(host, "Off"));
     const html = files["index.html"] ?? "";
     expect(html).not.toContain('data-motion-blur="on"');
-    for (const kept of ['shutter="720"', 'samples="64"', 'tier="filter"', 'events="on"']) {
+    expect(html).not.toContain("data-motion-blur-events");
+    for (const kept of ['shutter="720"', 'samples="64"', 'tier="filter"']) {
       expect(html).toContain(`data-motion-blur-${kept}`);
     }
   });
 
+  it("turns the events attribute on with Subtle and Strong, so callback-driven motion is found", async () => {
+    const host = await mount();
+    await click(radio(host, "Subtle"));
+    expect(files["index.html"]).toContain('data-motion-blur-events="on"');
+    await click(radio(host, "Strong"));
+    expect(files["index.html"]).toContain('data-motion-blur-events="on"');
+  });
+
   it("writes nothing when the chosen level is already set", async () => {
-    const host = await mount(' data-motion-blur="on"');
+    const host = await mount(' data-motion-blur="on" data-motion-blur-events="on"');
     await click(radio(host, "Subtle"));
     expect(writeProjectFile).not.toHaveBeenCalled();
   });

package/src/components/panels/motionBlurPanelModel.test.ts

@@ -130,9 +130,19 @@ describe("levelOf and patchForLevel", () => {
   });
 
   it("sets Subtle to the default blur and Strong to the maximum, and leaves the rest alone for Off", () => {
-    expect(patchForLevel("subtle")).toEqual({ enabled: true, shutterDeg: 240, samples: null });
-    expect(patchForLevel("strong")).toEqual({ enabled: true, shutterDeg: 720, samples: 64 });
-    expect(patchForLevel("off")).toEqual({ enabled: false });
+    expect(patchForLevel("subtle")).toEqual({
+      enabled: true,
+      events: true,
+      shutterDeg: 240,
+      samples: null,
+    });
+    expect(patchForLevel("strong")).toEqual({
+      enabled: true,
+      events: true,
+      shutterDeg: 720,
+      samples: 64,
+    });
+    expect(patchForLevel("off")).toEqual({ enabled: false, events: false });
   });
 
   it("reads back as the level that was chosen", () => {

package/src/components/panels/motionBlurPanelModel.ts

@@ -92,7 +92,9 @@ export function levelOf(settings: MotionBlurSettings): BlurLevel {
   return settings.shutterDeg > STRONG_ABOVE ? "strong" : "subtle";
 }
 
-/** What choosing `level` changes; Off leaves the shutter, samples and every other setting where they were. */
+/** What choosing `level` changes; blur on turns events on too, and Off leaves the shutter, samples and the rest alone. */
 export function patchForLevel(level: BlurLevel): Partial<MotionBlurSettings> {
-  return level === "off" ? { enabled: false } : { enabled: true, ...LEVEL_SETTINGS[level] };
+  return level === "off"
+    ? { enabled: false, events: false }
+    : { enabled: true, events: true, ...LEVEL_SETTINGS[level] };
 }

package/src/hooks/useGestureRecording.test.tsx

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { useGestureRecording, type GestureSample } from "./useGestureRecording";
+import { CLIP_HIDDEN_ATTR } from "@hyperframes/core/runtime/clip-reveal";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -65,6 +66,47 @@ describe("useGestureRecording", () => {
     act(() => root.unmount());
   });
 
+  it("lifts the runtime's hidden-clip mark while previewing a hidden clip and puts it back on release", () => {
+    const animationFrames: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn((callback: FrameRequestCallback) => animationFrames.push(callback)),
+    );
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const element = iframe.contentDocument!.createElement("div");
+    element.id = "card";
+    element.style.visibility = "hidden";
+    element.setAttribute(CLIP_HIDDEN_ATTR, "");
+    iframe.contentDocument!.body.append(element);
+    Reflect.set(iframe.contentWindow!, "gsap", { getProperty: vi.fn(() => 0), set: vi.fn() });
+    Reflect.set(iframe.contentWindow!, "__timelines", {
+      main: { duration: () => 5, seek: vi.fn() },
+    });
+    Reflect.set(iframe.contentWindow!, "__player", { getTime: () => 1 });
+
+    let recording: ReturnType<typeof useGestureRecording> | null = null;
+    function Harness() {
+      recording = useGestureRecording();
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+    act(() => recording?.startRecording(element, iframe, 4));
+    document.dispatchEvent(new MouseEvent("pointermove", { bubbles: true, clientX: 10 }));
+    act(() => animationFrames.shift()?.(1));
+    expect([element.style.visibility, element.hasAttribute(CLIP_HIDDEN_ATTR)]).toEqual([
+      "visible",
+      false,
+    ]);
+
+    act(() => root.unmount());
+    expect([element.style.visibility, element.hasAttribute(CLIP_HIDDEN_ATTR)]).toEqual([
+      "hidden",
+      true,
+    ]);
+  });
+
   it("releases the preview runtime when unmounted during a recording", () => {
     const cancelAnimationFrame = vi.fn();
     vi.stubGlobal(

package/src/hooks/useGestureRecording.ts

@@ -1,3 +1,4 @@
+import { revealClip } from "@hyperframes/core/runtime/clip-reveal";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { usePlayerStore, liveTime } from "../player/store/playerStore";
 import { frameToSeconds, secondsToFrame } from "../player/lib/time";
@@ -36,6 +37,7 @@ interface GsapRuntime {
   maxSeekTime: number;
   savedVisibility: string;
   savedTranslate: string;
+  putMarkBack: (() => void) | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -107,6 +109,7 @@ function connectGsapRuntime(
           elementEndTime != null && elementEndTime < tlDuration ? elementEndTime : tlDuration,
         savedVisibility: element.style.visibility,
         savedTranslate: element.style.getPropertyValue("translate"),
+        putMarkBack: null,
       };
     }
   } catch {
@@ -124,7 +127,8 @@ function applyRuntimePreview(
   runtime.timeline.seek(seekTime);
   runtime.element.style.setProperty("translate", "none");
   runtime.gsap.set(runtime.element, { ...properties });
-  runtime.element.style.visibility = "visible";
+  const putMarkBack = revealClip(runtime.element);
+  runtime.putMarkBack ??= putMarkBack;
   liveTime.notify(seekTime);
   usePlayerStore.getState().setCurrentTime(seekTime);
 }
@@ -251,6 +255,7 @@ function releaseRuntimePreview(r: RecordingRefs): void {
   if (!runtime) return;
   const { element, savedVisibility, savedTranslate } = runtime;
   element.style.visibility = savedVisibility;
+  runtime.putMarkBack?.();
   element.style.setProperty("translate", savedTranslate || "");
   try {
     runtime.gsap.set(runtime.element, {

package/src/utils/gsapSoftReload.test.ts

@@ -318,6 +318,28 @@ window.__timelines["root"] = tl;`;
     expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
   });
 
+  it("loads a missing soft-reload plugin from the iframe mirror and reports its failure", () => {
+    const { iframe, contentWindow } = buildMockIframe({
+      gsap: { timeline: vi.fn(), registerPlugin: vi.fn(), version: "3.14.2" },
+    });
+    const head = iframe.contentDocument!.head;
+    const meta = document.createElement("meta");
+    meta.name = "hyperframes-gsap-base-url";
+    meta.content = "http://localhost:8080/vendor/npm";
+    head.appendChild(meta);
+    const onAsyncFailure = vi.fn();
+    expect(applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, { onAsyncFailure })).toBe("applied");
+    const plugin = head.querySelector("script");
+    expect(plugin?.src).toBe(
+      "http://localhost:8080/vendor/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js",
+    );
+    plugin?.onerror?.(new Event("error"));
+    expect(onAsyncFailure).toHaveBeenCalledTimes(1);
+    expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+    expect(head.querySelectorAll("script")).toHaveLength(1);
+  });
+
   it('returns "cannot-soft-reload" when multiple GSAP scripts exist (ambiguous)', () => {
     const script1 = document.createElement("script");
     script1.textContent = "const tl = gsap.timeline({ paused: true });";
@@ -490,6 +512,45 @@ describe("ensureMotionPathPluginLoaded", () => {
     );
   });
 
+  it("preloads from the iframe mirror once, retaining the runtime version", () => {
+    const { iframe, appendedScripts, contentWindow, registerPlugin } = buildBootstrapIframe({
+      gsap: { version: "3.14.2", registerPlugin: vi.fn() },
+    });
+    const meta = document.createElement("meta");
+    meta.name = "hyperframes-gsap-base-url";
+    meta.content = "http://localhost:8080/vendor/npm";
+    iframe.contentDocument!.head.appendChild(meta);
+    ensureMotionPathPluginLoaded(iframe);
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(1);
+    expect(appendedScripts[0]!.src).toBe(
+      "http://localhost:8080/vendor/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js",
+    );
+    appendedScripts[0]!.onerror?.(new Event("error"));
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+    expect(registerPlugin).not.toHaveBeenCalled();
+    expect(appendedScripts).toHaveLength(1);
+  });
+
+  it.each([
+    ["3.15.0", "/api/vendor/npm/gsap@3.15.0/dist/MotionPathPlugin.min.js"],
+    ["3.14.2", "https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js"],
+  ])(
+    "preloads gsap %s from the host's bundled copy only when it holds that version",
+    (version, url) => {
+      const { iframe, appendedScripts } = buildBootstrapIframe({
+        gsap: { version, registerPlugin: vi.fn() },
+      });
+      const meta = document.createElement("meta");
+      meta.name = "hyperframes-gsap-base-url";
+      meta.content = "/api/vendor/npm";
+      iframe.contentDocument!.head.appendChild(meta);
+      ensureMotionPathPluginLoaded(iframe);
+      expect(appendedScripts).toHaveLength(1);
+      expect(appendedScripts[0]!.getAttribute("src")).toBe(url);
+    },
+  );
+
   it("appends the plugin script once and registers it on load", () => {
     const { iframe, contentWindow, appendedScripts, registerPlugin } = buildBootstrapIframe();
     ensureMotionPathPluginLoaded(iframe);

package/src/utils/gsapSoftReload.ts

@@ -1,5 +1,5 @@
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
-import { motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
+import { GSAP_BASE_URL_META, motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
 import { findAuthoredElement } from "./authoredSource";
 import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
 import {
@@ -50,6 +50,13 @@ type IframeWindow = Window & {
 // At most one preview waits for its runtime; a newer load replaces it, so a frame that never boots is not kept alive.
 let pendingReadyRetry: ((event: MessageEvent) => void) | null = null;
 
+function previewMotionPathUrl(doc: Document, version?: string): string {
+  const baseUrl = doc.head.querySelector<HTMLMetaElement>(
+    `meta[name="${GSAP_BASE_URL_META}"]`,
+  )?.content;
+  return motionPathPluginUrl(version, baseUrl);
+}
+
 export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null): void {
   if (pendingReadyRetry) window.removeEventListener("message", pendingReadyRetry);
   pendingReadyRetry = null;
@@ -86,7 +93,7 @@ export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null):
   try {
     win.__hfMotionPathPluginLoading = true;
     const pluginScript = doc.createElement("script");
-    pluginScript.src = motionPathPluginUrl(win.gsap?.version);
+    pluginScript.src = previewMotionPathUrl(doc, win.gsap?.version);
     const finalize = () => {
       win.__hfMotionPathPluginLoading = false;
       try {
@@ -480,7 +487,7 @@ export function applySoftReload(
       }
       win.__hfMotionPathPluginLoading = true;
       const pluginScript = doc.createElement("script");
-      pluginScript.src = motionPathPluginUrl(win.gsap?.version);
+      pluginScript.src = previewMotionPathUrl(doc, win.gsap?.version);
       pluginScript.onload = () => {
         win.__hfMotionPathPluginLoading = false;
         executeScript();