@hyperframes/studio 0.6.97 → 0.6.99

package/src/hooks/useDomGeometryCommits.ts

@@ -0,0 +1,181 @@
+import { useCallback } from "react";
+import { STUDIO_GSAP_DRAG_INTERCEPT_ENABLED } from "../components/editor/manualEditingAvailability";
+import { getDomEditTargetKey, type DomEditSelection } from "../components/editor/domEditing";
+import {
+  applyStudioPathOffset,
+  applyStudioBoxSize,
+  applyStudioRotation,
+  clearStudioPathOffset,
+  clearStudioBoxSize,
+  clearStudioRotation,
+} from "../components/editor/manualEdits";
+import {
+  buildPathOffsetPatches,
+  buildBoxSizePatches,
+  buildRotationPatches,
+  buildClearPathOffsetPatches,
+  buildClearBoxSizePatches,
+  buildClearRotationPatches,
+} from "../components/editor/manualEditsDomPatches";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+export const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
+  "This element is GSAP-animated — dragging via CSS would corrupt keyframes";
+
+// ── Helpers ──
+
+type TimelineLike = { getChildren?: (nested: boolean) => Array<{ targets?: () => Element[] }> };
+
+// fallow-ignore-next-line complexity
+function isElementGsapTargeted(iframe: HTMLIFrameElement | null, element: HTMLElement): boolean {
+  // When the GSAP drag intercept is disabled for debugging, treat every
+  // element as un-targeted so commits take the plain CSS persist path.
+  if (!STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) return false;
+  if (!iframe?.contentWindow) return false;
+  let timelines: Record<string, TimelineLike> | undefined;
+  try {
+    timelines = (iframe.contentWindow as Window & { __timelines?: Record<string, TimelineLike> })
+      .__timelines;
+  } catch {
+    return false;
+  }
+  if (!timelines) return false;
+  const id = element.id;
+  for (const tl of Object.values(timelines)) {
+    if (!tl?.getChildren) continue;
+    try {
+      for (const child of tl.getChildren(true)) {
+        if (!child.targets) continue;
+        for (const t of child.targets()) {
+          if (t === element || (id && t.id === id)) return true;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
+// ── Hook ──
+
+interface UseDomGeometryCommitsParams {
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  commitPositionPatchToHtml: (
+    selection: DomEditSelection,
+    patches: PatchOperation[],
+    options: { label: string; coalesceKey: string; skipRefresh?: boolean },
+  ) => Promise<void>;
+}
+
+export function useDomGeometryCommits({
+  previewIframeRef,
+  showToast,
+  commitPositionPatchToHtml,
+}: UseDomGeometryCommitsParams) {
+  const handleDomPathOffsetCommit = useCallback(
+    (selection: DomEditSelection, next: { x: number; y: number }) => {
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+        showToast(error.message, "error");
+        return Promise.reject(error);
+      }
+      applyStudioPathOffset(selection.element, next);
+      return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
+        label: "Move layer",
+        coalesceKey: `path-offset:${getDomEditTargetKey(selection)}`,
+      });
+    },
+    [commitPositionPatchToHtml, previewIframeRef, showToast],
+  );
+
+  const handleDomGroupPathOffsetCommit = useCallback(
+    (updates: DomEditGroupPathOffsetCommit[]) => {
+      if (updates.length === 0) return Promise.resolve();
+      const blockedUpdate = updates.find(({ selection }) =>
+        isElementGsapTargeted(previewIframeRef.current, selection.element),
+      );
+      if (blockedUpdate) {
+        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+        showToast(error.message, "error");
+        return Promise.reject(error);
+      }
+      const coalesceKey = updates
+        .map((u) => getDomEditTargetKey(u.selection))
+        .sort()
+        .join(":");
+      const saves = updates.map(({ selection, next }) => {
+        applyStudioPathOffset(selection.element, next);
+        return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
+          label: `Move ${updates.length} layers`,
+          coalesceKey: `group-path-offset:${coalesceKey}`,
+        });
+      });
+      return Promise.all(saves).then(() => undefined);
+    },
+    [commitPositionPatchToHtml, previewIframeRef, showToast],
+  );
+
+  const handleDomBoxSizeCommit = useCallback(
+    (selection: DomEditSelection, next: { width: number; height: number }) => {
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+        showToast(error.message, "error");
+        return Promise.reject(error);
+      }
+      applyStudioBoxSize(selection.element, next);
+      return commitPositionPatchToHtml(selection, buildBoxSizePatches(selection.element), {
+        label: "Resize layer box",
+        coalesceKey: `box-size:${getDomEditTargetKey(selection)}`,
+      });
+    },
+    [commitPositionPatchToHtml, previewIframeRef, showToast],
+  );
+
+  const handleDomRotationCommit = useCallback(
+    (selection: DomEditSelection, next: { angle: number }) => {
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+        showToast(error.message, "error");
+        return Promise.reject(error);
+      }
+      applyStudioRotation(selection.element, next);
+      return commitPositionPatchToHtml(selection, buildRotationPatches(selection.element), {
+        label: "Rotate layer",
+        coalesceKey: `rotation:${getDomEditTargetKey(selection)}`,
+      });
+    },
+    [commitPositionPatchToHtml, previewIframeRef, showToast],
+  );
+
+  const handleDomManualEditsReset = useCallback(
+    (selection: DomEditSelection) => {
+      const element = selection.element;
+      const clearPatches = [
+        ...buildClearPathOffsetPatches(element),
+        ...buildClearBoxSizePatches(element),
+        ...buildClearRotationPatches(element),
+      ];
+      clearStudioPathOffset(element);
+      clearStudioBoxSize(element);
+      clearStudioRotation(element);
+      // skipRefresh:false triggers reloadPreview() which re-syncs selection on load
+      void commitPositionPatchToHtml(selection, clearPatches, {
+        label: "Reset layer edits",
+        coalesceKey: `manual-reset:${getDomEditTargetKey(selection)}`,
+        skipRefresh: false,
+      }).catch(() => undefined);
+    },
+    [commitPositionPatchToHtml],
+  );
+
+  return {
+    handleDomPathOffsetCommit,
+    handleDomGroupPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleDomManualEditsReset,
+  };
+}

