@hyperframes/studio 0.7.59 → 0.7.61

package/src/hooks/useFileManager.ts

@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef } from "react";
+import { useState, useCallback, useMemo, useRef } from "react";
 import type { EditingFile } from "../utils/studioHelpers";
 import { FONT_EXT, isMediaFile } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
@@ -7,8 +7,10 @@ import { findTagByTarget, type PatchTarget } from "../utils/sourcePatcher";
 import {
   createStudioSaveHttpError,
   retryStudioSave,
+  StudioFileConflictError,
   StudioSaveNetworkError,
 } from "../utils/studioSaveDiagnostics";
+import { createStudioWriteToken, studioExpectedFileVersion } from "../utils/studioFileVersion";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 
@@ -50,6 +52,17 @@ export function useFileManager({
   projectIdRef.current = projectId;
 
   const importedFontAssetsRef = useRef<ImportedFontAsset[]>([]);
+  const fileVersionScope = useMemo(
+    () => ({ projectId, versions: new Map<string, string | null>() }),
+    [projectId],
+  );
+  const fileVersions = fileVersionScope.versions;
+  const observeProjectFileVersion = useCallback(
+    (path: string, version: string | null) => {
+      fileVersions.set(path, version);
+    },
+    [fileVersions],
+  );
 
   // ── File tree ──
 
@@ -73,17 +86,38 @@ export function useFileManager({
         `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}`,
       );
       if (!response.ok) throw new Error(`Failed to read ${path}`);
-      const data = (await response.json()) as { content?: string };
+      const data = (await response.json()) as { content?: string; version?: string };
       if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
+      fileVersions.set(path, data.version ?? response.headers.get("etag"));
       return data.content;
     },
-    [projectId],
+    [fileVersions, projectId],
   );
 
   const writeProjectFile = useCallback(
-    async (path: string, content: string): Promise<void> => {
+    async (path: string, content: string, expectedContent?: string): Promise<void> => {
       if (!projectId) throw new Error("No active project");
       const writeProjectId = projectId;
+      let expectedVersion = await studioExpectedFileVersion(fileVersions, path, expectedContent);
+      if (expectedVersion === undefined) {
+        const preflight = await fetch(
+          `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
+        );
+        if (preflight.ok) {
+          const data = (await preflight.json()) as { content?: string; version?: string };
+          throw new StudioFileConflictError({
+            filePath: path,
+            currentVersion: data.version ?? preflight.headers.get("etag"),
+            currentContent: data.content ?? null,
+            attemptedContent: content,
+          });
+        } else if (preflight.status === 404) {
+          expectedVersion = null;
+        } else {
+          throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
+        }
+      }
+      const writeToken = createStudioWriteToken();
       await retryStudioSave(async () => {
         let response: Response;
         try {
@@ -91,7 +125,11 @@ export function useFileManager({
             `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
             {
               method: "PUT",
-              headers: { "Content-Type": "text/plain" },
+              headers: {
+                "Content-Type": "text/plain",
+                "X-Hyperframes-Write-Token": writeToken,
+                ...(expectedVersion ? { "If-Match": expectedVersion } : { "If-None-Match": "*" }),
+              },
               body: content,
             },
           );
@@ -100,13 +138,35 @@ export function useFileManager({
             cause: error,
           });
         }
+        if (response.status === 409) {
+          const conflict = (await response.json().catch(() => null)) as {
+            currentVersion?: string | null;
+            currentContent?: string | null;
+          } | null;
+          const currentVersion = conflict?.currentVersion ?? null;
+          if (currentVersion && conflict?.currentContent === content) {
+            fileVersions.set(path, currentVersion);
+            return;
+          }
+          throw new StudioFileConflictError({
+            filePath: path,
+            currentVersion,
+            currentContent: conflict?.currentContent ?? null,
+            attemptedContent: content,
+          });
+        }
         if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`);
+        const result = (await response.json()) as { version?: string };
+        const version = result.version ?? response.headers.get("etag");
+        if (!version)
+          throw new Error(`Save response for ${path} did not include a content version`);
+        fileVersions.set(path, version);
       });
       if (projectIdRef.current === writeProjectId && editingPathRef.current === path) {
         setEditingFile({ path, content });
       }
     },
-    [projectId],
+    [fileVersions, projectId],
   );
 
   const updateEditingFileContent = useCallback((path: string, content: string) => {
@@ -122,10 +182,11 @@ export function useFileManager({
         `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
       );
       if (!response.ok) throw new Error(`Failed to read ${path}`);
-      const data = (await response.json()) as { content?: string };
+      const data = (await response.json()) as { content?: string; version?: string };
+      fileVersions.set(path, data.version ?? response.headers.get("etag"));
       return typeof data.content === "string" ? data.content : "";
     },
-    [projectId],
+    [fileVersions, projectId],
   );
 
   // ── Editor save (debounced content change) ──
@@ -163,8 +224,9 @@ export function useFileManager({
           if (!r.ok) throw new Error(`Failed to load ${path} (${r.status})`);
           return r.json();
         })
-        .then((data: { content?: string }) => {
+        .then((data: { content?: string; version?: string }) => {
           if (data.content != null) {
+            fileVersions.set(path, data.version ?? null);
             setEditingFile({ path, content: data.content });
           }
         })
@@ -172,7 +234,7 @@ export function useFileManager({
           showToast(err instanceof Error ? err.message : `Failed to load ${path}`, "error");
         });
     },
-    [showToast],
+    [fileVersions, showToast],
   );
 
   // ── Click-to-source ──
@@ -195,9 +257,10 @@ export function useFileManager({
         signal: controller.signal,
       })
         .then((r) => r.json())
-        .then((data: { content?: string }) => {
+        .then((data: { content?: string; version?: string }) => {
           if (requestId !== revealRequestIdRef.current) return;
           if (data.content != null) {
+            fileVersions.set(sourceFile, data.version ?? null);
             setEditingFile({ path: sourceFile, content: data.content });
             const match = findTagByTarget(data.content, target);
             setRevealSourceOffset(match ? match.start : null);
@@ -205,7 +268,7 @@ export function useFileManager({
         })
         .catch(() => {});
     },
-    [editingFile?.content],
+    [editingFile?.content, fileVersions],
   );
 
   // ── Upload ──
@@ -434,6 +497,7 @@ export function useFileManager({
     readProjectFile,
     writeProjectFile,
     readOptionalProjectFile,
+    observeProjectFileVersion,
     updateEditingFileContent,
 
     // Click-to-source

package/src/hooks/usePanelLayout.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePanelLayout } from "./usePanelLayout";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.doUnmock("../components/editor/manualEditingAvailability");
+  vi.resetModules();
+});
+
+function renderPanelLayoutWith(hook: typeof usePanelLayout) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  let current: ReturnType<typeof usePanelLayout> | null = null;
+
+  function Harness() {
+    current = hook();
+    return null;
+  }
+
+  act(() => {
+    root.render(React.createElement(Harness));
+  });
+
+  return {
+    getState: (): ReturnType<typeof usePanelLayout> => {
+      if (!current) throw new Error("usePanelLayout did not render");
+      return current;
+    },
+    unmount: () => act(() => root.unmount()),
+  };
+}
+
+function renderPanelLayout() {
+  return renderPanelLayoutWith(usePanelLayout);
+}
+
+describe("usePanelLayout — right inspector panes", () => {
+  it("toggleRightInspectorPane independently flips one pane, allowing both open at once", () => {
+    const harness = renderPanelLayout();
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });
+
+    act(() => harness.getState().toggleRightInspectorPane("layers"));
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: true, design: true });
+
+    harness.unmount();
+  });
+
+  it("toggleRightInspectorPane refuses to turn off the last remaining pane", () => {
+    const harness = renderPanelLayout();
+    act(() => harness.getState().toggleRightInspectorPane("design"));
+    // Only "design" was on; toggling it off would leave both false — guarded.
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });
+    harness.unmount();
+  });
+
+  it("setExclusiveRightInspectorPane is radio-style — selecting one turns the other off", () => {
+    const harness = renderPanelLayout();
+    act(() => harness.getState().toggleRightInspectorPane("layers"));
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: true, design: true });
+
+    act(() => harness.getState().setExclusiveRightInspectorPane("layers"));
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: true, design: false });
+
+    act(() => harness.getState().setExclusiveRightInspectorPane("design"));
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });
+
+    harness.unmount();
+  });
+
+  it("setRightPanelTab additively opens a pane when the flat inspector is off (legacy behavior)", async () => {
+    vi.resetModules();
+    vi.doMock("../components/editor/manualEditingAvailability", async () => {
+      const actual = await vi.importActual<
+        typeof import("../components/editor/manualEditingAvailability")
+      >("../components/editor/manualEditingAvailability");
+      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: false };
+    });
+    const { usePanelLayout: usePanelLayoutFlatOff } = await import("./usePanelLayout");
+    const harness = renderPanelLayoutWith(usePanelLayoutFlatOff);
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });
+
+    act(() => harness.getState().setRightPanelTab("layers"));
+    // Legacy (split-view) behavior: additive, both panes end up open.
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: true, design: true });
+
+    harness.unmount();
+  });
+
+  it("setRightPanelTab is flat-aware: exclusivity holds for callers other than a direct in-panel tab click", async () => {
+    vi.resetModules();
+    vi.doMock("../components/editor/manualEditingAvailability", async () => {
+      const actual = await vi.importActual<
+        typeof import("../components/editor/manualEditingAvailability")
+      >("../components/editor/manualEditingAvailability");
+      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: true };
+    });
+    const { usePanelLayout: usePanelLayoutFlatOn } = await import("./usePanelLayout");
+    const harness = renderPanelLayoutWith(usePanelLayoutFlatOn);
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });
+
+    // Element-select / block-params-close / header Inspector-button callers
+    // all reach setRightPanelTab directly, not through the in-panel tab
+    // click's own setExclusiveRightInspectorPane call — this must still
+    // enforce exclusivity under the flat flag, or both tabs end up
+    // highlighted while only one pane actually renders.
+    act(() => harness.getState().setRightPanelTab("layers"));
+    expect(harness.getState().rightInspectorPanes).toEqual({ layers: true, design: false });
+
+    harness.unmount();
+  });
+});

