@hyperframes/studio 0.8.115 → 0.8.116

package/src/hooks/gsapDragPositionCommit.ts

@@ -1,8 +1,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { PROPERTY_GROUPS } from "@hyperframes/parsers/gsap-constants";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { resolveTweenStart } from "../utils/globalTimeCompiler";
 import { KEYFRAME_PCT_MATCH, resolveEditableTweenDuration } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
@@ -10,8 +9,9 @@ import {
   type GsapDragCommitCallbacks,
   computeCurrentPercentage,
   parkPlayheadOnKeyframe,
-  materializeIfDynamic,
 } from "./gsapDragCommit";
+import type { GsapEditOutcome } from "./gsapEditOutcome";
+import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
 
 /**
  * The tween's keyframes with one inserted at `percentage`. Any existing keyframe
@@ -38,237 +38,26 @@ export function buildTemporalArcKeyframes(
   ].sort((a, b) => a.percentage - b.percentage);
 }
 
-async function extendTweenAndAddKeyframe(
+/** commitGsapPositionFromDrag's refusal, decided without writing. */
+export function gsapPositionFromDragOutcome(
   selection: DomEditSelection,
   anim: GsapAnimation,
-  properties: Record<string, number>,
-  targetTime: number,
-  tweenStart: number,
-  tweenDuration: number,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const tweenEnd = tweenStart + tweenDuration;
-  const newStart = Math.min(targetTime, tweenStart);
-  const newEnd = Math.max(targetTime, tweenEnd);
-  const newDuration = Math.max(0.01, newEnd - newStart);
-  const existingKfs = anim.keyframes?.keyframes ?? [];
-  const remappedKfs: Array<{ percentage: number; properties: Record<string, number | string> }> =
-    [];
-  for (const kf of existingKfs) {
-    const absTime = tweenStart + (kf.percentage / 100) * tweenDuration;
-    const newPct = Math.round(((absTime - newStart) / newDuration) * 1000) / 10;
-    const props: Record<string, number | string> = { ...kf.properties };
-    for (const k of Object.keys(properties)) {
-      if (!(k in props) && backfillDefaults?.[k] != null) props[k] = backfillDefaults[k];
-    }
-    remappedKfs.push({ percentage: newPct, properties: props });
-  }
-
-  const targetPct = Math.round(((targetTime - newStart) / newDuration) * 1000) / 10;
-  remappedKfs.push({ percentage: targetPct, properties });
-
-  remappedKfs.sort((a, b) => a.percentage - b.percentage);
-
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "replace-with-keyframes",
-      animationId: anim.id,
-      targetSelector: anim.targetSelector,
-      position: roundTo3(newStart),
-      duration: roundTo3(newDuration),
-      keyframes: remappedKfs,
-    },
-    {
-      label: `Move layer (extended keyframe)`,
-      keyframeAction: "add",
-      softReload: true,
-      beforeReload,
-    },
-  );
-}
-
-// fallow-ignore-next-line complexity
-async function commitKeyframedPosition(
-  selection: DomEditSelection,
-  anim: GsapAnimation,
-  properties: Record<string, number>,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-  const computedPct = computeCurrentPercentage(selection, anim);
-  const pct = activeKeyframePct ?? computedPct;
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties,
-      ...(backfillDefaults ? { backfillDefaults } : {}),
-    },
-    { label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload },
-  );
-  if (activeKeyframePct != null) {
-    setActiveKeyframePct(null);
-    parkPlayheadOnKeyframe(anim, pct);
-  }
-}
-
-interface DragRuntimeGsap {
-  getProperty: (target: Element, key: string) => unknown;
-  set: (target: Element, vars: Record<string, unknown>) => void;
-}
-interface DragRuntimeTimeline {
-  seek: (time: number) => void;
-}
-interface DragRuntime {
-  gsapLib: DragRuntimeGsap;
-  el: Element;
-  mainTl: DragRuntimeTimeline;
-}
-
-function resolveDragRuntime(
-  iframe: HTMLIFrameElement | null | undefined,
-  selector: string | undefined,
-): DragRuntime | null {
-  if (!iframe || !selector) return null;
-  const win = iframe.contentWindow as
-    | (Window & {
-        gsap?: Partial<DragRuntimeGsap>;
-        __timelines?: Record<string, Partial<DragRuntimeTimeline>>;
-      })
-    | null;
-  const gsap = win?.gsap;
-  if (typeof gsap?.getProperty !== "function" || typeof gsap.set !== "function") return null;
-  let el: Element | null = null;
-  try {
-    el = iframe.contentDocument?.querySelector(selector) ?? null;
-  } catch {
-    return null;
-  }
-  if (!el) return null;
-  const timelines = win?.__timelines;
-  const mainTl = timelines ? Object.values(timelines)[0] : undefined;
-  if (typeof mainTl?.seek !== "function") return null;
-  return {
-    gsapLib: gsap as DragRuntimeGsap,
-    el,
-    mainTl: mainTl as DragRuntimeTimeline,
-  };
-}
-
-// fallow-ignore-next-line complexity
-async function commitFlatViaKeyframes(
-  selection: DomEditSelection,
-  anim: GsapAnimation,
-  properties: Record<string, number>,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  iframe?: HTMLIFrameElement | null,
-  selector?: string,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const ct = usePlayerStore.getState().currentTime;
-  const ts = resolveTweenStart(anim);
-  const td = resolveEditableTweenDuration(anim, selection);
-  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-  const outsideRange =
-    activeKeyframePct == null && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-
-  const resolvedFromValues: Record<string, number | string> = {};
-  const runtime = resolveDragRuntime(iframe, selector);
-  if (runtime && ts !== null) {
-    const { gsapLib, el, mainTl } = runtime;
-    const draggedValues: Record<string, number> = {};
-    const channelsTheClearWipes = new Set([
-      ...Object.keys(properties),
-      ...PROPERTY_GROUPS.position,
-    ]);
-    for (const key of channelsTheClearWipes) {
-      const v = Number(gsapLib.getProperty(el, key));
-      if (Number.isFinite(v)) draggedValues[key] = v;
-    }
-    try {
-      gsapLib.set(el, { clearProps: Object.keys(properties).join(",") });
-      mainTl.seek(ts);
-      for (const key of Object.keys(properties)) {
-        const v = Number(gsapLib.getProperty(el, key));
-        if (Number.isFinite(v)) resolvedFromValues[key] = roundTo3(v);
-      }
-      mainTl.seek(ct);
-    } catch {
-      for (const key of Object.keys(resolvedFromValues)) delete resolvedFromValues[key];
-    } finally {
-      if (Object.keys(draggedValues).length > 0) gsapLib.set(el, draggedValues);
-    }
-  }
-
-  if (outsideRange && ts !== null) {
-    const coalesceKey = `gsap:convert-drag:${anim.id}`;
-    await callbacks.commitMutation(
-      selection,
-      {
-        type: "convert-to-keyframes",
-        animationId: anim.id,
-        ...(Object.keys(resolvedFromValues).length > 0 ? { resolvedFromValues } : {}),
-      },
-      { label: "Convert to keyframes for drag", skipReload: true, coalesceKey },
-    );
-    const fresh = callbacks.fetchAnimations ? await callbacks.fetchAnimations() : [];
-    // By id first: a target with several tweens (two `to`s on the same selector)
-    // matches the selector lookup on whichever one happens to be first, and the
-    // extend-and-add below would then rewrite a tween the drag never touched.
-    const converted =
-      fresh.find((a) => a.id === anim.id && a.keyframes) ??
-      fresh.find((a) => a.targetSelector === anim.targetSelector && a.keyframes) ??
-      anim;
-    const convertedStart = resolveTweenStart(converted) ?? ts;
-    const convertedDur = resolveTweenDuration(converted) || td;
-    await extendTweenAndAddKeyframe(
-      selection,
-      converted,
-      properties,
-      ct,
-      convertedStart,
-      convertedDur,
-      callbacks,
-      beforeReload,
-    );
-    return;
-  }
-
-  const coalesceKey = `gsap:convert-drag:${anim.id}`;
-  // fallow-ignore-next-line code-duplication
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "convert-to-keyframes",
-      animationId: anim.id,
-      ...(Object.keys(resolvedFromValues).length > 0 ? { resolvedFromValues } : {}),
-    },
-    { label: "Convert to keyframes for drag", skipReload: true, coalesceKey },
-  );
-  const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
-  const editedSelected = activeKeyframePct != null;
-  if (editedSelected) setActiveKeyframePct(null);
-
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties,
-      ...(backfillDefaults ? { backfillDefaults } : {}),
-    },
-    { label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload, coalesceKey },
+  studioOffset: { x: number; y: number },
+  gsapPos: { x: number; y: number },
+  iframe: HTMLIFrameElement | null,
+): GsapEditOutcome {
+  if (anim.arcPath?.enabled) return { status: "persisted" };
+  const { newX, newY, baseGsapX, baseGsapY } = computeDraggedGsapPosition(
+    selection.element,
+    studioOffset,
+    gsapPos,
   );
-  if (editedSelected) parkPlayheadOnKeyframe(anim, pct);
+  const plan = planValueEdit(selection, anim, { x: newX, y: newY }, iframe, {
+    backfill: { x: baseGsapX, y: baseGsapY },
+  });
+  return plan.ok
+    ? { status: "persisted" }
+    : { status: "blocked", reason: "keyframes-uneditable", detail: plan.reason };
 }
 
 // fallow-ignore-next-line code-duplication
