@hyperframes/studio 0.7.52 → 0.7.54

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -38,6 +38,27 @@ function result(over: Partial<MutationResult> = {}): MutationResult {
   return { ok: true, scriptText: "tl.set('#a',{})", ...over };
 }
 
+/** The canonical drag commit options every path-decision test drives with. */
+function dragOptions() {
+  return {
+    label: "drag",
+    softReload: true,
+    instantPatch: { selector: "#a", change: { kind: "set" as const, props: { x: 10 } } },
+  };
+}
+
+function syncDragPreview(res: MutationResult, reloadPreview: () => void) {
+  applyPreviewSync(FAKE_IFRAME, res, dragOptions(), reloadPreview);
+}
+
+function expectSoftReloadedWith(onAsyncFailure: unknown, authoredHtml: string | undefined) {
+  expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", {
+    onAsyncFailure,
+    currentTimeOverride: 0,
+    authoredHtml,
+  });
+}
+
 describe("applyPreviewSync", () => {
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
@@ -49,16 +70,7 @@ describe("applyPreviewSync", () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result(),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result(), reloadPreview);
 
     expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
       kind: "set",
@@ -73,20 +85,11 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("applied");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // reloadPreview is wired as onAsyncFailure (3rd arg) so a MotionPath-plugin
     // CDN load failure escalates to a full reload — but it is NOT called eagerly.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // A successful instant patch is the fast path; here it missed → fallback event.
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -100,20 +103,11 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("verify-failed");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // U4: "verify-failed" is the TRANSIENT empty-timeline window — the live state
     // is correct, so we must NOT escalate to a full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // Telemetry records the suppressed transient (escalated: false).
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -131,19 +125,10 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("cannot-soft-reload");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // Structural failure: the preview is genuinely stale/broken → full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -167,7 +152,7 @@ describe("applyPreviewSync", () => {
     );
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // "applied" emits no telemetry (only the failure paths do).
     expect(trackStudioEvent).not.toHaveBeenCalled();
@@ -185,7 +170,7 @@ describe("applyPreviewSync", () => {
     );
 
     // onAsyncFailure is wired, but the transient result does not trigger it.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -204,7 +189,7 @@ describe("applyPreviewSync", () => {
       reloadPreview,
     );
 
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -291,6 +276,57 @@ function mockFetchResult(over: Partial<MutationResult> = {}): void {
 }
 
 describe("runCommit — instantPatch wiring", () => {
+  it("no-op commit with an instantPatch still patches the runtime (paired x/y commits)", async () => {
+    patchRuntimeTweenInPlace.mockReturnValue(true);
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "update-property", property: "y", value: 311 },
+        {
+          label: "Move layer",
+          softReload: true,
+          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 485, y: 311 } } },
+        },
+      );
+    });
+
+    // The file already matched (changed:false) but the runtime patch deferred
+    // from the paired first commit must still land.
+    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
+      kind: "set",
+      props: { x: 485, y: 311 },
+    });
+    expect(deps.reloadPreview).not.toHaveBeenCalled();
+  });
+
+  it("no-op commit whose instant patch MISSES soft-reloads (never full-reloads)", async () => {
+    // Server contract: gsap-mutations returns scriptText on EVERY response,
+    // including changed:false — so the fallback re-runs the identical script
+    // ("applied") instead of escalating a genuine no-op to a full reload.
+    patchRuntimeTweenInPlace.mockReturnValue(false);
+    applySoftReload.mockReturnValue("applied");
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "update-property", property: "y", value: 311 },
+        {
+          label: "Move layer",
+          softReload: true,
+          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 485, y: 311 } } },
+        },
+      );
+    });
+
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
+    expect(deps.reloadPreview).not.toHaveBeenCalled();
+  });
+
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
     applySoftReload.mockReset();
