@hyperframes/studio 0.6.97 → 0.6.99

package/src/hooks/gsapRuntimeReaders.ts

@@ -3,31 +3,29 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { classifyPropertyGroup, type PropertyGroupName } from "@hyperframes/core/gsap-parser";
-
-interface IframeGsap {
-  getProperty: (el: Element, prop: string) => number;
-}
+import { getIframeGsap, queryIframeElement } from "./gsapShared";
+import { roundTo3 } from "../utils/rounding";
 
 export function readGsapProperty(
   iframe: HTMLIFrameElement | null,
   selector: string | null,
   prop: string,
 ): number | null {
-  if (!iframe?.contentWindow || !selector) return null;
+  if (!selector) return null;
+  const gsap = getIframeGsap(iframe);
+  if (!gsap) return null;
+  const el = queryIframeElement(iframe, selector);
+  if (!el) return null;
   try {
-    const gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
-    if (!gsap?.getProperty) return null;
-    const el = iframe.contentDocument?.querySelector(selector);
-    if (!el) return null;
     const val = Number(gsap.getProperty(el, prop));
     if (!Number.isFinite(val)) return null;
-    return POSITION_PROPS.has(prop) ? Math.round(val) : Math.round(val * 1000) / 1000;
+    return POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
   } catch {
     return null;
   }
 }
 
