@hyperframes/studio 0.8.24 → 0.8.26

package/src/hooks/useGsapSelectionHandlers.ts

@@ -200,8 +200,13 @@ export function useGsapSelectionHandlers({
   const handleGsapDeleteAnimation = useCallback(
     (animId: string, selectionOverride?: DomEditSelection | null) => {
       const sel = resolveWriteSelection(selectionOverride);
-      if (!sel) return;
-      observeGsapMutation(deleteGsapAnimation(sel, animId), sel, "delete", "Delete GSAP animation");
+      if (!sel) return Promise.resolve(false);
+      return observeGsapMutation(
+        deleteGsapAnimation(sel, animId),
+        sel,
+        "delete",
+        "Delete GSAP animation",
+      );
     },
     [resolveWriteSelection, deleteGsapAnimation, observeGsapMutation],
   );
@@ -222,20 +227,25 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapAddAnimation = useCallback(
-    (method: "to" | "from" | "set" | "fromTo") => {
-      if (!domEditSelection) return;
-      void addGsapAnimation(domEditSelection, method, usePlayerStore.getState().currentTime).catch(
-        (error) => {
-          trackGsapHandlerFailure(error, domEditSelection, "add", `Add GSAP ${method} animation`);
-        },
+    (method: "to" | "from" | "set" | "fromTo", selectionOverride?: DomEditSelection | null) => {
+      const selection = resolveWriteSelection(selectionOverride);
+      if (!selection) return Promise.resolve(false);
+      const landed = observeGsapMutation(
+        addGsapAnimation(selection, method, usePlayerStore.getState().currentTime),
+        selection,
+        "add",
+        `Add GSAP ${method} animation`,
       );
-      if (domEditSelection.element.hasAttribute("data-hf-studio-path-offset")) {
+      if (selection.element.hasAttribute("data-hf-studio-path-offset")) {
         // The reset owns rollback and the position commit already owns user and
         // telemetry reporting. This is only the fire-and-forget UI boundary.
-        void handleDomManualEditsReset(domEditSelection).catch(() => undefined);
+        void landed.then((didLand) => {
+          if (didLand) void handleDomManualEditsReset(selection).catch(() => undefined);
+        });
       }
+      return landed;
     },
-    [domEditSelection, addGsapAnimation, handleDomManualEditsReset, trackGsapHandlerFailure],
+    [resolveWriteSelection, addGsapAnimation, handleDomManualEditsReset, observeGsapMutation],
   );
 
   const handleGsapAddProperty = useCallback(

package/src/hooks/useRenderClipContent.test.ts

@@ -241,4 +241,31 @@ describe("useRenderClipContent", () => {
       });
     }
   });
+
+  it("forwards persisted content revision to mounted composition thumbnails", () => {
+    usePlayerStore.setState({
+      thumbnailMode: "adaptive",
+      timelineSessionEpoch: 7,
+      thumbnailContentRevision: 11,
+    });
+
+    const content = renderClipContent({
+      id: "nested",
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      compositionSrc: "compositions/nested.html",
+    });
+
+    expect(isValidElement(content)).toBe(true);
+    if (isValidElement(content)) {
+      expect(content.type).toBe(CompositionThumbnail);
+      expect(content.props).toMatchObject({
+        projectId: "my-project",
+        sessionEpoch: 7,
+        contentRevision: 11,
+      });
+    }
+  });
 });

package/src/hooks/useRenderClipContent.ts

@@ -110,6 +110,7 @@ export function useRenderClipContent({
   const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
   const effectiveMode = effectiveThumbnailMode(thumbnailMode);
   const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
+  const contentRevision = usePlayerStore((s) => s.thumbnailContentRevision);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
     // fallow-ignore-next-line complexity
@@ -153,6 +154,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -179,6 +181,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -232,6 +235,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
+          contentRevision,
           priority: context.priority,
           rich: context.rich,
         });
@@ -246,6 +250,7 @@ export function useRenderClipContent({
       effectiveTimelineDuration,
       effectiveMode,
       sessionEpoch,
+      contentRevision,
     ],
   );
 }

package/src/hooks/useStudioExternalFileChanges.ts

@@ -1,4 +1,5 @@
 import { useCallback, type MutableRefObject } from "react";