@@ -279,9 +68,8 @@ export async function commitGsapPositionFromDrag(
   studioOffset: { x: number; y: number },
   gsapPos: { x: number; y: number },
   iframe: HTMLIFrameElement | null,
-  selector: string,
   callbacks: GsapDragCommitCallbacks,
-): Promise<void> {
+): Promise<GsapEditOutcome> {
   const el = selection.element;
   // fallow-ignore-next-line code-duplication
   const { newX, newY, baseGsapX, baseGsapY } = computeDraggedGsapPosition(
@@ -298,8 +86,6 @@ export async function commitGsapPositionFromDrag(
     el.removeAttribute("data-hf-drag-initial-offset-y");
   };
 
-  const backfillDefaults: Record<string, number> = { x: baseGsapX, y: baseGsapY };
-  const ct = usePlayerStore.getState().currentTime;
   if (anim.arcPath?.enabled) {
     const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
     const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
@@ -324,14 +110,15 @@ export async function commitGsapPositionFromDrag(
       );
       setActiveKeyframePct(null);
       parkPlayheadOnKeyframe(anim, pct);
-      return;
+      return { status: "persisted" };
     }
 
     const tweenStart = resolveTweenStart(anim);
     // Clip-wide, same as applyArcKeyframeAtPlayhead: authoring GSAP's 0.5s
     // default here would collapse a duration-less arc's window on drag.
     const tweenDuration = resolveEditableTweenDuration(anim, selection);
-    if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2) return;
+    if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2)
+      return { status: "persisted" };
     const temporalKeyframes = buildTemporalArcKeyframes(anim, pct, { x: newX, y: newY });
     await callbacks.commitMutation(
       selection,
@@ -351,161 +138,11 @@ export async function commitGsapPositionFromDrag(
         beforeReload: restoreOffset,
       },
     );
