Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

20.9 KB
Raw Blame
/**
 * Bridge between the Studio drag system and GSAP animations running in the
 * preview iframe.
 *
 * The preview iframe exposes `window.gsap` with a `getProperty(element, prop)`
 * method that returns the ACTUAL interpolated value at the current seek time.
 * This module reads those runtime values so that drag commits can write correct
 * absolute positions back into the GSAP script, regardless of tween type,
 * easing, or seek position.
 */
import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
import { isXYPositionWrite, PROPERTY_GROUPS } from "@hyperframes/parsers/gsap-constants";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";

import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeReaders";
import { commitGsapPositionFromDrag, gsapPositionFromDragOutcome } from "./gsapDragPositionCommit";
import { commitValueAtPlayhead } from "./gsapValueAtPlayhead";
import {
  commitStaticGsapPosition,
  commitStaticGsapRotation,
  commitWholePathOffset,
  computeCurrentPercentage,
  findExistingPositionWrite,
  findRotationSetAnimation,
  stepListBlock,
} from "./gsapDragCommit";
import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
import { isGestureTransactionCommit } from "./gestureTransaction";
import { tweenReach, tweensForThisElement } from "./gsapTweenReach";
import { resolveTweenDuration } from "../utils/globalTimeCompiler";
import { roundTo3 } from "../utils/rounding";
import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
import { readDragStamp, type DragStamp } from "./draggedGsapPosition";
import { editMoment } from "./editMoment";
import type { EditMoment } from "../components/editor/manualEditsTypes";
import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
import {
  findGsapPositionAnimation,
  pickClosestToPlayhead,
  readGsapPositionFromIframe,
} from "./gsapPositionDetection";
import {
  hasNonHoldTweenForElement,
  POSITION_CHANNELS,
  ROTATION_CHANNELS,
} from "./gsapRuntimeKeyframes";
import { getAnimationsForElement } from "./gsapElementMatch";
import {
  animationWritesAnyProperty,
  directEditOutcomeForProperties,
  type GsapEditOutcome,
} from "./gsapEditOutcome";

const POSITION_CHANNEL_SET = new Set<string>(POSITION_CHANNELS);
const ROTATION_CHANNEL_SET = new Set<string>(ROTATION_CHANNELS);

// ── Property-group tween resolution ───────────────────────────────────────

/**
 * The tween to edit for a property group: a tween tagged with it, else a legacy tween that mixes
 * it with other groups. A mixed tween is edited in place, never split first: inside a gesture the
 * split is only buffered, so ids read after it are stale and the edit lands beside the old tween.
 */
export async function resolveGroupTween(
  group: PropertyGroupName,
  animations: GsapAnimation[],
  _selection: DomEditSelection,
  _commitMutation: GsapDragCommitCallbacks["commitMutation"],
  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
  time?: number,
): Promise<{ anim: GsapAnimation; animations: GsapAnimation[] } | null> {
  const inGroup = (list: GsapAnimation[]) => {
    const tagged = list.filter((a) => a.propertyGroup === group);
    const props = new Set(PROPERTY_GROUPS[group]);
    const mixed = list.filter((a) => !a.propertyGroup && animationWritesAnyProperty(a, props));
    return pickClosestToPlayhead(tagged.length > 0 ? tagged : mixed, time);
  };
  const anim = inGroup(animations);
  if (anim) return { anim, animations };
  if (!fetchFallbackAnimations) return null;
  const fresh = await fetchFallbackAnimations();
  const freshAnim = inGroup(fresh);
  return freshAnim ? { anim: freshAnim, animations: fresh } : null;
}

// ── High-level intercept ───────────────────────────────────────────────────

export type { GsapDragCommitCallbacks };

const writesPosition = (a: GsapAnimation) => animationWritesAnyProperty(a, POSITION_CHANNEL_SET);

/** Only a tween shared with siblings positions this element (a stagger on `.w`). */
function positionedOnlyBySharedTween(selection: DomEditSelection, animations: GsapAnimation[]) {
  const positioning = animations.filter(writesPosition);
  return (
    positioning.some((a) => tweenReach(a, selection.element) === "shared") &&
    tweensForThisElement(selection, positioning).length === 0
  );
}

