@hyperframes/studio 0.7.59 → 0.7.61

package/src/components/storyboard/storyboardReviewStage.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { deriveStoryboardHandoffStep, deriveStoryboardReviewStage } from "./storyboardReviewStage";
+
+describe("deriveStoryboardReviewStage", () => {
+  it.each([
+    [[], "empty"],
+    [["outline", "outline"], "plan-review"],
+    [["outline", "built"], "sketch-in-progress"],
+    [["outline", "animated"], "sketch-in-progress"],
+    [["built", "built"], "sketch-review"],
+    [["built", "animated"], "animation-in-progress"],
+    [["animated", "animated"], "final-review"],
+  ] as const)("maps %j to %s", (statuses, expected) => {
+    expect(deriveStoryboardReviewStage(statuses.map((status) => ({ status }))).stage).toBe(
+      expected,
+    );
+  });
+
+  it("returns counts for the visible progress summary", () => {
+    expect(
+      deriveStoryboardReviewStage([
+        { status: "outline" },
+        { status: "built" },
+        { status: "animated" },
+        { status: "animated" },
+      ]).counts,
+    ).toEqual({ outline: 1, built: 1, animated: 2 });
+  });
+});
+
+describe("storyboard review handoff", () => {
+  it.each([
+    [0, 0, 1],
+    [2, 0, 2],
+    [0, 3, 3],
+    [1, 3, 2],
+  ] as const)("maps %i drafts and %i pending comments to step %i", (drafts, pending, step) => {
+    expect(deriveStoryboardHandoffStep(drafts, pending)).toBe(step);
+  });
+});

package/src/components/storyboard/storyboardReviewStage.ts

@@ -0,0 +1,45 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+export type StoryboardReviewStage =
+  | "empty"
+  | "plan-review"
+  | "sketch-in-progress"
+  | "sketch-review"
+  | "animation-in-progress"
+  | "final-review";
+
+export interface StoryboardReviewSummary {
+  stage: StoryboardReviewStage;
+  counts: Record<FrameStatus, number>;
+  frameCount: number;
+}
+
+export type StoryboardHandoffStep = 1 | 2 | 3;
+
+/** Current user action in the Studio → agent feedback handoff. */
+export function deriveStoryboardHandoffStep(
+  draftCount: number,
+  pendingCount: number,
+): StoryboardHandoffStep {
+  if (draftCount > 0) return 2;
+  if (pendingCount > 0) return 3;
+  return 1;
+}
+
+/** Derive the board-level review moment from agent-owned frame statuses. */
+export function deriveStoryboardReviewStage(
+  frames: ReadonlyArray<{ status: FrameStatus }>,
+): StoryboardReviewSummary {
+  const counts: Record<FrameStatus, number> = { outline: 0, built: 0, animated: 0 };
+  for (const frame of frames) counts[frame.status] += 1;
+
+  let stage: StoryboardReviewStage;
+  if (frames.length === 0) stage = "empty";
+  else if (counts.outline === frames.length) stage = "plan-review";
+  else if (counts.outline > 0) stage = "sketch-in-progress";
+  else if (counts.built === frames.length) stage = "sketch-review";
+  else if (counts.built > 0) stage = "animation-in-progress";
+  else stage = "final-review";
+
+  return { stage, counts, frameCount: frames.length };
+}

package/src/components/storyboard/useFrameComments.ts

@@ -17,8 +17,10 @@ export interface FrameCommentsValue {
   /** How many frames currently carry a non-empty draft. */
   draftCount: number;
   submitState: CommentsSubmitState;
+  /** Most recent submit failure, shown next to the submit action. */
+  submitError: string | null;
   /** Write the batch to `.hyperframes/frame-comments.json` and clear the drafts. */
-  submit: () => Promise<void>;
+  submit: () => Promise<boolean>;
   /**
    * Comments already submitted but not yet consumed by the agent (the file
    * still exists on disk). Refreshed on mount, after submit, and on window
@@ -34,6 +36,7 @@ export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsVa
   const { writeProjectFile, readOptionalProjectFile } = useFileManagerContext();
   const [drafts, setDrafts] = useState<Record<number, string>>({});
   const [submitState, setSubmitState] = useState<CommentsSubmitState>("idle");
+  const [submitError, setSubmitError] = useState<string | null>(null);
   const [pending, setPending] = useState<FrameCommentEntry[] | null>(null);
 
   const refreshPending = useCallback(async () => {
@@ -61,22 +64,35 @@ export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsVa
     [drafts],
   );
 
+  // One guarded async transaction owns loading, success, failure, and cleanup state.
+  // fallow-ignore-next-line complexity
   const submit = useCallback(async () => {
-    if (draftCount === 0 || submitState === "saving") return;
+    if (draftCount === 0 || submitState === "saving") return false;
     setSubmitState("saving");
+    setSubmitError(null);
     try {
       const previous = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
       const file = buildCommentsFile(frames, drafts, previous, new Date().toISOString());
       await writeProjectFile(FRAME_COMMENTS_PATH, `${JSON.stringify(file, null, 2)}\n`);
       setDrafts({});
       setPending(file.comments);
-    } catch {
-      // writeProjectFile surfaces save failures through the studio save banner;
-      // just re-arm the button so the user can retry.
+      return true;
+    } catch (err: unknown) {
+      setSubmitError(err instanceof Error ? err.message : "Failed to submit comments");
+      return false;
     } finally {
       setSubmitState("idle");
     }
   }, [draftCount, submitState, frames, drafts, readOptionalProjectFile, writeProjectFile]);
 
-  return { drafts, setDraft, draftCount, submitState, submit, pending, refreshPending };
+  return {
+    drafts,
+    setDraft,
+    draftCount,
+    submitState,
+    submitError,
+    submit,
+    pending,
+    refreshPending,
+  };
 }

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/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

@@ -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/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/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",