-const POSITION_PROPS = new Set(["x", "y", "xPercent", "yPercent"]);
+export const POSITION_PROPS = new Set(["x", "y", "xPercent", "yPercent"]);
 const GSAP_CONFIG_KEYS = new Set([
   "duration",
   "ease",
@@ -56,22 +54,17 @@ export function readAllAnimatedProperties(
   group?: PropertyGroupName,
 ): Record<string, number> {
   const result: Record<string, number> = {};
-  if (!iframe?.contentWindow) return result;
-  let gsap: IframeGsap | undefined;
-  try {
-    gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
-  } catch {
-    return result;
-  }
-  if (!gsap?.getProperty) return result;
+  if (!iframe) return result;
+  const gsap = getIframeGsap(iframe);
+  if (!gsap) return result;
+  const el = queryIframeElement(iframe, selector);
+  if (!el) return result;
   let doc: Document | null = null;
   try {
-    doc = iframe.contentDocument;
+    doc = iframe?.contentDocument ?? null;
   } catch {
-    return result;
+    /* cross-origin guard — doc stays null */
   }
-  const el = doc?.querySelector(selector);
-  if (!el) return result;
 
   const propKeys = new Set<string>();
   if (anim.keyframes) {
@@ -94,7 +87,7 @@ export function readAllAnimatedProperties(
   for (const prop of propKeys) {
     const val = Number(gsap.getProperty(el, prop));
     if (Number.isFinite(val)) {
-      result[prop] = POSITION_PROPS.has(prop) ? Math.round(val) : Math.round(val * 1000) / 1000;
+      result[prop] = POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
     }
   }
 
@@ -166,7 +159,7 @@ export function readAllAnimatedProperties(
     if (!allTweenedProps.has(prop)) continue;
     const val = Number(gsap.getProperty(el, prop));
     if (Number.isFinite(val) && Math.round(val * 1000) !== Math.round(defaultVal * 1000)) {
-      result[prop] = Math.round(val * 1000) / 1000;
+      result[prop] = roundTo3(val);
     }
   }
 
@@ -208,7 +201,7 @@ export function readAllAnimatedProperties(
     }
     if (Number.isFinite(cssVal) && Math.round(gsapVal * 1000) === Math.round(cssVal * 1000))
       continue;
-    result[prop] = Math.round(gsapVal * 1000) / 1000;
+    result[prop] = roundTo3(gsapVal);
   }
 
   return result;

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -1,17 +1,7 @@
 import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 
-export const PROPERTY_DEFAULTS: Record<string, number> = {
-  opacity: 1,
-  x: 0,
-  y: 0,
-  scale: 1,
-  scaleX: 1,
-  scaleY: 1,
-  rotation: 0,
-  width: 100,
-  height: 100,
-};
+export { PROPERTY_DEFAULTS } from "./gsapShared";
 
 export function ensureElementAddressable(selection: DomEditSelection): {
   selector: string;

package/src/hooks/gsapScriptCommitTypes.ts

@@ -0,0 +1,58 @@
+import type { ParsedGsap } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+export interface MutationResult {
+  ok: boolean;
+  changed?: boolean;
+  parsed?: ParsedGsap;
+  before?: string;
+  after?: string;
+  scriptText?: string;
+}
+
+export interface CommitMutationOptions {
+  label: string;
+  coalesceKey?: string;
+  softReload?: boolean;
+  skipReload?: boolean;
+  beforeReload?: () => void;
+}
+
+export type CommitMutation = (
+  selection: DomEditSelection,
+  mutation: Record<string, unknown>,
+  options: CommitMutationOptions,
+) => Promise<void>;
+
+export type SafeGsapCommitMutation = (
+  selection: DomEditSelection,
+  mutation: Record<string, unknown>,
+  options: CommitMutationOptions,
+) => void;
+
+export type TrackGsapSaveFailure = (
+  error: unknown,
+  selection: DomEditSelection,
+  mutation: Record<string, unknown>,
+  label?: string,
+) => void;
+
+export interface GsapScriptCommitsParams {
+  projectIdRef: React.MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
+  editHistory: {
+    recordEdit: (entry: {
+      label: string;
+      kind: EditHistoryKind;
+      coalesceKey?: string;
+      files: Record<string, { before: string; after: string }>;
+    }) => Promise<void>;
+  };
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  reloadPreview: () => void;
+  onCacheInvalidate: () => void;
+  onFileContentChanged?: (path: string, content: string) => void;
+  showToast: (message: string, tone?: "error" | "info") => void;
+}

package/src/hooks/gsapShared.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared GSAP primitives used across multiple hook files.
+ * Centralises duplicated interfaces, constants, and small utilities
+ * to reduce drift risk.
+ */
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  absoluteToPercentage,
+  resolveTweenStart,
+  resolveTweenDuration,
+} from "../utils/globalTimeCompiler";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Canonical interface for the iframe-hosted GSAP runtime. */
+export interface IframeGsap {
+  getProperty: (el: Element, prop: string) => number;
+  set?: (target: string, vars: Record<string, number | string>) => void;
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+export const PROPERTY_DEFAULTS: Record<string, number> = {
+  opacity: 1,
+  x: 0,
+  y: 0,
+  scale: 1,
+  scaleX: 1,
+  scaleY: 1,
+  rotation: 0,
+  width: 100,
+  height: 100,
+};
+
+// ── Selector resolution ───────────────────────────────────────────────────────
+
+/**
+ * Get a CSS selector string from a DomEditSelection.
+ * Returns `#id` if the selection has an id, otherwise the raw selector,
+ * or null if neither exists.
+ */
+export function selectorFromSelection(selection: DomEditSelection): string | null {
+  if (selection.id) return `#${selection.id}`;
+  if (selection.selector) return selection.selector;
+  return null;
+}
+
+// ── Percentage computation ────────────────────────────────────────────────────
+
+/**
+ * Compute the current playback percentage within an element's animation range.
+ * Uses the animation's resolved timing if available, otherwise falls back to
+ * the element's data-start / data-duration attributes.
+ */
+export function computeElementPercentage(
+  currentTime: number,
+  selection: DomEditSelection,
+  animation?: GsapAnimation | null,
+): number {
+  if (animation) {
+    const start = resolveTweenStart(animation);
+    const duration = resolveTweenDuration(animation);
+    if (start !== null) {
+      return absoluteToPercentage(currentTime, start, duration);
+    }
+  }
+  const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
+  const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
+  return elDuration > 0
+    ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
+    : 0;
+}
+
+// ── Iframe accessors ──────────────────────────────────────────────────────────
+
+/** Safely retrieve the GSAP runtime from the preview iframe. */
+export function getIframeGsap(iframe: HTMLIFrameElement | null): IframeGsap | null {
+  if (!iframe?.contentWindow) return null;
+  try {
+    const gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
+    return gsap?.getProperty ? gsap : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Safely query an element inside the preview iframe's document. */
+export function queryIframeElement(
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+): Element | null {
+  try {
+    return iframe?.contentDocument?.querySelector(selector) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Safely access an iframe's contentDocument, returning null on cross-origin errors. */
+export function getIframeDocument(iframe: HTMLIFrameElement | null): Document | null {
+  if (!iframe) return null;
+  try {
+    return iframe.contentDocument;
+  } catch {
+    return null;
+  }
+}
+
+// ── Keyframe parsing ──────────────────────────────────────────────────────────
+
+export interface ParsedPercentageKeyframes {
+  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+  easeEach?: string;
+}
+
+/**
+ * Parse a GSAP percentage-keyframe object (`{ "0%": { x: 10 }, "100%": { x: 200 } }`)
+ * into a sorted array of `{ percentage, properties }` entries.
+ * Returns `null` when the object contains no valid keyframe entries.
+ */
+export function parsePercentageKeyframes(
+  kfObj: Record<string, unknown>,
+): ParsedPercentageKeyframes | null {
+  const keyframes: ParsedPercentageKeyframes["keyframes"] = [];
+  let easeEach: string | undefined;
+
+  for (const [key, val] of Object.entries(kfObj)) {
+    if (key === "easeEach") {
+      if (typeof val === "string") easeEach = val;
+      continue;
+    }
+    const pctMatch = key.match(/^(\d+(?:\.\d+)?)%$/);
+    if (!pctMatch || !val || typeof val !== "object") continue;
+    const percentage = parseFloat(pctMatch[1]);
+    const properties: Record<string, number | string> = {};
+    for (const [pk, pv] of Object.entries(val as Record<string, unknown>)) {
+      if (pk === "ease") continue;
+      if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
+      else if (typeof pv === "string") properties[pk] = pv;
+    }
+    if (Object.keys(properties).length > 0) {
+      keyframes.push({ percentage, properties });
+    }
+  }
+
+  if (keyframes.length === 0) return null;
+  keyframes.sort((a, b) => a.percentage - b.percentage);
+  return { keyframes, easeEach };
+}
+
+// ── Time conversion ───────────────────────────────────────────────────────────
+
+/** Convert a tween-relative percentage to an absolute time. */
+export function toAbsoluteTime(tweenPos: number, tweenDur: number, percentage: number): number {
+  return tweenPos + (percentage / 100) * tweenDur;
+}

package/src/hooks/timelineEditingHelpers.ts

@@ -1,4 +1,4 @@
-import type { TimelineElement } from "../player";
+import type { TimelineElement } from "../player/store/playerStore";
 import { applyPatchByTarget, readAttributeByTarget } from "../utils/sourcePatcher";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
@@ -6,7 +6,7 @@ import type { EditHistoryKind } from "../utils/editHistory";
 
 // ── Types ──
 
-interface RecordEditInput {
+export interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;
@@ -144,5 +144,66 @@ export async function readFileContent(projectId: string, targetPath: string): Pr
   return data.content;
 }
 
+/**
+ * Shift all GSAP animation positions targeting a given element by a time delta.
+ * Calls the server-side GSAP mutation endpoint which uses the AST-based parser.
+ */
+export async function shiftGsapPositions(
+  projectId: string,
+  filePath: string,
+  elementId: string,
+  delta: number,
+): Promise<void> {
+  if (delta === 0 || !elementId) return;
+  const res = await fetch(
+    `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "shift-positions",
+        targetSelector: `#${elementId}`,
+        delta,
+      }),
+    },
+  );
+  if (!res.ok) {
+    const err = await res.json().catch(() => null);
+    throw new Error((err as { error?: string })?.error ?? "shift-positions failed");
+  }
+}
+
+export async function scaleGsapPositions(
+  projectId: string,
+  filePath: string,
+  elementId: string,
+  oldStart: number,
+  oldDuration: number,
+  newStart: number,
+  newDuration: number,
+): Promise<void> {
+  if (!elementId || oldDuration <= 0 || newDuration <= 0) return;
+  if (oldStart === newStart && oldDuration === newDuration) return;
+  const res = await fetch(
+    `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "scale-positions",
+        targetSelector: `#${elementId}`,
+        oldStart,
+        oldDuration,
+        newStart,
+        newDuration,
+      }),
+    },
+  );
+  if (!res.ok) {
+    const err = await res.json().catch(() => null);
+    throw new Error((err as { error?: string })?.error ?? "scale-positions failed");
+  }
+}
+
 // Re-export applyPatchByTarget for use in the hook (avoids double import in callers)
 export { applyPatchByTarget, formatTimelineAttributeNumber };

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -12,6 +12,7 @@ import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
+import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
 
 interface CommitAnimatedPropertyDeps {
   selectedGsapAnimations: GsapAnimation[];
@@ -37,23 +38,6 @@ interface CommitAnimatedPropertyDeps {
   bumpGsapCache: () => void;
 }
 
-function computePercentage(selection: DomEditSelection, anim?: GsapAnimation): number {
-  const currentTime = usePlayerStore.getState().currentTime;
-  const tweenPos = anim?.resolvedStart ?? (typeof anim?.position === "number" ? anim.position : 0);
-  const tweenDur = anim?.duration ?? 0;
-  if (tweenDur > 0) {
-    return Math.max(
-      0,
-      Math.min(100, Math.round(((currentTime - tweenPos) / tweenDur) * 1000) / 10),
-    );
-  }
-  const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
-  const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
-  return elDuration > 0
-    ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
-    : 0;
-}
-
 function pickBestAnimation(
   animations: GsapAnimation[],
   selector: string | null,
@@ -78,12 +62,6 @@ function pickBestAnimation(
   return scored[0]?.anim;
 }
 
-function selectorFor(selection: DomEditSelection): string | null {
-  if (selection.id) return `#${selection.id}`;
-  if (selection.selector) return selection.selector;
-  return null;
-}
-
 export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
   const {
     selectedGsapAnimations,
@@ -102,7 +80,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
       if (!gsapCommitMutation) return;
 
       const iframe = previewIframeRef.current;
-      const selector = selectorFor(selection);
+      const selector = selectorFromSelection(selection);
 
       let anim: GsapAnimation | undefined = pickBestAnimation(
         selectedGsapAnimations,
@@ -132,7 +110,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         );
       }
 
-      const pct = computePercentage(selection, anim);
+      const pct = computeElementPercentage(usePlayerStore.getState().currentTime, selection, anim);
 
       // Read all currently animated properties from runtime for backfill
       const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};