@@ -308,15 +344,7 @@ describe("runCommit — instantPatch wiring", () => {
     const deps = renderCommitHook();
 
     await act(async () => {
-      await deps.api.commitMutation(
-        selection,
-        { x: 10 },
-        {
-          label: "drag",
-          softReload: true,
-          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-        },
-      );
+      await deps.api.commitMutation(selection, { x: 10 }, dragOptions());
     });
 
     expect(fetch).toHaveBeenCalledTimes(1); // source mutation persisted
@@ -333,19 +361,11 @@ describe("runCommit — instantPatch wiring", () => {
     const deps = renderCommitHook();
 
     await act(async () => {
-      await deps.api.commitMutation(
-        selection,
-        { x: 10 },
-        {
-          label: "drag",
-          softReload: true,
-          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-        },
-      );
+      await deps.api.commitMutation(selection, { x: 10 }, dragOptions());
     });
 
     expect(fetch).toHaveBeenCalledTimes(1);
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
     expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
   });
@@ -360,7 +380,7 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 });

package/src/hooks/useGsapScriptCommits.ts

@@ -66,12 +66,17 @@ function softReloadOrEscalate(
   scriptText: string,
   reloadPreview: () => void,
   origin: "preview_sync" | "sdk_refresh",
+  authoredHtml?: string,
 ): void {
   // Seek the rebuilt timeline to the studio's own authoritative scrub position,
   // not the iframe's raw `__player.getTime()` — see the comment in
   // applySoftReload for why the two can desync after a keyframe-node drag.
   const currentTime = usePlayerStore.getState().currentTime;
-  const result: SoftReloadResult = applySoftReload(iframe, scriptText, reloadPreview, currentTime);
+  const result: SoftReloadResult = applySoftReload(iframe, scriptText, {
+    onAsyncFailure: reloadPreview,
+    currentTimeOverride: currentTime,
+    authoredHtml,
+  });
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
     origin,
@@ -116,7 +121,13 @@ export function applyPreviewSync(
     // already correct on screen, and a remount re-flashes the WebGL context AND
     // re-inlines subcomps (reverting their keyframes). The async MotionPath-plugin
     // load failure escalates separately via `onAsyncFailure`.
-    softReloadOrEscalate(iframe, result.scriptText, reloadPreview, "preview_sync");
+    softReloadOrEscalate(
+      iframe,
+      result.scriptText,
+      reloadPreview,
+      "preview_sync",
+      result.after ?? undefined,
+    );
   } else {
     reloadPreview();
   }
@@ -149,7 +160,19 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       if (options.skipReload) return;
       throw error;
     }
-    if (result.changed === false) return;
+    if (result.changed === false) {
+      // The FILE already matched, but a deferred instant patch may still be
+      // owed to the RUNTIME: paired commits (x with skipReload, then y carrying
+      // the patch for both) rely on the SECOND commit to sync the preview — if
+      // that half happens to be a no-op (a purely-horizontal drag or resize
+      // compensation), returning here would leave the runtime showing the old
+      // value while the file holds the new one. Patching in place is idempotent
+      // when the values truly match everywhere.
+      if (!options.skipReload && options.instantPatch) {
+        applyPreviewSync(previewIframeRef.current, result, options, reloadPreview);
+      }
+      return;
+    }
     domEditSaveTimestampRef.current = Date.now();
     if (result.before != null && result.after != null) {
       await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
@@ -196,7 +219,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
         // plugin-CDN load error genuinely breaks the iframe → full reload. Per U4, a
         // synchronous "verify-failed" (transient empty __timelines) does NOT escalate,
         // but a "cannot-soft-reload" (structural failure) does.
-        softReloadOrEscalate(previewIframeRef.current, script, reloadPreview, "sdk_refresh");
+        softReloadOrEscalate(previewIframeRef.current, script, reloadPreview, "sdk_refresh", after);
       } else {
         reloadPreview();
       }

package/src/utils/authoredOpacity.ts

