@hyperframes/studio 0.6.121 → 0.7.0

package/src/utils/gsapSoftReload.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import { describe, it, expect, vi } from "vitest";
-import { applySoftReload } from "./gsapSoftReload";
+import { applySoftReload, ensureMotionPathPluginLoaded } from "./gsapSoftReload";
 
 const SCRIPT_TEXT = `
 window.__timelines = window.__timelines || {};
@@ -10,6 +10,13 @@ tl.to("#box", { opacity: 0.8 });
 window.__timelines["root"] = tl;
 `;
 
+const MOTION_PATH_SCRIPT_TEXT = `
+window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true });
+tl.to("#box", { motionPath: { path: [{ x: 0, y: 0 }, { x: 100, y: 50 }] } });
+window.__timelines["root"] = tl;
+`;
+
 function buildMockIframe(overrides: Record<string, unknown> = {}) {
   const scriptEl = document.createElement("script");
   scriptEl.textContent =
@@ -58,29 +65,35 @@ function buildMockIframe(overrides: Record<string, unknown> = {}) {
 }
 
 describe("applySoftReload", () => {
-  it("returns false when iframe is null", () => {
-    expect(applySoftReload(null, SCRIPT_TEXT)).toBe(false);
+  it('returns "cannot-soft-reload" when iframe is null', () => {
+    expect(applySoftReload(null, SCRIPT_TEXT)).toBe("cannot-soft-reload");
   });
 
-  it("returns false when scriptText is empty", () => {
+  it('returns "cannot-soft-reload" when scriptText is empty', () => {
     const { iframe } = buildMockIframe();
-    expect(applySoftReload(iframe, "")).toBe(false);
+    expect(applySoftReload(iframe, "")).toBe("cannot-soft-reload");
   });
 
-  it("returns false when gsap is not on iframe window", () => {
+  it('returns "cannot-soft-reload" when gsap is not on iframe window', () => {
     const { iframe } = buildMockIframe({ gsap: undefined });
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
   });
 
-  it("returns false when __hfForceTimelineRebind is missing", () => {
+  it('returns "cannot-soft-reload" when __hfForceTimelineRebind is missing', () => {
     const { iframe } = buildMockIframe({ __hfForceTimelineRebind: undefined });
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+  });
+
+  it('returns "cannot-soft-reload" when the script registers no scopable key', () => {
+    // No __timelines["key"] pattern → targetKeys is empty → can't scope safely.
+    const { iframe } = buildMockIframe();
+    expect(applySoftReload(iframe, 'gsap.to("#box", { x: 1 });')).toBe("cannot-soft-reload");
   });
 
   it("kills existing timelines, rebinds, and re-seeks on success", () => {
     const { iframe, contentWindow, mockTimeline } = buildMockIframe();
     const result = applySoftReload(iframe, SCRIPT_TEXT);
-    expect(result).toBe(true);
+    expect(result).toBe("applied");
     expect(mockTimeline.kill).toHaveBeenCalled();
     expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalled();
     expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
@@ -96,11 +109,119 @@ describe("applySoftReload", () => {
       },
     });
     const result = applySoftReload(iframe, SCRIPT_TEXT);
-    expect(result).toBe(true);
+    expect(result).toBe("applied");
     expect(suppressionCalled).toBe(true);
   });
 
-  it("returns false when multiple GSAP scripts exist (ambiguous)", () => {
+  it('returns "applied" when the re-run re-registers the script\'s expected key', () => {
+    // SCRIPT_TEXT registers __timelines["root"]; buildMockIframe's appendChild
+    // shim repopulates `root` on execution. The hardened verify checks the
+    // expected target key is present (not merely "some key"), so a correct re-run
+    // reliably reports "applied" — it doesn't spuriously hit the transient window.
+    const { iframe, contentWindow } = buildMockIframe();
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("applied");
+    expect(contentWindow.__timelines.root).toBeDefined();
+  });
+
+  it('returns "verify-failed" (transient) when the re-run leaves the key empty', () => {
+    // No appendChild shim repopulation: the body container has no shim, so the
+    // re-run kills __timelines["root"] and the new script doesn't re-register it.
+    // That is the TRANSIENT post-run window — surfaced as "verify-failed" so
+    // callers know NOT to escalate (the live gsap.set already shows the value).
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent = 'window.__timelines["root"] = gsap.timeline();';
+    const container = document.createElement("div"); // no appendChild shim
+    container.appendChild(scriptEl);
+    const { iframe } = buildMockIframe();
+    (iframe as unknown as { contentDocument: unknown }).contentDocument = {
+      querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [scriptEl] : []),
+      createElement: (tag: string) => document.createElement(tag),
+      body: container,
+      head: document.createElement("div"),
+    };
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("verify-failed");
+  });
+
+  it("editing composition A leaves composition B's timeline intact (scoped kill)", () => {
+    // Two comps live side by side; the soft reload only re-runs comp "root".
+    // Comp "subscene" must survive untouched — the regression the full remount
+    // (re-inline) used to cause.
+    const subsceneTimeline = { kill: vi.fn(), pause: vi.fn() };
+    const { iframe, contentWindow, mockTimeline } = buildMockIframe({
+      __timelines: {
+        root: { kill: vi.fn(), pause: vi.fn() },
+        subscene: subsceneTimeline,
+      } as Record<string, { kill: ReturnType<typeof vi.fn>; pause: ReturnType<typeof vi.fn> }>,
+    });
+    void mockTimeline;
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("applied");
+    // Comp B was never killed and is still registered.
+    expect(subsceneTimeline.kill).not.toHaveBeenCalled();
+    expect(contentWindow.__timelines.subscene).toBe(subsceneTimeline);
+  });
+
+  it("runs synchronously (no async plugin load) when MotionPathPlugin is already present", () => {
+    // The preview bootstrap pre-loads MotionPathPlugin, so win.MotionPathPlugin
+    // is set before any motion-path edit. The soft reload must then execute the
+    // script inline — no CDN <script> appended to <head>, the timeline is
+    // repopulated synchronously, and verifyTimelinesPopulated reports the real
+    // result (not the optimistic-true async path).
+    const headAppends: Node[] = [];
+    const head = document.createElement("div");
+    const realHeadAppend = head.appendChild.bind(head);
+    head.appendChild = <T extends Node>(node: T): T => {
+      headAppends.push(node);
+      return realHeadAppend(node);
+    };
+    const { iframe, contentWindow } = buildMockIframe({ MotionPathPlugin: {} });
+    (iframe.contentDocument as unknown as { head: unknown }).head = head;
+
+    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT);
+
+    expect(result).toBe("applied");
+    // No CDN plugin <script> was appended to <head> — ran inline.
+    expect(headAppends.filter((n) => n instanceof HTMLScriptElement)).toHaveLength(0);
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalled();
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
+    expect(contentWindow.__timelines.root).toBeDefined();
+  });
+
+  it("falls back to the async plugin load when MotionPathPlugin is genuinely absent", () => {
+    const head = document.createElement("div");
+    const appendedScripts: HTMLScriptElement[] = [];
+    const realHeadAppend = head.appendChild.bind(head);
+    head.appendChild = <T extends Node>(node: T): T => {
+      if (node instanceof HTMLScriptElement) appendedScripts.push(node);
+      return realHeadAppend(node);
+    };
+    // gsap present but MotionPathPlugin unset → async load path.
+    const { iframe, contentWindow } = buildMockIframe({
+      MotionPathPlugin: undefined,
+      gsap: { timeline: vi.fn(), registerPlugin: vi.fn() },
+    });
+    (iframe.contentDocument as unknown as { head: unknown }).head = head;
+
+    const onAsyncFailure = vi.fn();
+    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, onAsyncFailure);
+
+    // Optimistically "applied" (script will run once the plugin loads) — and the
+    // script has NOT executed yet, so the timeline isn't rebound synchronously.
+    expect(result).toBe("applied");
+    expect(appendedScripts).toHaveLength(1);
+    expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
+
+    // onerror must NOT run the script (that would reference a missing plugin) —
+    // it escalates via onAsyncFailure so the caller can full-reload to recover,
+    // and clears the in-flight loading flag.
+    appendedScripts[0]!.onerror?.(new Event("error"));
+    expect(onAsyncFailure).toHaveBeenCalledTimes(1);
+    expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+  });
+
+  it('returns "cannot-soft-reload" when multiple GSAP scripts exist (ambiguous)', () => {
     const script1 = document.createElement("script");
     script1.textContent = "const tl = gsap.timeline({ paused: true });";
     const script2 = document.createElement("script");
@@ -115,6 +236,89 @@ describe("applySoftReload", () => {
       createElement: (tag: string) => document.createElement(tag),
       body: container,
     };
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    // Multiple scripts, none registering "root" → can't identify what to replace
+    // → structural failure that genuinely needs a full reload.
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+  });
+});
+
+function buildBootstrapIframe(overrides: Record<string, unknown> = {}) {
+  const head = document.createElement("div");
+  const appendedScripts: HTMLScriptElement[] = [];
+  const realHeadAppend = head.appendChild.bind(head);
+  head.appendChild = <T extends Node>(node: T): T => {
+    if (node instanceof HTMLScriptElement) appendedScripts.push(node);
+    return realHeadAppend(node);
+  };
+
+  const registerPlugin = vi.fn();
+  const contentWindow = {
+    gsap: { registerPlugin } as Record<string, unknown> | undefined,
+    MotionPathPlugin: undefined as unknown,
+    __hfMotionPathPluginLoading: undefined as boolean | undefined,
+    ...overrides,
+  };
+  const contentDocument = {
+    createElement: (tag: string) => document.createElement(tag),
+    head,
+  };
+  return {
+    iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement,
+    contentWindow,
+    appendedScripts,
+    registerPlugin,
+  };
+}
+
+describe("ensureMotionPathPluginLoaded", () => {
+  it("no-ops when the iframe is null", () => {
+    expect(() => ensureMotionPathPluginLoaded(null)).not.toThrow();
+  });
+
+  it("no-ops when gsap is unavailable", () => {
+    const { iframe, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(0);
+  });
+
+  it("appends the plugin script once and registers it on load", () => {
+    const { iframe, contentWindow, appendedScripts, registerPlugin } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(1);
+    expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(true);
+
+    // Simulate the CDN load completing; the plugin is now present.
+    contentWindow.MotionPathPlugin = {};
+    appendedScripts[0]!.onload?.(new Event("load"));
+    expect(registerPlugin).toHaveBeenCalledWith(contentWindow.MotionPathPlugin);
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+  });
+
+  it("is idempotent: a second call while loading does not append a second script", () => {
+    const { iframe, appendedScripts } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(1);
+  });
+
+  it("registers an already-present plugin without appending a script", () => {
+    const plugin = {};
+    const { iframe, appendedScripts, registerPlugin } = buildBootstrapIframe({
+      MotionPathPlugin: plugin,
+    });
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(0);
+    expect(registerPlugin).toHaveBeenCalledWith(plugin);
+  });
+
+  it("clears the loading flag and still resolves when the CDN load errors", () => {
+    const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    appendedScripts[0]!.onerror?.(new Event("error"));
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+    // A subsequent call can retry (plugin still absent, flag cleared).
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(2);
   });
 });

package/src/utils/gsapSoftReload.ts

@@ -4,6 +4,10 @@ type IframeWindow = Window & {
   __hfForceTimelineRebind?: () => void;
   __hfSuppressSceneMutations?: <T>(fn: () => T) => T;
   __hfStudioManualEditsApply?: () => void;
+  // Set while a MotionPathPlugin <script> is being fetched, so overlapping soft
+  // reloads (each needing the plugin) don't queue duplicate plugin scripts that
+  // re-flash the iframe. Cleared once the plugin loads or errors.
+  __hfMotionPathPluginLoading?: boolean;
   gsap?: {
     timeline?: (...args: unknown[]) => unknown;
     registerPlugin?: (...plugins: unknown[]) => unknown;
@@ -13,6 +17,67 @@ type IframeWindow = Window & {
   MotionPathPlugin?: unknown;
 };
 
+/**
+ * CDN URL for the GSAP MotionPathPlugin. Shared between the one-time preview
+ * bootstrap (ensureMotionPathPluginLoaded) and the soft-reload fallback so the
+ * version is pinned in a single place.
+ */
+const MOTION_PATH_PLUGIN_CDN =
+  "https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/MotionPathPlugin.min.js";
+
+/**
+ * Pre-load + register MotionPathPlugin ONCE in the preview iframe so
+ * `win.MotionPathPlugin` is reliably set before any studio edit. Called from the
+ * preview bootstrap (NLELayout's onIframeLoad) on every iframe load.
+ *
+ * Why: when a user ADDS a motion path to a composition that never used one, the
+ * plugin isn't loaded, so the first soft reload takes the async `<script src>`
+ * load path — the timeline is killed/cleared while the CDN load is pending,
+ * producing a visible flash. Loading it eagerly here means the soft reload runs
+ * synchronously and `needsMotionPath && !win.MotionPathPlugin` never fires for
+ * studio edits.
+ *
+ * Idempotent (no-ops once the plugin is present or already loading) and
+ * defensive: no-ops without gsap/registerPlugin and tolerates a CDN failure
+ * (the soft-reload async fallback in applySoftReload still covers that case).
+ */
+export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null): void {
+  if (!iframe?.contentWindow || !iframe.contentDocument) return;
+  const win = iframe.contentWindow as IframeWindow;
+  const doc = iframe.contentDocument;
+
+  // Already registered (composition shipped its own plugin, or a prior bootstrap
+  // ran) — register it on gsap to be safe, then bail.
+  if (win.MotionPathPlugin) {
+    try {
+      if (win.gsap?.registerPlugin) win.gsap.registerPlugin(win.MotionPathPlugin);
+    } catch {}
+    return;
+  }
+  if (!win.gsap?.registerPlugin) return;
+  // A load is already in flight for this iframe — don't queue a second script.
+  if (win.__hfMotionPathPluginLoading) return;
+
+  try {
+    win.__hfMotionPathPluginLoading = true;
+    const pluginScript = doc.createElement("script");
+    pluginScript.src = MOTION_PATH_PLUGIN_CDN;
+    const finalize = () => {
+      win.__hfMotionPathPluginLoading = false;
+      try {
+        if (win.MotionPathPlugin && win.gsap?.registerPlugin) {
+          win.gsap.registerPlugin(win.MotionPathPlugin);
+        }
+      } catch {}
+    };
+    pluginScript.onload = finalize;
+    pluginScript.onerror = finalize;
+    doc.head.appendChild(pluginScript);
+  } catch {
+    win.__hfMotionPathPluginLoading = false;
+  }
+}
+
 function isGsapScript(text: string): boolean {
   return (
     text.includes("gsap.timeline") ||
@@ -44,14 +109,44 @@ export function extractGsapScriptText(html: string): string | null {
   return scripts[0].textContent || null;
 }
 
-/** Check that the new script repopulated __timelines with at least one entry. */
-function verifyTimelinesPopulated(win: IframeWindow): boolean {
-  const tlKeys = win.__timelines
-    ? Object.keys(win.__timelines).filter((k) => k !== "__proxied")
-    : [];
-  return tlKeys.length > 0;
+/**
+ * Confirm the re-run repopulated the timeline(s) this script owns. We check the
+ * EXPECTED keys (the ones the script re-registers), not merely "any key": a
+ * scoped soft reload only re-runs ONE composition, so the right success signal is
+ * "my target keys are back", not "the global map is non-empty". Checking the
+ * exact keys avoids the transient false where the global map momentarily looks
+ * empty right after the re-run — the spurious trigger of the full-remount fallback.
+ */
+function verifyTimelinesPopulated(win: IframeWindow, targetKeys: string[]): boolean {
+  const timelines = win.__timelines;
+  if (!timelines) return false;
+  if (targetKeys.length > 0) {
+    return targetKeys.every((key) => timelines[key] != null);
+  }
+  return Object.keys(timelines).filter((k) => k !== "__proxied").length > 0;
 }
 
+/**
+ * Outcome of a soft-reload attempt. Callers must distinguish PERMANENT failures
+ * (the preview genuinely can't be soft-updated — escalate to a full reload) from
+ * the TRANSIENT post-run empty-timeline window (the live `gsap.set` already shows
+ * the correct value — do NOT escalate; a remount would re-flash the WebGL context
+ * and revert subcomposition keyframes):
+ *
+ * - `"applied"`            — the script ran (or is deferred to the async plugin
+ *                            load and WILL run). The preview is/will be correct.
+ * - `"verify-failed"`      — TRANSIENT: the re-run happened but `__timelines`
+ *                            momentarily read empty. Live state is correct → do
+ *                            NOT escalate. (Was a bare `false` before.)
+ * - `"cannot-soft-reload"` — PERMANENT/STRUCTURAL: no gsap runtime, no rebind
+ *                            hook, no scopable target key, or no script element
+ *                            to replace. The preview is stale/broken → escalate.
+ *
+ * The async MotionPath-plugin load failure is still surfaced via
+ * `onAsyncFailure` (it fires after this returned `"applied"` optimistically).
+ */
+export type SoftReloadResult = "applied" | "verify-failed" | "cannot-soft-reload";
+
 /**
  * Replace the GSAP script in the live iframe without reloading. This preserves
  * the WebGL context and shader transition cache.
@@ -60,22 +155,60 @@ function verifyTimelinesPopulated(win: IframeWindow): boolean {
  * elements (sub-compositions) are not visible to `querySelectorAll` and will
  * fall back to a full iframe reload.
  *
- * Returns false (triggering a full reload fallback) when:
+ * Returns `"cannot-soft-reload"` (caller should full-reload) when:
  * - The iframe or GSAP runtime isn't available
- * - Multiple GSAP scripts are found (ambiguous which to replace)
- * - No matching GSAP script element exists in the live DOM
+ * - The rebind hook isn't installed
+ * - The script registers no scopable `__timelines` key
+ * - No GSAP script element exists in the live DOM
+ * - The synchronous re-run threw
+ *
+ * Returns `"verify-failed"` when the re-run executed but the target timeline
+ * keys read empty in the transient post-run window (live state is still correct).
+ *
+ * `onAsyncFailure` is invoked when the soft reload was deferred to load the
+ * MotionPath plugin (so this returned `"applied"` optimistically) but the plugin
+ * `<script>` then failed to load — the iframe is left without the plugin and the
+ * caller should perform a full reload to recover. It never fires on the
+ * synchronous paths.
  */
-export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: string): boolean {
-  if (!iframe || !scriptText) return false;
+export function applySoftReload(
+  iframe: HTMLIFrameElement | null,
+  scriptText: string,
+  onAsyncFailure?: () => void,
+): SoftReloadResult {
+  if (!iframe || !scriptText) return "cannot-soft-reload";
 
   const win = iframe.contentWindow as IframeWindow | null;
   const doc = iframe.contentDocument;
-  if (!win || !doc) return false;
-  if (!win.gsap || !win.__hfForceTimelineRebind) return false;
+  if (!win || !doc) return "cannot-soft-reload";
+  if (!win.gsap || !win.__hfForceTimelineRebind) return "cannot-soft-reload";
 
+  // Which composition(s) does this script rebuild? A soft reload re-runs ONE
+  // composition's GSAP script, which re-registers its own window.__timelines[key].
+  // In a multi-composition preview (top-level + inlined subcompositions) each
+  // composition owns a separate timeline keyed by its id, and they're all children
+  // of the global timeline — so tearing down ALL of them (or the global timeline's
+  // children) and re-running a single script wipes every OTHER composition,
+  // reverting its edits. Scope the teardown to the keys THIS script re-registers.
+  const targetKeys = [...scriptText.matchAll(/__timelines\s*\[\s*["'`]([^"'`]+)["'`]\s*\]/g)]
+    .map((m) => m[1]!)
+    .filter((key) => key !== "__proxied");
+  if (targetKeys.length === 0) return "cannot-soft-reload"; // can't scope safely → full reload
   const gsapScripts = findGsapScriptElements(doc);
-  if (gsapScripts.length !== 1) return false;
-  const oldScriptEl = gsapScripts[0]!;
+  if (gsapScripts.length === 0) return "cannot-soft-reload";
+  // Remove only the stale script element(s) that registered a target key; one we
+  // can't match in the doc is left alone (re-running appends a fresh element).
+  const staleScripts = gsapScripts.filter((script) =>
+    targetKeys.some((key) => {
+      const text = script.textContent || "";
+      return text.includes(`__timelines["${key}"]`) || text.includes(`__timelines['${key}']`);
+    }),
+  );
+  // Multiple GSAP scripts exist but none registers a key this script owns — we
+  // can't identify which element to replace (ambiguous, matching
+  // extractGsapScriptText's single-script requirement). Escalate to a full reload
+  // rather than killing the target timeline and appending an orphan script.
+  if (gsapScripts.length > 1 && staleScripts.length === 0) return "cannot-soft-reload";
 
   const currentTime = win.__player?.getTime?.() ?? 0;
 
@@ -91,47 +224,55 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
     const timelines = win.__timelines;
     const allTargets: Element[] = [];
 
+    // Kill ONLY the target composition's timeline(s) — leaving every other
+    // composition's timeline (and its children on the global timeline) intact.
     if (timelines) {
-      for (const key of Object.keys(timelines)) {
-        if (key === "__proxied") continue;
-        try {
-          const tl = timelines[key] as {
-            kill?: () => void;
-            getChildren?: (deep: boolean) => Array<{ targets?: () => Element[] }>;
-          };
-          if (tl?.getChildren) {
-            try {
-              for (const child of tl.getChildren(true)) {
-                if (typeof child.targets === "function") {
-                  for (const t of child.targets()) allTargets.push(t);
-                }
+      for (const key of targetKeys) {
+        const tl = timelines[key] as
+          | {
+              kill?: () => void;
+              getChildren?: (deep: boolean) => Array<{ targets?: () => Element[] }>;
+            }
+          | undefined;
+        if (!tl) continue;
+        if (tl.getChildren) {
+          try {
+            for (const child of tl.getChildren(true)) {
+              if (typeof child.targets === "function") {
+                for (const t of child.targets()) allTargets.push(t);
               }
-            } catch {}
-          }
-          tl?.kill?.();
+            }
+          } catch {}
+        }
+        try {
+          tl.kill?.();
         } catch {}
         delete timelines[key];
       }
     }
 
-    // Kill bare gsap.to/from tweens not registered on __timelines
-    if (win.gsap?.globalTimeline?.getChildren) {
-      try {
-        for (const child of win.gsap.globalTimeline.getChildren(false)) {
-          child.kill?.();
-        }
-      } catch {}
-    }
-
-    // Clear residual inline transforms left by killed tweens so from() tweens
-    // don't read stale end values from the DOM on re-execution
+    // Reset GSAP's internal transform cache so from() tweens don't read stale
+    // end values. `clearProps: "all"` is needed to flush the cache, but it also
+    // nukes the element's CSS base (position, width, height, etc.) from the
+    // HTML `style=""` attribute. Save → clear → restore → strip `transform`.
     if (allTargets.length > 0 && win.gsap?.set) {
+      const saved: Array<[Element, string]> = [];
+      for (const el of allTargets) {
+        const s = (el as HTMLElement).style;
+        if (s?.cssText != null) saved.push([el, s.cssText]);
+      }
       try {
         win.gsap.set(allTargets, { clearProps: "all" });
       } catch {}
+      for (const [el, css] of saved) {
+        const s = (el as HTMLElement).style;
+        if (!s) continue;
+        s.cssText = css;
+        s.removeProperty("transform");
+      }
     }
 
-    oldScriptEl.remove();
+    for (const script of staleScripts) script.remove();
 
     const executeScript = () => {
       if (win.MotionPathPlugin && win.gsap?.registerPlugin) {
@@ -148,10 +289,41 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
     const needsMotionPath = /motionPath\s*[:{]/.test(scriptText);
     if (needsMotionPath && !win.MotionPathPlugin && win.gsap) {
       deferredToAsync = true;
+      // A prior soft reload is already fetching the plugin — don't queue a second
+      // <script> (it re-flashes the iframe). Defer THIS script's execution until
+      // the in-flight load settles via a one-shot poll. The bootstrap guard is
+      // the single source of truth for "plugin fetch in progress".
+      if (win.__hfMotionPathPluginLoading) {
+        const started = Date.now();
+        const poll = win.setInterval(() => {
+          if (win.MotionPathPlugin) {
+            win.clearInterval(poll);
+            executeScript();
+          } else if (!win.__hfMotionPathPluginLoading || Date.now() - started > 10000) {
+            // The in-flight load finished without registering the plugin (errored)
+            // or we timed out — recover with a full reload instead of running a
+            // script that references a missing plugin.
+            win.clearInterval(poll);
+            onAsyncFailure?.();
+          }
+        }, 50);
+        return;
+      }
+      win.__hfMotionPathPluginLoading = true;
       const pluginScript = doc.createElement("script");
-      pluginScript.src = "https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/MotionPathPlugin.min.js";
-      pluginScript.onload = () => executeScript();
-      pluginScript.onerror = () => executeScript();
+      pluginScript.src = MOTION_PATH_PLUGIN_CDN;
+      pluginScript.onload = () => {
+        win.__hfMotionPathPluginLoading = false;
+        executeScript();
+      };
+      pluginScript.onerror = () => {
+        // The plugin failed to load. Running executeScript() now would leave the
+        // iframe with a motionPath tween referencing a missing plugin while the
+        // caller already thinks the soft reload succeeded. Signal failure so the
+        // caller can full-reload (which fetches the plugin fresh) instead.
+        win.__hfMotionPathPluginLoading = false;
+        onAsyncFailure?.();
+      };
       doc.head.appendChild(pluginScript);
       return;
     }
@@ -166,10 +338,16 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
       doReload();
     }
     // When MotionPath needs async loading, the script hasn't executed yet —
-    // skip the __timelines check and return true optimistically.
-    if (deferredToAsync) return true;
-    return verifyTimelinesPopulated(win);
+    // skip the __timelines check and report success optimistically (the script
+    // WILL run on plugin load; onAsyncFailure covers the CDN-error case).
+    if (deferredToAsync) return "applied";
+    // The re-run executed. If the target keys read back, we're done; otherwise
+    // it's the TRANSIENT empty-timeline window (live state is correct) — surfaced
+    // as "verify-failed" so callers know NOT to escalate.
+    return verifyTimelinesPopulated(win, targetKeys) ? "applied" : "verify-failed";
   } catch {
-    return false;
+    // The synchronous re-run threw — the preview is now genuinely broken (target
+    // timeline killed, script not re-registered). Escalate to a full reload.
+    return "cannot-soft-reload";
   }
 }

package/src/utils/studioHelpers.test.ts

@@ -1,5 +1,11 @@
+// @vitest-environment happy-dom
+
 import { describe, expect, it } from "vitest";
-import { findMatchingTimelineElementId, resolveTimelineSelectionSeekTime } from "./studioHelpers";
+import {
+  findMatchingTimelineElementId,
+  findTimelineIdByAncestor,
+  resolveTimelineSelectionSeekTime,
+} from "./studioHelpers";
 
 describe("resolveTimelineSelectionSeekTime", () => {
   it("keeps the current time when it is already inside the clip range", () => {
@@ -42,3 +48,27 @@ describe("findMatchingTimelineElementId", () => {
     expect(findMatchingTimelineElementId({ id: "ghost", sourceFile: "index.html" }, [])).toBe(null);
   });
 });
+
+describe("findTimelineIdByAncestor", () => {
+  const el = (over: Record<string, unknown>) =>
+    ({ id: "x", start: 0, duration: 1, track: 0, tag: "div", ...over }) as never;
+
+  it("resolves a static descendant (.num) to its nearest clip ancestor", () => {
+    // #stat1 (a clip) > .num (selected, not a clip)
+    const stat1 = document.createElement("div");
+    stat1.id = "stat1";
+    const num = document.createElement("div");
+    num.className = "num";
+    stat1.appendChild(num);
+
+    const els = [el({ id: "stat1", domId: "stat1", key: "index.html#stat1" })];
+    expect(findTimelineIdByAncestor(num, els, "index.html")).toBe("index.html#stat1");
+  });
+
+  it("returns null when no ancestor is a clip", () => {
+    const wrap = document.createElement("div");
+    const child = document.createElement("span");
+    wrap.appendChild(child);
+    expect(findTimelineIdByAncestor(child, [], "index.html")).toBe(null);
+  });
+});