-    return;
-  }
-  if (anim.keyframes) {
-    const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
-    const effectiveAnim = newId ? { ...anim, id: newId } : anim;
-    const dragProps: Record<string, number> = { x: newX, y: newY };
-
-    const ts = resolveTweenStart(effectiveAnim);
-    const td = resolveEditableTweenDuration(effectiveAnim, selection);
-    const outsideRange = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-    const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
-    if (outsideRange && !hasSelectedKeyframe) {
-      await extendTweenAndAddKeyframe(
-        selection,
-        effectiveAnim,
-        dragProps,
-        ct,
-        ts,
-        td,
-        callbacks,
-        restoreOffset,
-        backfillDefaults,
-      );
-    } else {
-      await commitKeyframedPosition(
-        selection,
-        effectiveAnim,
-        dragProps,
-        callbacks,
-        restoreOffset,
-        backfillDefaults,
-      );
-    }
-  } else if (anim.method === "from" || anim.method === "fromTo") {
-    const ct = usePlayerStore.getState().currentTime;
-    const ts = resolveTweenStart(anim);
-    const td = resolveEditableTweenDuration(anim, selection);
-    const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
-    const outsideRange =
-      !hasSelectedKeyframe && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-    const dragProps: Record<string, number> = { x: newX, y: newY };
-
-    if (outsideRange && ts !== null) {
-      await callbacks.commitMutation(
-        selection,
-        { type: "split-into-property-groups", animationId: anim.id },
-        { label: "Split from() for drag", skipReload: true },
-      );
-
-      const allAnims = callbacks.fetchAnimations ? await callbacks.fetchAnimations() : [];
-      const existingPosAnim = allAnims.find(
-        (a) => a.propertyGroup === "position" && a.targetSelector === anim.targetSelector,
-      );
-
-      if (existingPosAnim?.keyframes) {
-        const posTs = resolveTweenStart(existingPosAnim);
-        const posTd = resolveEditableTweenDuration(existingPosAnim, selection);
-        if (posTs !== null) {
-          await extendTweenAndAddKeyframe(
-            selection,
-            existingPosAnim,
-            { x: newX, y: newY },
-            ct,
-            posTs,
-            posTd,
-            callbacks,
-            restoreOffset,
-            backfillDefaults,
-          );
-          return;
-        }
-      }
-
-      const newStart = Math.min(ct, ts);
-      const newEnd = Math.max(ct, ts + td);
-      const newDuration = Math.max(0.01, newEnd - newStart);
-      const dragBefore = ct < ts;
-      const origStartPct = Math.round(((ts - newStart) / newDuration) * 1000) / 10;
-      const origEndPct = Math.round(((ts + td - newStart) / newDuration) * 1000) / 10;
-
-      const keyframes: Array<{ percentage: number; properties: Record<string, number | string> }> =
-        [];
-      if (dragBefore) {
-        keyframes.push({ percentage: 0, properties: { x: newX, y: newY } });
-        if (origStartPct > 0.5 && origStartPct < 99.5) {
-          keyframes.push({ percentage: origStartPct, properties: { x: 0, y: 0 } });
-        }
-        keyframes.push({ percentage: 100, properties: { x: 0, y: 0 } });
-      } else {
-        keyframes.push({ percentage: 0, properties: { x: 0, y: 0 } });
-        if (origEndPct > 0.5 && origEndPct < 99.5) {
-          keyframes.push({ percentage: origEndPct, properties: { x: 0, y: 0 } });
-        }
-        keyframes.push({ percentage: 100, properties: { x: newX, y: newY } });
-      }
-      keyframes.sort((a, b) => a.percentage - b.percentage);
-
-      const baseKf = {
-        targetSelector: anim.targetSelector,
-        position: roundTo3(newStart),
-        duration: roundTo3(newDuration),
-        keyframes,
-      };
-      await callbacks.commitMutation(
-        selection,
-        existingPosAnim
-          ? { type: "replace-with-keyframes", animationId: existingPosAnim.id, ...baseKf }
-          : { type: "add-with-keyframes", ...baseKf },
-        {
-          label: "Move layer (from extended)",
-          keyframeAction: "add",
-          softReload: true,
-          beforeReload: restoreOffset,
-        },
-      );
-    } else {
-      const coalesceKey = `gsap:convert-drag:${anim.id}`;
-      await callbacks.commitMutation(
-        selection,
-        {
-          type: "convert-to-keyframes",
-          animationId: anim.id,
-        },
-        { label: "Convert from() for drag", skipReload: true, coalesceKey },
-      );
-      const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-      const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
-      if (activeKeyframePct != null) setActiveKeyframePct(null);
-      await callbacks.commitMutation(
-        selection,
-        {
-          type: "add-keyframe",
-          animationId: anim.id,
-          percentage: pct,
-          properties: dragProps,
-          ...(backfillDefaults ? { backfillDefaults } : {}),
-        },
-        {
-          label: `Move layer (keyframe ${pct}%)`,
-          softReload: true,
-          beforeReload: restoreOffset,
-          coalesceKey,
-        },
-      );
-    }
-  } else {
-    await commitFlatViaKeyframes(
-      selection,
-      anim,
-      { x: newX, y: newY },
-      callbacks,
-      restoreOffset,
-      iframe,
-      selector,
-      backfillDefaults,
-    );
+    return { status: "persisted" };
   }
