@hyperframes/studio 0.7.60 → 0.7.62

package/src/contexts/ViewModeContext.tsx

@@ -4,6 +4,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type ReactNode,
 } from "react";
@@ -17,6 +18,7 @@ import {
  * user straight into the storyboard by navigating the tab to `?view=storyboard`.
  */
 export type StudioViewMode = "timeline" | "storyboard";
+export type ViewModeGuard = (nextMode: StudioViewMode) => boolean;
 
 const VIEW_QUERY_PARAM = "view";
 
@@ -38,9 +40,24 @@ function writeViewModeToUrl(mode: StudioViewMode): void {
   window.history.replaceState(window.history.state, "", url);
 }
 
+interface HistoryLocation {
+  href: string;
+  state: unknown;
+}
+
+function readHistoryLocation(): HistoryLocation | null {
+  if (typeof window === "undefined") return null;
+  return {
+    href: window.location.href,
+    state: window.history.state,
+  };
+}
+
 export interface ViewModeValue {
   viewMode: StudioViewMode;
-  setViewMode: (mode: StudioViewMode) => void;
+  /** Returns false when an active editor vetoes the transition. */
+  setViewMode: (mode: StudioViewMode) => boolean;
+  registerViewModeGuard: (guard: ViewModeGuard) => () => void;
 }
 
 /**
@@ -49,6 +66,15 @@ export interface ViewModeValue {
  */
 export function useViewModeState(): ViewModeValue {
   const [viewMode, setMode] = useState<StudioViewMode>(() => readViewModeFromUrl());
+  const guardsRef = useRef(new Set<ViewModeGuard>());
+  const acceptedLocationRef = useRef<HistoryLocation | null>(readHistoryLocation());
+
+  const canSetViewMode = useCallback((mode: StudioViewMode) => {
+    for (const guard of guardsRef.current) {
+      if (!guard(mode)) return false;
+    }
+    return true;
+  }, []);
 
   // Reflect genuine browser back/forward between history entries with a different
   // `?view=`. Note: our own writes use `replaceState` (below), which does NOT fire
@@ -57,17 +83,44 @@ export function useViewModeState(): ViewModeValue {
   // the mount-time read); a scripted `pushState`/`replaceState` to `?view=` would not be
   // reflected here, by design.
   useEffect(() => {
-    const onPopState = () => setMode(readViewModeFromUrl());
+    const onPopState = () => {
+      const mode = readViewModeFromUrl();
+      if (mode !== viewMode && !canSetViewMode(mode)) {
+        const acceptedLocation = acceptedLocationRef.current;
+        if (acceptedLocation) {
+          window.history.pushState(acceptedLocation.state, "", acceptedLocation.href);
+        }
+        return;
+      }
+      setMode(mode);
+      acceptedLocationRef.current = readHistoryLocation();
+    };
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
-  }, []);
+  }, [canSetViewMode, viewMode]);
+
+  const setViewMode = useCallback(
+    (mode: StudioViewMode) => {
+      if (!canSetViewMode(mode)) return false;
+      setMode(mode);
+      writeViewModeToUrl(mode);
+      acceptedLocationRef.current = readHistoryLocation();
+      return true;
+    },
+    [canSetViewMode],
+  );
 
-  const setViewMode = useCallback((mode: StudioViewMode) => {
-    setMode(mode);
-    writeViewModeToUrl(mode);
+  const registerViewModeGuard = useCallback((guard: ViewModeGuard) => {
+    guardsRef.current.add(guard);
+    return () => {
+      guardsRef.current.delete(guard);
+    };
   }, []);
 
-  return useMemo(() => ({ viewMode, setViewMode }), [viewMode, setViewMode]);
+  return useMemo(
+    () => ({ viewMode, setViewMode, registerViewModeGuard }),
+    [viewMode, setViewMode, registerViewModeGuard],
+  );
 }
 
 const ViewModeContext = createContext<ViewModeValue | null>(null);

package/src/hooks/timelineEditingHelpers.ts

@@ -166,6 +166,14 @@ export function patchIframeDomTiming(
     // Cross-origin or mid-navigation — file save is enqueued; iframe patch is best-effort.
   }
 }
+
+export function playbackStartAttributeForElement(
+  element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
+): "data-media-start" | "data-playback-start" {
+  return element.playbackStartAttr === "playback-start" || element.kind === "composition"
+    ? "data-playback-start"
+    : "data-media-start";
+}
 // fallow-ignore-next-line complexity
 function resolveResizePlaybackStart(
   original: string,
@@ -174,8 +182,7 @@ function resolveResizePlaybackStart(
   updates: Pick<TimelineElement, "start" | "playbackStart">,
 ): { attrName: string; value: number } | null {
   if (updates.playbackStart != null) {
-    const attrName =
-      element.playbackStartAttr === "playback-start" ? "playback-start" : "media-start";
+    const attrName = playbackStartAttributeForElement(element).slice("data-".length);
     return { attrName, value: updates.playbackStart };
   }
   const trimDelta = updates.start - element.start;
@@ -185,8 +192,7 @@ function resolveResizePlaybackStart(
     readAttributeByTarget(original, target, "media-start");
   const current = raw != null ? parseFloat(raw) : undefined;
   if (current == null || !Number.isFinite(current)) return null;
-  const attrName =
-    element.playbackStartAttr === "playback-start" ? "playback-start" : "media-start";
+  const attrName = playbackStartAttributeForElement(element).slice("data-".length);
   return {
     attrName,
     value: Math.max(0, current + trimDelta * Math.max(element.playbackRate ?? 1, 0.1)),

package/src/hooks/useAddAssetAtPlayhead.test.ts

@@ -0,0 +1,44 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../player";
+import { useAddAssetAtPlayhead } from "./useAddAssetAtPlayhead";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("useAddAssetAtPlayhead", () => {
+  it("drops the asset on track 0 at the current playhead time", () => {
+    usePlayerStore.getState().setCurrentTime(4.5);
+    const handleTimelineAssetDrop = vi.fn();
+    let addAsset: (assetPath: string) => unknown = () => undefined;
+
+    function Harness() {
+      addAsset = useAddAssetAtPlayhead(handleTimelineAssetDrop);
+      return null;
+    }
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(React.createElement(Harness));
+    });
+
+    act(() => {
+      addAsset("assets/clip.mp4");
+    });
+
+    expect(handleTimelineAssetDrop).toHaveBeenCalledWith("assets/clip.mp4", {
+      start: 4.5,
+      track: 0,
+    });
+
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useAddAssetAtPlayhead.ts

@@ -0,0 +1,21 @@
+import { useCallback } from "react";
+import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
+
+/** Drops an asset onto track 0 at the current playhead time. */
+export function useAddAssetAtPlayhead(
+  handleTimelineAssetDrop: (
+    assetPath: string,
+    placement: Pick<TimelineElement, "start" | "track">,
+    durationOverride?: number,
+  ) => unknown,
+) {
+  return useCallback(
+    (assetPath: string) =>
+      handleTimelineAssetDrop(assetPath, {
+        start: usePlayerStore.getState().currentTime,
+        track: 0,
+      }),
+    [handleTimelineAssetDrop],
+  );
+}

package/src/hooks/usePreviewPersistence.ts

@@ -208,13 +208,19 @@ export function usePreviewPersistence({
       // attributes onto the live DOM and re-runs the timeline at the SAME playhead,
       // falling back to reloadPreview for anything structural (split/delete undo),
       // multi-file, sub-comp, or a permanent soft-reload failure.
-      applyUndoRestoreToPreview(
+      const strategy = applyUndoRestoreToPreview(
         previewIframeRef.current,
         activeCompPathRef.current,
         restore.files,
         usePlayerStore.getState().currentTime,
         reloadPreview,
       );
+      if (strategy === "full") {
+        const player = usePlayerStore.getState();
+        player.setElements([]);
+        player.setSelectedElementId(null);
+        player.setTimelineReady(false);
+      }
     },
     [previewIframeRef, activeCompPathRef, reloadPreview],
   );

package/src/hooks/useRazorSplit.history.test.tsx

@@ -67,43 +67,36 @@ function mountRazorSplit(opts: { gsap?: boolean; previewStamp?: boolean } = {}):
     onChange: () => {},
   });
 
-  // Faithful stand-in for the studio-server file-mutation endpoints: the server
-  // writes the split to disk itself, then returns the patched content.
+  // Faithful stand-in for the atomic server cut: one forward file write and one
+  // response carrying the canonical history snapshots.
   const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
     const u = String(url);
-    if (u.includes("/gsap-mutations/")) {
-      if (opts.gsap) {
-        // Mirror the server: rewrites the GSAP script for the new id, writes to
-        // disk, returns the final content.
-        disk["index.html"] = SPLIT_GSAP;
-        const version = `"test-gsap-${SPLIT_GSAP.length}"`;
-        return new Response(JSON.stringify({ ok: true, after: SPLIT_GSAP, version }), {
-          status: 200,
-          headers: { "Content-Type": "application/json", ETag: version },
-        });
-      }
-      // The fixture has no GSAP script — mirror the server's 400 response.
-      return new Response(JSON.stringify({ error: "no GSAP script found in file" }), {
-        status: 400,
-        headers: { "Content-Type": "application/json" },
-      });
-    }
-    if (u.includes("/file-mutations/split-element/")) {
-      disk["index.html"] = SPLIT;
-      const version = `"test-split-${SPLIT.length}"`;
+    if (u.includes("/file-mutations/split-batch")) {
+      const before = disk["index.html"];
+      disk["index.html"] = finalContent;
+      const version = `"test-cut-${finalContent.length}"`;
       return new Response(
         JSON.stringify({
           ok: true,
-          changed: true,
-          content: SPLIT,
-          newId: "clip1-split",
-          version,
+          outcome: "committed",
+          files: [
+            {
+              path: "index.html",
+              before,
+              after: finalContent,
+              version,
+              writeToken: "test-cut",
+              splitCount: 1,
+              skippedSelectors: [],
+            },
+          ],
         }),
-        { status: 200, headers: { "Content-Type": "application/json", ETag: version } },
+        { status: 200, headers: { "Content-Type": "application/json" } },
       );
     }
     if (u.includes("/files/")) {
-      return new Response(JSON.stringify({ content: disk["index.html"] }), {
+      const content = disk["index.html"];
+      return new Response(JSON.stringify({ content, version: `"test-${content.length}"` }), {
         status: 200,
         headers: { "Content-Type": "application/json" },
       });

package/src/hooks/useRazorSplit.test.tsx

@@ -17,19 +17,30 @@ function jsonResponse(body: unknown, status = 200): Response {
 describe("useRazorSplit mutation versions", () => {
   afterEach(() => vi.restoreAllMocks());
 
-  it("observes each out-of-band mutation version before the OCC writer runs", async () => {
+  it("observes the batch version without a redundant client forward write", async () => {
     const original = '<div id="clip" data-start="0" data-duration="4">Clip</div>';
     const htmlSplit =
       '<div id="clip" data-start="0" data-duration="2">Clip</div><div id="clip-split" data-start="2" data-duration="2">Clip</div>';
     const final = `${htmlSplit}<script>window.__timelines = {}</script>`;
     vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
       const url = String(input);
-      if (url.includes("/files/")) return jsonResponse({ content: original });
-      if (url.includes("/file-mutations/split-element/")) {
-        return jsonResponse({ ok: true, changed: true, content: htmlSplit, version: '"v-html"' });
-      }
-      if (url.includes("/gsap-mutations/")) {
-        return jsonResponse({ ok: true, changed: true, after: final, version: '"v-gsap"' });
+      if (url.includes("/files/")) return jsonResponse({ content: original, version: '"v0"' });
+      if (url.includes("/file-mutations/split-batch")) {
+        return jsonResponse({
+          ok: true,
+          outcome: "committed",
+          files: [
+            {
+              path: "index.html",
+              before: original,
+              after: final,
+              version: '"v-cut"',
+              writeToken: "cut-1",
+              splitCount: 1,
+              skippedSelectors: [],
+            },
+          ],
+        });
       }
       throw new Error(`Unexpected request: ${url}`);
     });
@@ -78,8 +89,8 @@ describe("useRazorSplit mutation versions", () => {
       );
     });
 
-    expect(order).toEqual(['observe:index.html:"v-html"', 'observe:index.html:"v-gsap"', "write"]);
-    expect(writeProjectFile).toHaveBeenCalledWith("index.html", final, original);
+    expect(order).toEqual(['observe:index.html:"v-cut"']);
+    expect(writeProjectFile).not.toHaveBeenCalled();
     expect(recordEdit).toHaveBeenCalledTimes(1);
 
     act(() => root.unmount());

package/src/hooks/useRazorSplit.testHelpers.ts

@@ -8,15 +8,19 @@ export interface SplitBody {
   elementDuration: number;
 }
 
+interface BatchFileBody {
+  path: string;
+  targets: SplitBody[];
+}
+
 function decodePathFromUrl(url: string, marker: string): string {
   const encoded = url.slice(url.indexOf(marker) + marker.length);
   return decodeURIComponent(encoded);
 }
 
 /**
- * Fetch mock shared by both harnesses: GSAP mutations 400 (no script in fixtures),
- * split-element writes a `<!--split-->` marker so `changed` is true, and file reads
- * echo the in-memory `disk`. `onSplit` (when set) records each split request's body.
+ * Fetch mock shared by both harnesses: the atomic split batch writes each file
+ * once and returns its canonical snapshots; file reads echo the in-memory disk.
  */
 export function createSplitFetchMock(
   disk: Record<string, string>,
@@ -24,31 +28,39 @@ export function createSplitFetchMock(
 ) {
   return vi.fn(async (url: string, init?: RequestInit) => {
     const u = String(url);
-    if (u.includes("/gsap-mutations/")) {
-      // No GSAP script in the fixtures — mirror the server's 400 response.
-      return new Response(JSON.stringify({ error: "no GSAP script found in file" }), {
-        status: 400,
-        headers: { "Content-Type": "application/json" },
+    if (u.includes("/file-mutations/split-batch")) {
+      const body = JSON.parse(String(init?.body)) as { files: BatchFileBody[] };
+      const files = body.files.map((file) => {
+        const before = disk[file.path];
+        for (const target of file.targets) onSplit?.(file.path, target);
+        const after = `${before}${"<!--split-->".repeat(file.targets.length)}`;
+        const version = `"test-${file.path}-${after.length}"`;
+        return {
+          path: file.path,
+          before,
+          after,
+          version,
+          writeToken: "test-cut",
+          splitCount: file.targets.length,
+          skippedSelectors: [],
+        };
       });
-    }
-    if (u.includes("/file-mutations/split-element/")) {
-      const path = decodePathFromUrl(u, "/file-mutations/split-element/");
-      onSplit?.(path, JSON.parse(String(init?.body)) as SplitBody);
-      // Return content that differs from the original so `changed` is true.
-      const after = `${disk[path]}<!--split-->`;
-      const version = `"test-${path}-${after.length}"`;
-      disk[path] = after; // server writes the split to disk
-      return new Response(JSON.stringify({ ok: true, changed: true, content: after, version }), {
+      for (const file of files) disk[file.path] = file.after;
+      return new Response(JSON.stringify({ ok: true, outcome: "committed", files }), {
         status: 200,
-        headers: { "Content-Type": "application/json", ETag: version },
+        headers: { "Content-Type": "application/json" },
       });
     }
     if (u.includes("/files/")) {
       const path = decodePathFromUrl(u, "/files/").replace(/\?.*$/, "");
-      return new Response(JSON.stringify({ content: disk[path] ?? "" }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      });
+      const content = disk[path] ?? "";
+      return new Response(
+        JSON.stringify({ content, version: `"test-${path}-${content.length}"` }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
     }
     void init;
     throw new Error(`unexpected fetch: ${u}`);