+import { usePlayerStore } from "../player/store/playerStore";
 import {
   deleteExternalConflictSnapshot,
   loadExternalConflictSnapshot,
@@ -48,6 +49,9 @@ export function useStudioExternalFileChanges({
 }: UseStudioExternalFileChangesOptions) {
   const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;
   const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;
+  const bumpThumbnailContentRevision = usePlayerStore(
+    (state) => state.bumpThumbnailContentRevision,
+  );
   const drainPendingChanges = useCallback(async () => {
     const source = await flushPendingSourceSave();
     if (source.status !== "clean") return source;
@@ -77,5 +81,6 @@ export function useStudioExternalFileChanges({
     readProjectFile: fileManager.readProjectFile,
     onUseExternalFile: fileManager.updateEditingFileContent,
     resetSaveQueues: resetDomEditSaveQueueBreaker,
+    onAcceptedPersistedFileChange: bumpThumbnailContentRevision,
   });
 }

package/src/player/components/CompositionThumbnail.test.ts

@@ -73,7 +73,7 @@ describe("buildCompositionThumbnailUrl", () => {
         origin: "http://localhost:3000",
       }),
     ).toBe(
-      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v3&selector=.card&selectorIndex=2",
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v3&revision=0&selector=.card&selectorIndex=2",
     );
   });
 
@@ -91,6 +91,16 @@ describe("buildCompositionThumbnailUrl", () => {
       "output=storyboard",
     );
   });
