@hyperframes/studio 0.7.57 → 0.7.58

package/src/utils/gsapSoftReload.ts

@@ -90,7 +90,7 @@ function isGsapScript(text: string): boolean {
   );
 }
 
-function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
+export function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
   const results: HTMLScriptElement[] = [];
   const scripts = doc.querySelectorAll<HTMLScriptElement>("script:not([src])");
   for (const script of scripts) {
@@ -102,8 +102,9 @@ function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
 /**
  * Extract the GSAP timeline script text from a serialized HTML document, for
  * feeding into applySoftReload. Returns null when zero or multiple GSAP scripts
- * are present (ambiguous — caller should fall back to a full reload), matching
- * applySoftReload's own single-script requirement.
+ * are present (ambiguous — a serialized snapshot can't say WHICH script a
+ * single rewritten text corresponds to; caller should fall back to a full
+ * reload), matching applySoftReload's own single-script requirement.
  */
 export function extractGsapScriptText(html: string): string | null {
   const doc = new DOMParser().parseFromString(html, "text/html");
@@ -183,157 +184,53 @@ export interface SoftReloadOptions {
   authoredHtml?: string;
 }
 
-/** One file's restore from the edit-history store: before (live) / after (target) bytes. */
-export interface UndoRestoreFile {
-  previous: string;
-  restored: string;
-}
-function idElementMap(doc: Document): Map<string, Element> {
-  const map = new Map<string, Element>();
-  for (const el of doc.querySelectorAll("[id]")) {
-    const id = el.getAttribute("id");
-    if (id) map.set(id, el);
-  }
-  return map;
-}
-
-// Strip id'd elements to bare `id` and blank GSAP scripts, in place: docs that
-// differ only in id'd attributes/inline-style/script text normalize equal; any
-// residual difference is beyond soft-reload's reach → caller full-reloads.
-function normalizeSoftResidual(doc: Document): void {
-  for (const el of doc.querySelectorAll("[id]")) {
-    const id = el.getAttribute("id");
-    for (const name of [...el.getAttributeNames()]) {
-      if (name !== "id") el.removeAttribute(name);
-    }
-    if (id) el.setAttribute("id", id);
-  }
-  for (const script of findGsapScriptElements(doc)) script.textContent = "";
-}
-
-// Soft-reloadable iff the docs differ SOLELY in id'd-element attributes/inline
-// style and/or the GSAP script; returns the changed ids to sync onto the live
-// DOM. Structural/text diffs → null → the caller full-reloads. Pure.
-export function diffSoftReloadableRestore(
-  previous: string,
-  restored: string,
-): { changedElementIds: string[] } | null {
-  let prevDoc: Document;
-  let nextDoc: Document;
-  try {
-    prevDoc = new DOMParser().parseFromString(previous, "text/html");
-    nextDoc = new DOMParser().parseFromString(restored, "text/html");
-  } catch {
-    return null;
-  }
-  const prevById = idElementMap(prevDoc);
-  const nextById = idElementMap(nextDoc);
-  // A different id set means an element was added or removed (e.g. a split, a
-  // delete) — structural, so soft-reload can't express it.
-  if (prevById.size !== nextById.size) return null;
-  const changedElementIds: string[] = [];
-  for (const [id, nextEl] of nextById) {
-    const prevEl = prevById.get(id);
-    if (!prevEl || prevEl.tagName !== nextEl.tagName) return null;
-    // A change inside the element (text / children) is out of soft scope; only
-    // its own attributes may differ. (GSAP scripts are handled via re-run.)
-    if (prevEl.innerHTML !== nextEl.innerHTML) return null;
-    if (prevEl.outerHTML !== nextEl.outerHTML) changedElementIds.push(id);
-  }
-  // Confirm nothing OUTSIDE id'd-element attributes and GSAP scripts changed.
-  normalizeSoftResidual(prevDoc);
-  normalizeSoftResidual(nextDoc);
-  if (prevDoc.documentElement.outerHTML !== nextDoc.documentElement.outerHTML) return null;
-  return { changedElementIds };
-}
-
-/** Copy every attribute from `source` onto the live `target`, dropping extras. */
-function syncElementAttributes(target: Element, source: Element): void {
-  for (const name of [...target.getAttributeNames()]) {
-    if (!source.hasAttribute(name)) target.removeAttribute(name);
-  }
-  for (const name of source.getAttributeNames()) {
-    target.setAttribute(name, source.getAttribute(name) ?? "");
-  }
+/**
+ * The soft reload's finalization step, shared with the rebind-only preview sync
+ * below: seek → force timeline rebind → reapply studio manual edits.
+ *
+ * Seek BEFORE rebind: __hfForceTimelineRebind's own internal force-render
+ * (see init.ts) renders the freshly-created timeline at whatever the
+ * runtime's internal scrub position already is, not at whatever we pass
+ * here afterward — a redundant seek() call after rebind can be a GSAP
+ * no-op if the timeline already reports being at that time internally.
+ */
+function finalizeSoftReload(win: IframeWindow, currentTime: number): void {
+  win.__player?.seek?.(currentTime);
+  win.__hfForceTimelineRebind?.();
+  win.__hfStudioManualEditsApply?.();
 }
 
 /**
- * Soft-apply an undo/redo restore to the live preview WITHOUT a full iframe
- * remount (which blanks the frame black and re-flashes the WebGL context). Only
- * the active composition — the document living in the root iframe — is eligible;
- * a sub-comp or multi-file restore falls back to `reloadPreview`.
+ * Run ONLY applySoftReload's finalization (seek → __hfForceTimelineRebind →
+ * manual-edits reapply) against the live iframe — executing NO scripts and
+ * touching NO script elements. `__hfForceTimelineRebind` makes the runtime
+ * re-derive every clip's visibility window from the live DOM's `data-start` /
+ * `data-duration` attributes (init.ts: bindRootTimelineIfAvailable +
+ * syncTimedElementVisibility), so this is the flashless sync for a timing edit
+ * whose attributes were already live-patched and whose GSAP scripts are
+ * unchanged (`window.__timelines` still valid). Works for compositions with
+ * zero GSAP scripts too — the rebind hook is installed unconditionally by the
+ * runtime, independent of any animation library.
  *
- * The restore is soft-applied when its only differences are id'd-element
- * attributes / inline-style and/or the GSAP script (see diffSoftReloadableRestore):
- *   1. Each changed element's attribute surface (inline style, data-start /
- *      -duration, the studio manual-offset props + flags) is synced onto the live
- *      element — so a canvas-position revert lands on the live DOM the runtime's
- *      seek-reapply reads from, not just on disk.
- *   2. The restored GSAP script is re-run in place via applySoftReload, which
- *      re-seeks to `currentTime` (playhead-invariant) and re-folds manual edits.
- *      With no single script, the manual-edit reapply is invoked directly.
- *
- * Returns "soft" when applied in place, "full" when it escalated to reloadPreview
- * (ineligible restore, missing target, or a permanent soft-reload failure).
+ * Returns false when the iframe/runtime hook is unavailable or the run threw —
+ * the caller should escalate to a full reload.
  */
-export function applyUndoRestoreToPreview(
+export function applySoftReloadFinalization(
   iframe: HTMLIFrameElement | null,
-  activeCompPath: string | null,
-  files: Record<string, UndoRestoreFile> | undefined,
   currentTime: number,
-  reloadPreview: () => void,
-): "soft" | "full" {
-  const paths = files ? Object.keys(files) : [];
-  // Soft path only covers the single active-comp document in the root iframe.
-  if (!iframe || !activeCompPath || !files || paths.length !== 1 || paths[0] !== activeCompPath) {
-    reloadPreview();
-    return "full";
-  }
-  const doc = iframe.contentDocument;
-  const win = iframe.contentWindow as IframeWindow | null;
-  if (!doc || !win) {
-    reloadPreview();
-    return "full";
-  }
-  const { previous, restored } = files[activeCompPath]!;
-  const diff = diffSoftReloadableRestore(previous, restored);
-  if (!diff) {
-    reloadPreview();
-    return "full";
-  }
-
-  // Sync each changed element's attributes onto the live DOM from the restored
-  // markup, so the runtime's seek-reapply (which reads inline offset props off
-  // the live element) folds the REVERTED values, not the stale current ones.
-  const restoredById = idElementMap(new DOMParser().parseFromString(restored, "text/html"));
-  for (const id of diff.changedElementIds) {
-    const liveEl = doc.getElementById(id);
-    const restoredEl = restoredById.get(id);
-    if (liveEl && restoredEl) syncElementAttributes(liveEl, restoredEl);
-  }
-
-  const script = extractGsapScriptText(restored);
-  if (script) {
-    const result = applySoftReload(iframe, script, {
-      onAsyncFailure: reloadPreview,
-      currentTimeOverride: currentTime,
-    });
-    if (result === "cannot-soft-reload") {
-      reloadPreview();
-      return "full";
-    }
-    return "soft";
-  }
-  // No single GSAP script to re-run — the change was pure attribute/style. Re-fold
-  // manual edits and hold the playhead so the synced attributes take visible effect.
+): boolean {
+  const win = iframe?.contentWindow as IframeWindow | null;
+  if (!win?.__hfForceTimelineRebind) return false;
   try {
-    win.__player?.seek?.(currentTime);
-    win.__hfStudioManualEditsApply?.();
+    if (win.__hfSuppressSceneMutations) {
+      win.__hfSuppressSceneMutations(() => finalizeSoftReload(win, currentTime));
+    } else {
+      finalizeSoftReload(win, currentTime);
+    }
+    return true;
   } catch {
-    reloadPreview();
-    return "full";
+    return false;
   }
-  return "soft";
 }
 
 export function applySoftReload(
@@ -523,14 +420,7 @@ export function applySoftReload(
       const s = doc.createElement("script");
       s.textContent = `(function(){${scriptText}\n})();`;
       doc.body.appendChild(s);
-      // Seek BEFORE rebind: __hfForceTimelineRebind's own internal force-render
-      // (see init.ts) renders the freshly-created timeline at whatever the
-      // runtime's internal scrub position already is, not at whatever we pass
-      // here afterward — a redundant seek() call after rebind can be a GSAP
-      // no-op if the timeline already reports being at that time internally.
-      win.__player?.seek?.(currentTime);
-      win.__hfForceTimelineRebind?.();
-      win.__hfStudioManualEditsApply?.();
+      finalizeSoftReload(win, currentTime);
     };
 
     const needsMotionPath = /motionPath\s*[:{]/.test(scriptText);

package/src/utils/gsapUndoRestore.test.ts

@@ -0,0 +1,269 @@
+// @vitest-environment happy-dom
+
+import { describe, it, expect, vi } from "vitest";
+import { applyUndoRestoreToPreview, diffSoftReloadableRestore } from "./gsapUndoRestore";
+
+// ── Bug 2: undo/redo restore soft-apply ──────────────────────────────────────
+
+const wrap = (body: string) => `<html><body>${body}</body></html>`;
+
+describe("diffSoftReloadableRestore", () => {
+  it("reports the changed id for an attribute/inline-style-only diff", () => {
+    const prev = wrap(`<div id="a" style="translate: 10px 10px">t</div>`);
+    const next = wrap(`<div id="a" style="translate: 0px 0px">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementKeys: ["id:a"] });
+  });
+
+  it("identifies id-less elements by data-hf-id (selector-targeted clips)", () => {
+    const prev = wrap(`<div class="sub" data-hf-id="hf-x1" style="z-index: 3">t</div>`);
+    const next = wrap(`<div class="sub" data-hf-id="hf-x1" style="z-index: 8">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementKeys: ["hf:hf-x1"] });
+  });
+
+  it("fails closed when fallback ids are duplicated without unique data-hf-ids", () => {
+    const prev = wrap(
+      `<div id="dup" style="z-index: 8">first</div><div id="dup" style="z-index: 9">last</div>`,
+    );
+    const next = wrap(
+      `<div id="dup" style="z-index: 3">first</div><div id="dup" style="z-index: 9">last</div>`,
+    );
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("a child change inside an identified CONTAINER is soft (nested identities)", () => {
+    // The composition root wraps every clip — the old innerHTML comparison at
+    // the root re-detected the child's change and forced a full reload.
+    const prev = wrap(
+      `<div id="main" data-duration="42"><div class="sub" data-hf-id="hf-x1" data-start="39">t</div></div>`,
+    );
+    const next = wrap(
+      `<div id="main" data-duration="39"><div class="sub" data-hf-id="hf-x1" data-start="26">t</div></div>`,
+    );
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({
+      changedElementKeys: ["id:main", "hf:hf-x1"],
+    });
+  });
+
+  it("a changed data-hf-id itself is structural — NOT soft-reloadable", () => {
+    const prev = wrap(`<div data-hf-id="hf-x1">t</div>`);
+    const next = wrap(`<div data-hf-id="hf-x2">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("treats a structural change (added element) as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">t</div>`);
+    const next = wrap(`<div id="a">t</div><div id="a-split">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("treats an element text/child change as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">one</div>`);
+    const next = wrap(`<div id="a">two</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("allows a GSAP-script-only change (no id'd-attribute diff)", () => {
+    const prev = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:1});</script>`,
+    );
+    const next = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:9});</script>`,
+    );
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementKeys: [] });
+  });
+});
+
+function buildLiveIframe(bodyHtml: string) {
+  const doc = document.implementation.createHTMLDocument("");
+  doc.body.innerHTML = bodyHtml;
+  const contentWindow = {
+    gsap: { timeline: () => {} },
+    __hfForceTimelineRebind: () => {},
+    __timelines: {} as Record<string, unknown>,
+    __player: { getTime: () => 3, seek: vi.fn() },
+    __hfStudioManualEditsApply: vi.fn(),
+  };
+  return {
+    iframe: { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement,
+    contentWindow,
+    doc,
+  };
+}
+
+describe("applyUndoRestoreToPreview", () => {
+  const ROOT = "index.html";
+
+  it("soft-applies an attribute/style-only restore: syncs the live element, no full reload", () => {
+    const { iframe, contentWindow, doc } = buildLiveIframe(
+      `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(
+          `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+        ),
+        restored: wrap(`<div id="a" style="translate: 0px 0px" data-hf-path-offset="true">t</div>`),
+      },
+    };
+    const outcome = applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview);
+    expect(outcome).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    // Live element reverted to the restored inline style.
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("translate: 0px 0px");
+    // No GSAP script in the restore → the manual-edit reapply runs, playhead held.
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(3);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
+  });
+
+  it("syncs a data-hf-id-identified live element (no DOM id) without reloading", () => {
+    const { iframe, doc } = buildLiveIframe(
+      `<div class="sub" data-hf-id="hf-x1" style="z-index: 8">t</div>`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div class="sub" data-hf-id="hf-x1" style="z-index: 8">t</div>`),
+        restored: wrap(`<div class="sub" data-hf-id="hf-x1" style="z-index: 3">t</div>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    expect(doc.querySelector('[data-hf-id="hf-x1"]')!.getAttribute("style")).toBe("z-index: 3");
+  });
+
+  it.each([
+    { label: "first", firstRestored: 3, lastRestored: 9 },
+    { label: "last", firstRestored: 8, lastRestored: 3 },
+  ])(
+    "soft-restores the $label element when authored ids are duplicated",
+    ({ firstRestored, lastRestored }) => {
+      const markup = (firstZ: number, lastZ: number) =>
+        `<div id="dup" data-hf-id="hf-first" style="z-index: ${firstZ}">first</div>` +
+        `<div id="dup" data-hf-id="hf-last" style="z-index: ${lastZ}">last</div>`;
+      const { iframe, doc } = buildLiveIframe(markup(8, 9));
+      const reloadPreview = vi.fn();
+      const files = {
+        [ROOT]: {
+          previous: wrap(markup(8, 9)),
+          restored: wrap(markup(firstRestored, lastRestored)),
+        },
+      };
+
+      expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+      expect(reloadPreview).not.toHaveBeenCalled();
+      expect(doc.querySelector('[data-hf-id="hf-first"]')!.getAttribute("style")).toBe(
+        `z-index: ${firstRestored}`,
+      );
+      expect(doc.querySelector('[data-hf-id="hf-last"]')!.getAttribute("style")).toBe(
+        `z-index: ${lastRestored}`,
+      );
+    },
+  );
+
+  it("full-reloads without partially restoring when any changed live target is missing", () => {
+    const { iframe, doc } = buildLiveIframe(`<div id="a" style="z-index: 8">a</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(
+          `<div id="a" style="z-index: 8">a</div><div id="b" style="z-index: 8">b</div>`,
+        ),
+        restored: wrap(
+          `<div id="a" style="z-index: 3">a</div><div id="b" style="z-index: 3">b</div>`,
+        ),
+      },
+    };
+
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    // Target a resolved first, but the preflight found missing b before syncing either.
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("z-index: 8");
+  });
+
+  it("does NOT re-run an UNCHANGED GSAP script for an attribute-only restore", () => {
+    // The live doc holds a script element; a re-run would mutate/remove it
+    // (applySoftReload removes stale script elements before re-running).
+    const script = `window.__timelines["root"]=gsap.timeline().to("#a",{x:1});`;
+    const { iframe, contentWindow, doc } = buildLiveIframe(
+      `<div id="a" style="z-index: 8">t</div><script>${script}</script>`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="z-index: 8">t</div><script>${script}</script>`),
+        restored: wrap(`<div id="a" style="z-index: 3">t</div><script>${script}</script>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    // The live script element is untouched — rebind-only finalization ran instead.
+    expect(doc.querySelectorAll("script")).toHaveLength(1);
+    expect(doc.querySelector("script")!.textContent).toBe(script);
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(3);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("z-index: 3");
+  });
+
+  it("full-reloads a changed two-script restore without partially touching the live DOM", () => {
+    const previousScripts = [
+      `window.__timelines["root"]=gsap.timeline().to("#a",{x:1});`,
+      `window.__timelines["captions"]=gsap.timeline().to("#a",{y:1});`,
+    ];
+    const restoredScripts = previousScripts.map((script) => script.replace(":1", ":9"));
+    const scripts = (values: string[]) =>
+      values.map((value) => `<script>${value}</script>`).join("");
+    const { iframe, doc } = buildLiveIframe(
+      `<div id="a" style="z-index: 8">t</div>${scripts(previousScripts)}`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="z-index: 8">t</div>${scripts(previousScripts)}`),
+        restored: wrap(`<div id="a" style="z-index: 3">t</div>${scripts(restoredScripts)}`),
+      },
+    };
+
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("z-index: 8");
+    expect([...doc.querySelectorAll("script")].map((script) => script.textContent)).toEqual(
+      previousScripts,
+    );
+  });
+
+  it("full-reloads a multi-file restore", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="x">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+      "scenes/intro.html": { previous: "a", restored: "b" },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads a structural restore (split/delete undo)", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div><div id="a-split">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a">t</div><div id="a-split">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = { "scenes/intro.html": { previous: "a", restored: "b" } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+});