// fallow-ignore-next-line complexity
async function preflightGsapDragIntercept(
  selection: DomEditSelection,
  animations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
  group?: boolean,
): Promise<GsapEditOutcome> {
  const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
  return dragEditOutcome(selection, animations, iframe, fetchedAnimations, group);
}

/** The move commit's refusal rule, also run ahead of time to hide the move handles. */
// fallow-ignore-next-line complexity
export function dragEditOutcome(
  selection: DomEditSelection,
  animations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  fetchedAnimations: GsapAnimation[] = [],
  group = false,
): GsapEditOutcome {
  const selector = selectorFromSelection(selection);
  if (!selector) return { status: "blocked", reason: "no-selector" };
  // The fallback API currently represents both a definitive empty parse and an
  // exhausted fetch failure as `[]`. Keep the selected cache in the preflight
  // set as well: ignoring it would let a transient fetch failure bypass helper /
  // runtime-source ownership and reach a destructive split or property write.
  const allKnownAnimations = [...animations, ...fetchedAnimations];
  const reaching = allKnownAnimations.filter(
    (a) => tweenReach(a, selection.element) !== "elsewhere",
  );
  const editability = directEditOutcomeForProperties(reaching, POSITION_CHANNEL_SET);
  if (editability.status === "blocked") return editability;
  if (positionedOnlyBySharedTween(selection, allKnownAnimations)) {
    return { status: "element-offset" };
  }
  const sourceAnimations = tweensForThisElement(
    selection,
    fetchedAnimations.length > 0 ? fetchedAnimations : animations,
  );
  // In a group only a tween naming this member by id or by its own selector counts,
  // so a class tween shared with id-selected members cannot take one member's write.
  const positionSources = group
    ? getAnimationsForElement(sourceAnimations, { id: selection.id ?? null, selector })
    : sourceAnimations;
  const posAnim = findGsapPositionAnimation(positionSources, selector);
  const hasLivePosition = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);

  if (hasLivePosition && !posAnim) {
    // GSAP is visibly moving this element but the parser found no position
    // tween for it — a source-match gap, not necessarily computed source.
    return {
      status: "blocked",
      reason: "source-uneditable",
      detail: "live-position-no-source-tween",
    };
  }
  if (!posAnim && !writeTargetSelector(selection)) {
    return { status: "blocked", reason: "no-selector" };
  }
  return { status: "persisted" };
}

let dragGestureCounter = 0;

/** Every write one drag makes (a split, then the move) records as ONE undo step. A
 *  transaction or group commit already owns its key. */
function oneUndoStep(
  commit: GsapDragCommitCallbacks["commitMutation"],
): GsapDragCommitCallbacks["commitMutation"] {
  if (isGestureTransactionCommit(commit)) return commit;
  const coalesceKey = `gsap:drag:${++dragGestureCounter}`;
  return (selection, mutation, options) =>
    commit(selection, mutation, { ...options, coalesceKey, coalesceMs: Number.POSITIVE_INFINITY });
}

const isPositionWriteOf = (selector: string) => (a: GsapAnimation) =>
  a.targetSelector === selector && isXYPositionWrite(a);

/** The one position write a self-heal keeps when holds fight over `selector`, else null. */
function positionWriteKeeper(animations: GsapAnimation[], selector: string): GsapAnimation | null {
  const dupes = animations.filter(isPositionWriteOf(selector));
  // Real tweens one after another are a motion, not a conflict: only holds can fight.
  if (dupes.length < 2 || dupes.filter((a) => !isInstantHold(a)).length > 1) return null;
  return dupes.find((a) => a.keyframes) ?? dupes.find((a) => (a.duration ?? 0) > 0) ?? dupes[0]!;
}

/** Where a drag writes. With no live motion and no keyframed tween (a hold, or a
 *  zero-length keyframed tween) the position belongs in a `tl.set`, never keyframes. */