@@ -0,0 +1,35 @@
+/**
+ * Authored-opacity contract, studio side. The runtime stamps every graded
+ * element's authored inline opacity at document parse time (see
+ * installAuthoredOpacityCapture in @hyperframes/core); studio code that makes
+ * GSAP re-initialize tweens (soft reload, in-place patches) restores it so
+ * re-captures never bake a runtime transient in as a tween bound.
+ */
+import { COLOR_GRADING_AUTHORED_OPACITY_ATTR } from "@hyperframes/core/color-grading";
+
+interface AttributeReader {
+  getAttribute(name: string): string | null;
+}
+
+/**
+ * The stamped authored inline opacity. Three-state:
+ *   "0.98" — the authored value; "" — captured, authored none;
+ *   null — never captured (unknown).
+ * Duck-typed so iframe-realm elements (no shared HTMLElement) work.
+ */
+export function readStampedAuthoredOpacity(element: AttributeReader): string | null {
+  return element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
+}
+
+/**
+ * Write an authored inline opacity back: "" removes the property, a value sets
+ * it. Priority-lossy by design: the capture reads `style.opacity` (value only)
+ * and the write sets no priority, so an authored `opacity: X !important`
+ * round-trips as `opacity: X`. The only `!important` opacity in the pipeline
+ * is the color-grading runtime hide — a transient this contract exists to
+ * discard — and authored compositions don't `!important` their opacity.
+ */
+export function applyAuthoredInlineOpacity(style: CSSStyleDeclaration, authored: string): void {
+  if (authored === "") style.removeProperty("opacity");
+  else style.setProperty("opacity", authored);
+}

package/src/utils/elementGsap.ts

@@ -0,0 +1,31 @@
+/**
+ * GSAP access through an ELEMENT'S OWN window (the preview iframe's runtime),
+ * not the studio window. This is the single way studio gesture code touches an
+ * iframe element's GSAP position outside the commit pipeline — the resize
+ * anchor pin (apply + restore) and the post-commit live correction. The commit
+ * pipeline itself stays the owner of persisted values.
+ */
+type ElementGsapWindow = Window & {
+  gsap?: {
+    set?: (target: Element, vars: Record<string, number>) => void;
+    getProperty?: (target: Element, prop: string) => unknown;
+  };
+};
+
+function gsapOf(element: HTMLElement): ElementGsapWindow["gsap"] | undefined {
+  return (element.ownerDocument.defaultView as ElementGsapWindow | null)?.gsap;
+}
+
+/** Set the element's GSAP x/y. Returns false when no runtime is reachable. */
+export function setElementGsapPosition(element: HTMLElement, x: number, y: number): boolean {
+  const gsap = gsapOf(element);
+  if (!gsap?.set) return false;
+  gsap.set(element, { x, y });
+  return true;
+}
+
+/** The element's GSAP numeric property, or null when unreadable. */
+export function readElementGsapNumber(element: HTMLElement, prop: string): number | null {
+  const value = Number(gsapOf(element)?.getProperty?.(element, prop));
+  return Number.isFinite(value) ? value : null;
+}

package/src/utils/gsapSoftReload.test.ts

@@ -107,7 +107,7 @@ describe("applySoftReload", () => {
     // async commit resolves. The rebuilt timeline must re-seek to the caller's
     // value, not the iframe's possibly-stale one.
     const { iframe, contentWindow } = buildMockIframe();
-    const result = applySoftReload(iframe, SCRIPT_TEXT, undefined, 0);
+    const result = applySoftReload(iframe, SCRIPT_TEXT, { currentTimeOverride: 0 });
     expect(result).toBe("applied");
     expect(contentWindow.__player.seek).toHaveBeenCalledWith(0);
   });
@@ -244,7 +244,7 @@ describe("applySoftReload", () => {
     (iframe.contentDocument as unknown as { head: unknown }).head = head;
 
     const onAsyncFailure = vi.fn();
-    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, onAsyncFailure);
+    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.
@@ -363,3 +363,87 @@ describe("ensureMotionPathPluginLoaded", () => {
     expect(appendedScripts).toHaveLength(2);
   });
 });