package/src/hooks/useDomSelection.ts

@@ -389,47 +389,30 @@ export function useDomSelection({
 
   // ── Effects ──
 
-  // Clear hover on caption mode change
-  // eslint-disable-next-line no-restricted-syntax
-  useEffect(() => {
-    if (captionEditMode) updateDomEditHoverSelection(null);
-  }, [captionEditMode, updateDomEditHoverSelection]);
-
-  // Clear hover on composition/project/preview change
+  // Clear hover unconditionally on composition/project/preview change
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
     updateDomEditHoverSelection(null);
   }, [activeCompPath, projectId, previewIframe, refreshKey, updateDomEditHoverSelection]);
 
-  // Clear hover when matching selection
+  // Clear hover conditionally (caption mode, matches selection, disconnected element)
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
     if (!domEditHoverSelection) return;
-    const hoverMatchesSelection = domEditSelectionsTargetSame(
-      domEditHoverSelection,
-      domEditSelection,
-    );
-    const hoverMatchesGroup = domEditSelectionInGroup(
-      domEditGroupSelections,
-      domEditHoverSelection,
-    );
-    if (!hoverMatchesSelection && !hoverMatchesGroup) return;
-    updateDomEditHoverSelection(null);
+    const shouldClear =
+      captionEditMode ||
+      domEditSelectionsTargetSame(domEditHoverSelection, domEditSelection) ||
+      domEditSelectionInGroup(domEditGroupSelections, domEditHoverSelection) ||
+      !domEditHoverSelection.element.isConnected;
+    if (shouldClear) updateDomEditHoverSelection(null);
   }, [
-    domEditGroupSelections,
+    captionEditMode,
     domEditHoverSelection,
     domEditSelection,
+    domEditGroupSelections,
     updateDomEditHoverSelection,
   ]);
 