+  return commitValueAtPlayhead(selection, anim, { x: newX, y: newY }, iframe, callbacks, {
+    label: "Move layer",
+    backfill: { x: baseGsapX, y: baseGsapY },
+    beforeReload: restoreOffset,
+  });
 }

package/src/hooks/gsapEditOutcome.ts

@@ -1,6 +1,11 @@
 import { editabilityForProvenance, type GsapAnimation } from "@hyperframes/core/gsap-parser";
 
-export type GsapEditBlockReason = "no-selector" | "unroll-required" | "source-uneditable";
+export type GsapEditBlockReason =
+  | "no-selector"
+  | "unroll-required"
+  | "source-uneditable"
+  | "keyframes-uneditable"
+  | "mixed-files";
 
 /**
  * Which of the nine situations produced a block. The user-facing `reason` stays
@@ -21,7 +26,18 @@ export type GsapEditBlockDetail =
   | "no-position-tween"
   | "live-rotation-no-source-tween"
   | "live-resize-no-source-tween"
-  | "zero-duration-tween";
+  | "zero-duration-tween"
+  | PlayheadEditRefusal;
+
+/** Why an edit at the playhead could not be written as keyframes of the file's tween. */
+export type PlayheadEditRefusal =
+  | "eased-keyframes"
+  | "simple-array-keyframes"
+  | "unknown-ease"
+  | "implicit-end-unknown"
+  | "not-a-tween"
+  | "no-timing"
+  | "shared-tween";
 
 export type GsapEditOutcome =
   | {
@@ -52,6 +68,10 @@ export const GSAP_EDIT_BLOCK_COPY: Record<GsapEditBlockReason, string> = {
   "unroll-required":
     "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
   "source-uneditable": "This animation is computed at runtime. Edit the animation in the Code tab.",
+  "keyframes-uneditable":
+    "Studio can't add this edit to the animation's keyframes. Edit this animation in the Code tab.",
+  "mixed-files":
+    "These layers are animated in different files. Move each file's layers separately.",
 };
 
 export class GsapEditBlockedError extends Error {

package/src/hooks/gsapGroupPreflight.ts

@@ -0,0 +1,34 @@
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
+import { gsapWriteFile } from "./gsapScriptCommitTypes";
+
+/** The first member a group's preflight refused, else one from a second file. */
+export function firstPreflightFailure(
+  results: PromiseSettledResult<void>[],
+  updates: DomEditGroupPathOffsetCommit[],
+  savedOnElement: Map<DomEditSelection, boolean>,
+  activeCompPath: string | null | undefined,
+): { error: unknown; selection: DomEditSelection } | null {
+  for (const [index, result] of results.entries()) {
+    if (result.status !== "rejected") continue;
+    const selection = updates[index]?.selection;
+    if (selection) return { error: result.reason, selection };
+  }
+  return secondFile(updates, savedOnElement, activeCompPath);
+}
+
+/** The group's script writes go out as one batch to one file, so members from two files refuse. */
+function secondFile(
+  updates: DomEditGroupPathOffsetCommit[],
+  savedOnElement: Map<DomEditSelection, boolean>,
+  activeCompPath: string | null | undefined,
+): { error: unknown; selection: DomEditSelection } | null {
+  const scripted = updates.filter(({ selection }) => !savedOnElement.has(selection));
+  const fileOf = (s: DomEditSelection) => gsapWriteFile(s, activeCompPath);
+  const file = scripted[0] && fileOf(scripted[0].selection);
+  const other = scripted.find(({ selection }) => fileOf(selection) !== file);
+  return other
+    ? { error: new GsapEditBlockedError("mixed-files"), selection: other.selection }
+    : null;
+}

package/src/hooks/gsapMutationClient.ts

@@ -1,11 +1,12 @@
 import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export class GsapPreviewConvergenceError extends Error {}
 export class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
 
 /** Verify rollback ownership support before any GSAP mutation can land. */
 export async function requireGsapOwnershipProtocol(projectId: string): Promise<void> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-capabilities`,
   );
   if (!response.ok) {
@@ -29,7 +30,7 @@ export async function rollbackOwnedMutation(
   if (targetPath.includes("\0") || targetPath.includes("..")) {
     throw new Error(`Unsafe path: ${targetPath}`);
   }
-  const response = await fetch(
+  const response = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
     {
       method: "POST",
@@ -95,7 +96,7 @@ export async function postGsapMutation(
 ): Promise<GsapMutationStatus> {
   let response: Response;
   try {
-    response = await fetch(
+    response = await studioApiFetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
       {
         method: "POST",

package/src/hooks/gsapParsedTween.test-helpers.ts

@@ -0,0 +1,75 @@
+import { vi } from "vitest";
+import { classifyTweenPropertyGroup } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../player/store/playerStore";
+
+/** A property's `[start, end]` as GSAP parsed it from the file when the tween first rendered. */
+type Ends = Record<string, [number, number]>;
+
+/** A GSAP 3 tween as the preview runtime holds it, with the property tweens the parse readers walk. */
+export function liveTween(
+  target: Element,
+  tween: { start: number; duration: number; vars: Record<string, unknown>; ends?: Ends },
+  { from = false, parts }: { from?: boolean; parts?: unknown[] } = {},
+) {
+  let head: Record<string, unknown> | undefined;
+  for (const [p, [s, e]] of Object.entries(tween.ends ?? {}).reverse())
+    head = from ? { p, s: e, c: s - e, _next: head } : { p, s, c: e - s, _next: head };
+  return {
+    targets: () => [target],
+    startTime: () => tween.start,
+    duration: () => tween.duration,
+    vars: tween.vars,
+    _from: from,
+    ...(head && { _pt: { d: { _pt: head } } }),
+    ...(parts && { timeline: { getChildren: () => parts } }),
+  };
+}
+
+/** A preview iframe whose one timeline holds `tweens`, answering `getProperty` from `live`. */
+export function previewWith(
+  element: Element,
+  tweens: unknown[],
+  live: Record<string, number> = {},
+): HTMLIFrameElement {
+  return {
+    contentWindow: {
+      __timelines: { main: { getChildren: () => tweens, duration: () => 10 } },
+      gsap: {
+        getProperty: (_el: Element, prop: string) => live[prop] ?? 0,
+        defaults: () => ({ ease: "power1.out" }),
+      },
+    },
+    contentDocument: element.ownerDocument,
+  } as unknown as HTMLIFrameElement;
+}
+
+export const tween = (fields: Partial<GsapAnimation>): GsapAnimation =>
+  ({ targetSelector: "#box", propertyGroup: "position", ...fields }) as GsapAnimation;
+
+/** A `to` tween on `#el` from 0, grouped as the parser would; duration 0 is an immediate-render hold. */
+export function elTween(
+  id: string,
+  properties: Record<string, number>,
+  duration: number,
+  ease?: string,
+): GsapAnimation {
+  return {
+    id,
+    targetSelector: "#el",
+    propertyGroup: classifyTweenPropertyGroup(properties),
+    method: "to",
+    properties,
+    position: 0,
+    resolvedStart: 0,
+    duration,
+    ...(duration === 0 ? { extras: { immediateRender: "__raw:true" } } : ease && { ease }),
+  } as unknown as GsapAnimation;
+}
+
+/** Per-test cleanup for the intercept sweeps: mocks, the playhead store and the document. */
+export function resetGsapEditState(): void {
+  vi.restoreAllMocks();
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
+  document.body.innerHTML = "";
+}