@hyperframes/studio 0.7.60 → 0.7.61

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