+
+  it("includes the persisted content revision in the cache identity", () => {
+    const url = buildCompositionThumbnailUrl({
+      previewUrl: "/api/projects/demo/preview",
+      origin: "http://localhost:3000",
+      contentRevision: 7,
+    });
+
+    expect(new URL(url).searchParams.get("revision")).toBe("7");
+  });
 });
 
 describe("CompositionThumbnail", () => {
@@ -148,4 +158,59 @@ describe("CompositionThumbnail", () => {
     expect(probe.src).toBe("");
     expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:composition-thumbnail");
   });
+
+  it("releases the old request and ignores its late result when persisted content changes", async () => {
+    const signals: AbortSignal[] = [];
+    const resolveFetches: Array<(response: Response) => void> = [];
+    globalThis.fetch = vi.fn((_url, init) => {
+      signals.push(init?.signal as AbortSignal);
+      return new Promise<Response>((resolve) => resolveFetches.push(resolve));
+    });
+    root = createRoot(host);
+
+    await act(async () => {
+      root!.render(
+        React.createElement(CompositionThumbnail, {
+          previewUrl: "/api/projects/demo/preview",
+          label: "",
+          labelColor: "#fff",
+          projectId: "demo",
+          contentRevision: 0,
+        }),
+      );
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    await act(async () => {
+      root!.render(
+        React.createElement(CompositionThumbnail, {
+          previewUrl: "/api/projects/demo/preview",
+          label: "",
+          labelColor: "#fff",
+          projectId: "demo",
+          contentRevision: 1,
+        }),
+      );
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+    expect(signals[0]?.aborted).toBe(true);
+    expect(signals[1]?.aborted).toBe(false);
+    expect((globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[1]?.[0]).toContain(
+      "revision=1",
+    );
+
+    await act(async () => {
+      resolveFetches[0]?.(new Response(new Blob(["stale"]), { status: 200 }));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(MockImage.instances).toHaveLength(0);
+
+    await act(async () => {
+      resolveFetches[1]?.(new Response(new Blob(["fresh"]), { status: 200 }));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(MockImage.instances).toHaveLength(1);
+    expect(MockImage.instances[0]?.src).toBe("blob:composition-thumbnail");
+  });
 });

package/src/player/components/CompositionThumbnail.tsx

@@ -17,6 +17,7 @@ interface CompositionThumbnailProps {
   height?: number;
   projectId?: string;
   sessionEpoch?: number;
+  contentRevision?: number;
   priority?: ThumbnailPriority;
   rich?: boolean;
 }
@@ -32,6 +33,7 @@ export function buildCompositionThumbnailUrl({
   selectorIndex,
   origin,
   output,
+  contentRevision = 0,
 }: {
   previewUrl: string;
   seekTime?: number;
@@ -46,6 +48,7 @@ export function buildCompositionThumbnailUrl({
    * high-density review size; `"source"` uses the composition's own dimensions.
    */
   output?: "source" | "storyboard";
+  contentRevision?: number;
 }): string {
   const thumbnailBase = previewUrl
     .replace("/preview/comp/", "/thumbnail/")
@@ -53,6 +56,7 @@ export function buildCompositionThumbnailUrl({
   const thumbnailUrl = new URL(thumbnailBase, origin);
   thumbnailUrl.searchParams.set("t", (seekTime + duration / 2).toFixed(2));
   thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  thumbnailUrl.searchParams.set("revision", String(contentRevision));
   if (output) thumbnailUrl.searchParams.set("output", output);
   if (selector) {
     thumbnailUrl.searchParams.set("selector", selector);
@@ -96,6 +100,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   duration = 5,
   projectId = previewUrl,
   sessionEpoch = 0,
+  contentRevision = 0,
   priority = "visible",
 }: CompositionThumbnailProps) {
   const [containerWidth, setContainerWidth] = useState(0);
@@ -107,6 +112,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     selector,
     selectorIndex,
     origin: window.location.origin,
+    contentRevision,
   });
   const request = useMemo(
     () => ({

package/src/player/hooks/timelineSyncHydration.ts

@@ -290,6 +290,15 @@ export function resolveReloadSeekTime(input: {
   return Math.min(target, input.duration);
 }
 
+type SeekablePreview = Pick<PlaybackAdapter, "seek">;
+
+/** Re-run the current frame even when the runtime already reports that time. */
+export function reseekPreviewAtTime(preview: SeekablePreview, time: number): void {
+  const target = Number.isFinite(time) && time > 0 ? time : 0;
+  preview.seek(target > 0.001 ? Math.max(0, target - 0.001) : 0.001);
+  preview.seek(target);
+}
+
 export function seekAdapterToRestorePoint(
   adapter: PlaybackAdapter,
   pendingSeekRef: { current: number | null },
@@ -303,8 +312,7 @@ export function seekAdapterToRestorePoint(
   });
   pendingSeekRef.current = null;
   if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
-  adapter.seek(startTime > 0.001 ? Math.max(0, startTime - 0.001) : 0.001);
-  adapter.seek(startTime);
+  reseekPreviewAtTime(adapter, startTime);
   return startTime;
 }
 

package/src/player/store/playerStore.test.ts

@@ -30,6 +30,30 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("thumbnail content revision", () => {
+    it("advances once per accepted persisted file event", () => {
+      const before = usePlayerStore.getState().thumbnailContentRevision;
+
+      usePlayerStore.getState().bumpThumbnailContentRevision();
+
+      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(before + 1);
+    });
+
+    it("remains monotonic across soft resets while project identity stays with the session epoch", () => {
+      const store = usePlayerStore.getState();
+      store.beginTimelineSession("project-a");
+      store.bumpThumbnailContentRevision();
+      const revision = usePlayerStore.getState().thumbnailContentRevision;
+      const firstEpoch = usePlayerStore.getState().timelineSessionEpoch;
+
+      store.reset();
+      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(revision);
+      store.beginTimelineSession("project-b");
+      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(revision);
+      expect(usePlayerStore.getState().timelineSessionEpoch).toBe(firstEpoch + 1);
+    });
+  });
+
   describe("expandedClipIds", () => {
     it("toggles clip membership", () => {
       const store = usePlayerStore.getState();

package/src/player/store/thumbnailSlice.ts

@@ -4,15 +4,21 @@ import { defaultThumbnailMode, type ThumbnailMode } from "../lib/thumbnailPolicy
 
 export interface ThumbnailSlice {
   thumbnailMode: ThumbnailMode;
+  /** Monotonic identity for persisted project content shown by mounted thumbnails. */
+  thumbnailContentRevision: number;
   setThumbnailMode: (mode: ThumbnailMode) => void;
+  bumpThumbnailContentRevision: () => void;
 }
 
 export function createThumbnailSlice(set: StoreApi<ThumbnailSlice>["setState"]): ThumbnailSlice {
   return {
     thumbnailMode: defaultThumbnailMode(readStudioUiPreferences().thumbnailMode),
+    thumbnailContentRevision: 0,
     setThumbnailMode: (mode) => {
       writeStudioUiPreferences({ thumbnailMode: mode });
       set({ thumbnailMode: mode });
     },
+    bumpThumbnailContentRevision: () =>
+      set((state) => ({ thumbnailContentRevision: state.thumbnailContentRevision + 1 })),
   };
 }

package/src/styles/studio.css

@@ -618,6 +618,185 @@ body {
   }
 }
 
+/* Receipt-driven WebMCP Topology Lens. Every animation is one-shot Studio
+   chrome; none of these nodes enter the composition iframe or rendered output. */
+.hf-topology-contour {
+  border: 1px solid rgba(60, 230, 172, 0.62);
+  box-shadow:
+    0 0 0 1px rgba(6, 227, 250, 0.08),
+    inset 0 0 18px rgba(60, 230, 172, 0.035);
+}
+
+.hf-topology-field::before,
+.hf-topology-contour::before,
+.hf-topology-target::before {
+  content: attr(data-topology-node);
+  position: absolute;
+  top: 2px;
+  left: 3px;
+  z-index: 2;
+  padding: 1px 3px;
+  border-radius: 2px;
+  background: rgba(5, 15, 12, 0.86);
+  color: rgb(90, 247, 193);
+  font:
+    600 7px/1.3 ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    monospace;
+  letter-spacing: 0.04em;
+  text-transform: lowercase;
+}
+
+.hf-topology-field {
+  z-index: 0;
+  border: 1px solid rgba(60, 230, 172, 0.28);
+  background: linear-gradient(
+    90deg,
+    rgba(60, 230, 172, 0.025),
+    rgba(60, 230, 172, 0.1) 68%,
+    rgba(6, 227, 250, 0.06)
+  );
+  box-shadow: inset 0 0 28px rgba(60, 230, 172, 0.05);
+}
+
+.hf-topology-target {
+  border: 1px solid rgba(60, 230, 172, 0.82);
+  box-shadow:
+    0 0 0 1px rgba(60, 230, 172, 0.14),
+    0 0 18px rgba(6, 227, 250, 0.09);
+}
+
+.hf-topology-scan {
+  background: linear-gradient(
+    90deg,
+    transparent,
+    rgba(60, 230, 172, 0.16) 55%,
+    rgba(230, 255, 247, 0.9)
+  );
+  clip-path: polygon(0 0, 100% 0, 72% 100%, 0 100%);
+}
+
+.hf-topology-seal {
+  filter: drop-shadow(0 0 6px rgba(60, 230, 172, 0.36));
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .hf-topology-contour {
+    animation: hf-topology-reveal 176ms cubic-bezier(0.77, 0, 0.175, 1) both;
+  }
+
+  .hf-topology-field[data-topology-phase="acquiring"] {
+    animation: hf-topology-reveal 240ms cubic-bezier(0.77, 0, 0.175, 1) both;
+  }
+
+  .hf-topology-scan {
+    animation: hf-topology-scan 224ms cubic-bezier(0.77, 0, 0.175, 1) both;
+  }
+
+  .hf-topology-target[data-topology-phase="acquiring"] {
+    animation: hf-topology-localize 224ms cubic-bezier(0.23, 1, 0.32, 1) 72ms both;
+  }
+
+  .hf-topology-target[data-topology-phase="localizing"] {
+    animation: hf-topology-localize 176ms cubic-bezier(0.23, 1, 0.32, 1) both;
+  }
+
+  .hf-topology-target[data-topology-phase="sealing"] {
+    animation: hf-topology-localize 144ms cubic-bezier(0.23, 1, 0.32, 1) both;
+  }
+
+  .hf-topology-seal {
+    animation: hf-topology-seal 224ms cubic-bezier(0.23, 1, 0.32, 1) both;
+  }
+
+  .hf-topology-seal path:first-of-type {
+    animation: hf-topology-seal-left 224ms cubic-bezier(0.23, 1, 0.32, 1) both;
+  }
+
+  .hf-topology-seal path:nth-of-type(2) {
+    animation: hf-topology-seal-right 224ms cubic-bezier(0.23, 1, 0.32, 1) both;
+  }
+}
+
+@keyframes hf-topology-reveal {
+  from {
+    opacity: 0;
+    clip-path: inset(0 100% 0 0);
+  }
+  to {
+    opacity: 1;
+    clip-path: inset(0);
+  }
+}
+
+@keyframes hf-topology-scan {
+  from {
+    opacity: 0;
+    transform: translate3d(-100%, 0, 0);
+  }
+  16% {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+    transform: translate3d(400%, 0, 0);
+  }
+}
+
+@keyframes hf-topology-localize {
+  from {
+    opacity: 0;
+    transform: scaleX(0.76);
+  }
+  to {
+    opacity: 1;
+    transform: scaleX(1);
+  }
+}
+
+@keyframes hf-topology-seal {
+  from {
+    opacity: 0;
+    transform: scale(0.88);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@keyframes hf-topology-seal-left {
+  from {
+    transform: translate3d(-9px, 0, 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@keyframes hf-topology-seal-right {
+  from {
+    transform: translate3d(9px, 0, 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-topology-contour,
+  .hf-topology-field,
+  .hf-topology-target,
+  .hf-topology-seal,
+  .hf-topology-seal path {
+    animation: none;
+    transform: none;
+  }
+}
+
 @keyframes hf-fx-preset-wave {
   0%,
   100% {

package/src/utils/domEditSaveQueue.test.ts

@@ -51,7 +51,7 @@ describe("dom edit save queue", () => {
     queue.destroy();
   });
 
-  it("keeps an open breaker paused even when already queued work succeeds", async () => {
+  it("stops already queued work when the preceding save opens the breaker", async () => {
     const onOpen = vi.fn();
     const onReset = vi.fn();
     const queue = createDomEditSaveQueue({
@@ -72,13 +72,15 @@ describe("dom edit save queue", () => {
           resolveFirstStarted?.();
         }),
     );
-    const second = queue.enqueue(async () => {});
+    const secondSave = vi.fn(async () => undefined);
+    const second = queue.enqueue(secondSave);
 
     await firstStarted;
     expect(rejectFirst).toBeTypeOf("function");
     rejectFirst?.(new StudioSaveHttpError("Server down", 503));
     await expect(first).rejects.toThrow("Server down");
-    await expect(second).resolves.toBeUndefined();
+    await expect(second).rejects.toThrow("Auto-save is paused");
+    expect(secondSave).not.toHaveBeenCalled();
 
     expect(onOpen).toHaveBeenCalledOnce();
     expect(onReset).not.toHaveBeenCalled();

package/src/utils/domEditSaveQueue.ts

@@ -81,7 +81,12 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   return {
     enqueue(save) {
       if (breakerOpen) return Promise.reject(new DomEditSaveQueueOpenError());
-      const queued = tail.catch(() => undefined).then(() => run(save));
+      const queued = tail
+        .catch(() => undefined)
+        .then(() => {
+          if (breakerOpen) throw new DomEditSaveQueueOpenError();
+          return run(save);
+        });
       tail = queued.then(
         () => undefined,
         () => undefined,

package/src/webmcp/StudioAgentTools.test.ts

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { vi } from "vitest";
+import { readLiveSelectionBox, resizeSelectionFromAgent } from "./StudioAgentTools";
+
+function rect(width: number, height: number): DOMRect {
+  return { x: 10, y: 20, width, height } as DOMRect;
+}
+
+describe("readLiveSelectionBox", () => {
+  it("measures the replacement preview node after a commit reload", () => {
+    const oldElement = document.createElement("h1");
+    oldElement.id = "headline";
+    oldElement.getBoundingClientRect = () => rect(300, 50);
+    const selection = {
+      id: "headline",
+      sourceFile: "index.html",
+      element: oldElement,
+    } as DomEditSelection;
+
+    const liveDocument = document.implementation.createHTMLDocument();
+    const replacement = liveDocument.createElement("h1");
+    replacement.id = "headline";
+    replacement.getBoundingClientRect = () => rect(280, 60);
+    liveDocument.body.append(replacement);
+
+    expect(readLiveSelectionBox(liveDocument, selection, "index.html")).toEqual({
+      x: 10,
+      y: 20,
+      width: 280,
+      height: 60,
+    });
+  });
+
+  it("does not hide a stale target behind its detached old node", () => {
+    const oldElement = document.createElement("h1");
+    oldElement.id = "headline";
+    const selection = {
+      id: "headline",
+      sourceFile: "index.html",
+      element: oldElement,
+    } as DomEditSelection;
+    const liveDocument = document.implementation.createHTMLDocument();
+
+    expect(() => readLiveSelectionBox(liveDocument, selection, "index.html")).toThrow(
+      "target is missing",
+    );
+  });
+});
+
+describe("resizeSelectionFromAgent", () => {
+  it("applies the same live draft a pointer gesture shows before persistence", async () => {
+    const element = document.createElement("div");
+    element.style.width = "300px";
+    element.style.height = "50px";
+    const selection = { element } as DomEditSelection;
+    const commit = vi.fn(async (_selection, _next, _offset, restore: () => void) => {
+      expect(element.style.width).toBe("280px");
+      expect(element.style.height).toBe("60px");
+      restore();
+    });
+
+    await resizeSelectionFromAgent(selection, { width: 280, height: 60 }, commit);
+
+    expect(commit).toHaveBeenCalledOnce();
+    expect(element.style.width).toBe("300px");
+    expect(element.style.height).toBe("50px");
+  });
+});