package/src/hooks/usePanelLayout.ts

@@ -6,6 +6,7 @@ import type {
 } from "../utils/studioHelpers";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../utils/studioUiPreferences";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { STUDIO_FLAT_INSPECTOR_ENABLED } from "../components/editor/manualEditingAvailability";
 
 export interface InitialPanelLayoutState {
   rightCollapsed?: boolean | null;
@@ -80,7 +81,20 @@ export function usePanelLayout(initialState?: InitialPanelLayoutState) {
   const trackedSetRightPanelTab = useCallback(
     (tab: RightPanelTab) => {
       if (tab === "design" || tab === "layers") {
-        setRightInspectorPanes((panes) => ({ ...panes, [tab]: true }));
+        // Flat inspector: Layers always renders full-height by itself (see
+        // StudioRightPanel's render gate), so this MUST land on the same
+        // radio-style exclusivity setExclusiveRightInspectorPane enforces for
+        // the direct in-panel tab click — every OTHER path that reaches here
+        // (element select, closing block-params, the header Inspector
+        // button, and this function's own callers outside an active
+        // inspector tab) would otherwise additively leave both panes `true`
+        // and reproduce the "both tabs highlight, only one renders" bug this
+        // still-additive branch used to cause under the flat flag.
+        setRightInspectorPanes(
+          STUDIO_FLAT_INSPECTOR_ENABLED
+            ? { design: tab === "design", layers: tab === "layers" }
+            : (panes) => ({ ...panes, [tab]: true }),
+        );
       }
       setRightPanelTab(tab);
       trackStudioEvent("tab_switch", { panel: "right_panel", tab });
@@ -96,6 +110,14 @@ export function usePanelLayout(initialState?: InitialPanelLayoutState) {
     });
   }, []);
 
+  // Radio-style variant for the flat inspector: Layers always renders full-
+  // height by itself there (never split-shared with Design), so leaving both
+  // panes independently toggleable would highlight both tabs as "active"
+  // while only one actually shows. Selecting one turns the other off.
+  const setExclusiveRightInspectorPane = useCallback((pane: RightInspectorPane) => {
+    setRightInspectorPanes({ design: pane === "design", layers: pane === "layers" });
+  }, []);
+
   return {
     leftWidth,
     setLeftWidth,
@@ -109,6 +131,7 @@ export function usePanelLayout(initialState?: InitialPanelLayoutState) {
     setRightPanelTab: trackedSetRightPanelTab,
     rightInspectorPanes,
     toggleRightInspectorPane,
+    setExclusiveRightInspectorPane,
     toggleLeftSidebar,
     handlePanelResizeStart,
     handlePanelResizeMove,

package/src/hooks/usePreviewPersistence.ts

@@ -133,7 +133,10 @@ export function usePreviewPersistence({
   if (!domEditSaveQueueRef.current) {
     domEditSaveQueueRef.current = createDomEditSaveQueue({
       onOpen: (event) => {
-        const message = "Auto-save is paused. Check your connection.";
+        const message =
+          event.statusCode === 409
+            ? "Save paused: this file changed elsewhere. Reload and review the latest version before reapplying your edit."
+            : "Auto-save is paused. Check your connection.";
         setDomEditSaveQueuePaused(message);
         showToastRef.current(message, "error");
         trackStudioEvent("save_queue_paused", {

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

@@ -76,9 +76,10 @@ function mountRazorSplit(opts: { gsap?: boolean; previewStamp?: boolean } = {}):
         // Mirror the server: rewrites the GSAP script for the new id, writes to
         // disk, returns the final content.
         disk["index.html"] = SPLIT_GSAP;
-        return new Response(JSON.stringify({ ok: true, after: 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" },
+          headers: { "Content-Type": "application/json", ETag: version },
         });
       }
       // The fixture has no GSAP script — mirror the server's 400 response.
@@ -89,9 +90,16 @@ function mountRazorSplit(opts: { gsap?: boolean; previewStamp?: boolean } = {}):
     }
     if (u.includes("/file-mutations/split-element/")) {
       disk["index.html"] = SPLIT;
+      const version = `"test-split-${SPLIT.length}"`;
       return new Response(
-        JSON.stringify({ ok: true, changed: true, content: SPLIT, newId: "clip1-split" }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
+        JSON.stringify({
+          ok: true,
+          changed: true,
+          content: SPLIT,
+          newId: "clip1-split",
+          version,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json", ETag: version } },
       );
     }
     if (u.includes("/files/")) {

package/src/hooks/useRazorSplit.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { useRazorSplit } from "./useRazorSplit";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("useRazorSplit mutation versions", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("observes each out-of-band mutation version before the OCC writer runs", 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"' });
+      }
+      throw new Error(`Unexpected request: ${url}`);
+    });
+
+    const order: string[] = [];
+    const observeProjectFileVersion = vi.fn((path: string, version: string | null) => {
+      order.push(`observe:${path}:${version}`);
+    });
+    const writeProjectFile = vi.fn(async () => {
+      order.push("write");
+    });
+    const recordEdit = vi.fn().mockResolvedValue(undefined);
+    let split: ((element: TimelineElement, splitTime: number) => Promise<void>) | undefined;
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+
+    function Harness() {
+      split = useRazorSplit({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile,
+        observeProjectFileVersion,
+        recordEdit,
+        domEditSaveTimestampRef: { current: 0 },
+        reloadPreview: vi.fn(),
+      }).handleRazorSplit;
+      return null;
+    }
+
+    await act(async () => root.render(React.createElement(Harness)));
+    await act(async () => {
+      await split?.(
+        {
+          id: "clip",
+          domId: "clip",
+          hfId: "clip",
+          tag: "div",
+          start: 0,
+          duration: 4,
+          track: 0,
+          timingSource: "authored",
+        },
+        2,
+      );
+    });
+
+    expect(order).toEqual(['observe:index.html:"v-html"', 'observe:index.html:"v-gsap"', "write"]);
+    expect(writeProjectFile).toHaveBeenCalledWith("index.html", final, original);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+    container.remove();
+  });
+});

package/src/hooks/useRazorSplit.testHelpers.ts

@@ -36,10 +36,11 @@ export function createSplitFetchMock(
       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 }), {
+      return new Response(JSON.stringify({ ok: true, changed: true, content: after, version }), {
         status: 200,
-        headers: { "Content-Type": "application/json" },
+        headers: { "Content-Type": "application/json", ETag: version },
       });
     }
     if (u.includes("/files/")) {