+
+// The authored-opacity restore: before the script re-runs (and its tweens
+// re-capture bounds), every animated element's inline opacity must be put back
+// to its AUTHORED value — from the after-write file HTML when provided, else
+// from the parse-time stamp. Otherwise a runtime transient (the color-grading
+// hide's 0, a mid-flight tween value) becomes a permanent tween bound.
+describe("applySoftReload authored-opacity restore", () => {
+  function buildIframeWithTarget(el: HTMLElement, overrides: Record<string, unknown> = {}) {
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent =
+      'const tl = gsap.timeline({ paused: true }); tl.to("#box", { opacity: 0.5 });';
+    const tl = {
+      kill: vi.fn(),
+      pause: vi.fn(),
+      getChildren: () => [{ targets: () => [el] }],
+    };
+    const contentWindow = {
+      gsap: { timeline: vi.fn(), set: vi.fn() },
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: { root: tl } as Record<string, unknown>,
+      __player: { getTime: () => 2.0, seek: vi.fn() },
+      __hfStudioManualEditsApply: vi.fn(),
+      ...overrides,
+    };
+    const container = document.createElement("div");
+    container.appendChild(scriptEl);
+    // Intercept only POST-SETUP appends: simulate the re-run script
+    // repopulating __timelines (as in buildMockIframe).
+    const realAppendChild = container.appendChild.bind(container);
+    container.appendChild = <T extends Node>(node: T): T => {
+      const result = realAppendChild(node);
+      if (node instanceof HTMLScriptElement && node.textContent?.includes("gsap.timeline")) {
+        contentWindow.__timelines.root = { kill: vi.fn(), pause: vi.fn() };
+      }
+      return result;
+    };
+    const contentDocument = {
+      querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [scriptEl] : []),
+      createElement: (tag: string) => document.createElement(tag),
+      body: container,
+      head: document.createElement("div"),
+    };
+    return { iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement };
+  }
+
+  /** Run one restore cycle over `el` and return the final inline opacity. */
+  function restoreOpacity(el: HTMLElement, authoredHtml?: string): string {
+    const { iframe } = buildIframeWithTarget(el);
+    expect(applySoftReload(iframe, SCRIPT_TEXT, authoredHtml ? { authoredHtml } : {})).toBe(
+      "applied",
+    );
+    return el.style.getPropertyValue("opacity");
+  }
+
+  it("restores opacity from the after-write HTML (matched by data-hf-id)", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-id", "hf-1");
+    el.style.setProperty("opacity", "0", "important"); // the grading hide
+
+    const opacity = restoreOpacity(
+      el,
+      '<html><body><img data-hf-id="hf-1" style="opacity: 0.98"></body></html>',
+    );
+
+    expect(opacity).toBe("0.98");
+    expect(el.style.getPropertyPriority("opacity")).toBe("");
+  });
+
+  it("falls back to the parse-time stamp when no after-write HTML is given", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-authored-opacity", "0.75");
+    el.style.opacity = "0.123"; // mid-flight tween transient
+
+    expect(restoreOpacity(el)).toBe("0.75");
+  });
+
+  it("an empty stamp (authored none) removes the inline opacity", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-authored-opacity", "");
+    el.style.opacity = "0";
+
+    expect(restoreOpacity(el)).toBe("");
+  });
+});

package/src/utils/gsapSoftReload.ts

