@hyperframes/studio 0.7.59 → 0.7.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.59",
+  "version": "0.7.60",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.59",
-    "@hyperframes/studio-server": "0.7.59",
-    "@hyperframes/sdk": "0.7.59",
-    "@hyperframes/parsers": "0.7.59",
-    "@hyperframes/player": "0.7.59"
+    "@hyperframes/core": "0.7.60",
+    "@hyperframes/player": "0.7.60",
+    "@hyperframes/sdk": "0.7.60",
+    "@hyperframes/parsers": "0.7.60",
+    "@hyperframes/studio-server": "0.7.60"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.59"
+    "@hyperframes/producer": "0.7.60"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -64,7 +64,6 @@ import {
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
 import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
-
 type CanvasRect = { left: number; top: number; width: number; height: number };
 // fallow-ignore-next-line complexity
 export function StudioApp() {
@@ -166,6 +165,7 @@ export function StudioApp() {
     timelineElements,
     showToast,
     writeProjectFile: fileManager.writeProjectFile,
+    observeProjectFileVersion: fileManager.observeProjectFileVersion,
     recordEdit: editHistory.recordEdit,
     domEditSaveTimestampRef,
     reloadPreview,

package/src/components/StudioRightPanel.tsx

@@ -12,7 +12,10 @@ import { usePreviewVariablesStore } from "../hooks/previewVariablesStore";
 import type { RenderJob } from "./renders/useRenderQueue";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { IframeWindow } from "../player/lib/playbackTypes";
-import { STUDIO_INSPECTOR_PANELS_ENABLED } from "./editor/manualEditingAvailability";
+import {
+  STUDIO_FLAT_INSPECTOR_ENABLED,
+  STUDIO_INSPECTOR_PANELS_ENABLED,
+} from "./editor/manualEditingAvailability";
 import type { Composition } from "@hyperframes/sdk";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { useSlideshowPersist, type UseSlideshowPersistParams } from "../hooks/useSlideshowPersist";
@@ -80,6 +83,7 @@ export function StudioRightPanel({
     setRightPanelTab,
     rightInspectorPanes,
     toggleRightInspectorPane,
+    setExclusiveRightInspectorPane,
     handlePanelResizeStart,
     handlePanelResizeMove,
     handlePanelResizeEnd,
@@ -223,6 +227,13 @@ export function StudioRightPanel({
       setRightPanelTab(pane);
       return;
     }
+    // Flat inspector: Layers always renders full-height by itself (see the
+    // render branch below), so the two panes are mutually exclusive here —
+    // otherwise both tabs could show "active" while only one actually shows.
+    if (STUDIO_FLAT_INSPECTOR_ENABLED) {
+      setExclusiveRightInspectorPane(pane);
+      return;
+    }
     toggleRightInspectorPane(pane);
   };
 
@@ -516,7 +527,7 @@ export function StudioRightPanel({
                   domEditSaveTimestampRef={domEditSaveTimestampRef}
                   recordEdit={recordEdit}
                 />
-              ) : layersPaneOpen && designPaneOpen ? (
+              ) : layersPaneOpen && designPaneOpen && !STUDIO_FLAT_INSPECTOR_ENABLED ? (
                 <div ref={splitContainerRef} className="flex h-full min-h-0 min-w-0 flex-col">
                   <div
                     className="min-h-[120px] overflow-hidden"

package/src/components/editor/propertyPanelFlatColorGradingSection.tsx

@@ -377,7 +377,7 @@ export function FlatColorGradingSection({
                   track("select", "Custom LUT");
                   applyLut(src || null, src && lut?.src === src ? lut.intensity : 1);
                 }}
-                className="bg-transparent font-mono text-[10px] text-panel-text-3 outline-none"
+                className="border-b border-panel-border-input/50 bg-transparent font-mono text-[10px] text-panel-text-3 outline-none hover:border-panel-border-input"
               >
                 <option value="">None</option>
                 {lutAssets.map((asset) => (
@@ -545,7 +545,7 @@ export function FlatColorGradingSection({
                 onSetApplyScope(e.target.value as "source-file" | "project");
               }}
               disabled={applyBusy}
-              className="bg-transparent font-mono text-[11px] text-panel-text-0 outline-none disabled:opacity-50"
+              className="border-b border-panel-border-input/50 bg-transparent font-mono text-[11px] text-panel-text-0 outline-none hover:border-panel-border-input disabled:opacity-50"
             >
               <option value="source-file">Current file media</option>
               <option value="project">All project media</option>

package/src/components/editor/propertyPanelFlatMotionSection.tsx

@@ -85,7 +85,7 @@ export function FlatTimingRow({
   const cell = (label: string, value: string, onCommit: (next: string) => void) => (
     <div className="grid gap-px">
       <span className="text-[9px] text-panel-text-4">{label}</span>
-      <span className="border-b border-transparent font-mono text-[11px] text-panel-text-0 hover:border-panel-border-input">
+      <span className="border-b border-panel-border-input/50 font-mono text-[11px] text-panel-text-0 hover:border-panel-border-input">
         <CommitField
           value={value}
           onCommit={(next) => {

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -43,8 +43,8 @@ export function FlatRow({
           data-flat-row-value="true"
           className={`min-w-0 border-b pb-px font-mono text-[11px] ${VALUE_TIER_VALUE_CLASS[tier]} ${
             tier === "explicitCustom"
-              ? "border-transparent group-hover:border-panel-accent/35"
-              : "border-transparent group-hover:border-panel-border-input"
+              ? "border-panel-accent/30 group-hover:border-panel-accent/70"
+              : "border-panel-border-input/50 group-hover:border-panel-border-input"
           }`}
         >
           <CommitField

package/src/components/editor/propertyPanelFlatSelectRow.tsx

@@ -53,7 +53,13 @@ export function FlatSelectRow({
     <div className="group flex min-h-[30px] items-center justify-between">
       <span className={`text-[11px] ${VALUE_TIER_LABEL_CLASS[tier]}`}>{label}</span>
       <span className="flex items-center gap-2">
-        <label className="flex items-center gap-1.5">
+        <label
+          className={`flex items-center gap-1.5 border-b pb-px ${
+            tier === "explicitCustom"
+              ? "border-panel-accent/30 group-hover:border-panel-accent/70"
+              : "border-panel-border-input/50 group-hover:border-panel-border-input"
+          }`}
+        >
           <select
             value={value}
             disabled={disabled}

package/src/components/editor/propertyPanelFlatTextSection.tsx

@@ -111,7 +111,7 @@ function FlatTextFieldEditor({
         >
           Weight
         </span>
-        <label className="flex items-center gap-1.5">
+        <label className="flex items-center gap-1.5 border-b border-panel-border-input/50 pb-px hover:border-panel-border-input">
           <select
             value={weight}
             onChange={(e) => {

package/src/contexts/FileManagerContext.tsx

@@ -30,6 +30,7 @@ export function FileManagerProvider({
     readProjectFile,
     writeProjectFile,
     readOptionalProjectFile,
+    observeProjectFileVersion,
     updateEditingFileContent,
     revealSourceOffset,
     openSourceForSelection,
@@ -69,6 +70,7 @@ export function FileManagerProvider({
       readProjectFile,
       writeProjectFile,
       readOptionalProjectFile,
+      observeProjectFileVersion,
       updateEditingFileContent,
       revealSourceOffset,
       openSourceForSelection,
@@ -102,6 +104,7 @@ export function FileManagerProvider({
       readProjectFile,
       writeProjectFile,
       readOptionalProjectFile,
+      observeProjectFileVersion,
       updateEditingFileContent,
       revealSourceOffset,
       openSourceForSelection,

package/src/contexts/PanelLayoutContext.tsx

@@ -25,6 +25,7 @@ export function PanelLayoutProvider({
     setRightPanelTab,
     rightInspectorPanes,
     toggleRightInspectorPane,
+    setExclusiveRightInspectorPane,
     toggleLeftSidebar,
     handlePanelResizeStart,
     handlePanelResizeMove,
@@ -49,6 +50,7 @@ export function PanelLayoutProvider({
       setRightPanelTab,
       rightInspectorPanes,
       toggleRightInspectorPane,
+      setExclusiveRightInspectorPane,
       toggleLeftSidebar,
       handlePanelResizeStart,
       handlePanelResizeMove,
@@ -67,6 +69,7 @@ export function PanelLayoutProvider({
       setRightPanelTab,
       rightInspectorPanes,
       toggleRightInspectorPane,
+      setExclusiveRightInspectorPane,
       toggleLeftSidebar,
       handlePanelResizeStart,
       handlePanelResizeMove,

package/src/hooks/timelineEditingHelpers.ts

@@ -262,7 +262,7 @@ export interface PersistTimelineEditInput {
   activeCompPath: string | null;
   label: string;
   buildPatches: (original: string, target: PatchTarget) => string;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
@@ -308,7 +308,7 @@ export interface PersistTimelineBatchEditInput {
   activeCompPath: string | null;
   label: string;
   changes: PersistTimelineBatchChange[];
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;

package/src/hooks/useDomEditCommits.test.tsx

@@ -34,7 +34,7 @@ interface RenderedDomEditCommits {
 
 interface RenderDomEditCommitsOptions {
   importedFontAssets?: ImportedFontAsset[];
-  writeProjectFile?: (path: string, content: string) => Promise<void>;
+  writeProjectFile?: (path: string, content: string, expectedContent?: string) => Promise<void>;
 }
 
 type FetchHandler = (
@@ -1050,6 +1050,46 @@ describe("useDomEditCommits style persist handling", () => {
     }
   });
 
+  it("uses the patched server content as the custom-font write precondition", async () => {
+    const patchedContent =
+      '<!doctype html><html><head></head><body><div data-hf-id="hf-card">Card</div></body></html>';
+    stubPatchFetch(
+      { ok: true, changed: true, matched: true, content: patchedContent },
+      patchedContent,
+    );
+    const { iframe, element } = createPreviewElement();
+    const selection = createSelection(element, {
+      textFields: [textField({ key: "self", value: "Card", source: "self", tagName: "div" })],
+    });
+    const writeProjectFile = vi.fn(async () => {});
+    const rendered = renderDomEditCommits(selection, iframe, { writeProjectFile });
+
+    try {
+      await act(async () => {
+        await rendered.hook.commitDomTextFields(
+          selection,
+          [textField({ key: "self", value: "Card", source: "self", tagName: "div" })],
+          {
+            importedFont: {
+              family: "Imported",
+              path: "fonts/Imported.woff2",
+              url: "/api/projects/p1/preview/fonts/Imported.woff2",
+            },
+          },
+        );
+      });
+
+      expect(writeProjectFile).toHaveBeenCalledWith(
+        "index.html",
+        expect.stringContaining("@font-face"),
+        patchedContent,
+      );
+      expect(rendered.showToast).not.toHaveBeenCalled();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
   it("keeps a rejected patch request (HTTP error) to one toast", async () => {
     const { rendered, cleanup } = renderStyleCommitWithFetch(async (input) => {
       const url = requestUrl(input);

package/src/hooks/useDomEditCommits.ts

@@ -46,7 +46,7 @@ export interface UseDomEditCommitsParams {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
   fileTree: string[];
@@ -245,7 +245,7 @@ export function useDomEditCommits({
         const preparedContent = options.prepareContent(patchedContent, targetPath);
         if (preparedContent !== patchedContent) {
           try {
-            await writeProjectFile(targetPath, preparedContent);
+            await writeProjectFile(targetPath, preparedContent, patchedContent);
             finalContent = preparedContent;
           } catch (error) {
             // The patch above already landed on disk — only the prepareContent

package/src/hooks/useDomEditSession.ts

@@ -45,7 +45,7 @@ export interface UseDomEditSessionParams {
   refreshPreviewDocumentVersion: () => void;
   queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
   readProjectFile: (path: string) => Promise<string>;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   updateEditingFileContent: (path: string, content: string) => void;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };

package/src/hooks/useEditorSave.ts

@@ -14,7 +14,7 @@ interface UseEditorSaveOptions {
   editingPathRef: React.RefObject<string | undefined>;
   projectIdRef: React.RefObject<string | null>;
   readProjectFile: (path: string) => Promise<string>;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   setRefreshKey: React.Dispatch<React.SetStateAction<number>>;

package/src/hooks/useFileManager.projectOwnership.test.tsx

@@ -38,14 +38,17 @@ describe("useFileManager project ownership", () => {
       resolveProjectARead = resolve;
     });
     const fetchMock = vi.fn((url: string, init?: RequestInit) => {
+      if (url.endsWith("/files/missing.html") && !init?.method) {
+        return Promise.resolve({ ok: false, status: 404 } as Response);
+      }
       if (url.includes("project-a") && !init?.method) return projectARead;
       if (!init?.method) {
         return Promise.resolve({
           ok: true,
-          json: async () => ({ content: "PROJECT_B" }),
+          json: async () => ({ content: "PROJECT_B", version: "b-v1" }),
         } as Response);
       }
-      return Promise.resolve({ ok: true } as Response);
+      return Promise.resolve({ ok: true, json: async () => ({ version: "a-v2" }) } as Response);
     });
     vi.stubGlobal("fetch", fetchMock);
 
@@ -74,10 +77,11 @@ describe("useFileManager project ownership", () => {
 
     resolveProjectARead?.({
       ok: true,
-      json: async () => ({ content: "PROJECT_A" }),
+      json: async () => ({ content: "PROJECT_A", version: "a-v1" }),
     } as Response);
     await expect(delayedRead).resolves.toBe("PROJECT_A");
     await managerA.writeProjectFile("index.html", "A_AFTER");
+    await managerA.writeProjectFile("missing.html", "A_NEW");
     await expect(managerB.readProjectFile("index.html")).resolves.toBe("PROJECT_B");
     await expect(managerB.readOptionalProjectFile("index.html")).resolves.toBe("PROJECT_B");
 
@@ -88,6 +92,13 @@ describe("useFileManager project ownership", () => {
       "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/index.html",
       expect.objectContaining({ method: "PUT", body: "A_AFTER" }),
     );
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/missing.html",
+    );
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/missing.html",
+      expect.objectContaining({ method: "PUT", body: "A_NEW" }),
+    );
     expect(fetchMock).toHaveBeenCalledWith("/api/projects/project-b%23fragment/files/index.html");
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-b%23fragment/files/index.html?optional=1",

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