-  // Clear hover when element disconnected
-  // eslint-disable-next-line no-restricted-syntax
-  useEffect(() => {
-    if (!domEditHoverSelection) return;
-    if (domEditHoverSelection.element.isConnected) return;
-    updateDomEditHoverSelection(null);
-  }, [domEditHoverSelection, updateDomEditHoverSelection]);
-
   // Clear selection on caption mode change
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {

package/src/hooks/useEditorSave.ts

@@ -0,0 +1,82 @@
+import { useCallback, useRef } from "react";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import type { EditHistoryKind } from "../utils/editHistory";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, { before: string; after: string }>;
+}
+
+interface UseEditorSaveOptions {
+  editingPathRef: React.RefObject<string | undefined>;
+  projectIdRef: React.RefObject<string | null>;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
+}
+
+export function useEditorSave({
+  editingPathRef,
+  projectIdRef,
+  readProjectFile,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  setRefreshKey,
+}: UseEditorSaveOptions) {
+  const saveRafRef = useRef<number | null>(null);
+  const refreshRafRef = useRef<number | null>(null);
+
+  const handleContentChange = useCallback(
+    (content: string) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const path = editingPathRef.current;
+      if (!path) return;
+
+      if (saveRafRef.current != null) cancelAnimationFrame(saveRafRef.current);
+      saveRafRef.current = requestAnimationFrame(() => {
+        domEditSaveTimestampRef.current = Date.now();
+        saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Edit source",
+          kind: "source",
+          coalesceKey: `source:${path}`,
+          files: { [path]: content },
+          readFile: readProjectFile,
+          writeFile: writeProjectFile,
+          recordEdit,
+        })
+          .then(() => {
+            if (refreshRafRef.current != null) cancelAnimationFrame(refreshRafRef.current);
+            refreshRafRef.current = requestAnimationFrame(() => setRefreshKey((k) => k + 1));
+          })
+          .catch((error) => {
+            trackStudioEvent("save_failure", {
+              source: "code_editor",
+              error_message: error instanceof Error ? error.message : "unknown",
+            });
+          });
+      });
+    },
+    [
+      domEditSaveTimestampRef,
+      editingPathRef,
+      projectIdRef,
+      readProjectFile,
+      recordEdit,
+      setRefreshKey,
+      writeProjectFile,
+    ],
+  );
+
+  return {
+    saveRafRef,
+    handleContentChange,
+  };
+}

package/src/hooks/useElementLifecycleOps.ts

@@ -0,0 +1,177 @@
+import { useCallback } from "react";
+import { usePlayerStore } from "../player";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import {
+  buildDomEditPatchTarget,
+  readHfId,
+  type DomEditSelection,
+} from "../components/editor/domEditing";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, { before: string; after: string }>;
+}
+
+interface UseElementLifecycleOpsParams {
+  activeCompPath: string | null;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
+  projectIdRef: React.MutableRefObject<string | null>;
+  reloadPreview: () => void;
+  clearDomSelection: () => void;
+  commitPositionPatchToHtml: (
+    selection: DomEditSelection,
+    patches: PatchOperation[],
+    options: { label: string; coalesceKey: string; skipRefresh?: boolean },
+  ) => Promise<void>;
+}
+
+export function useElementLifecycleOps({
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  domEditSaveTimestampRef,
+  editHistory,
+  projectIdRef,
+  reloadPreview,
+  clearDomSelection,
+  commitPositionPatchToHtml,
+}: UseElementLifecycleOpsParams) {
+  // fallow-ignore-next-line complexity
+  const handleDomEditElementDelete = useCallback(
+    // fallow-ignore-next-line complexity
+    async (selection: DomEditSelection) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const label = selection.label || selection.id || selection.selector || selection.tagName;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      try {
+        const response = await fetch(
+          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        );
+        if (!response.ok) {
+          throw await createStudioSaveHttpError(response, `Failed to read ${targetPath}`);
+        }
+
+        const data = (await response.json()) as { content?: string };
+        const originalContent = data.content;
+        if (typeof originalContent !== "string")
+          throw new Error(`Missing file contents for ${targetPath}`);
+
+        const patchTarget = buildDomEditPatchTarget(selection);
+        if (!patchTarget.id && !patchTarget.selector && !patchTarget.hfId) {
+          throw new Error("Selected element has no patchable target");
+        }
+
+        domEditSaveTimestampRef.current = Date.now();
+        const removeResponse = await fetch(
+          `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ target: patchTarget }),
+          },
+        );
+        if (!removeResponse.ok) {
+          throw await createStudioSaveHttpError(
+            removeResponse,
+            `Failed to delete element from ${targetPath}`,
+          );
+        }
+
+        const removeData = (await removeResponse.json()) as { changed?: boolean; content?: string };
+        const patchedContent =
+          typeof removeData.content === "string" ? removeData.content : originalContent;
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Delete element",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
+
+        clearDomSelection();
+        usePlayerStore.getState().setSelectedElementId(null);
+        reloadPreview();
+        showToast(`Deleted ${label}. Use Undo to restore it.`, "info");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to delete element";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      clearDomSelection,
+      domEditSaveTimestampRef,
+      editHistory.recordEdit,
+      projectIdRef,
+      reloadPreview,
+      showToast,
+      writeProjectFile,
+    ],
+  );
+
+  const handleDomZIndexReorderCommit = useCallback(
+    (
+      entries: Array<{
+        element: HTMLElement;
+        zIndex: number;
+        id?: string;
+        selector?: string;
+        selectorIndex?: number;
+        sourceFile: string;
+      }>,
+    ) => {
+      if (entries.length === 0) return;
+      const coalesceKey = `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        entry.element.style.zIndex = String(entry.zIndex);
+        const patches: Array<{ type: "inline-style"; property: string; value: string }> = [
+          { type: "inline-style", property: "z-index", value: String(entry.zIndex) },
+        ];
+        try {
+          const win = entry.element.ownerDocument?.defaultView;
+          if (win && win.getComputedStyle(entry.element).position === "static") {
+            entry.element.style.position = "relative";
+            patches.push({ type: "inline-style", property: "position", value: "relative" });
+          }
+        } catch {
+          /* cross-origin or detached — skip */
+        }
+        void commitPositionPatchToHtml(
+          {
+            element: entry.element,
+            id: entry.id ?? null,
+            hfId: readHfId(entry.element),
+            selector: entry.selector,
+            selectorIndex: entry.selectorIndex,
+            sourceFile: entry.sourceFile,
+          } as unknown as DomEditSelection,
+          patches,
+          {
+            label: "Reorder layers",
+            coalesceKey,
+            skipRefresh: i < entries.length - 1,
+          },
+        ).catch(() => undefined);
+      }
+    },
+    [commitPositionPatchToHtml],
+  );
+
+  return {
+    handleDomEditElementDelete,
+    handleDomZIndexReorderCommit,
+  };
+}

