@hyperframes/studio 0.7.7 → 0.7.9

package/src/hooks/gsapDragCommit.test.ts

@@ -332,7 +332,7 @@ describe("commitStaticGsapPosition — instantPatch (value-only set)", () => {
     expect(yPatch.change.props[xMutation.property]).toBe(xMutation.value);
   });
 
-  it("does NOT attach instantPatch when ADDING a new set (structural — new tween)", async () => {
+  it("ADDS a global gsap.set with a global-set instantPatch (off-timeline, no flash)", async () => {
     const { commits, callbacks } = optionRecordingCallbacks();
 
     await commitStaticGsapPosition(
@@ -340,13 +340,15 @@ describe("commitStaticGsapPosition — instantPatch (value-only set)", () => {
       { x: -50, y: 30 },
       { x: 0, y: 0 },
       "#puck-a",
-      null, // no existing set → `add` a new tween
+      null, // no existing set → `add` a new base gsap.set
       callbacks,
     );
 
     expect(commits).toHaveLength(1);
     expect(commits[0].mutation.type).toBe("add");
-    expect(commits[0].options.instantPatch).toBeUndefined();
+    expect((commits[0].mutation as { global?: boolean }).global).toBe(true);
+    const patch = commits[0].options.instantPatch as { change: { kind: string } } | undefined;
+    expect(patch?.change.kind).toBe("global-set");
   });
 });
 
@@ -372,14 +374,16 @@ describe("commitStaticGsapRotation — instantPatch (value-only set)", () => {
     expect(patch.change.props[m.property]).toBe(m.value);
   });
 
-  it("does NOT attach instantPatch when ADDING a new rotation set (structural)", async () => {
+  it("ADDS a global gsap.set with a global-set instantPatch (off-timeline, no flash)", async () => {
     const { commits, callbacks } = optionRecordingCallbacks();
 
     await commitStaticGsapRotation(selection(), 42, "#puck-a", null, callbacks);
 
     expect(commits).toHaveLength(1);
     expect(commits[0].mutation.type).toBe("add");
-    expect(commits[0].options.instantPatch).toBeUndefined();
+    expect((commits[0].mutation as { global?: boolean }).global).toBe(true);
+    const patch = commits[0].options.instantPatch as { change: { kind: string } } | undefined;
+    expect(patch?.change.kind).toBe("global-set");
   });
 });
 

package/src/hooks/gsapDragCommit.ts

@@ -120,18 +120,22 @@ interface UpdatePropertyMutation {
 function setPatchFromUpdateProperties(
   selector: string,
   mutations: UpdatePropertyMutation[],
+  global = false,
 ): { selector: string; change: RuntimeTweenChange } {
   const props: SetPatchProps = {};
   for (const m of mutations) props[m.property as keyof SetPatchProps] = m.value;
-  return { selector, change: { kind: "set", props } };
+  // An off-timeline `gsap.set` has no runtime tween to patch — apply it to the
+  // element directly. An on-timeline `tl.set` mutates its tween (so a re-seek keeps it).
+  return { selector, change: { kind: global ? "global-set" : "set", props } };
 }
 
 /** Single-mutation convenience over {@link setPatchFromUpdateProperties}. */
 function setPatchFromUpdateProperty(
   selector: string,
   mutation: UpdatePropertyMutation,
+  global = false,
 ): { selector: string; change: RuntimeTweenChange } {
-  return setPatchFromUpdateProperties(selector, [mutation]);
+  return setPatchFromUpdateProperties(selector, [mutation], global);
 }
 
 /**
@@ -194,22 +198,25 @@ export async function commitStaticGsapPosition(
     // preview still reflects what DID persist. The x commit carries skipReload
     // (no reload), so its instantPatch gives instant feedback without a reload;
     // the y commit triggers the soft reload (skipped when the patch applies).
+    const global = !!existingSet.global;
     await callbacks.commitMutation(selection, xMutation, {
       label: "Move layer",
       skipReload: true,
       coalesceKey,
-      instantPatch: setPatchFromUpdateProperty(selector, xMutation),
+      instantPatch: setPatchFromUpdateProperty(selector, xMutation, global),
     });
     await callbacks.commitMutation(selection, yMutation, {
       label: "Move layer",
       softReload: true,
       coalesceKey,
       // Final commit of the coalesced x/y pair: carry both channels so the
-      // runtime `tl.set` lands the complete {x,y} pose in place.
-      instantPatch: setPatchFromUpdateProperties(selector, [xMutation, yMutation]),
+      // runtime set lands the complete {x,y} pose in place.
+      instantPatch: setPatchFromUpdateProperties(selector, [xMutation, yMutation], global),
     });
     return;
   }
+  // New static hold → a base `gsap.set` (off-timeline, no 0% keyframe marker), with
+  // an instant patch so the first nudge shows immediately (no soft-reload flash).
   await callbacks.commitMutation(
     selection,
     {
@@ -218,8 +225,13 @@ export async function commitStaticGsapPosition(
       method: "set",
       position: 0,
       properties: { x: newX, y: newY },
+      global: true,
+    },
+    {
+      label: "Move layer",
+      softReload: true,
+      instantPatch: { selector, change: { kind: "global-set", props: { x: newX, y: newY } } },
     },
-    { label: "Move layer", softReload: true },
   );
 }
 
@@ -264,11 +276,13 @@ export async function commitStaticGsapRotation(
     await callbacks.commitMutation(selection, rotationMutation, {
       label: "Rotate layer",
       softReload: true,
-      // Value-only rotation set: patch the runtime `tl.set` rotation in place.
-      instantPatch: setPatchFromUpdateProperty(selector, rotationMutation),
+      // Value-only rotation set — patch the runtime in place (off-timeline gsap.set
+      // applies to the element directly; on-timeline tl.set patches its tween).
+      instantPatch: setPatchFromUpdateProperty(selector, rotationMutation, !!existingSet.global),
     });
     return;
   }
+  // New static hold → off-timeline `gsap.set` (no 0% keyframe marker) + instant patch.
   await callbacks.commitMutation(
     selection,
     {
@@ -277,8 +291,13 @@ export async function commitStaticGsapRotation(
       method: "set",
       position: 0,
       properties: { rotation: newRotation },
+      global: true,
+    },
+    {
+      label: "Rotate layer",
+      softReload: true,
+      instantPatch: { selector, change: { kind: "global-set", props: { rotation: newRotation } } },
     },
-    { label: "Rotate layer", softReload: true },
   );
 }
 

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;
@@ -267,6 +310,7 @@ function readCarriesChannel(read: ReadTween, channels: string[]): boolean {
  * 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,
@@ -334,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;