@hyperframes/studio 0.8.108 → 0.8.110

package/src/hooks/timelineElementsAttribute.test.ts

@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { configurable: true, value: true });
+import type { TimelineElement } from "../player";
+
+const saved = vi.hoisted(() => ({ inputs: [] as Array<Record<string, unknown>> }));
+vi.mock("../utils/studioFileHistory", () => ({
+  saveProjectFilesWithHistory: vi.fn(async (input: Record<string, unknown>) => {
+    saved.inputs.push(input);
+    return [];
+  }),
+}));
+
+import { useSetElementsAttribute } from "./timelineElementsAttribute";
+
+const clip = (id: string, sourceFile?: string): TimelineElement => ({
+  id,
+  domId: id,
+  tag: "audio",
+  start: 0,
+  duration: 1,
+  track: 0,
+  sourceFile,
+});
+
+describe("useSetElementsAttribute", () => {
+  it("writes every clip's attribute in one history entry, one builder per file", async () => {
+    const showToast = vi.fn();
+    let write: ReturnType<typeof useSetElementsAttribute> | null = null;
+    function Probe() {
+      write = useSetElementsAttribute({
+        projectIdRef: { current: "p1" },
+        activeCompPath: "index.html",
+        showToast,
+        writeProjectFile: vi.fn(async () => {}),
+        recordEdit: vi.fn(async () => {}),
+        previewIframeRef: { current: null },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Probe)));
+    await write?.(
+      [
+        { element: clip("a"), value: "0.5" },
+        { element: clip("b"), value: "2" },
+        { element: clip("c", "scene.html"), value: "1.5" },
+      ],
+      "data-volume",
+      "Audio Gain",
+    );
+    act(() => root.unmount());
+    expect(showToast).not.toHaveBeenCalled();
+    expect(saved.inputs).toHaveLength(1);
+    const input = saved.inputs[0];
+    expect(input?.["label"]).toBe("Audio Gain");
+    const files = input?.["files"];
+    if (typeof files !== "object" || files === null) throw new Error("no files");
+    expect(Object.keys(files).sort()).toEqual(["index.html", "scene.html"]);
+    const build = Reflect.get(files, "index.html");
+    const html = '<audio id="a" data-volume="1"></audio><audio id="b"></audio>';
+    const out = typeof build === "function" ? String(build(html)) : "";
+    expect(out).toContain('id="a" data-volume="0.5"');
+    expect(out).toMatch(/id="b"[^>]*data-volume="2"/);
+  });
+
+  it("refuses while recording, like the single-clip write", async () => {
+    saved.inputs.length = 0;
+    const showToast = vi.fn();
+    let write: ReturnType<typeof useSetElementsAttribute> | null = null;
+    function Probe() {
+      write = useSetElementsAttribute({
+        projectIdRef: { current: "p1" },
+        activeCompPath: "index.html",
+        showToast,
+        writeProjectFile: vi.fn(async () => {}),
+        recordEdit: vi.fn(async () => {}),
+        previewIframeRef: { current: null },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        isRecordingRef: { current: true },
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Probe)));
+    await write?.([{ element: clip("a"), value: "0.5" }], "data-volume", "Audio Gain");
+    act(() => root.unmount());
+    expect(saved.inputs).toHaveLength(0);
+    expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error");
+  });
+});

package/src/hooks/timelineElementsAttribute.ts

