@hyperframes/studio 0.7.6 → 0.7.8

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -12,12 +12,23 @@ import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 
+/**
+ * A GSAP tween's `vars` object — intentionally open: it mixes channel values
+ * (numbers), easing (strings), flags (booleans), nested keyframes (objects) and
+ * callbacks. Named so call sites read as "GSAP config", not an untyped escape hatch.
+ */
+export type GsapVars = Record<string, unknown>;
+
 export interface RuntimeTween {
   targets?: () => Element[];
-  vars?: Record<string, unknown>;
+  vars?: GsapVars;
   duration?: () => number;
   startTime?: () => number;
   invalidate?: () => RuntimeTween;
+  /** Remove this tween from its parent timeline (GSAP `kill()`). */
+  kill?: () => void;
+  /** The timeline this tween lives in — used to re-insert a rebuilt tween. */
+  parent?: RuntimeTimeline;
 }
 
 export interface RuntimeTimeline {
@@ -25,6 +36,8 @@ export interface RuntimeTimeline {
   duration?: () => number;
   time?: () => number;
   invalidate?: () => RuntimeTimeline;
+  /** Add a tween at an absolute position — used to rebuild a keyframe tween in place. */
+  to?: (targets: Element[], vars: GsapVars, position?: number) => RuntimeTween;
 }
 
 type Pct = { percentage: number; properties: Record<string, number | string> };
@@ -184,6 +197,26 @@ function varsCarryChannel(vars: Record<string, unknown> | undefined, channels: s
   return false;
 }
 
+/**
+ * Like `varsCarryChannel` but for a keyframe tween: the channels live inside the
+ * keyframe steps (`vars.keyframes`), not as own props of `vars`. Handles the object
+ * form (`{ "0%": {...} }`) and the array form (`[{...}, ...]`).
+ */
+function keyframeVarsCarryChannel(
+  vars: Record<string, unknown> | undefined,
+  channels: string[],
+): boolean {
+  const kf = vars?.keyframes;
+  if (!kf || typeof kf !== "object") return false;
+  const steps = Array.isArray(kf) ? kf : Object.values(kf);
+  return steps.some(
+    (step) =>
+      step != null &&
+      typeof step === "object" &&
+      channels.some((ch) => Object.prototype.hasOwnProperty.call(step, ch)),
+  );
+}
+
 /**
  * Resolve the live tween targeting `selector` using the SAME all-timelines scan
  * `readRuntimeKeyframes` uses, so read and write agree on "which tween". With
@@ -197,6 +230,7 @@ function varsCarryChannel(vars: Record<string, unknown> | undefined, channels: s
  * on a rotation-only set). With no channel-matching set, it falls back to the
  * first matching set (back-compat). `channels` is ignored for `kind: "keyframe"`.
  */
+// fallow-ignore-next-line complexity
 export function resolveRuntimeTween(
   iframe: HTMLIFrameElement | null,
   selector: string,
@@ -219,7 +253,12 @@ export function resolveRuntimeTween(
     ? [compositionId]
     : Object.keys(timelines).filter((k) => typeof timelines[k]?.getChildren === "function");
 
-  const wantChannels = kind === "set" && channels && channels.length > 0 ? channels : null;
+  // Channels disambiguate co-located tweens for BOTH kinds: a `set` carries them as
+  // own vars props, a keyframe tween carries them inside its keyframe steps. An
+  // element can have a rotation keyframe tween AND a position keyframe tween; a
+  // rotation edit must land on the former. The reader passes no channels, so its
+  // playhead-containment path below is unchanged.
+  const wantChannels = channels && channels.length > 0 ? channels : null;
 
   let first: ResolvedRuntimeTween | null = null;
   let channelMatch: ResolvedRuntimeTween | null = null;
@@ -233,11 +272,15 @@ export function resolveRuntimeTween(
       const isSet = !(dur > 0);
       if (kind === "set" ? !isSet : isSet) continue;
       if (wantChannels) {
-        if (varsCarryChannel(tween.vars, wantChannels)) {
+        const carries =
+          kind === "set"
+            ? varsCarryChannel(tween.vars, wantChannels)
+            : keyframeVarsCarryChannel(tween.vars, wantChannels);
+        if (carries) {
           if (channelMatch === null) channelMatch = { tween, timeline };
         } else if (first === null) {
-          // A set carrying only disjoint channels: remember as last-resort
-          // fallback, but never prefer it over a channel-matching set.
+          // A tween carrying only disjoint channels: remember as last-resort
+          // fallback, but never prefer it over a channel-matching one.
           first = { tween, timeline };
         }
         continue;
@@ -252,14 +295,27 @@ export function resolveRuntimeTween(
   return channelMatch ?? first;
 }
 
+/** Whether a read carries at least one of `channels` as a keyframe property. */
+function readCarriesChannel(read: ReadTween, channels: string[]): boolean {
+  return read.keyframes.some((kf) => channels.some((c) => kf.properties[c] != null));
+}
+
 /**
  * Read keyframes (incl. motionPath arcs) for one selector from the live timeline.
  * Returns tween-relative percentages; callers convert to clip-relative.
+ *
+ * `requireChannels` restricts the scan to tweens whose read carries one of those
+ * properties — e.g. the motion-path overlay passes `["x","y"]` so it never picks
+ * up a co-located size/scale tween (which has no x/y and would blank the path
+ * whenever the playhead sits in that tween's range but outside the position
+ * tween's). Omitted → any keyframed tween qualifies (back-compat).
  */
+// fallow-ignore-next-line complexity
 export function readRuntimeKeyframes(
   iframe: HTMLIFrameElement | null,
   selector: string,
   compositionId?: string,
+  requireChannels?: string[],
 ): ReadTween | null {
   const timelines = timelinesOf(iframe);
   if (!timelines) return null;
@@ -299,6 +355,7 @@ export function readRuntimeKeyframes(
       if (isZeroDurationSet(dur)) continue; // skip hold/set tweens (see isZeroDurationSet)
       const read = readTween(tween.vars);
       if (!read) continue;
+      if (requireChannels && !readCarriesChannel(read, requireChannels)) continue;
       if (firstRead === null) firstRead = read;
       // Prefer the tween whose [start, start+dur] contains the playhead.
       if (now != null) {
@@ -321,6 +378,7 @@ export function readRuntimeKeyframes(
  * only a hold may remain, and resurrecting the deleted tween from the stale parse
  * must be avoided.
  */
+// fallow-ignore-next-line complexity
 export function hasNonHoldTweenForElement(
   iframe: HTMLIFrameElement | null,
   selector: string,

package/src/hooks/gsapRuntimePatch.ts

@@ -13,13 +13,22 @@
  * "Which tween" is resolved by the same all-timelines scan `readRuntimeKeyframes`
  * uses (`resolveRuntimeTween`), so read and write agree on the target.
  */
-import { resolveRuntimeTween, type RuntimeTween } from "./gsapRuntimeKeyframes";
+import {
+  resolveRuntimeTween,
+  type RuntimeTween,
+  type RuntimeTimeline,
+} from "./gsapRuntimeKeyframes";
 
 /** Value-only channels a `tl.set(...)` patch may touch. */
 export interface SetPatchProps {
   x?: number;
   y?: number;
   rotation?: number;
+  rotationX?: number;
+  rotationY?: number;
+  rotationZ?: number;
+  z?: number;
+  transformPerspective?: number;
   scaleX?: number;
   scaleY?: number;
   scale?: number;
@@ -31,12 +40,28 @@ export type KeyframeStep = Record<string, number>;
 
 export type RuntimeTweenChange =
   | { kind: "set"; props: SetPatchProps }
-  | { kind: "keyframes"; keyframes: KeyframeStep[] };
+  | { kind: "keyframes"; keyframes: KeyframeStep[] }
+  // Edit ONE step (at `pct`) of an object-form keyframe tween — the form the studio
+  // writes (`keyframes: { "0%": {...} }`). GSAP pre-compiles those into sub-tweens
+  // and won't re-read `vars.keyframes` on `invalidate()`, so this REBUILDS the tween
+  // (kill + recreate at the same position) instead of mutating it. Lets a design-panel
+  // keyframe edit show instantly rather than soft-reloading the iframe (a flash).
+  | { kind: "keyframe-rebuild"; pct: number; props: KeyframeStep }
+  // Apply a base `gsap.set` value to the element directly (`gsap.set(el, props)`).
+  // A base set lives OFF the timeline, so there's no runtime tween to patch — but
+  // the element is static on these channels, so setting them immediately reflects
+  // the edit with no soft reload (no flash) and leaves no keyframe marker.
+  | { kind: "global-set"; props: SetPatchProps };
 
 const SET_CHANNELS: Array<keyof SetPatchProps> = [
   "x",
   "y",
   "rotation",
+  "rotationX",
+  "rotationY",
+  "rotationZ",
+  "z",
+  "transformPerspective",
   "scaleX",
   "scaleY",
   "scale",
@@ -45,8 +70,42 @@ const SET_CHANNELS: Array<keyof SetPatchProps> = [
 
 type IframeWindow = Window & {
   __player?: { getTime?: () => number; seek?: (t: number) => void };
+  gsap?: { set?: (target: Element, vars: Record<string, number>) => void };
 };
 
+/**
+ * Apply a base `gsap.set` value to the element in the live runtime. Returns `true`
+ * if applied. Used for off-timeline static holds (position / 3D transform) — there's
+ * no tween to patch, so we set the channels directly. Safe because the element is
+ * static on these channels (the caller only uses this for non-animated values).
+ */
+/** The props as finite numbers, or null if any value is non-finite / none present. */
+function finiteNumericProps(props: SetPatchProps): Record<string, number> | null {
+  const numeric: Record<string, number> = {};
+  for (const [k, v] of Object.entries(props)) {
+    if (typeof v !== "number" || !Number.isFinite(v)) return null;
+    numeric[k] = v;
+  }
+  return Object.keys(numeric).length > 0 ? numeric : null;
+}
+
+function applyGlobalSet(
+  iframe: HTMLIFrameElement,
+  selector: string,
+  props: SetPatchProps,
+): boolean {
+  try {
+    const gsapLib = (iframe.contentWindow as IframeWindow | null)?.gsap;
+    const el = iframe.contentDocument?.querySelector(selector) ?? null;
+    const numeric = finiteNumericProps(props);
+    if (!gsapLib?.set || !el || !numeric) return false;
+    gsapLib.set(el, numeric);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function playerOf(iframe: HTMLIFrameElement): IframeWindow["__player"] | null {
   try {
     return (iframe.contentWindow as IframeWindow | null)?.__player ?? null;
@@ -100,10 +159,95 @@ function patchKeyframes(tween: RuntimeTween, keyframes: KeyframeStep[]): boolean
   return true;
 }
 
+/** The object-form keyframes map with `props` merged into the step at `pct`. */
+function mergeKeyframeStep(
+  map: Record<string, Record<string, number>>,
+  pct: number,
+  props: KeyframeStep,
+): Record<string, Record<string, number>> {
+  const next: Record<string, Record<string, number>> = {};
+  for (const [k, step] of Object.entries(map)) next[k] = { ...step };
+  // Match the existing percentage key numerically ("50%" ≡ pct 50), else add one.
+  let key: string | null = null;
+  for (const k of Object.keys(next)) {
+    const n = parseFloat(k);
+    if (Number.isFinite(n) && Math.abs(n - pct) < 0.05) {
+      key = k;
+      break;
+    }
+  }
+  if (key === null) key = `${pct}%`;
+  next[key] = { ...(next[key] ?? {}), ...props };
+  return next;
+}
+
+/**
+ * Rebuild an object-form keyframe tween with `props` merged into the step at `pct`,
+ * in place: kill the old tween and recreate it on the SAME parent timeline at the
+ * SAME position, with all other vars (duration, ease, repeat, …) preserved. This
+ * is the only way to reflect an object-form keyframe edit live — GSAP compiles
+ * those keyframes into sub-tweens at creation and ignores later `vars.keyframes`
+ * mutations. Declines (→ caller soft-reloads) for array-form, motionPath arcs,
+ * non-finite/dynamic values, or a tween whose parent/targets can't be resolved.
+ */
+// fallow-ignore-next-line complexity
+function rebuildKeyframeTween(tween: RuntimeTween, pct: number, props: KeyframeStep): boolean {
+  const vars = tween.vars;
+  if (!vars || "motionPath" in vars) return false;
+  const kf = vars.keyframes;
+  if (!kf || typeof kf !== "object" || Array.isArray(kf)) return false;
+  for (const v of Object.values(props)) {
+    if (typeof v !== "number" || !Number.isFinite(v)) return false;
+  }
+  const parent = tween.parent;
+  const targets = tween.targets?.();
+  if (!parent?.to || !targets || targets.length === 0) return false;
+  if (typeof tween.startTime !== "function" || typeof tween.kill !== "function") return false;
+
+  const next = mergeKeyframeStep(kf as Record<string, Record<string, number>>, pct, props);
+  const newVars = { ...vars, keyframes: next };
+  const position = tween.startTime();
+  tween.kill();
+  parent.to(targets, newVars, position);
+  return true;
+}
+
+/** The channels a change writes, for the resolver to disambiguate co-located tweens. */
+function changeChannels(change: RuntimeTweenChange): string[] | undefined {
+  if (change.kind === "set") {
+    return Object.keys(change.props).filter(
+      (k) => change.props[k as keyof SetPatchProps] !== undefined,
+    );
+  }
+  if (change.kind === "keyframe-rebuild") return Object.keys(change.props);
+  return undefined;
+}
+
+/** Re-render the timeline at the current playhead after an in-place edit. */
+function seekToCurrent(iframe: HTMLIFrameElement, timeline: RuntimeTimeline): void {
+  const player = playerOf(iframe);
+  const currentTime =
+    typeof player?.getTime === "function"
+      ? player.getTime()
+      : typeof timeline.time === "function"
+        ? timeline.time()
+        : 0;
+  player?.seek?.(Number.isFinite(currentTime) ? currentTime : 0);
+}
+
+/** Apply `change` to the resolved tween. `true` if applied, `false` to soft-reload.
+ *  `global-set` is handled before this (no tween) and never reaches here. */
+function applyChange(tween: RuntimeTween, change: RuntimeTweenChange): boolean {
+  if (change.kind === "set") return patchSet(tween, change.props);
+  if (change.kind === "keyframes") return patchKeyframes(tween, change.keyframes);
+  if (change.kind === "keyframe-rebuild")
+    return rebuildKeyframeTween(tween, change.pct, change.props);
+  return false;
+}
+
 /**
- * Update one tween's values in `window.__timelines` in place + re-seek to the
- * current playhead. Returns `true` on a confident patch, `false` otherwise
- * (caller falls back to a soft reload).
+ * Edit one tween in `window.__timelines` in place + re-seek to the current playhead.
+ * Returns `true` on a confident patch, `false` otherwise (caller soft-reloads).
  */
 export function patchRuntimeTweenInPlace(
   iframe: HTMLIFrameElement | null,
@@ -112,46 +256,29 @@ export function patchRuntimeTweenInPlace(
   compositionId?: string,
 ): boolean {
   if (!iframe) return false;
+  // A base `gsap.set` has no timeline tween to resolve — apply the value straight
+  // to the element so the edit shows instantly (no soft reload, no flash).
+  if (change.kind === "global-set") return applyGlobalSet(iframe, selector, change.props);
   try {
-    // For a `set` patch, hand the resolver the channels actually being written so
-    // it picks the set whose vars carry them — an element can have separate
-    // {x,y} and {rotation} sets, and a position patch must not corrupt the
-    // rotation set (channel-blind resolution would return the first match).
-    const channels =
-      change.kind === "set"
-        ? Object.keys(change.props).filter(
-            (k) => change.props[k as keyof SetPatchProps] !== undefined,
-          )
-        : undefined;
     const resolved = resolveRuntimeTween(
       iframe,
       selector,
       change.kind === "set" ? "set" : "keyframe",
       compositionId,
-      channels,
+      changeChannels(change),
     );
     if (!resolved) return false;
     const { tween, timeline } = resolved;
 
-    const applied =
-      change.kind === "set"
-        ? patchSet(tween, change.props)
-        : patchKeyframes(tween, change.keyframes);
-    if (!applied) return false;
-
-    // Recompute the tween (and its timeline) from the new vars, then re-render at
-    // the current playhead. `invalidate()` makes GSAP re-read vars on the next render.
-    tween.invalidate?.();
-    timeline.invalidate?.();
-
-    const player = playerOf(iframe);
-    const currentTime =
-      typeof player?.getTime === "function"
-        ? player.getTime()
-        : typeof timeline.time === "function"
-          ? timeline.time()
-          : 0;
-    player?.seek?.(Number.isFinite(currentTime) ? currentTime : 0);
+    if (!applyChange(tween, change)) return false;
+
+    // A rebuild already recreated the tween; set/keyframes mutate vars in place, so
+    // invalidate to make GSAP re-read them on the next render. Either way, re-seek.
+    if (change.kind !== "keyframe-rebuild") {
+      tween.invalidate?.();
+      timeline.invalidate?.();
+    }
+    seekToCurrent(iframe, timeline);
     return true;
   } catch {
     return false;