function dragRoute(
  posAnim: GsapAnimation | null,
  iframe: HTMLIFrameElement | null,
  selector: string,
  altKey?: boolean,
): "static" | "whole-path" | "at-playhead" {
  const hasNonHold = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);
  const hasKeyframedPosTween = !!posAnim?.keyframes && resolveTweenDuration(posAnim) > 0;
  if (!hasNonHold && !hasKeyframedPosTween) return "static";
  // Alt-drag shifts the whole path; with auto-keyframe off (#1808) that is the default.
  return altKey || !usePlayerStore.getState().autoKeyframeEnabled ? "whole-path" : "at-playhead";
}

/** The commit's route and keyframe plan, writing nothing, so a group refuses whole. */
async function planDrag(
  selection: DomEditSelection,
  offset: { x: number; y: number },
  allAnimations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  options: { altKey?: boolean },
  moment: EditMoment,
): Promise<GsapEditOutcome> {
  const selector = selectorFromSelection(selection);
  if (!selector) return { status: "blocked", reason: "no-selector" };
  const own = tweensForThisElement(selection, allAnimations);
  const keeper = positionWriteKeeper(own, selector);
  const animations = keeper
    ? own.filter((a) => a === keeper || !isPositionWriteOf(selector)(a))
    : own;
  const resolved = await resolveGroupTween(
    "position",
    animations,
    selection,
    async () => {},
    undefined,
    moment.time,
  );
  const posAnim = resolved?.anim ?? findGsapPositionAnimation(animations, selector, moment.time);
  const route = dragRoute(posAnim, iframe, selector, options.altKey);
  if (route === "static") return { status: "persisted" };
  if (!posAnim) {
    return { status: "blocked", reason: "source-uneditable", detail: "no-position-tween" };
  }
  if (route === "whole-path") {
    const step = stepListBlock(posAnim);
    return step
      ? { status: "blocked", reason: "keyframes-uneditable", detail: step }
      : { status: "persisted" };
  }
  const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
  return gsapPositionFromDragOutcome(selection, posAnim, offset, gsapPos, iframe, moment);
}

/** Commits a drag through the GSAP script. Callers reject `blocked` (the gesture layer
 *  restores its drafts) and save `element-offset` on the element itself. */
