@hyperframes/studio 0.6.95 → 0.6.97

package/src/hooks/usePreviewPersistence.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from "react";
+import { useCallback, useRef, useState } from "react";
 import { useMountEffect } from "./useMountEffect";
 import {
   installStudioManualEditSeekReapply,
@@ -7,6 +7,8 @@ import {
 } from "../components/editor/manualEdits";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import type { EditHistoryKind } from "../utils/editHistory";
+import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 
 // ── Types ──
 
@@ -35,11 +37,51 @@ interface UsePreviewPersistenceParams {
   reloadPreview: () => void;
 }
 
+function readIframeDocument(iframe: HTMLIFrameElement): Document | null {
+  try {
+    return iframe.contentDocument;
+  } catch {
+    return null;
+  }
+}
+
+function installManualEditReapply(iframe: HTMLIFrameElement): void {
+  const reapply = () => {
+    const doc = readIframeDocument(iframe);
+    if (doc) reapplyPositionEditsAfterSeek(doc);
+  };
+  const install = () => {
+    reapply();
+    if (iframe.contentWindow) installStudioManualEditSeekReapply(iframe.contentWindow, reapply);
+  };
+  const win = iframe.contentWindow;
+  install();
+  win?.requestAnimationFrame?.(install);
+  for (const delayMs of [80, 250, 500, 1000, 2000]) {
+    win?.setTimeout?.(install, delayMs);
+  }
+}
+
+function shouldReloadForStudioFileChange(
+  payload: unknown,
+  pendingTimelineEditPathRef: React.MutableRefObject<Set<string>> | undefined,
+  domEditSaveTimestampRef: React.MutableRefObject<number>,
+): boolean {
+  const changedPath = readStudioFileChangePath(payload);
+  if (!changedPath) return false;
+  const pendingTimelinePaths = pendingTimelineEditPathRef?.current;
+  if (pendingTimelinePaths?.has(changedPath)) {
+    pendingTimelinePaths.delete(changedPath);
+    return false;
+  }
+  return Date.now() - domEditSaveTimestampRef.current >= 4000;
+}
+
 // ── Hook ──
 
 export function usePreviewPersistence({
   projectId,
-  showToast: _showToast,
+  showToast,
   readOptionalProjectFile: _readOptionalProjectFile,
   writeProjectFile: _writeProjectFile,
   recordEdit: _recordEdit,
@@ -49,16 +91,38 @@ export function usePreviewPersistence({
   reloadPreview,
   pendingTimelineEditPathRef,
 }: UsePreviewPersistenceParams) {
-  void _showToast;
   void _recordEdit;
   void _activeCompPathRef;
 
+  const [domEditSaveQueuePaused, setDomEditSaveQueuePaused] = useState<string | null>(null);
+
   const domTextCommitVersionRef = useRef(0);
-  const domEditSaveQueueRef = useRef(Promise.resolve());
+  const showToastRef = useRef(showToast);
+  showToastRef.current = showToast;
+  const domEditSaveQueueRef = useRef<ReturnType<typeof createDomEditSaveQueue> | null>(null);
   const applyStudioManualEditsToPreviewRef = useRef<
     (iframe?: HTMLIFrameElement | null) => Promise<void>
   >(async () => {});
 
+  if (!domEditSaveQueueRef.current) {
+    domEditSaveQueueRef.current = createDomEditSaveQueue({
+      onOpen: (event) => {
+        const message = "Auto-save is paused. Check your connection.";
+        setDomEditSaveQueuePaused(message);
+        showToastRef.current(message, "error");
+        trackStudioEvent("save_queue_paused", {
+          source: "dom_edit",
+          error_message: event.errorMessage,
+          status_code: event.statusCode,
+          consecutive_failures: event.consecutiveFailures,
+        });
+      },
+      onReset: () => {
+        setDomEditSaveQueuePaused(null);
+      },
+    });
+  }
+
   // Keep a ref to the latest projectId so async save callbacks always read the
   // current value, even when the callback was captured in a stale closure.
   const projectIdRef = useRef(projectId);
@@ -67,55 +131,30 @@ export function usePreviewPersistence({
   // ── Queue / drain helpers ──
 
   const queueDomEditSave = useCallback((save: () => Promise<void>) => {
-    const queuedSave = domEditSaveQueueRef.current.catch(() => undefined).then(save);
-    domEditSaveQueueRef.current = queuedSave.then(
-      () => undefined,
-      () => undefined,
-    );
-    return queuedSave;
+    return domEditSaveQueueRef.current?.enqueue(save) ?? save();
   }, []);
 
   const waitForPendingDomEditSaves = useCallback(async () => {
-    await domEditSaveQueueRef.current.catch(() => undefined);
+    await domEditSaveQueueRef.current?.waitForIdle();
+  }, []);
+
+  const resetDomEditSaveQueueBreaker = useCallback(() => {
+    domEditSaveQueueRef.current?.reset();
+    setDomEditSaveQueuePaused(null);
   }, []);
 
+  useMountEffect(() => () => {
+    domEditSaveQueueRef.current?.destroy();
+  });
+
   // ── Apply manual edits (HTML-baked — install seek hooks) ──
   // reapplyPositionEditsAfterSeek now also handles motion reapply from DOM attributes.
 
   const applyCurrentStudioManualEditsToPreview = useCallback(
     (iframe: HTMLIFrameElement | null = previewIframeRef.current) => {
       if (!iframe) return;
-      let doc: Document | null = null;
-      try {
-        doc = iframe.contentDocument;
-      } catch {
-        return;
-      }
-      if (!doc) return;
-
-      const reapply = () => {
-        let d: Document | null = null;
-        try {
-          d = iframe.contentDocument;
-        } catch {
-          return;
-        }
-        if (d) reapplyPositionEditsAfterSeek(d);
-      };
-
-      const install = () => {
-        reapply();
-        if (iframe.contentWindow) installStudioManualEditSeekReapply(iframe.contentWindow, reapply);
-      };
-
-      const win = iframe.contentWindow;
-      install();
-      win?.requestAnimationFrame?.(install);
-      win?.setTimeout?.(install, 80);
-      win?.setTimeout?.(install, 250);
-      win?.setTimeout?.(install, 500);
-      win?.setTimeout?.(install, 1000);
-      win?.setTimeout?.(install, 2000);
+      if (!readIframeDocument(iframe)) return;
+      installManualEditReapply(iframe);
     },
     [previewIframeRef],
   );
@@ -165,16 +204,14 @@ export function usePreviewPersistence({
   // ── Listen for external file changes (HMR / SSE) ──
   useMountEffect(() => {
     const handler = (payload?: unknown) => {
-      const changedPath = readStudioFileChangePath(payload);
-      if (!changedPath) return;
-      const recentDomEditSave = Date.now() - domEditSaveTimestampRef.current < 4000;
-      if (pendingTimelineEditPathRef?.current.has(changedPath)) {
-        pendingTimelineEditPathRef.current.delete(changedPath);
-        return;
-      }
-      if (!recentDomEditSave) {
+      if (
+        shouldReloadForStudioFileChange(
+          payload,
+          pendingTimelineEditPathRef,
+          domEditSaveTimestampRef,
+        )
+      )
         reloadPreview();
-      }
     };
     if (import.meta.hot) {
       import.meta.hot.on("hf:file-change", handler);
@@ -192,6 +229,8 @@ export function usePreviewPersistence({
     applyStudioManualEditsToPreviewRef,
     queueDomEditSave,
     waitForPendingDomEditSaves,
+    domEditSaveQueuePaused,
+    resetDomEditSaveQueueBreaker,
     applyCurrentStudioManualEditsToPreview,
     applyStudioManualEditsToPreview,
     syncHistoryPreviewAfterApply,

package/src/hooks/useSafeGsapCommitMutation.ts

@@ -0,0 +1,66 @@
+import { useCallback } from "react";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { getStudioSaveErrorMessage, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+
+type CommitMutationOptions = {
+  label: string;
+  coalesceKey?: string;
+  softReload?: boolean;
+  skipReload?: boolean;
+  beforeReload?: () => void;
+};
+
+type CommitMutation = (
+  selection: DomEditSelection,
+  mutation: Record<string, unknown>,
+  options: CommitMutationOptions,
+) => Promise<void>;
+
+type TrackGsapSaveFailure = (
+  error: unknown,
+  selection: DomEditSelection,
+  mutation: Record<string, unknown>,
+  label?: string,
+) => void;
+
+function getGsapMutationType(mutation: Record<string, unknown>): string {
+  return typeof mutation.type === "string" ? mutation.type : "gsap";
+}
+
+export function useGsapSaveFailureTelemetry(activeCompPath: string | null): TrackGsapSaveFailure {
+  return useCallback(
+    (error, selection, mutation, label) => {
+      trackStudioSaveFailure({
+        source: "gsap_commit",
+        error,
+        filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
+        mutationType: getGsapMutationType(mutation),
+        label,
+        targetId: selection.id,
+        targetSelector: selection.selector,
+        targetSourceFile: selection.sourceFile,
+      });
+    },
+    [activeCompPath],
+  );
+}
+
+export function useSafeGsapCommitMutation(
+  commitMutation: CommitMutation,
+  trackGsapSaveFailure: TrackGsapSaveFailure,
+  showToast?: (message: string, tone?: "error" | "info") => void,
+) {
+  return useCallback(
+    (
+      selection: DomEditSelection,
+      mutation: Record<string, unknown>,
+      options: CommitMutationOptions,
+    ) => {
+      void commitMutation(selection, mutation, options).catch((error) => {
+        trackGsapSaveFailure(error, selection, mutation, options.label);
+        showToast?.(`Couldn't save animation: ${getStudioSaveErrorMessage(error)}`, "error");
+      });
+    },
+    [commitMutation, trackGsapSaveFailure, showToast],
+  );
+}

package/src/hooks/useStudioContextValue.ts

@@ -1,11 +1,6 @@
 import { useCallback, useMemo, useRef, useState, type DragEvent } from "react";
-import {
-  STUDIO_INSPECTOR_PANELS_ENABLED,
-  STUDIO_MOTION_PANEL_ENABLED,
-} from "../components/editor/manualEditingAvailability";
-import { readStudioMotionFromElement } from "../components/editor/studioMotion";
+import { STUDIO_INSPECTOR_PANELS_ENABLED } from "../components/editor/manualEditingAvailability";
 import type { StudioContextValue } from "../contexts/StudioContext";
-import type { DomEditSelection } from "../components/editor/domEditing";
 
 interface StudioContextInput {
   projectId: string;
@@ -66,10 +61,8 @@ export function buildStudioContextValue(input: StudioContextInput): StudioContex
 }
 
 export interface InspectorState {
-  selectedStudioMotion: ReturnType<typeof readStudioMotionFromElement> | null;
   layersPanelActive: boolean;
   designPanelActive: boolean;
-  motionPanelActive: boolean;
   inspectorPanelActive: boolean;
   inspectorButtonActive: boolean;
   shouldShowSelectedDomBounds: boolean;
@@ -79,32 +72,23 @@ export function useInspectorState(
   rightPanelTab: string,
   rightCollapsed: boolean,
   isPlaying: boolean,
-  domEditSelection: DomEditSelection | null,
   isGestureRecording?: boolean,
 ): InspectorState {
   // fallow-ignore-next-line complexity
   return useMemo(() => {
-    const selectedStudioMotion =
-      STUDIO_INSPECTOR_PANELS_ENABLED && domEditSelection
-        ? readStudioMotionFromElement(domEditSelection.element)
-        : null;
     const layersPanelActive = STUDIO_INSPECTOR_PANELS_ENABLED && rightPanelTab === "layers";
     const designPanelActive = STUDIO_INSPECTOR_PANELS_ENABLED && rightPanelTab === "design";
-    const motionPanelActive =
-      STUDIO_INSPECTOR_PANELS_ENABLED && STUDIO_MOTION_PANEL_ENABLED && rightPanelTab === "motion";
-    const inspectorPanelActive = layersPanelActive || designPanelActive || motionPanelActive;
+    const inspectorPanelActive = layersPanelActive || designPanelActive;
     return {
-      selectedStudioMotion,
       layersPanelActive,
       designPanelActive,
-      motionPanelActive,
       inspectorPanelActive,
       inspectorButtonActive:
         STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive,
       shouldShowSelectedDomBounds:
         inspectorPanelActive && !rightCollapsed && !isPlaying && !isGestureRecording,
     };
-  }, [rightPanelTab, rightCollapsed, isPlaying, domEditSelection, isGestureRecording]);
+  }, [rightPanelTab, rightCollapsed, isPlaying, isGestureRecording]);
 }
 
 // fallow-ignore-next-line complexity

package/src/player/hooks/useTimelinePlayer.ts

@@ -22,12 +22,14 @@ export {
   shouldIgnorePlaybackShortcutTarget,
 } from "../lib/playbackShortcuts";
 
-import type { PlaybackAdapter, RuntimePlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
+import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
 import {
   getAdapterDuration,
   wrapTimeline,
-  createStaticSeekPlaybackAdapter,
   getDefaultStaticSeekPlaybackClock,
+  releaseStaticSeekCache,
+  resolveStaticSeekFallback,
+  type StaticSeekCacheEntry,
 } from "../lib/playbackAdapter";
 import {
   readTimelineDurationFromDocument,
@@ -53,11 +55,8 @@ export function useTimelinePlayer() {
   const shuttleSpeedIndexRef = useRef(0);
   const iframeShortcutCleanupRef = useRef<(() => void) | null>(null);
   const lastTimelineMessageRef = useRef<number>(0);
-  const staticSeekAdapterRef = useRef<{
-    player: RuntimePlaybackAdapter | PlaybackAdapter;
-    duration: number;
-    adapter: PlaybackAdapter;
-  } | null>(null);
+  const staticSeekAdapterRef = useRef<StaticSeekCacheEntry | null>(null);
+  const staticSeekWarnedRef = useRef(false);
 
   const { setIsPlaying, setCurrentTime, setDuration, setTimelineReady, setElements } =
     usePlayerStore.getState();
@@ -141,6 +140,7 @@ export function useTimelinePlayer() {
       const adapterDur = getAdapterDuration(playerAdapter);
 
       if (adapterDur > 0 && docDuration <= adapterDur) {
+        releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
         return playerAdapter;
       }
 
@@ -148,24 +148,28 @@ export function useTimelinePlayer() {
       if (win.__timeline) {
         const adapter = wrapTimeline(win.__timeline);
         const dur = getAdapterDuration(adapter);
-        if (dur > 0 && docDuration <= dur) return adapter;
+        if (dur > 0 && docDuration <= dur) {
+          releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
+          return adapter;
+        }
         if (dur > 0) timelineAdapter ??= adapter;
       }
 
       if (win.__timelines) {
         const keys = Object.keys(win.__timelines);
         if (keys.length > 0) {
-          // Resolve the root composition id from the DOM — the outermost
-          // `[data-composition-id]` element is the master. Without this,
-          // Object.keys() order would let a sub-composition's timeline
-          // hijack play/pause/seek and the duration readout.
+          // Resolve the root composition id from the DOM — the outermost [data-composition-id]
+          // is the master; otherwise Object.keys() order lets a sub-composition hijack transport.
           const rootId = iframe?.contentDocument
             ?.querySelector("[data-composition-id]")
             ?.getAttribute("data-composition-id");
           const key = rootId && rootId in win.__timelines ? rootId : keys[keys.length - 1];
           const adapter = wrapTimeline(win.__timelines[key]);
           const dur = getAdapterDuration(adapter);
-          if (dur > 0 && docDuration <= dur) return adapter;
+          if (dur > 0 && docDuration <= dur) {
+            releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
+            return adapter;
+          }
           if (dur > 0) timelineAdapter ??= adapter;
         }
       }
@@ -184,23 +188,15 @@ export function useTimelinePlayer() {
         effectiveDuration > 0 &&
         ("renderSeek" in bestAdapter || typeof bestAdapter.seek === "function")
       ) {
-        const cached = staticSeekAdapterRef.current;
-        if (cached?.player === bestAdapter && cached.duration === effectiveDuration) {
-          return cached.adapter;
-        }
-        cached?.adapter.pause();
-        const adapter = createStaticSeekPlaybackAdapter(
+        return resolveStaticSeekFallback({
+          cache: staticSeekAdapterRef,
+          warned: staticSeekWarnedRef,
           bestAdapter,
           effectiveDuration,
-          getDefaultStaticSeekPlaybackClock(win),
-          () => usePlayerStore.getState().playbackRate,
-        );
-        staticSeekAdapterRef.current = {
-          player: bestAdapter,
-          duration: effectiveDuration,
-          adapter,
-        };
-        return adapter;
+          docDuration,
+          clock: getDefaultStaticSeekPlaybackClock(win),
+          getPlaybackRate: () => usePlayerStore.getState().playbackRate,
+        });
       }
 
       return bestAdapter;
@@ -561,6 +557,7 @@ export function useTimelinePlayer() {
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       stopRAFLoop();
       stopReverseLoop();
+      releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
     };
   });

package/src/player/lib/playbackAdapter.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it, vi } from "vitest";
-import { createStaticSeekPlaybackAdapter, wrapTimeline } from "./playbackAdapter";
+import {
+  createStaticSeekPlaybackAdapter,
+  wrapTimeline,
+  resolveStaticSeekFallback,
+  releaseStaticSeekCache,
+  type StaticSeekCacheEntry,
+} from "./playbackAdapter";
 import type {
   RuntimePlaybackAdapter,
   StaticSeekPlaybackClock,
@@ -211,3 +217,82 @@ describe("createStaticSeekPlaybackAdapter seek keepPlaying option", () => {
     expect(adapter.isPlaying()).toBe(false);
   });
 });
+
+describe("static-seek fallback cache (resolveStaticSeekFallback / releaseStaticSeekCache)", () => {
+  function makeClock(): StaticSeekPlaybackClock {
+    return {
+      now: () => 0,
+      requestAnimationFrame: () => 0,
+      cancelAnimationFrame: () => {},
+    };
+  }
+
+  function makePlayer() {
+    return { getTime: () => 0, renderSeek: vi.fn() };
+  }
+
+  function resolve(
+    cache: { current: StaticSeekCacheEntry | null },
+    warned: { current: boolean },
+    player: ReturnType<typeof makePlayer>,
+    duration: number,
+  ) {
+    return resolveStaticSeekFallback({
+      cache,
+      warned,
+      bestAdapter: player as unknown as RuntimePlaybackAdapter,
+      effectiveDuration: duration,
+      docDuration: duration,
+      clock: makeClock(),
+      getPlaybackRate: () => 1,
+    });
+  }
+
+  it("warns once per downgrade streak and re-arms after release", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const cache: { current: StaticSeekCacheEntry | null } = { current: null };
+    const warned = { current: false };
+    const player = makePlayer();
+
+    resolve(cache, warned, player, 10);
+    resolve(cache, warned, player, 11); // cache miss (new duration) — must not warn again
+    expect(warn).toHaveBeenCalledTimes(1);
+
+    releaseStaticSeekCache(cache, warned);
+    resolve(cache, warned, player, 12);
+    expect(warn).toHaveBeenCalledTimes(2);
+    warn.mockRestore();
+  });
+
+  it("returns the cached adapter for the same player and duration", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const cache: { current: StaticSeekCacheEntry | null } = { current: null };
+    const warned = { current: false };
+    const player = makePlayer();
+
+    const first = resolve(cache, warned, player, 10);
+    const second = resolve(cache, warned, player, 10);
+    expect(second).toBe(first);
+    warn.mockRestore();
+  });
+
+  it("pauses the replaced adapter on cache miss and the cached adapter on release", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const cache: { current: StaticSeekCacheEntry | null } = { current: null };
+    const warned = { current: false };
+    const player = makePlayer();
+
+    const first = resolve(cache, warned, player, 10);
+    first.play();
+    expect(first.isPlaying()).toBe(true);
+    const second = resolve(cache, warned, player, 20);
+    expect(first.isPlaying()).toBe(false);
+
+    second.play();
+    expect(second.isPlaying()).toBe(true);
+    releaseStaticSeekCache(cache, warned);
+    expect(second.isPlaying()).toBe(false);
+    expect(cache.current).toBeNull();
+    vi.restoreAllMocks();
+  });
+});

package/src/player/lib/playbackAdapter.ts

@@ -134,6 +134,68 @@ export function createStaticSeekPlaybackAdapter(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Static-seek fallback cache
+// ---------------------------------------------------------------------------
+
+export type StaticSeekCacheEntry = {
+  player: RuntimePlaybackAdapter | PlaybackAdapter;
+  duration: number;
+  adapter: PlaybackAdapter;
+};
+
+type StaticSeekCacheRef = { current: StaticSeekCacheEntry | null };
+type WarnedRef = { current: boolean };
+
+/**
+ * Pause and drop the cached static-seek adapter. Must be called whenever
+ * adapter selection switches to a native adapter — a cached static-seek
+ * adapter that was mid-play keeps its private rAF loop seeking the player
+ * forever otherwise, fighting the native transport. Also re-arms the
+ * downgrade warning so a later re-downgrade is surfaced again.
+ */
+export function releaseStaticSeekCache(cache: StaticSeekCacheRef, warned: WarnedRef): void {
+  cache.current?.adapter.pause();
+  cache.current = null;
+  warned.current = false;
+}
+
+/**
+ * Resolve (with caching) the seek-driven fallback adapter. Warns once per
+ * downgrade streak: seek-driven playback never starts media elements or
+ * WebAudio, so without the warning the downgrade silently loses audio.
+ */
+export function resolveStaticSeekFallback(opts: {
+  cache: StaticSeekCacheRef;
+  warned: WarnedRef;
+  bestAdapter: RuntimePlaybackAdapter | PlaybackAdapter;
+  effectiveDuration: number;
+  docDuration: number;
+  clock: StaticSeekPlaybackClock;
+  getPlaybackRate: () => number;
+}): PlaybackAdapter {
+  const { cache, warned, bestAdapter, effectiveDuration, docDuration } = opts;
+  const cached = cache.current;
+  if (cached?.player === bestAdapter && cached.duration === effectiveDuration) {
+    return cached.adapter;
+  }
+  cached?.adapter.pause();
+  if (!warned.current) {
+    warned.current = true;
+    console.warn(
+      `[useTimelinePlayer] Selected adapter duration (${getAdapterDuration(bestAdapter)}s) does not cover the document duration (${docDuration}s); falling back to seek-driven playback, which never starts media elements or WebAudio. Audio will not play in preview — extend the GSAP timeline to cover the declared data-duration.`,
+    );
+  }
+  const adapter = createStaticSeekPlaybackAdapter(
+    bestAdapter,
+    effectiveDuration,
+    opts.clock,
+    opts.getPlaybackRate,
+  );
+  cache.current = { player: bestAdapter, duration: effectiveDuration, adapter };
+  return adapter;
+}
+
 // ---------------------------------------------------------------------------
 // GSAP timeline wrapper
 // ---------------------------------------------------------------------------