@@ -0,0 +1,113 @@
+import { useCallback } from "react";
+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
+import { syncStoredElementAttribute } from "../player/lib/automationStoreSync";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { applyPatchByTarget } from "../utils/sourcePatcher";
+import {
+  buildPatchTarget,
+  findTimelineElementInIframe,
+  readFileContent,
+} from "./timelineEditingHelpers";
+import type { UseTimelineElementVisibilityEditingInput } from "./timelineTrackVisibility";
+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
+
+type ElementAttributeEdits = Parameters<
+  NonNullable<TimelineEditCallbacks["onSetElementsAttributeQuiet"]>
+>[0];
+
+type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
+
+function editsByFile(
+  edits: ElementAttributeEdits,
+  activeCompPath: string | null,
+): Map<string, Array<{ target: PatchTarget; value: string | null }>> {
+  const byFile = new Map<string, Array<{ target: PatchTarget; value: string | null }>>();
+  for (const { element, value } of edits) {
+    const target = buildPatchTarget(element);
+    if (!target) throw new Error("A clip has no id to save it by");
+    const path = element.sourceFile || activeCompPath || "index.html";
+    byFile.set(path, [...(byFile.get(path) ?? []), { target, value }]);
+  }
+  return byFile;
+}
+
+function patchLive(
+  iframe: HTMLIFrameElement | null,
+  edits: ElementAttributeEdits,
+  attr: string,
+  activeCompPath: string | null,
+): void {
+  for (const { element, value } of edits) {
+    const node = findTimelineElementInIframe(iframe, element, activeCompPath);
+    if (value === null) node?.removeAttribute(attr);
+    else node?.setAttribute(attr, value);
+    syncStoredElementAttribute(element, attr, value);
+  }
+}
+
+/** One attribute written on several clips as a single save and a single undo step. */
+export function useSetElementsAttribute({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+}: UseTimelineElementVisibilityEditingInput) {
+  return useCallback(
+    async (
+      edits: ElementAttributeEdits,
+      attr: string,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const projectId = projectForTimelineSave(
+        isRecordingRef?.current,
+        projectIdRef.current,
+        showToast,
+      );
+      if (typeof projectId !== "string") return projectId;
+      if (edits.length === 0) return { status: "saved" };
+      try {
+        const byFile = editsByFile(edits, activeCompPath);
+        const files = Object.fromEntries(
+          [...byFile].map(([path, patches]) => [
+            path,
+            (before: string) =>
+              patches.reduce(
+                (html, { target, value }) =>
+                  applyPatchByTarget(html, target, { type: "attribute", property: attr, value }),
+                before,
+              ),
+          ]),
+        );
+        for (const path of byFile.keys()) pendingTimelineEditPathRef.current.add(path);
+        await saveProjectFilesWithHistory({
+          projectId,
+          label,
+          files,
+          readFile: (path) => readFileContent(projectId, path),
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+        patchLive(previewIframeRef.current, edits, attr, activeCompPath);
+        return { status: "saved" };
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : "Could not save the clips";
+        showToast(reason, "error");
+        return { status: "failed", reason };
+      }
+    },
+    [
+      projectIdRef,
+      activeCompPath,
+      showToast,
+      writeProjectFile,
+      recordEdit,
+      previewIframeRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+    ],
+  );
+}

package/src/hooks/timelineLinkEditPlan.test.ts

@@ -0,0 +1,141 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../player";
+import { clipSyncState } from "../player/components/clipSync";
+import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";
+
+const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({
+  id,
+  domId: id,
+  tag,
+  src: "talk.mp4",
+  start: 2,
+  duration: 6,
+  track: tag === "audio" ? 1 : 0,
+  ...extra,
+});
+
+const video = clip("talk", "video", { link: "lk-1", muted: true });
+const audio = clip("talk-audio", "audio", { link: "lk-1" });
+const title = clip("title", "div");
+
+const SOURCE =
+  '<div><video id="talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6"></video><audio id="talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-volume="0.5"></audio></div>';
+
+describe("clipsToUnlink", () => {
+  it("unlinks a lone removed member and its orphaned partner", () => {
+    expect(clipsToUnlink([video], [video, audio, title]).map((el) => el.id)).toEqual([
+      "talk",
+      "talk-audio",
+    ]);
+  });
+
+  it("keeps a three-member group linked when one leaves", () => {
+    const third = clip("talk-2", "audio", { link: "lk-1" });
+    expect(clipsToUnlink([video], [video, audio, third]).map((el) => el.id)).toEqual(["talk"]);
+  });
+
+  it("ignores unlinked clips", () => {
+    expect(clipsToUnlink([title], [video, audio, title])).toEqual([]);
+  });
+
+  it("never reaches a same-id link in another source file", () => {
+    const childVideo = clip("c", "video", { link: "lk-1", sourceFile: "child.html" });
+    const removed = clipsToUnlink([video], [video, audio, childVideo]).map((el) => el.id);
+    expect(removed).toEqual(["talk", "talk-audio"]);
+  });
+});
+
+describe("planLinkEdit", () => {
+  const elements = [video, audio, title];
+
+  it("unlink strips data-link from both members", () => {
+    const plan = planLinkEdit({ kind: "unlink", elements: [video, audio] }, elements);
+    expect(plan?.label).toBe("Unlink clips");
+    expect(plan?.transform(SOURCE)).not.toContain("data-link");
+  });
+
+  it("link writes one fresh id on both", () => {
+    const unlinked = SOURCE.replaceAll(' data-link="lk-1"', "");
+    const plan = planLinkEdit({ kind: "link", elements: [video, audio] }, elements);
+    expect(plan?.transform(unlinked)?.match(/data-link="lk-1"/g)).toHaveLength(2);
+  });
+
+  it("merge folds the audio into the video", () => {
+    const plan = planLinkEdit({ kind: "merge", video, audio }, elements);
+    const merged = plan?.transform(SOURCE) ?? "";
+    expect(merged).not.toContain("<audio");
+    expect(merged).toContain('data-volume="0.5"');
+    expect(merged).toContain('data-has-audio="true"');
+  });
+
+  it("detach puts the audio on the first free audio track", () => {
+    const talk = clip("talk", "video", { hasAudio: true });
+    const src =
+      '<div><video id="talk" src="talk.mp4" data-has-audio="true" data-start="2" data-duration="6"></video></div>';
+    const plan = planLinkEdit({ kind: "detach", element: talk }, [talk, title]);
+    const out = plan?.transform(src) ?? "";
+    expect(out).toContain('id="talk-audio"');
+    expect(out).toContain('data-track-index="1"');
+  });
+});
+
+describe("planLinkEdit into sync", () => {
+  const drifted =
+    '<div data-composition-id="main" data-duration="10"><video id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2" data-duration="6"></video><audio id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2.5" data-duration="6" data-media-start="0"></audio></div>';
+  const late = clip("talk-audio", "audio", { start: 2.5, playbackStart: 0 });
+
+  it("moves one clip's start, leaving its partner and link alone", () => {
+    const plan = planLinkEdit({ kind: "move-into-sync", element: late, start: 2 }, [video, late]);
+    expect(plan?.label).toBe("Move into Sync");
+    const html = plan?.transform(drifted) ?? "";
+    expect(html).toContain('id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2"');
+    expect(html).toContain('id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2"');
+  });
+
+  it("slips one clip's media start in place", () => {
+    const plan = planLinkEdit({ kind: "slip-into-sync", element: late, mediaStart: 0.5 }, [
+      video,
+      late,
+    ]);
+    expect(plan?.label).toBe("Slip into Sync");
+    const html = plan?.transform(drifted) ?? "";
+    expect(html).toContain('data-start="2.5" data-duration="6" data-media-start="0.5"');
+  });
+
+  it("slips the legacy playback-start attribute when that is what the clip uses", () => {
+    const legacy = { ...late, playbackStartAttr: "playback-start" as const };
+    const html =
+      planLinkEdit({ kind: "slip-into-sync", element: legacy, mediaStart: 0.5 }, [])?.transform(
+        '<audio id="talk-audio" data-playback-start="0"></audio>',
+      ) ?? "";
+    expect(html).toBe('<audio id="talk-audio" data-playback-start="0.5"></audio>');
+  });
+});
+
+describe("link edit plan", () => {
+  const PAIR =
+    '<div><video id="talk" src="talk.mp4" muted data-start="2" data-duration="6"></video><audio id="a" src="%SRC%" data-start="3" data-duration="3" data-media-start="1"></audio></div>';
+  const linkPlan = (src: string, audioEl: TimelineElement) => {
+    const v = clip("talk", "video", { muted: true });
+    const plan = planLinkEdit({ kind: "link", elements: [v, audioEl] }, [v, audioEl]);
+    return plan?.transform(PAIR.replace("%SRC%", src)) ?? "";
+  };
+
+  it("links a trimmed same-file audio with a sync origin that shows a nonzero offset", () => {
+    const trimmed = clip("a", "audio", { start: 3, duration: 3, playbackStart: 0 });
+    const out = linkPlan("talk.mp4", trimmed);
+    expect(out).toMatch(/<video[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);
+    expect(out).toMatch(/<audio[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);
+    const v = clip("talk", "video", { muted: true, syncOrigin: "lk-1" });
+    const a = { ...trimmed, syncOrigin: "lk-1" };
+    expect(clipSyncState(a, [v, a], 30)?.frames).toBe(30);
+  });
+
+  it("links different files without a sync origin", () => {
+    const music = clip("a", "audio", { src: "bgm.mp3" });
+    const out = linkPlan("bgm.mp3", music);
+    expect(out).toContain('data-link="lk-1"');
+    expect(out).not.toContain("data-sync-origin");
+  });
+});

package/src/hooks/timelineLinkEditPlan.ts

@@ -0,0 +1,128 @@
+import type { TimelineElement } from "../player";
+import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";
+import { buildPatchTarget, type PatchTarget } from "./timelineEditingHelpers";
+import { sharesLinkGroup } from "../player/components/audioClipLink";
+import { toAuthoredStart } from "../player/store/timelineElement";
+import { formatTimelineMediaOffset } from "../player/components/timelineEditing";
+import { applyPatchByTarget } from "../utils/sourcePatcher";
+import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
+import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
+import {
+  detachAudioInSource,
+  linkInSource,
+  mergeAudioInSource,
+  pickDetachedAudioTrack,
+  setLinkInSource,
+  sharesSourceFile,
+} from "../components/editor/mediaLinkEdits";
+
+export interface LinkEditPlan {
+  label: string;
+  anchor: TimelineElement;
+  transform: (source: string) => string | null;
+}
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+
+function targetsOf(elements: readonly TimelineElement[]): PatchTarget[] | null {
+  const targets = elements.map(buildPatchTarget);
+  return targets.every((target): target is PatchTarget => target !== null) ? targets : null;
+}
+
+/**
+ * The clips to strip `data-link` from when `removed` leave their groups: the
+ * removed clips themselves, plus any partner left alone in its group.
+ */
+export function clipsToUnlink(
+  removed: readonly TimelineElement[],
+  elements: readonly TimelineElement[],
+): TimelineElement[] {
+  const removedKeys = new Set(removed.map(keyOf));
+  const orphans = new Map<string, TimelineElement>();
+  for (const leaving of removed) {
+    const survivors = elements.filter(
+      (el) => sharesLinkGroup(el, leaving) && !removedKeys.has(keyOf(el)),
+    );
+    if (survivors.length === 1 && survivors[0]) orphans.set(keyOf(survivors[0]), survivors[0]);
+  }
+  return [...removed.filter((el) => el.link), ...orphans.values()];
+}
+
+type SyncEdit = Extract<TimelineLinkEdit, { kind: "move-into-sync" | "slip-into-sync" }>;
+
+function planSyncEdit(edit: SyncEdit): LinkEditPlan | null {
+  const target = buildPatchTarget(edit.element);
+  if (!target) return null;
+  if (edit.kind === "move-into-sync") {
+    const value = formatTimelineMediaOffset(toAuthoredStart(edit.element, edit.start));
+    return {
+      label: "Move into Sync",
+      anchor: edit.element,
+      transform: (s) => {
+        const moved = applyPatchByTarget(s, target, {
+          type: "attribute",
+          property: "start",
+          value,
+        });
+        return setCompositionDurationToContent(moved, furthestClipEndFromSource(moved));
+      },
+    };
+  }
+  const property = edit.element.playbackStartAttr ?? "media-start";
+  const value = formatTimelineMediaOffset(edit.mediaStart);
+  return {
+    label: "Slip into Sync",
+    anchor: edit.element,
+    transform: (s) => applyPatchByTarget(s, target, { type: "attribute", property, value }),
+  };
+}
+
+export function planLinkEdit(
+  edit: TimelineLinkEdit,
+  elements: readonly TimelineElement[],
+): LinkEditPlan | null {
+  switch (edit.kind) {
+    case "unlink": {
+      const members = clipsToUnlink(edit.elements, elements);
+      const targets = targetsOf(members);
+      const anchor = members[0];
+      if (!targets || !anchor) return null;
+      return { label: "Unlink clips", anchor, transform: (s) => setLinkInSource(s, targets, null) };
+    }
+    case "link": {
+      const targets = targetsOf(edit.elements);
+      const anchor = edit.elements[0];
+      if (!targets || !anchor) return null;
+      return {
+        label: "Link clips",
+        anchor,
+        transform: (s) => linkInSource(s, targets, { syncOrigin: sharesSourceFile(edit.elements) }),
+      };
+    }
+    case "detach": {
+      const target = buildPatchTarget(edit.element);
+      if (!target) return null;
+      const track = pickDetachedAudioTrack(elements, edit.element);
+      return {
+        label: "Detach audio",
+        anchor: edit.element,
+        transform: (s) =>
+          detachAudioInSource(s, { target, videoId: edit.element.domId ?? null, track })?.html ??
+          null,
+      };
+    }
+    case "move-into-sync":
+    case "slip-into-sync":
+      return planSyncEdit(edit);
+    case "merge": {
+      const videoTarget = buildPatchTarget(edit.video);
+      const audioTarget = buildPatchTarget(edit.audio);
+      if (!videoTarget || !audioTarget) return null;
+      return {
+        label: "Merge audio back into video",
+        anchor: edit.video,
+        transform: (s) => mergeAudioInSource(s, { videoTarget, audioTarget }),
+      };
+    }
+  }
+}

package/src/hooks/timelineMoveAdapter.ts

@@ -1,3 +1,4 @@
+import { useCallback } from "react";
 import type { TimelineElement } from "../player";
 import type {
   TimelineGroupCommitOptions,
@@ -45,3 +46,15 @@ export function persistTimelineMoveEditsAtomically(
     { coalesceKey, coalesceMs },
   );
 }
+
+export function useTimelineMoveEditsHandler(
+  handleTimelineGroupMove: AtomicMoveDeps["handleTimelineGroupMove"],
+): TimelineMoveEditsHandler {
+  return useCallback(
+    async (edits, coalesceKey, operation: TimelineMoveOperation = "timing", coalesceMs) => {
+      const deps = { handleTimelineGroupMove };
+      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);
+    },
+    [handleTimelineGroupMove],
+  );
+}

package/src/hooks/timelineTimingSync.test.ts

@@ -548,6 +548,65 @@ describe("nothing-to-rewrite timing edits rebind in place (no script re-executio
   });
 });
 
