@hyperframes/studio 0.8.127 → 0.8.129

package/src/utils/gsapLiveRetime.ts

@@ -0,0 +1,286 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
+import { hasExplicitTime } from "@hyperframes/parsers/gsap-writer-acorn";
+import { RUNTIME_FILLER } from "@hyperframes/core/runtime/protocol";
+import {
+  applySoftReloadFinalization,
+  findGsapScriptElements,
+  scriptsRegistering,
+  timelineKeys,
+} from "./gsapSoftReload";
+
+interface TweenTiming {
+  selector: string;
+  start: number;
+  duration: number;
+  wasStart: number;
+  wasDuration: number;
+  moved: boolean;
+  /** Its place in the script, which is the order a fresh run adds it to the timeline. */
+  source: number;
+}
+
+/**
+ * How a saved script differs from the live one: `retime` when only tween starts and lengths moved
+ * (`tweens` in the live timeline's child order), `rerun` for anything only a re-run reproduces.
+ */
+export type LiveRetimePlan =
+  | { kind: "retime"; key: string; after: string; tweens: TweenTiming[] }
+  | { kind: "rerun" };
+
+const RERUN = { kind: "rerun" } as const;
+
+/** The preview runs a reformatted copy of the script: compare code, not its layout. */
+const withoutLayout = (code: string) =>
+  code
+    .replace(/\s+/g, " ")
+    .replace(/ ?([^\w$ ]) ?/g, "$1")
+    .trim();
+
+function untimedShape(animation: GsapAnimation): string {
+  const { id: _id, position: _p, resolvedStart: _s, duration: _d, ...rest } = animation;
+  // An offset into the text, which moves when the preview reformats its copy of the script.
+  const provenance = rest.provenance && { ...rest.provenance, sourceRange: undefined };
+  return JSON.stringify({ ...rest, provenance }, (_key, value) =>
+    typeof value === "string" && value.startsWith("__raw:") ? withoutLayout(value) : value,
+  );
+}
+
+const onTimeline = (animation: GsapAnimation) => !animation.global;
+
+const placedAlone = (animation: GsapAnimation) =>
+  hasExplicitTime(animation) && typeof animation.resolvedStart === "number";
+
+/** Undefined when only GSAP knows it: an unwritten length takes `gsap.defaults`, which a script may change. */
+const lengthOf = (animation: GsapAnimation) =>
+  animation.method === "set" ? 0 : animation.durationUnresolved ? undefined : animation.duration;
+
+/** A timing edit rewrites numbers only; anything else may be code the parser does not read. */
+const withoutNumbers = (script: string) =>
+  withoutLayout(script.replace(/(?<![\w$#.])\d*\.?\d+/g, "0"));
+
+/** Decides, from the two scripts alone, whether a saved edit moved tweens and nothing else. */
+export function planLiveRetime(before: string, after: string): LiveRetimePlan {
+  if (withoutNumbers(before) !== withoutNumbers(after)) return RERUN;
+  const keys = timelineKeys(after);
+  if (keys.length !== 1 || timelineKeys(before).join() !== keys.join()) return RERUN;
+  const was = parseGsapScriptAcorn(before).animations.filter(onTimeline);
+  const now = parseGsapScriptAcorn(after).animations.filter(onTimeline);
+  if (was.length !== now.length) return RERUN;
+  const tweens: TweenTiming[] = [];
+  for (const [index, next] of now.entries()) {
+    const prev = was[index]!;
+    if (untimedShape(prev) !== untimedShape(next)) return RERUN;
+    // A relative position follows the parser's playhead, which is not GSAP's; only numbers place a tween alone.
+    if (!placedAlone(next) || !placedAlone(prev)) return RERUN;
+    const duration = lengthOf(next);
+    const wasDuration = lengthOf(prev);
+    if (duration === undefined || wasDuration === undefined) return RERUN;
+    tweens.push({
+      selector: next.targetSelector,
+      start: next.resolvedStart!,
+      duration,
+      wasStart: prev.resolvedStart!,
+      wasDuration,
+      moved: next.resolvedStart !== prev.resolvedStart || duration !== wasDuration,
+      source: index,
+    });
+  }
+  // A GSAP timeline keeps its children sorted by start, an equal start after the earlier one: pair in that order.
+  tweens.sort((x, y) => x.wasStart - y.wasStart || x.source - y.source);
+  return { kind: "retime", key: keys[0]!, after, tweens };
+}
+
+export type LiveRetime = Extract<LiveRetimePlan, { kind: "retime" }> & {
+  script: HTMLScriptElement;
+};
+
+/** Plans against the script the preview is running now; `rerun` when no single live script owns the timeline. */
+export function planLiveRetimeFromPreview(
+  iframe: HTMLIFrameElement | null,
+  after: string,
+): LiveRetime | typeof RERUN {
+  const doc = iframe?.contentDocument;
+  const [key] = timelineKeys(after);
+  if (!doc || !key) return RERUN;
+  const [script, ...extra] = scriptsRegistering(findGsapScriptElements(doc), [key]);
+  if (!script || extra.length > 0) return RERUN;
+  const plan = planLiveRetime(script.textContent ?? "", after);
+  return plan.kind === "retime" ? { ...plan, script } : RERUN;
+}
+
+interface LiveTween {
+  duration: (value?: number) => number;
+  startTime: () => number;
+  delay: () => number;
+  repeatDelay?: () => number;
+  data?: unknown;
+  targets?: () => unknown[];
+}
+interface LiveTimeline {
+  getChildren(nested: boolean, tweens: true, timelines: false): LiveTween[];
+  getChildren(nested: false, tweens: false, timelines: true): LiveTimeline[];
+  remove: (child: LiveTween) => unknown;
+  add: (child: LiveTween, position: number) => unknown;
+  time: () => number;
+  progress: (value: number, suppressEvents: boolean) => unknown;
+  totalTime: (time: number, suppressEvents: boolean) => unknown;
+}
+
+const same = (a: number, b: number) => Math.abs(a - b) < 1e-6;
+
+const targetsMatch = (tween: LiveTween, selector: string) => {
+  const targets = tween.targets?.() ?? [];
+  try {
+    return targets.length > 0 && targets.every((t) => (t as Element).matches?.(selector) === true);
+  } catch {
+    return false;
+  }
+};
+
+/** The live tweens, one per planned tween, when each sits exactly where the parser says it did. */
+function pairedLiveTweens(timeline: LiveTimeline, plan: LiveRetime): LiveTween[] | null {
+  // The script's tweens only: the runtime also nests sub-composition timelines and adds filler tweens here.
+  const children = timeline
+    .getChildren(false, true, false)
+    .filter((tween) => tween.data !== RUNTIME_FILLER);
+  if (children.length !== plan.tweens.length) return null;
+  const paired = plan.tweens.every((t, i) => {
+    const live = children[i]!;
+    return (
+      targetsMatch(live, t.selector) &&
+      same(live.startTime() - live.delay(), t.wasStart) &&
+      same(live.duration(), t.wasDuration)
+    );
+  });
+  return paired ? children : null;
+}
+
+/** The writer rounds every time it writes to 3 decimals. */
+const near = (a: number, b: number) => Math.abs(a - b) <= 2e-3;
+
+/** One stretch for every tween (start = shift + stretch × old start, length = stretch × old length), in old order. */
+function sharesOneStretch(tweens: TweenTiming[]): boolean {
+  const first = tweens[0]!;
+  const last = tweens.at(-1)!;
+  const longest = tweens.reduce((x, y) => (y.wasDuration > x.wasDuration ? y : x));
+  const spread = last.wasStart - first.wasStart;
+  // Taken over the widest span, so the writer's rounding cannot push it past `near`.
+  const stretch =
+    spread > longest.wasDuration
+      ? (last.start - first.start) / spread
+      : longest.wasDuration > 0
+        ? longest.duration / longest.wasDuration
+        : 1;
+  const fits = tweens.every(
+    (t) =>
+      near(t.start, first.start + stretch * (t.wasStart - first.wasStart)) &&
+      near(t.duration, stretch * t.wasDuration),
+  );
+  return stretch > 0 && fits;
+}
+
+/** The runtime places a sub-composition's timeline at its host's start once; moving the host leaves it there. */
+function inOrHostsSubComposition(target: unknown, ownId: string): boolean {
+  const element = target as Element;
+  const owner = element.closest?.("[data-composition-id]");
+  return (
+    (owner != null && owner.getAttribute("data-composition-id") !== ownId) ||
+    element.querySelector?.("[data-composition-id]") != null
+  );
+}
+
+/** Tweens on one element still start in the order they did, an equal start in script order. */
+const keepsOrder = (tweens: TweenTiming[]) =>
+  tweens.every(
+    (t, k) => k === 0 || (tweens[k - 1]!.start - t.start || tweens[k - 1]!.source - t.source) < 0,
+  );
+
+/**
+ * A tween keeps the start values it recorded when it first played, so every element a move touches
+ * must keep its tweens' spacing, and no timeline the script does not own may animate it.
+ */
+function movesKeepEachElementsHistory(
+  timeline: LiveTimeline,
+  plan: LiveRetime,
+  children: LiveTween[],
+): boolean {
+  const byElement = new Map<unknown, number[]>();
+  children.forEach((child, i) => {
+    for (const target of child.targets?.() ?? []) {
+      const indexes = byElement.get(target);
+      if (indexes) indexes.push(i);
+      else byElement.set(target, [i]);
+    }
+  });
+  const moved = new Set<unknown>();
+  for (const [target, indexes] of byElement) {
+    if (!indexes.some((i) => plan.tweens[i]!.moved)) continue;
+    if (inOrHostsSubComposition(target, plan.key)) return false;
+    const tweens = indexes.map((i) => plan.tweens[i]!);
+    // GSAP adds delays to the schedule unstretched; a shift keeps every length.
+    const shifted = tweens.every((t) => t.duration === t.wasDuration);
+    const undelayed = indexes.every((i) => !children[i]!.delay() && !children[i]!.repeatDelay?.());
+    if (!keepsOrder(tweens) || !sharesOneStretch(tweens) || !(shifted || undelayed)) return false;
+    moved.add(target);
+  }
+  return !timeline
+    .getChildren(false, false, true)
+    .some((sub) =>
+      sub
+        .getChildren(true, true, false)
+        .some((tween) => tween.targets?.().some((t) => moved.has(t))),
+    );
+}
+
+/**
+ * Moves the live tweens a `retime` plan names and records the saved script as the live one.
+ * False, with nothing changed, when the live timeline is not exactly what the parser read.
+ */
+export function applyLiveRetime(iframe: HTMLIFrameElement | null, plan: LiveRetime): boolean {
+  const win = iframe?.contentWindow as { __timelines?: Record<string, unknown> } | null;
+  const timeline = win?.__timelines?.[plan.key] as LiveTimeline | undefined;
+  if (typeof timeline?.getChildren !== "function") return false;
+  // Paired before anything moves: moving a tween re-sorts the timeline's children.
+  const children = pairedLiveTweens(timeline, plan);
+  if (!children) return false;
+  if (plan.tweens.some((t) => t.moved)) {
+    if (!movesKeepEachElementsHistory(timeline, plan, children)) return false;
+    // Re-added in script order: GSAP orders equal starts by when they were added, as a fresh run does.
+    const bySource = plan.tweens
+      .map((t, i) => ({ ...t, tween: children[i]! }))
+      .sort((a, b) => a.source - b.source);
+    for (const { tween } of bySource) timeline.remove(tween);
+    for (const { tween, start, duration } of bySource) {
+      if (tween.duration() !== duration) tween.duration(duration);
+      timeline.add(tween, start);
+    }
+    // Replayed to the playhead as the runtime binds a fresh load, callbacks included.
+    const at = timeline.time();
+    timeline.progress(0.0001, true);
+    timeline.totalTime(at, false);
+  }
+  // A script element runs once, so this only keeps the next comparison honest; nothing re-executes.
+  plan.script.textContent = plan.after;
+  return true;
+}
+
+/** Syncs a saved timing edit by moving the live tweens; false when only re-running the script can. */
+export function moveLiveTweens(
+  iframe: HTMLIFrameElement,
+  scriptText: string,
+  currentTime: number,
+  reloadPreview: () => void,
+): boolean {
+  const plan = planLiveRetimeFromPreview(iframe, scriptText);
+  if (plan.kind !== "retime") return false;
+  try {
+    if (!applyLiveRetime(iframe, plan)) return false;
+  } catch (error) {
+    console.error("[Studio] Moving the live tweens threw; reloading the preview", error);
+    reloadPreview();
+    return true;
+  }
+  if (!applySoftReloadFinalization(iframe, currentTime)) reloadPreview();
+  return true;
+}

package/src/utils/gsapSoftReload.ts

@@ -277,12 +277,26 @@ export function applySoftReloadFinalization(
   }
 }
 
-function timelineKeys(scriptText: string): string[] {
+export function timelineKeys(scriptText: string): string[] {
   return [...scriptText.matchAll(/__timelines\s*\[\s*["'`]([^"'`]+)["'`]\s*\]/g)]
     .map((m) => m[1]!)
     .filter((key) => key !== "__proxied");
 }
 
+/** The live script elements that register one of `keys` on `window.__timelines`. */
+export function scriptsRegistering(
+  scripts: readonly HTMLScriptElement[],
+  keys: readonly string[],
+): HTMLScriptElement[] {
+  return scripts.filter((script) => {
+    const text = script.textContent || "";
+    return keys.some(
+      (key) => text.includes(`__timelines["${key}"]`) || text.includes(`__timelines['${key}']`),
+    );
+  });
+}
+
+// fallow-ignore-next-line complexity
 export function applySoftReload(
   iframe: HTMLIFrameElement | null,
   scriptText: string,
@@ -311,12 +325,7 @@ export function applySoftReload(
   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}']`);
-    }),
-  );
+  const staleScripts = scriptsRegistering(gsapScripts, targetKeys);
   // 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

package/src/utils/gsapUndoRestore.test.ts

@@ -1,6 +1,19 @@
 // @vitest-environment happy-dom
 
 import { describe, it, expect, vi } from "vitest";
+import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
+
+const stamping = vi.hoisted(() => ({ calls: 0 }));
+vi.mock("@hyperframes/parsers/hf-ids", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@hyperframes/parsers/hf-ids")>();
+  return {
+    ...real,
+    ensureHfIds: (html: string) => {
+      stamping.calls += 1;
+      return real.ensureHfIds(html);
+    },
+  };
+});
 import {
   applyUndoRestoreToPreview,
   diffSoftReloadableRestore,
@@ -100,6 +113,36 @@ function buildLiveIframe(bodyHtml: string) {
 describe("applyUndoRestoreToPreview", () => {
   const ROOT = "index.html";
 
+  it("never stamps an undo whose sides are both already stamped", () => {
+    const film = (color: string) =>
+      `<div id="root" data-composition-id="root"><div id="target" style="background-color: ${color}">T</div><p>caption</p></div>`;
+    const blue = ensureHfIds(film("blue"));
+    const red = blue.replace("background-color: blue", "background-color: red");
+    const { iframe } = buildLiveIframe(red);
+    stamping.calls = 0;
+
+    const files = { [ROOT]: { previous: wrap(red), restored: wrap(blue) } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn())).toBe("soft");
+    expect(stamping.calls).toBe(0);
+  });
+
+  it("repaints in place an undo back to the film before Studio first stamped it", () => {
+    const film = (color: string) =>
+      `<div id="root" data-composition-id="root"><div id="target" style="background-color: ${color}">T</div><p>caption</p></div>`;
+    // The preview stamped the film as it loaded; the first edit wrote those stamps with its red.
+    const edited = ensureHfIds(film("blue")).replace(
+      "background-color: blue",
+      "background-color: red",
+    );
+    const { iframe, doc } = buildLiveIframe(edited);
+    const reloadPreview = vi.fn();
+    const files = { [ROOT]: { previous: wrap(edited), restored: wrap(film("blue")) } };
+
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    expect((doc.getElementById("target") as HTMLElement).style.backgroundColor).toBe("blue");
+  });
+
   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>`,

package/src/utils/gsapUndoRestore.ts

@@ -9,7 +9,7 @@ import {
   findGsapScriptElements,
   readNestedFiles,
 } from "./gsapSoftReload";
-import { isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
+import { ensureHfIds, isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
 import { findAuthoredElement, parseSavedSource } from "./authoredSource";
 import { STUDIO_EDIT_ATTRS } from "../components/editor/manualEditsSeekReapply";
 import { markScenesStale } from "../player/sceneSwap";
@@ -252,8 +252,11 @@ function fileTargets(
   isActive: boolean,
   file: UndoRestoreFile,
 ): RestorePlan | null {
-  const prevDoc = parseRestoreSource(file.previous);
-  const nextDoc = parseRestoreSource(file.restored);
+  const previewStamped = doc.querySelector("[data-hf-id]") !== null;
+  const stampedLikeThePreview = (html: string) =>
+    previewStamped && !html.includes("data-hf-id") ? ensureHfIds(html) : html;
+  const prevDoc = parseRestoreSource(stampedLikeThePreview(file.previous));
+  const nextDoc = parseRestoreSource(stampedLikeThePreview(file.restored));
   const scripted = restoreScripted(prevDoc, nextDoc, isActive);
   if (scripted === null) return null;
   const keys = diffRestoreDocs(prevDoc, nextDoc);

package/src/utils/sameData.ts

@@ -0,0 +1,9 @@
+/** Structural equality for plain data; DOM nodes (from any realm) compare by identity. */
+export function sameData(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+  if ("nodeType" in a || "nodeType" in b || Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => sameData((a as never)[key], (b as never)[key]));
+}

package/src/utils/studioFileHistory.ts

@@ -81,6 +81,7 @@ export async function saveServerRewriteWithHistory(input: {
   path: string;
   label: string;
   coalesceKey?: string;
+  coalesceMs?: number;
   writeFile: ProjectFileWriter;
   recordEdit: (entry: RecordEditInput) => Promise<void>;
   rewrite: (original: string) => Promise<{ disk: string; after?: string } | null>;

package/src/utils/studioPendingEdits.ts

@@ -16,6 +16,7 @@ interface PendingEdit {
   landed: () => Promise<boolean>;
   redraws: Array<() => void>;
   showAgain: (() => void) | null;
+  claimsAtBegin: number;
 }
 
 export interface StudioEditInFlight {
@@ -27,6 +28,11 @@ export interface StudioEditInFlight {
 }
 
 const pendingEdits = new Map<Promise<unknown>, PendingEdit>();
+let historyClaims: () => number = () => 0;
+
+export function setStudioPendingEditClaimClock(read: (() => number) | null): void {
+  historyClaims = read ?? (() => 0);
+}
 const NOT_SAVED = () => Promise.resolve(false);
 let adopting: StudioEditInFlight | null = null;
 
@@ -87,7 +93,13 @@ export function trackStudioPendingEdit(
   if (!result) return undefined;
   const promise = Promise.resolve(result);
   if (adopting) return promise;
-  pendingEdits.set(promise, { revert: null, landed: NOT_SAVED, redraws: [], showAgain: null });
+  pendingEdits.set(promise, {
+    revert: null,
+    landed: NOT_SAVED,
+    redraws: [],
+    showAgain: null,
+    claimsAtBegin: historyClaims(),
+  });
   promise.then(
     () => pendingEdits.delete(promise),
     () => pendingEdits.delete(promise),
@@ -162,6 +174,7 @@ export function beginStudioPendingEdit(revert: StudioEditRevert | null) {
 export function paintBackNewestStudioPendingEdit(): {
   showAgain: () => void;
   landed: () => Promise<boolean>;
+  claimsAtBegin: number;
 } | null {
   const newest = [...pendingEdits.values()].at(-1);
   const revert = newest?.revert;
@@ -174,6 +187,7 @@ export function paintBackNewestStudioPendingEdit(): {
       for (const redraw of newest.redraws.splice(0)) redraw();
     },
     landed: newest.landed,
+    claimsAtBegin: newest.claimsAtBegin,
   };
 }