package/src/hooks/useEnableKeyframes.ts

@@ -12,6 +12,9 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
+import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
+import { POSITION_PROPS } from "./gsapRuntimeReaders";
+import { roundTo3 } from "../utils/rounding";
 
 export interface EnableKeyframesSession {
   domEditSelection: DomEditSelection | null;
@@ -52,12 +55,11 @@ function readElementPosition(
   const element = sel.element;
   if (!element?.isConnected || !gsap?.getProperty) return result;
 
-  const POSITION_PROPS = new Set(["x", "y", "xPercent", "yPercent"]);
   const props = anim ? Object.keys(anim.properties) : ["x", "y", "opacity"];
   for (const prop of props) {
     const val = Number(gsap.getProperty(element, prop));
     if (!Number.isFinite(val)) continue;
-    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);
   }
 
   return result;
@@ -75,13 +77,6 @@ async function fetchAnimationsForElement(sel: DomEditSelection): Promise<GsapAni
   });
 }
 
-function computePercentage(t: number, sel: DomEditSelection): number {
-  const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
-  const elDuration = Number.parseFloat(sel.dataAttributes?.duration ?? "1") || 1;
-  if (elDuration <= 0) return 0;
-  return Math.max(0, Math.min(100, Math.round(((t - elStart) / elDuration) * 1000) / 10));
-}
-
 // fallow-ignore-next-line complexity
 export function useEnableKeyframes(
   sessionRef: React.RefObject<EnableKeyframesSession | undefined>,
@@ -104,7 +99,7 @@ export function useEnableKeyframes(
     const flatAnim = anims.find((a) => !a.keyframes);
 
     if (kfAnim?.keyframes) {
-      const pct = computePercentage(t, sel);
+      const pct = computeElementPercentage(t, sel);
       const existing = kfAnim.keyframes.keyframes.find((k) => Math.abs(k.percentage - pct) <= 1);
       if (existing) {
         session.handleGsapRemoveKeyframe(kfAnim.id, existing.percentage);
@@ -120,17 +115,17 @@ export function useEnableKeyframes(
 
       await session.handleGsapConvertToKeyframes(flatAnim.id, hasPosition ? position : undefined);
 
-      const pct = computePercentage(t, sel);
+      const pct = computeElementPercentage(t, sel);
       if (pct > 1 && pct < 99 && hasPosition && session.handleGsapAddKeyframeBatch) {
         await session.handleGsapAddKeyframeBatch(flatAnim.id, pct, position);
         await session.handleGsapAddKeyframeBatch(flatAnim.id, 100, position);
       }
     } else {
       const position = readElementPosition(iframe, sel, null);
-      const pct = computePercentage(t, sel);
+      const pct = computeElementPercentage(t, sel);
       const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
       const elDuration = Number.parseFloat(sel.dataAttributes?.duration ?? "1") || 1;
-      const selector = sel.id ? `#${sel.id}` : sel.selector;
+      const selector = selectorFromSelection(sel);
 
       if (!selector) {
         session.handleGsapAddAnimation("to");
@@ -159,8 +154,8 @@ export function useEnableKeyframes(
           {
             type: "add-with-keyframes",
             targetSelector: selector,
-            position: Math.round(elStart * 1000) / 1000,
-            duration: Math.round(elDuration * 1000) / 1000,
+            position: roundTo3(elStart),
+            duration: roundTo3(elDuration),
             keyframes,
           },
           { label: "Enable keyframes", softReload: true },