@hyperframes/studio 0.7.59 → 0.7.61

package/src/hooks/useRazorSplit.ts

@@ -16,7 +16,8 @@ interface UseRazorSplitOptions {
   projectId: string | null;
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  observeProjectFileVersion?: (path: string, version: string | null) => void;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   reloadPreview: () => void;
@@ -48,7 +49,7 @@ async function splitHtmlElement(
   newId: string,
   elementStart: number,
   elementDuration: number,
-): Promise<{ ok: boolean; changed?: boolean; content?: string }> {
+): Promise<{ ok: boolean; changed?: boolean; content?: string; version: string }> {
   const response = await fetch(
     `/api/projects/${projectId}/file-mutations/split-element/${encodeURIComponent(targetPath)}`,
     {
@@ -64,9 +65,18 @@ async function splitHtmlElement(
     },
   );
   if (!response.ok) throw new Error("Split request failed");
-  return (await response.json()) as { ok: boolean; changed?: boolean; content?: string };
+  const data = (await response.json()) as {
+    ok: boolean;
+    changed?: boolean;
+    content?: string;
+    version?: string;
+  };
+  const version = data.version ?? response.headers.get("etag");
+  if (!version) throw new Error("Split response did not include a content version");
+  return { ...data, version };
 }
 
+// fallow-ignore-next-line complexity
 async function splitGsapAnimations(
   projectId: string,
   targetPath: string,
@@ -75,7 +85,7 @@ async function splitGsapAnimations(
   splitTime: number,
   elementStart: number,
   elementDuration: number,
-): Promise<{ content: string | null; skippedSelectors?: string[] }> {
+): Promise<{ content: string | null; version?: string; skippedSelectors?: string[] }> {
   const response = await fetch(
     `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(targetPath)}`,
     {
@@ -101,10 +111,12 @@ async function splitGsapAnimations(
   const data = (await response.json()) as {
     ok?: boolean;
     after?: string;
+    version?: string;
     skippedSelectors?: string[];
   };
   return {
     content: data.ok && data.after ? data.after : null,
+    version: data.version ?? response.headers.get("etag") ?? undefined,
     skippedSelectors: data.skippedSelectors,
   };
 }
@@ -119,11 +131,11 @@ function getOriginalContent(originals: ReadonlyMap<string, string>, path: string
 
 async function restoreFilesToOriginal(
   originals: ReadonlyMap<string, string>,
-  paths: Iterable<string>,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  snapshots: ReadonlyMap<string, { before: string; after: string }>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
 ): Promise<void> {
-  for (const path of paths) {
-    await writeProjectFile(path, getOriginalContent(originals, path));
+  for (const [path, snapshot] of snapshots) {
+    await writeProjectFile(path, getOriginalContent(originals, path), snapshot.after);
   }
 }
 
@@ -149,17 +161,25 @@ async function splitElementsAtTime(
   activeCompPath: string | null,
   originals: ReadonlyMap<string, string>,
   snapshots: Map<string, { before: string; after: string }>,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+  observeProjectFileVersion?: (path: string, version: string | null) => void,
 ): Promise<number> {
   let count = 0;
   for (const element of elements) {
-    const result = await executeSplit(pid, element, splitTime, activeCompPath, writeProjectFile);
+    const result = await executeSplit(
+      pid,
+      element,
+      splitTime,
+      activeCompPath,
+      writeProjectFile,
+      observeProjectFileVersion,
+    );
     if (!result.changed) continue;
     snapshots.set(result.targetPath, {
       before: getOriginalContent(originals, result.targetPath),
       after: result.patchedContent,
     });
-    await writeProjectFile(result.targetPath, result.patchedContent);
+    await writeProjectFile(result.targetPath, result.patchedContent, result.patchedContent);
     count++;
   }
   return count;
@@ -171,7 +191,8 @@ async function executeSplit(
   element: TimelineElement,
   splitTime: number,
   activeCompPath: string | null,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+  observeProjectFileVersion?: (path: string, version: string | null) => void,
 ): Promise<{
   targetPath: string;
   originalContent: string;
@@ -209,6 +230,7 @@ async function executeSplit(
   if (!splitResult.changed) {
     return { targetPath, originalContent, patchedContent: originalContent, changed: false };
   }
+  observeProjectFileVersion?.(targetPath, splitResult.version);
 
   let patchedContent =
     typeof splitResult.content === "string" ? splitResult.content : originalContent;
@@ -226,11 +248,12 @@ async function executeSplit(
         element.duration,
       );
       if (gsapResult.content) patchedContent = gsapResult.content;
+      if (gsapResult.version) observeProjectFileVersion?.(targetPath, gsapResult.version);
       if (gsapResult.skippedSelectors?.length) skippedSelectors = gsapResult.skippedSelectors;
     } catch (gsapError) {
       // GSAP mutation failed — the HTML split already wrote to disk.
       // Restore the original content to avoid a corrupt half-split state.
-      await writeProjectFile(targetPath, originalContent);
+      await writeProjectFile(targetPath, originalContent, patchedContent);
       throw gsapError;
     }
   }
@@ -243,6 +266,7 @@ export function useRazorSplit({
   activeCompPath,
   showToast,
   writeProjectFile,
+  observeProjectFileVersion,
   recordEdit,
   domEditSaveTimestampRef,
   reloadPreview,
@@ -265,7 +289,14 @@ export function useRazorSplit({
 
       try {
         const { targetPath, originalContent, patchedContent, changed, skippedSelectors } =
-          await executeSplit(pid, element, splitTime, activeCompPath, writeProjectFile);
+          await executeSplit(
+            pid,
+            element,
+            splitTime,
+            activeCompPath,
+            writeProjectFile,
+            observeProjectFileVersion,
+          );
 
         if (!changed) {
           showToast("Failed to split clip — playhead may be outside the clip", "error");
@@ -305,6 +336,7 @@ export function useRazorSplit({
       recordEdit,
       showToast,
       writeProjectFile,
+      observeProjectFileVersion,
       domEditSaveTimestampRef,
       reloadPreview,
       forceReloadSdkSession,
@@ -312,8 +344,8 @@ export function useRazorSplit({
     ],
   );
 
-  // fallow-ignore-next-line complexity
   const handleRazorSplitAll = useCallback(
+    // fallow-ignore-next-line complexity
     async (splitTime: number) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -338,6 +370,7 @@ export function useRazorSplit({
           originals,
           finalSnapshots,
           writeProjectFile,
+          observeProjectFileVersion,
         );
         if (splitCount === 0) return;
 
@@ -358,7 +391,7 @@ export function useRazorSplit({
         // Best-effort rollback — a failing restore write must not swallow the
         // original error's toast, which is what tells the user the split failed.
         try {
-          await restoreFilesToOriginal(originals, finalSnapshots.keys(), writeProjectFile);
+          await restoreFilesToOriginal(originals, finalSnapshots, writeProjectFile);
         } catch {
           /* leave disk as-is; the original failure is reported below */
         }
@@ -371,6 +404,7 @@ export function useRazorSplit({
       recordEdit,
       showToast,
       writeProjectFile,
+      observeProjectFileVersion,
       domEditSaveTimestampRef,
       reloadPreview,
       forceReloadSdkSession,

package/src/hooks/useSlideshowTabState.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { useSlideshowTabState } from "./useSlideshowTabState";
+import type { RightPanelTab } from "../utils/studioHelpers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const SLIDESHOW_HTML = `<html><body><script type="application/hyperframes-slideshow+json">{"slides":[]}</script></body></html>`;
+const PLAIN_HTML = `<html><body><div id="title">hi</div></body></html>`;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function renderHook(params: {
+  editingFileContent: string | null | undefined;
+  rightPanelTab: RightPanelTab;
+}) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const setRightPanelTabCalls: RightPanelTab[] = [];
+  let current: ReturnType<typeof useSlideshowTabState> | null = null;
+
+  function Harness() {
+    current = useSlideshowTabState({
+      editingFileContent: params.editingFileContent,
+      previewIframeRef: { current: null },
+      refreshKey: 0,
+      rightPanelTab: params.rightPanelTab,
+      setRightPanelTab: (tab) => setRightPanelTabCalls.push(tab),
+    });
+    return null;
+  }
+
+  act(() => {
+    root.render(React.createElement(Harness));
+  });
+
+  return {
+    getState: (): ReturnType<typeof useSlideshowTabState> => {
+      if (!current) throw new Error("useSlideshowTabState did not render");
+      return current;
+    },
+    setRightPanelTabCalls,
+    unmount: () => act(() => root.unmount()),
+  };
+}
+
+describe("useSlideshowTabState", () => {
+  it("detects a slideshow composition via the JSON island", () => {
+    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(true);
+    harness.unmount();
+  });
+
+  it("reports false for a plain (non-slideshow) composition", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(false);
+    harness.unmount();
+  });
+
+  it("reports false when there is no editing file yet", () => {
+    const harness = renderHook({ editingFileContent: undefined, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(false);
+    harness.unmount();
+  });
+
+  it("still detects a malformed island — presence-only, not full manifest validation", () => {
+    const malformed = `<html><body><script type="application/hyperframes-slideshow+json">{not valid json</script></body></html>`;
+    const harness = renderHook({ editingFileContent: malformed, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(true);
+    harness.unmount();
+  });
+
+  it("bounces rightPanelTab off 'slideshow' to 'renders' on a non-slideshow composition", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "slideshow" });
+    expect(harness.setRightPanelTabCalls).toEqual(["renders"]);
+    harness.unmount();
+  });
+
+  it("does not bounce when the composition is a slideshow", () => {
+    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "slideshow" });
+    expect(harness.setRightPanelTabCalls).toEqual([]);
+    harness.unmount();
+  });
+
+  it("does not bounce a tab other than 'slideshow'", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "renders" });
+    expect(harness.setRightPanelTabCalls).toEqual([]);
+    harness.unmount();
+  });
+});

package/src/hooks/useSlideshowTabState.ts

@@ -0,0 +1,61 @@
+import { useEffect, useMemo, type MutableRefObject } from "react";
+import { SLIDESHOW_ISLAND_TYPE, slideshowIslandRegex } from "@hyperframes/core/slideshow";
+import type { SceneInfo } from "../components/panels/SlideshowPanel";
+import type { IframeWindow } from "../player/lib/playbackTypes";
+import type { RightPanelTab } from "../utils/studioHelpers";
+
+/**
+ * Derives whether the currently-edited composition is a slideshow (carries
+ * the slideshow JSON island — the same definitive marker the CLI's `present`
+ * command requires; it refuses to run without one) and the live scene list
+ * for the Slideshow panel, and bounces `rightPanelTab` off "slideshow" the
+ * moment it stops applying (e.g. the user switches to a non-slideshow file
+ * while that tab was open) so the panel never shows a dangling active tab
+ * whose button is no longer even rendered.
+ *
+ * Extracted from StudioRightPanel to keep that file under the 600-LOC gate.
+ */
+export function useSlideshowTabState(params: {
+  editingFileContent: string | null | undefined;
+  previewIframeRef: MutableRefObject<HTMLIFrameElement | null>;
+  refreshKey: number;
+  rightPanelTab: RightPanelTab;
+  setRightPanelTab: (tab: RightPanelTab) => void;
+}): { isSlideshowComposition: boolean; slideshowScenes: SceneInfo[] } {
+  const { editingFileContent, previewIframeRef, refreshKey, rightPanelTab, setRightPanelTab } =
+    params;
+
+  // Presence-only (not full manifest validation): a malformed island should
+  // still surface the Slideshow tab so the user can see/fix it, rather than
+  // making the whole panel disappear. The plain substring check short-circuits
+  // the regex scan on every non-slideshow file (the common case) without
+  // paying for a full-content RegExp pass.
+  const isSlideshowComposition = useMemo(() => {
+    if (!editingFileContent || !editingFileContent.includes(SLIDESHOW_ISLAND_TYPE)) return false;
+    return slideshowIslandRegex("i").test(editingFileContent);
+  }, [editingFileContent]);
+
+  // Derive scene list from the live clip manifest in the preview iframe.
+  const slideshowScenes = useMemo<SceneInfo[]>(() => {
+    try {
+      const win = previewIframeRef.current?.contentWindow as IframeWindow | null;
+      return (win?.__clipManifest?.scenes ?? []).map((s) => ({
+        id: s.id,
+        label: s.label,
+        start: s.start,
+        duration: s.duration,
+      }));
+    } catch {
+      return [];
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [previewIframeRef, rightPanelTab, refreshKey]);
+
+  useEffect(() => {
+    if (rightPanelTab === "slideshow" && !isSlideshowComposition) {
+      setRightPanelTab("renders");
+    }
+  }, [rightPanelTab, isSlideshowComposition, setRightPanelTab]);
+
+  return { isSlideshowComposition, slideshowScenes };
+}

package/src/hooks/useTimelineEditing.ts

@@ -46,6 +46,7 @@ export function useTimelineEditing({
   timelineElements,
   showToast,
   writeProjectFile,
+  observeProjectFileVersion,
   recordEdit,
   domEditSaveTimestampRef,
   reloadPreview,
@@ -503,6 +504,7 @@ export function useTimelineEditing({
     activeCompPath,
     showToast,
     writeProjectFile,
+    observeProjectFileVersion,
     recordEdit,
     domEditSaveTimestampRef,
     reloadPreview,

package/src/hooks/useTimelineEditingTypes.ts

@@ -31,7 +31,8 @@ export interface UseTimelineEditingOptions {
   activeCompPath: string | null;
   timelineElements: TimelineElement[];
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  observeProjectFileVersion?: (path: string, version: string | null) => void;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: MutableRefObject<number>;
   reloadPreview: () => void;

package/src/hooks/useTimelineGroupEditing.ts

@@ -60,7 +60,7 @@ interface UseTimelineGroupEditingOptions {
   sdkSession?: Composition | null;
   publishSdkSession?: PublishSdkSession;
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
 }
 
 function targetPathFor(element: TimelineElement, activeCompPath: string | null): string {

package/src/player/lib/playbackTypes.ts

@@ -50,9 +50,16 @@ export interface ClipManifestClip {
 }
 
 export interface ClipManifest {
+  protocolVersion?: number;
+  compositionContractVersion?: number;
+  capabilities?: readonly string[];
+  fps?: { numerator: number; denominator: number };
+  durationSeconds?: number;
   clips: ClipManifestClip[];
   scenes: Array<{ id: string; label: string; start: number; duration: number }>;
   durationInFrames: number;
+  compositionWidth?: number;
+  compositionHeight?: number;
 }
 
 export type IframeWindow = Window & {

package/src/player/lib/runtimeProtocol.test.ts

@@ -14,7 +14,12 @@ describe("Studio runtime protocol", () => {
       type: "control",
       action: "seek",
       protocolVersion: 1,
-      capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
+      capabilities: [
+        "seconds-time",
+        "rational-fps",
+        "seek-keep-playing",
+        "composition-manifest-v1",
+      ],
       fps: { numerator: 60, denominator: 1 },
       timeSeconds: 1.25,
     });

package/src/player/lib/timelineDOM.ts

@@ -11,6 +11,7 @@
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
+import { readClipTiming } from "@hyperframes/core/composition-contract";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -255,24 +256,20 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     if (node === rootComp) return;
     if (isTimelineIgnoredElement(node)) return;
     const el = node as HTMLElement;
-    const startStr = el.getAttribute("data-start");
-    if (startStr == null) return;
-    const start = parseFloat(startStr);
-    if (isNaN(start)) return;
+    const timing = readClipTiming(el);
+    const start = timing.start;
+    if (start == null) return;
     if (Number.isFinite(rootDuration) && rootDuration > 0 && start >= rootDuration) return;
 
     const tagLower = el.tagName.toLowerCase();
-    let dur = 0;
-    const durStr = el.getAttribute("data-duration");
-    if (durStr != null) dur = parseFloat(durStr);
-    if (isNaN(dur) || dur <= 0) dur = Math.max(0, rootDuration - start);
+    let dur = timing.duration ?? 0;
+    if (dur <= 0) dur = Math.max(0, rootDuration - start);
     if (Number.isFinite(rootDuration) && rootDuration > 0) {
       dur = Math.min(dur, Math.max(0, rootDuration - start));
     }
     if (!Number.isFinite(dur) || dur <= 0) return;
 
-    const trackStr = el.getAttribute("data-track-index");
-    const track = trackStr != null ? parseInt(trackStr, 10) : trackCounter++;
+    const track = timing.trackSource === "default" ? trackCounter++ : timing.trackIndex;
     // fallow-ignore-next-line code-duplication
     const compId = el.getAttribute("data-composition-id");
     const selector = getTimelineElementSelector(el);
@@ -299,7 +296,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       tag: tagLower,
       start,
       duration: dur,
-      track: isNaN(track) ? 0 : track,
+      track,
       domId: el.id || undefined,
       hfId: el.getAttribute("data-hf-id") || undefined,
       selector,