@hyperframes/studio 0.6.5 → 0.6.7

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -9,7 +9,7 @@
  */
 
 import { useCallback } from "react";
-import { usePlayerStore } from "../store/playerStore";
+import { liveTime, usePlayerStore } from "../store/playerStore";
 import type { TimelineElement } from "../store/playerStore";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
@@ -24,7 +24,6 @@ import {
 import {
   normalizePreviewViewport,
   autoHealMissingCompositionIds,
-  unmutePreviewMedia,
   buildMissingCompositionElements,
 } from "../lib/timelineIframeHelpers";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
@@ -41,6 +40,7 @@ interface UseTimelineSyncCallbacksParams {
   setTimelineReady: (v: boolean) => void;
   setIsPlaying: (v: boolean) => void;
   attachIframeShortcutListeners: () => void;
+  applyPreviewAudioState: () => void;
 }
 
 export function useTimelineSyncCallbacks({
@@ -55,6 +55,7 @@ export function useTimelineSyncCallbacks({
   setTimelineReady,
   setIsPlaying,
   attachIframeShortcutListeners,
+  applyPreviewAudioState,
 }: UseTimelineSyncCallbacksParams) {
   // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
   const processTimelineMessage = useCallback(
@@ -158,6 +159,9 @@ export function useTimelineSyncCallbacks({
     const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
 
     adapter.seek(startTime);
+    // Keep non-React listeners such as the capture link and time display in sync
+    // with the initial adapter seek on iframe load.
+    liveTime.notify(startTime);
     const adapterDur = adapter.getDuration();
     if (
       Number.isFinite(adapterDur) &&
@@ -189,6 +193,7 @@ export function useTimelineSyncCallbacks({
         processTimelineMessage(manifest);
       }
       enrichMissingCompositions();
+      applyPreviewAudioState();
 
       if (usePlayerStore.getState().elements.length === 0 && doc) {
         const els = parseTimelineFromDOM(doc, adapter.getDuration());
@@ -222,13 +227,14 @@ export function useTimelineSyncCallbacks({
     enrichMissingCompositions,
     syncTimelineElements,
     attachIframeShortcutListeners,
+    applyPreviewAudioState,
     iframeRef,
     isRefreshingRef,
     pendingSeekRef,
   ]);
 
   const onIframeLoad = useCallback(() => {
-    unmutePreviewMedia(iframeRef.current);
+    applyPreviewAudioState();
     if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
 
     // Fast path: adapter already available (in-place reloads, cached compositions)
@@ -267,7 +273,7 @@ export function useTimelineSyncCallbacks({
       }
       window.removeEventListener("message", onMessage);
     }, 5000) as unknown as ReturnType<typeof setInterval>;
-  }, [initializeAdapter, iframeRef, probeIntervalRef]);
+  }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
 
   // Stable refs so mount-effect closures always call the latest version
   const processTimelineMessageRef = { current: processTimelineMessage };

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

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from "vitest";
+import { wrapTimeline } from "./playbackAdapter";
+import type { TimelineLike } from "./playbackTypes";
+
+describe("wrapTimeline seek keepPlaying option (#834)", () => {
+  function mockTimeline(): TimelineLike & {
+    play: ReturnType<typeof vi.fn>;
+    pause: ReturnType<typeof vi.fn>;
+    seek: ReturnType<typeof vi.fn>;
+  } {
+    return {
+      play: vi.fn(),
+      pause: vi.fn(),
+      seek: vi.fn(),
+      time: () => 0,
+      duration: () => 10,
+      isActive: () => false,
+    };
+  }
+
+  it("default seek pauses the GSAP timeline before seeking", () => {
+    const tl = mockTimeline();
+    const adapter = wrapTimeline(tl);
+
+    adapter.seek(5);
+
+    expect(tl.pause).toHaveBeenCalledTimes(1);
+    expect(tl.seek).toHaveBeenCalledWith(5);
+  });
+
+  it("seek with { keepPlaying: true } skips the implicit pause", () => {
+    const tl = mockTimeline();
+    const adapter = wrapTimeline(tl);
+
+    adapter.seek(5, { keepPlaying: true });
+
+    expect(tl.pause).not.toHaveBeenCalled();
+    expect(tl.seek).toHaveBeenCalledWith(5);
+  });
+
+  it("seek with { keepPlaying: false } still pauses (explicit default)", () => {
+    const tl = mockTimeline();
+    const adapter = wrapTimeline(tl);
+
+    adapter.seek(5, { keepPlaying: false });
+
+    expect(tl.pause).toHaveBeenCalledTimes(1);
+    expect(tl.seek).toHaveBeenCalledWith(5);
+  });
+});

package/src/player/lib/playbackAdapter.ts

@@ -134,8 +134,8 @@ export function wrapTimeline(tl: TimelineLike): PlaybackAdapter {
   return {
     play: () => tl.play(),
     pause: () => tl.pause(),
-    seek: (t) => {
-      tl.pause();
+    seek: (t, options) => {
+      if (!options?.keepPlaying) tl.pause();
       tl.seek(t);
     },
     getTime: () => tl.time(),

package/src/player/lib/playbackTypes.ts

@@ -7,7 +7,7 @@
 export interface PlaybackAdapter {
   play: () => void;
   pause: () => void;
-  seek: (time: number) => void;
+  seek: (time: number, options?: { keepPlaying?: boolean }) => void;
   getTime: () => number;
   getDuration: () => number;
   isPlaying: () => boolean;

package/src/player/lib/timelineDOM.ts

@@ -2,7 +2,7 @@
  * Higher-level timeline DOM operations: element factories, DOM-to-element
  * parsing, timeline merging, and standalone composition helpers.
  *
- * Preview iframe utilities (normaliseViewport, autoHeal, unmute, resolveIframe,
+ * Preview iframe utilities (normaliseViewport, autoHeal, audio controls, resolveIframe,
  * buildMissingCompositionElements) live in timelineIframeHelpers.ts.
  *
  * Pure functions (no React, no store reads) — testable in isolation.
@@ -42,7 +42,9 @@ export {
 export {
   normalizePreviewViewport,
   autoHealMissingCompositionIds,
-  unmutePreviewMedia,
+  setPreviewMediaMuted,
+  setPreviewPlaybackRate,
+  shouldMutePreviewAudio,
   resolveIframe,
   buildMissingCompositionElements,
 } from "./timelineIframeHelpers";

package/src/player/lib/timelineIframeHelpers.ts

@@ -73,18 +73,74 @@ export function autoHealMissingCompositionIds(doc: Document): void {
 }
 
 // ---------------------------------------------------------------------------
-// Muting / iframe resolution
+// Audio / iframe resolution
 // ---------------------------------------------------------------------------
 
-export function unmutePreviewMedia(iframe: HTMLIFrameElement | null): void {
+type PreviewPlayerHost = HTMLElement & {
+  muted?: boolean;
+  playbackRate?: number;
+};
+
+function isPreviewPlayerHost(value: unknown): value is PreviewPlayerHost {
+  return value instanceof HTMLElement;
+}
+
+function resolvePreviewPlayerHost(iframe: HTMLIFrameElement): PreviewPlayerHost | null {
+  const root = iframe.getRootNode();
+  if (
+    typeof ShadowRoot !== "undefined" &&
+    root instanceof ShadowRoot &&
+    isPreviewPlayerHost(root.host)
+  ) {
+    return root.host;
+  }
+  return null;
+}
+
+function postPreviewControl(
+  iframe: HTMLIFrameElement,
+  action: string,
+  payload: Record<string, unknown>,
+): void {
+  iframe.contentWindow?.postMessage(
+    { source: "hf-parent", type: "control", action, ...payload },
+    "*",
+  );
+}
+
+export function shouldMutePreviewAudio(audioMuted: boolean, playbackRate: number): boolean {
+  return audioMuted || playbackRate > 1;
+}
+
+export function setPreviewMediaMuted(iframe: HTMLIFrameElement | null, muted: boolean): void {
   if (!iframe) return;
   try {
-    iframe.contentWindow?.postMessage(
-      { source: "hf-parent", type: "control", action: "set-muted", muted: false },
-      "*",
-    );
+    const host = resolvePreviewPlayerHost(iframe);
+    if (host && typeof host.muted === "boolean") {
+      host.muted = muted;
+      return;
+    }
+    postPreviewControl(iframe, "set-muted", { muted });
+  } catch (err) {
+    console.warn("[useTimelinePlayer] Failed to set preview media mute state", err);
+  }
+}
+
+export function setPreviewPlaybackRate(
+  iframe: HTMLIFrameElement | null,
+  playbackRate: number,
+): void {
+  if (!iframe) return;
+  const rate = Number.isFinite(playbackRate) && playbackRate > 0 ? playbackRate : 1;
+  try {
+    const host = resolvePreviewPlayerHost(iframe);
+    if (host && typeof host.playbackRate === "number") {
+      host.playbackRate = rate;
+      return;
+    }
+    postPreviewControl(iframe, "set-playback-rate", { playbackRate: rate });
   } catch (err) {
-    console.warn("[useTimelinePlayer] Failed to unmute preview media", err);
+    console.warn("[useTimelinePlayer] Failed to set preview playback rate", err);
   }
 }
 

package/src/player/store/playerStore.test.ts

@@ -16,6 +16,7 @@ describe("usePlayerStore", () => {
       expect(state.elements).toEqual([]);
       expect(state.selectedElementId).toBeNull();
       expect(state.playbackRate).toBe(1);
+      expect(state.audioMuted).toBe(false);
       expect(state.loopEnabled).toBe(false);
       expect(state.zoomMode).toBe("fit");
       expect(state.manualZoomPercent).toBe(100);
@@ -62,6 +63,13 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("setAudioMuted", () => {
+    it("updates audioMuted", () => {
+      usePlayerStore.getState().setAudioMuted(true);
+      expect(usePlayerStore.getState().audioMuted).toBe(true);
+    });
+  });
+
   describe("setLoopEnabled", () => {
     it("updates loopEnabled", () => {
       usePlayerStore.getState().setLoopEnabled(true);
@@ -69,6 +77,100 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("setInPoint", () => {
+    it("updates inPoint", () => {
+      usePlayerStore.getState().setInPoint(1.5);
+      expect(usePlayerStore.getState().inPoint).toBe(1.5);
+    });
+
+    it("clears inPoint when given null", () => {
+      usePlayerStore.getState().setInPoint(1.5);
+      usePlayerStore.getState().setInPoint(null);
+      expect(usePlayerStore.getState().inPoint).toBeNull();
+    });
+
+    it("rejects non-finite values", () => {
+      usePlayerStore.getState().setInPoint(Number.NaN);
+      expect(usePlayerStore.getState().inPoint).toBeNull();
+    });
+
+    it("nullifies outPoint when new inPoint is at or past existing outPoint", () => {
+      usePlayerStore.getState().setOutPoint(2);
+      usePlayerStore.getState().setInPoint(3);
+      expect(usePlayerStore.getState().outPoint).toBeNull();
+      expect(usePlayerStore.getState().inPoint).toBe(3);
+    });
+
+    it("preserves outPoint when new inPoint is before it", () => {
+      usePlayerStore.getState().setOutPoint(5);
+      usePlayerStore.getState().setInPoint(2);
+      expect(usePlayerStore.getState().outPoint).toBe(5);
+    });
+
+    it("auto-enables loopEnabled when set to a non-null value", () => {
+      usePlayerStore.getState().setLoopEnabled(false);
+      usePlayerStore.getState().setInPoint(1.5);
+      expect(usePlayerStore.getState().loopEnabled).toBe(true);
+    });
+
+    it("preserves loopEnabled when cleared with null", () => {
+      usePlayerStore.getState().setLoopEnabled(true);
+      usePlayerStore.getState().setInPoint(null);
+      expect(usePlayerStore.getState().loopEnabled).toBe(true);
+
+      usePlayerStore.getState().setLoopEnabled(false);
+      usePlayerStore.getState().setInPoint(null);
+      expect(usePlayerStore.getState().loopEnabled).toBe(false);
+    });
+  });
+
+  describe("setOutPoint", () => {
+    it("updates outPoint", () => {
+      usePlayerStore.getState().setOutPoint(4.2);
+      expect(usePlayerStore.getState().outPoint).toBe(4.2);
+    });
+
+    it("clears outPoint when given null", () => {
+      usePlayerStore.getState().setOutPoint(4.2);
+      usePlayerStore.getState().setOutPoint(null);
+      expect(usePlayerStore.getState().outPoint).toBeNull();
+    });
+
+    it("rejects non-finite values", () => {
+      usePlayerStore.getState().setOutPoint(Number.POSITIVE_INFINITY);
+      expect(usePlayerStore.getState().outPoint).toBeNull();
+    });
+
+    it("nullifies inPoint when new outPoint is at or before existing inPoint", () => {
+      usePlayerStore.getState().setInPoint(5);
+      usePlayerStore.getState().setOutPoint(3);
+      expect(usePlayerStore.getState().inPoint).toBeNull();
+      expect(usePlayerStore.getState().outPoint).toBe(3);
+    });
+
+    it("preserves inPoint when new outPoint is after it", () => {
+      usePlayerStore.getState().setInPoint(2);
+      usePlayerStore.getState().setOutPoint(5);
+      expect(usePlayerStore.getState().inPoint).toBe(2);
+    });
+
+    it("auto-enables loopEnabled when set to a non-null value", () => {
+      usePlayerStore.getState().setLoopEnabled(false);
+      usePlayerStore.getState().setOutPoint(4.2);
+      expect(usePlayerStore.getState().loopEnabled).toBe(true);
+    });
+
+    it("preserves loopEnabled when cleared with null", () => {
+      usePlayerStore.getState().setLoopEnabled(true);
+      usePlayerStore.getState().setOutPoint(null);
+      expect(usePlayerStore.getState().loopEnabled).toBe(true);
+
+      usePlayerStore.getState().setLoopEnabled(false);
+      usePlayerStore.getState().setOutPoint(null);
+      expect(usePlayerStore.getState().loopEnabled).toBe(false);
+    });
+  });
+
   describe("setTimelineReady", () => {
     it("updates timelineReady", () => {
       usePlayerStore.getState().setTimelineReady(true);
@@ -213,9 +315,10 @@ describe("usePlayerStore", () => {
       expect(state.selectedElementId).toBeNull();
     });
 
-    it("does not reset playbackRate, loopEnabled, zoomMode, or manualZoomPercent", () => {
+    it("does not reset playbackRate, audioMuted, loopEnabled, zoomMode, or manualZoomPercent", () => {
       const store = usePlayerStore.getState();
       store.setPlaybackRate(2);
+      store.setAudioMuted(true);
       store.setLoopEnabled(true);
       store.setZoomMode("manual");
       store.setManualZoomPercent(200);
@@ -225,6 +328,7 @@ describe("usePlayerStore", () => {
       const state = usePlayerStore.getState();
       // reset() only resets the fields explicitly listed in the reset function
       expect(state.playbackRate).toBe(2);
+      expect(state.audioMuted).toBe(true);
       expect(state.loopEnabled).toBe(true);
       expect(state.zoomMode).toBe("manual");
       expect(state.manualZoomPercent).toBe(200);

package/src/player/store/playerStore.ts

@@ -38,16 +38,22 @@ interface PlayerState {
   elements: TimelineElement[];
   selectedElementId: string | null;
   playbackRate: number;
+  audioMuted: boolean;
   loopEnabled: boolean;
   /** Timeline zoom: 'fit' auto-scales to viewport, 'manual' uses manualZoomPercent */
   zoomMode: ZoomMode;
   /** Timeline zoom percent relative to the fit width when in manual mode */
   manualZoomPercent: number;
+  /** Work-area in-point (seconds). When set, loop starts here and A jumps here. */
+  inPoint: number | null;
+  /** Work-area out-point (seconds). When set, loop ends here and E jumps here. */
+  outPoint: number | null;
 
   setIsPlaying: (playing: boolean) => void;
   setCurrentTime: (time: number) => void;
   setDuration: (duration: number) => void;
   setPlaybackRate: (rate: number) => void;
+  setAudioMuted: (muted: boolean) => void;
   setLoopEnabled: (enabled: boolean) => void;
   setTimelineReady: (ready: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
@@ -58,6 +64,8 @@ interface PlayerState {
   ) => void;
   setZoomMode: (mode: ZoomMode) => void;
   setManualZoomPercent: (percent: number) => void;
+  setInPoint: (time: number | null) => void;
+  setOutPoint: (time: number | null) => void;
   reset: () => void;
 
   /**
@@ -90,9 +98,12 @@ export const usePlayerStore = create<PlayerState>((set) => ({
   elements: [],
   selectedElementId: null,
   playbackRate: readStudioUiPreferences().playbackRate ?? 1,
+  audioMuted: readStudioUiPreferences().audioMuted ?? false,
   loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
+  inPoint: null,
+  outPoint: null,
 
   requestedSeekTime: null,
   requestSeek: (time) => set({ requestedSeekTime: time }),
@@ -103,8 +114,33 @@ export const usePlayerStore = create<PlayerState>((set) => ({
     writeStudioUiPreferences({ playbackRate: rate });
     set({ playbackRate: rate });
   },
+  setAudioMuted: (muted) => {
+    writeStudioUiPreferences({ audioMuted: muted });
+    set({ audioMuted: muted });
+  },
   setLoopEnabled: (enabled) => set({ loopEnabled: enabled }),
   setZoomMode: (mode) => set({ zoomMode: mode }),
+  setInPoint: (time) =>
+    set((state) => {
+      const t = time !== null && Number.isFinite(time) ? time : null;
+      return {
+        inPoint: t,
+        outPoint:
+          t !== null && state.outPoint !== null && t >= state.outPoint ? null : state.outPoint,
+        // Setting a work-area marker implies the user wants playback bounded by it.
+        // Auto-enable loop so the playhead respects the marker instead of running past.
+        loopEnabled: t !== null ? true : state.loopEnabled,
+      };
+    }),
+  setOutPoint: (time) =>
+    set((state) => {
+      const t = time !== null && Number.isFinite(time) ? time : null;
+      return {
+        outPoint: t,
+        inPoint: t !== null && state.inPoint !== null && t <= state.inPoint ? null : state.inPoint,
+        loopEnabled: t !== null ? true : state.loopEnabled,
+      };
+    }),
   setManualZoomPercent: (percent) =>
     set({ manualZoomPercent: Math.max(10, Math.min(2000, Math.round(percent))) }),
   setCurrentTime: (time) => set({ currentTime: Number.isFinite(time) ? time : 0 }),
@@ -119,7 +155,7 @@ export const usePlayerStore = create<PlayerState>((set) => ({
       ),
     })),
   // Resets project-specific state when switching compositions.
-  // playbackRate, loopEnabled, zoomMode, and manualZoomPercent are intentionally preserved
+  // playbackRate, audioMuted, loopEnabled, zoomMode, and manualZoomPercent are intentionally preserved
   // because they are user preferences that should survive project switches.
   reset: () =>
     set({
@@ -129,5 +165,7 @@ export const usePlayerStore = create<PlayerState>((set) => ({
       timelineReady: false,
       elements: [],
       selectedElementId: null,
+      inPoint: null,
+      outPoint: null,
     }),
 }));

package/src/utils/projectRouting.test.ts

@@ -4,6 +4,7 @@ import {
   buildProjectApiPath,
   buildProjectHash,
   encodeProjectId,
+  parseProjectHashRoute,
   parseProjectIdFromHash,
 } from "./projectRouting";
 
@@ -61,6 +62,20 @@ describe("project routing utilities", () => {
     expect(parseProjectIdFromHash(hash)).toBe("Mañana demo");
   });
 
+  it("parses project hash routes with query params", () => {
+    const route = parseProjectHashRoute("#project/Notion%20Showcase?tab=design&t=4.2");
+
+    expect(route?.projectId).toBe("Notion Showcase");
+    expect(route?.params.get("tab")).toBe("design");
+    expect(route?.params.get("t")).toBe("4.2");
+  });
+
+  it("builds hash routes with query params", () => {
+    expect(buildProjectHash("Notion Showcase", { tab: "design", t: "4.2" })).toBe(
+      "#project/Notion%20Showcase?tab=design&t=4.2",
+    );
+  });
+
   it("encodes project ids as one API path segment", () => {
     expect(encodeProjectId("Notion Showcase")).toBe("Notion%20Showcase");
     expect(encodeProjectId("Notion%20Showcase")).toBe("Notion%2520Showcase");

package/src/utils/projectRouting.ts

@@ -1,24 +1,61 @@
 const PROJECT_HASH_PREFIX = "#project/";
 
+export interface ProjectHashRoute {
+  projectId: string;
+  params: URLSearchParams;
+}
+
+function decodeHashProjectId(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function normalizeHashParams(
+  params?: URLSearchParams | Record<string, string | null | undefined>,
+): URLSearchParams {
+  if (!params) return new URLSearchParams();
+  if (params instanceof URLSearchParams) return params;
+
+  const next = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (!key || value == null || value === "") continue;
+    next.set(key, value);
+  }
+  return next;
+}
+
 export function encodeProjectId(projectId: string): string {
   return encodeURIComponent(projectId);
 }
 
-export function buildProjectHash(projectId: string): string {
-  return `${PROJECT_HASH_PREFIX}${encodeProjectId(projectId)}`;
+export function buildProjectHash(
+  projectId: string,
+  params?: URLSearchParams | Record<string, string | null | undefined>,
+): string {
+  const search = normalizeHashParams(params).toString();
+  return `${PROJECT_HASH_PREFIX}${encodeProjectId(projectId)}${search ? `?${search}` : ""}`;
 }
 
-export function parseProjectIdFromHash(hash: string): string | null {
+export function parseProjectHashRoute(hash: string): ProjectHashRoute | null {
   if (!hash.startsWith(PROJECT_HASH_PREFIX)) return null;
 
-  const encodedProjectId = hash.slice(PROJECT_HASH_PREFIX.length);
+  const route = hash.slice(PROJECT_HASH_PREFIX.length);
+  const queryIndex = route.indexOf("?");
+  const encodedProjectId = queryIndex >= 0 ? route.slice(0, queryIndex) : route;
   if (!encodedProjectId || encodedProjectId.includes("/")) return null;
 
-  try {
-    return decodeURIComponent(encodedProjectId);
-  } catch {
-    return encodedProjectId;
-  }
+  const rawParams = queryIndex >= 0 ? route.slice(queryIndex + 1) : "";
+  return {
+    projectId: decodeHashProjectId(encodedProjectId),
+    params: new URLSearchParams(rawParams),
+  };
+}
+
+export function parseProjectIdFromHash(hash: string): string | null {
+  return parseProjectHashRoute(hash)?.projectId ?? null;
 }
 
 export function buildProjectApiPath(projectId: string, suffix = ""): string {