+describe("a timing edit's soft reload restores what GSAP wrote from the files", () => {
+  const script = (at: number) =>
+    `var tl = gsap.timeline({ paused: true }); tl.to("#wt", { width: 450 }, ${at}); tl.to("#nwid", { width: 400 }, ${at}); window.__timelines["root"] = tl;`;
+  const SUB = `<template><div data-composition-id="sub"><div id="nwid" data-hf-id="hf-n" style="left: 40px"></div></div></template>`;
+
+  // The live preview: the top-level timeline tweened a root element's and a nested element's width inline.
+  async function shift(fileOk: boolean) {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.body.innerHTML =
+      `<div id="root" data-composition-id="root"><div id="wt" data-hf-id="hf-w" style="left: 700px; width: 366px"></div>` +
+      `<div data-composition-file="compositions/sub.html"><div id="nwid" data-hf-id="hf-n" style="left: 40px; width: 288px"></div></div></div>` +
+      `<script>${script(0)}</script>`;
+    const [wt, nwid] = [doc.getElementById("wt")!, doc.getElementById("nwid")!];
+    const contentWindow = {
+      gsap: { timeline: vi.fn(), set: vi.fn() },
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: {
+        root: {
+          kill: vi.fn(),
+          getChildren: () => [{ targets: () => [wt, nwid], vars: { width: 450 } }],
+        },
+      } as Record<string, unknown>,
+      __player: { getTime: () => 1, seek: vi.fn() },
+    };
+    const iframe = { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement;
+    const fetchMock = vi.fn(async () =>
+      fileOk ? jsonResponse({ content: SUB }) : new Response("{}", { status: 404 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const after = `<html><body><div id="root" data-composition-id="root"><div id="wt" data-hf-id="hf-w" style="left: 700px"></div></div><script>${script(1)}</script></body></html>`;
+    const reloadPreview = vi.fn();
+
+    await finishClipTimingFallback({
+      ...clipFallbackInput({ reloadPreview, recordEdit: vi.fn(async () => {}) }),
+      iframe,
+      sdkGsap: { mutated: true, scriptText: script(1), after },
+    });
+    return { wt, nwid, reloadPreview, fetchMock };
+  }
+
+  it("puts back the root element from the file it wrote and the nested one from its own file", async () => {
+    const { wt, nwid, reloadPreview, fetchMock } = await shift(true);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining("/files/compositions%2Fsub.html"),
+    );
+    expect(reloadPreview).not.toHaveBeenCalled();
+    expect(wt.getAttribute("style")).toBe("left: 700px;");
+    expect(nwid.getAttribute("style")).toBe("left: 40px;");
+  });
+
+  it("reloads the preview in full when the nested file cannot be read", async () => {
+    const { nwid, reloadPreview } = await shift(false);
+
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(nwid.getAttribute("style")).toBe("left: 40px; width: 288px");
+  });
+});
+
 function installOwnedFileServer(
   contents: Map<string, string>,
   options: {

package/src/hooks/timelineTimingSync.ts

@@ -7,6 +7,8 @@ import {
   applySoftReload,
   applySoftReloadFinalization,
   extractGsapScriptText,
+  readNestedFiles,
+  settleNestedReads,
 } from "../utils/gsapSoftReload";
 import { furthestClipEndFromDocument } from "../player/lib/timelineElementHelpers";
 import type { RecordEditInput } from "../utils/studioFileHistory";
@@ -118,6 +120,7 @@ function syncTimingEditPreview(
   currentTime: number,
   reloadPreview: () => void,
   rebindWhenUnmutated: boolean,
+  nestedFiles: Map<string, string> | null | undefined,
 ): void {
   if (!outcome.mutated && rebindWhenUnmutated) {
     if (!rebindPreviewTiming(iframe, currentTime)) reloadPreview();
@@ -130,12 +133,15 @@ function syncTimingEditPreview(
   const result = applySoftReload(iframe, outcome.scriptText, {
     onAsyncFailure: reloadPreview,
     currentTimeOverride: currentTime,
+    authoredHtml: outcome.after,
+    nestedFiles,
   });
   if (result === "cannot-soft-reload") reloadPreview();
 }
 
 async function finishTimelineTimingFallback(input: {
   iframe: HTMLIFrameElement | null;
+  projectId: string | null;
   reloadPreview: () => void;
   gsapMutation?: () => Promise<GsapMutationStatus>;
   onGsapError: (error: unknown) => void;
@@ -160,12 +166,21 @@ async function finishTimelineTimingFallback(input: {
       return;
     }
   }
+  const { projectId } = input;
+  const nestedFiles = await settleNestedReads(
+    projectId && outcome.scriptText
+      ? readNestedFiles(input.iframe, outcome.scriptText, (path) =>
+          readFileContent(projectId, path),
+        )
+      : null,
+  );
   syncTimingEditPreview(
     input.iframe,
     outcome,
     usePlayerStore.getState().currentTime,
     input.reloadPreview,
     input.rebindWhenUnmutated,
+    nestedFiles,
   );
 }
 
@@ -384,7 +399,7 @@ export function sdkTimingGsapSync(
     return findTimelineScript(scripts)?.textContent ?? null;
   };
   if (timelineText(result.before) === timelineText(result.after)) return null;
-  return { mutated: true, scriptText: extractGsapScriptText(result.after) };
+  return { mutated: true, scriptText: extractGsapScriptText(result.after), after: result.after };
 }
 
 /** Timing delta a single-clip edit applies to its GSAP tweens. */
@@ -440,6 +455,7 @@ export function finishClipTimingFallback(input: {
     console.error(`[Timeline] Failed to ${edit.kind} GSAP positions`, err);
   return finishTimelineTimingFallback({
     iframe: input.iframe,
+    projectId,
     reloadPreview: input.reloadPreview,
     gsapMutation: sdkGsap
       ? () => Promise.resolve(sdkGsap)
@@ -498,6 +514,7 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
   if (sdkGsap) {
     await finishTimelineTimingFallback({
       iframe: input.iframe,
+      projectId: input.projectId,
       reloadPreview: input.reloadPreview,
       gsapMutation: () => Promise.resolve(sdkGsap),
       onGsapError,
@@ -507,6 +524,7 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
   }
   await finishTimelineTimingFallback({
     iframe: input.iframe,
+    projectId: input.projectId,
     reloadPreview: input.reloadPreview,
     gsapMutation: () =>
       foldGsapMutationIntoHistory({
@@ -519,6 +537,7 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
         gsapMutation: async (runOwnedMutation) => {
           let mutated = false;
           let scriptText: GsapMutationStatus["scriptText"] = null;
+          let after: string | undefined;
           for (const change of input.changes) {
             const changePath = input.resolveChangePath(change.element);
             const status = await runOwnedMutation(changePath, () =>
@@ -527,9 +546,9 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
             mutated = mutated || status.mutated;
             // The LAST mutation against the active comp carries the cumulative
             // rewritten script for that file.
-            if (changePath === activePath) scriptText = status.scriptText;
+            if (changePath === activePath) ({ scriptText, after } = status);
           }
-          return { mutated, scriptText: otherFileChanged ? null : scriptText };
+          return { mutated, scriptText: otherFileChanged ? null : scriptText, after };
         },
         onRollbackError: onGsapError,
       }),