@@ -1,3 +1,6 @@
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
+
 type IframeWindow = Window & {
   __timelines?: Record<string, { kill?: () => void; pause?: () => void }>;
   __player?: { getTime?: () => number; seek?: (t: number) => void };
@@ -171,12 +174,21 @@ export type SoftReloadResult = "applied" | "verify-failed" | "cannot-soft-reload
  * caller should perform a full reload to recover. It never fires on the
  * synchronous paths.
  */
+export interface SoftReloadOptions {
+  /** Escalation for async plugin-load failures (e.g. MotionPath CDN error). */
+  onAsyncFailure?: () => void;
+  /** Seek target for the rebuilt timeline; defaults to the iframe player time. */
+  currentTimeOverride?: number;
+  /** After-write file HTML — the primary source for authored-opacity restore. */
+  authoredHtml?: string;
+}
+
 export function applySoftReload(
   iframe: HTMLIFrameElement | null,
   scriptText: string,
-  onAsyncFailure?: () => void,
-  currentTimeOverride?: number,
+  options: SoftReloadOptions = {},
 ): SoftReloadResult {
+  const { onAsyncFailure, currentTimeOverride, authoredHtml } = options;
   if (!iframe || !scriptText) return "cannot-soft-reload";
 
   const win = iframe.contentWindow as IframeWindow | null;
@@ -227,6 +239,36 @@ export function applySoftReload(
   // full iframe reload that destroys the very WebGL context we're preserving.
   let deferredToAsync = false;
 
+  // Authored-opacity resolution for the restore loop below. Three-state:
+  //   "0.98" — the element's authored inline opacity
+  //   ""     — resolved, and the element has NO authored inline opacity
+  //   null   — unknown (no authored HTML supplied, element not found in it,
+  //            and no runtime parse-time stamp)
+  // The just-written file (`authoredHtml`) is the current truth; the runtime's
+  // parse-time stamp (data-hf-authored-opacity, installAuthoredOpacityCapture)
+  // covers elements the file lookup can't resolve. Parsed lazily, at most once.
+  let authoredDoc: Document | null | undefined;
+  const findAuthoredSource = (el: HTMLElement): Element | null => {
+    if (authoredDoc === undefined) {
+      try {
+        authoredDoc = authoredHtml
+          ? new DOMParser().parseFromString(authoredHtml, "text/html")
+          : null;
+      } catch {
+        authoredDoc = null;
+      }
+    }
+    if (!authoredDoc) return null;
+    const hfId = el.getAttribute("data-hf-id");
+    if (hfId) return authoredDoc.querySelector(`[data-hf-id="${hfId}"]`);
+    return el.id ? authoredDoc.getElementById(el.id) : null;
+  };
+  const readAuthoredOpacity = (el: HTMLElement): string | null => {
+    const source = findAuthoredSource(el);
+    if (source instanceof HTMLElement) return source.style.opacity;
+    return readStampedAuthoredOpacity(el);
+  };
+
   // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
@@ -283,19 +325,39 @@ export function applySoftReload(
     // 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]> = [];
+      const saved: Array<[HTMLElement, string]> = [];
       for (const el of allTargets) {
-        const s = (el as HTMLElement).style;
-        if (s?.cssText != null) saved.push([el, s.cssText]);
+        // Iframe-realm node: instanceof HTMLElement fails across realms, and
+        // gsap targets() only yields elements here — style access is duck-typed.
+        const styled = el as HTMLElement;
+        if (styled.style?.cssText != null) saved.push([styled, styled.style.cssText]);
       }
       try {
         win.gsap.set(allTargets, { clearProps: "all" });
       } catch {}
       for (const [el, css] of saved) {
-        const s = (el as HTMLElement).style;
-        if (!s) continue;
+        const s = el.style;
         s.cssText = css;
         s.removeProperty("transform");
+        // The restored cssText carries RUNTIME opacity, not authored opacity:
+        // a mid-flight tween's interpolated value, or the color-grading hide
+        // (`opacity: 0 !important`). The re-run script's tweens re-initialize
+        // against it — a from() captures it as its END, a to() as its START —
+        // turning the transient into the tween's permanent bound (dimmed or
+        // invisible elements). Put the AUTHORED inline opacity back; the seek
+        // below re-renders the correct animated value either way.
+        const authored = readAuthoredOpacity(el);
+        if (authored !== null) {
+          applyAuthoredInlineOpacity(s, authored);
+        } else if (
+          el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR) &&
+          s.getPropertyValue("opacity") === "0" &&
+          s.getPropertyPriority("opacity") === "important"
+        ) {
+          // Authored value unknown, but this is definitely the grading hide —
+          // never let a from() capture 0; fall back to the CSS cascade.
+          s.removeProperty("opacity");
+        }
       }
     }