export async function tryGsapDragIntercept(
  selection: DomEditSelection,
  offset: { x: number; y: number },
  allAnimations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  gestureCommit: GsapDragCommitCallbacks["commitMutation"],
  fetchAllAnimations?: () => Promise<GsapAnimation[]>,
  options?: {
    altKey?: boolean;
    preflightOnly?: boolean;
    preflightPassed?: boolean;
    group?: boolean;
    stamp?: DragStamp;
  },
): Promise<GsapEditOutcome> {
  const stamp = options?.stamp ?? readDragStamp(selection.element);
  const moment = editMoment(stamp);
  const time = moment.time;
  if (!options?.preflightPassed) {
    const preflight = await preflightGsapDragIntercept(
      selection,
      allAnimations,
      iframe,
      fetchAllAnimations,
      options?.group,
    );
    if (preflight.status !== "persisted") return preflight;
    if (options?.preflightOnly) {
      return options.group
        ? planDrag(selection, offset, allAnimations, iframe, options, moment)
        : preflight;
    }
  }
  const animations = tweensForThisElement(selection, allAnimations);
  const fetchFallbackAnimations =
    fetchAllAnimations && (async () => tweensForThisElement(selection, await fetchAllAnimations()));
  const selector = selectorFromSelection(selection);
  // The preflight above proves this; retain a defensive result for DOM churn.
  if (!selector) return { status: "blocked", reason: "no-selector" };
  const commitMutation = oneUndoStep(gestureCommit);

  // Self-heal: enforce a single position write BEFORE committing. A corrupted
  // file can carry 2+ conflicting position writes for one selector (e.g. a
  // degenerate `tl.to(...,{duration:0,x,y})` AND a `gsap.set(...,{x,y})`) — the
  // later one silently overrides the earlier, so the element "can't move". Keep
  // the live keyframed/real tween if present (else any), strip the rest, so the
  // commit below updates ONE write instead of fighting duplicates.
  let workingAnimations = animations;
  if (animations.filter(isPositionWriteOf(selector)).length > 1 && fetchFallbackAnimations) {
    const fresh = await fetchFallbackAnimations();
    const keeper = positionWriteKeeper(fresh, selector);
    if (keeper) {
      await commitMutation(
        selection,
        {
          type: "consolidate-position-writes",
          targetSelector: selector,
          keepAnimationId: keeper.id,
        },
        { label: "Consolidate position writes", skipReload: true },
      );
      workingAnimations = await fetchFallbackAnimations();
    } else {
      workingAnimations = fresh;
    }
  }

  const resolved = await resolveGroupTween(
    "position",
    workingAnimations,
    selection,
    commitMutation,
    fetchFallbackAnimations,
    time,
  );

  let posAnim = resolved?.anim ?? null;
  let resolvedAnimations = resolved?.animations ?? workingAnimations;
  if (!posAnim) {
    posAnim = findGsapPositionAnimation(workingAnimations, selector, time);
    if (!posAnim && fetchFallbackAnimations) {
      const fresh = await fetchFallbackAnimations();
      resolvedAnimations = fresh;
      posAnim = findGsapPositionAnimation(fresh, selector, time);
    }
  }

  const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
  const route = dragRoute(posAnim, iframe, selector, options?.altKey);
  if (route === "static") {
    const existingSet =
      posAnim && isInstantHold(posAnim) && posAnim.targetSelector === selector
        ? posAnim
        : findExistingPositionWrite(resolvedAnimations, selector, selection.element);
    await commitStaticGsapPosition(selection, offset, gsapPos, selector, existingSet, {
      commitMutation,
      fetchAnimations: fetchFallbackAnimations,
      stamp: options?.stamp,
    });
    return { status: "persisted" };
  }

  if (!posAnim) {
    return { status: "blocked", reason: "source-uneditable", detail: "no-position-tween" };
  }

  // Verify the anim ID is still valid in the current file. The React-state
  // `animations` list can lag behind the file after a prior mutation changed
  // the tween's position/method (which changes the ID). Re-fetch to get the
  // current ID and avoid a stale-ID remove that creates duplicate tweens.
  if (fetchFallbackAnimations) {
    const fresh = await fetchFallbackAnimations();
    const freshMatch =
      fresh.find((a) => a.id === posAnim!.id) ??
      pickClosestToPlayhead(
        fresh.filter(
          (a) =>
            a.targetSelector === posAnim!.targetSelector &&
            a.propertyGroup === posAnim!.propertyGroup &&
            isXYPositionWrite(a) === isXYPositionWrite(posAnim!),
        ),
        time,
      );
    if (freshMatch && freshMatch.id !== posAnim.id) {
      posAnim = freshMatch;
    }
  }

  const cbs = { commitMutation, fetchAnimations: fetchFallbackAnimations, stamp };
  if (route === "whole-path") {
    await commitWholePathOffset(selection, posAnim, offset, gsapPos, iframe, selector, cbs);
  } else {
    return commitGsapPositionFromDrag(selection, posAnim, offset, gsapPos, iframe, cbs);
  }
  return { status: "persisted" };
}

// ── Runtime property readers (re-exported for external callers) ───────────

export { readGsapProperty, readAllAnimatedProperties };

// ── Identity-prop synthesis ───────────────────────────────────────────────

/** The rotation commit's refusal rule, also run ahead of time to hide the rotate handle. */
export function preflightGsapRotationIntercept(
  selection: DomEditSelection,
  animations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  fetchedAnimations: GsapAnimation[] = [],
): GsapEditOutcome {
  const liveSelector = selectorFromSelection(selection);
  if (!(liveSelector ?? writeTargetSelector(selection))) {
    return { status: "blocked", reason: "no-selector" };
  }
  const editability = directEditOutcomeForProperties(
    [...animations, ...fetchedAnimations],
    ROTATION_CHANNEL_SET,
  );
  if (editability.status === "blocked") return editability;
  const workingAnimations = animations.length > 0 ? animations : fetchedAnimations;
  const hasSourceTween = workingAnimations.some((a) =>
    animationWritesAnyProperty(a, ROTATION_CHANNEL_SET),
  );
  if (
    !hasSourceTween &&
    liveSelector &&
    hasNonHoldTweenForElement(iframe, liveSelector, undefined, ROTATION_CHANNELS)
  ) {
    // Rotation twin of the position case above: live tween, no source match.
    return {
      status: "blocked",
      reason: "source-uneditable",
      detail: "live-rotation-no-source-tween",
    };
  }
  return { status: "persisted" };
}

export async function tryGsapRotationIntercept(
  selection: DomEditSelection,
  angle: number,
  animations: GsapAnimation[],
  iframe: HTMLIFrameElement | null,
  commitMutation: GsapDragCommitCallbacks["commitMutation"],
  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
  stamp?: DragStamp,
): Promise<GsapEditOutcome> {
  const time = editMoment(stamp).time;
  const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
  const outcome = preflightGsapRotationIntercept(selection, animations, iframe, fetchedAnimations);
  if (outcome.status === "blocked") return outcome;
  const selector = (selectorFromSelection(selection) ?? writeTargetSelector(selection))!;
  const workingAnimations = animations.length > 0 ? animations : fetchedAnimations;
  const postSplitFetch = workingAnimations.some((animation) => !animation.propertyGroup)
    ? fetchFallbackAnimations
    : undefined;

  // Resolve the rotation-group tween, splitting legacy mixed tweens if needed.
  const resolved = await resolveGroupTween(
    "rotation",
    workingAnimations,
    selection,
    commitMutation,
    postSplitFetch,
    time,
  );
  const resolvedAnimations = resolved?.animations ?? workingAnimations;

  // Fallback: legacy heuristic for hand-written scripts
  let anim =
    resolved?.anim && animationWritesAnyProperty(resolved.anim, ROTATION_CHANNEL_SET)
      ? resolved.anim
      : null;
  if (!anim) {
    anim = pickClosestToPlayhead(
      workingAnimations.filter((a) => animationWritesAnyProperty(a, ROTATION_CHANNEL_SET)),
      time,
    );
  }

  // `angle` is the ABSOLUTE target rotation resolved by the gesture (gsap base +
  // pointer sweep) or the inspector — so it IS the new rotation. No base re-add: the
  // gesture's live preview already gsap.set this value (single source of truth).
  const newRotation = roundTo3(angle);
  // STATIC case (single source of truth = GSAP timeline): no rotation tween, so the
  // angle belongs in a `tl.set("#el",{rotation})`, not a keyframe conversion —
  // mirroring the static position set. Idempotent: re-rotate updates an existing
  // rotation set in place, else add a new one. This replaces the old
  // `--hf-studio-rotation` CSS-var fallback (the same dual-channel bug class).
  if (!anim || isInstantHold(anim)) {
    const existingSet =
      anim ?? findRotationSetAnimation(resolvedAnimations, selector, selection.element);
    await commitStaticGsapRotation(selection, newRotation, selector, existingSet, {
      commitMutation,
      fetchAnimations: fetchFallbackAnimations,
    });
    return { status: "persisted" };
  }

  const pct = computeCurrentPercentage(selection, anim, time);

  // With auto-keyframe off (#1808), a rotation tween already exists for this
  // element (checked above) so nudge it as a whole rather than adding a
  // keyframe at the playhead.
  if (!usePlayerStore.getState().autoKeyframeEnabled) {
    await commitWholePropertyOffset(
      selection,
      anim,
      { rotation: newRotation },
      pct,
      iframe,
      { commitMutation, fetchAnimations: fetchFallbackAnimations },
      "Rotate animation",
    );
    return { status: "persisted" };
  }

  return commitValueAtPlayhead(
    selection,
    anim,
    { rotation: newRotation },
    iframe,
    { commitMutation, fetchAnimations: fetchFallbackAnimations, stamp },
    { label: "Rotate", backfill: { rotation: newRotation }, holdFromStart: true },
  );
}

export { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";