@hyperframes/studio 0.6.6 → 0.6.7

package/src/player/hooks/useTimelinePlayer.ts

@@ -37,7 +37,11 @@ import {
   mergeTimelineElementsPreservingDowngrades,
   parseTimelineFromDOM,
 } from "../lib/timelineDOM";
-import { unmutePreviewMedia } from "../lib/timelineIframeHelpers";
+import {
+  setPreviewMediaMuted,
+  setPreviewPlaybackRate,
+  shouldMutePreviewAudio,
+} from "../lib/timelineIframeHelpers";
 
 // ---------------------------------------------------------------------------
 // Hook
@@ -218,11 +222,7 @@ export function useTimelinePlayer() {
   const applyPlaybackRate = useCallback((rate: number) => {
     const iframe = iframeRef.current;
     if (!iframe) return;
-    // Send to runtime via bridge (works with both new and CDN runtime)
-    iframe.contentWindow?.postMessage(
-      { source: "hf-parent", type: "control", action: "set-playback-rate", playbackRate: rate },
-      "*",
-    );
+    setPreviewPlaybackRate(iframe, rate);
     // Also set directly on GSAP timeline if accessible
     try {
       const win = iframe.contentWindow as IframeWindow | null;
@@ -241,6 +241,15 @@ export function useTimelinePlayer() {
     }
   }, []);
 
+  const applyPreviewAudioState = useCallback((playbackRateOverride?: number) => {
+    const { audioMuted, playbackRate } = usePlayerStore.getState();
+    const effectivePlaybackRate = playbackRateOverride ?? playbackRate;
+    setPreviewMediaMuted(
+      iframeRef.current,
+      shouldMutePreviewAudio(audioMuted, effectivePlaybackRate),
+    );
+  }, []);
+
   const play = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
@@ -249,13 +258,21 @@ export function useTimelinePlayer() {
     if (adapter.getTime() >= adapter.getDuration()) {
       adapter.seek(usePlayerStore.getState().inPoint ?? 0);
     }
-    unmutePreviewMedia(iframeRef.current);
     applyPlaybackRate(usePlayerStore.getState().playbackRate);
+    applyPreviewAudioState();
     adapter.play();
     shuttleDirectionRef.current = "forward";
     setIsPlaying(true);
     startRAFLoop();
-  }, [getAdapter, setIsPlaying, startRAFLoop, applyPlaybackRate, stopRAFLoop, stopReverseLoop]);
+  }, [
+    getAdapter,
+    setIsPlaying,
+    startRAFLoop,
+    applyPlaybackRate,
+    applyPreviewAudioState,
+    stopRAFLoop,
+    stopReverseLoop,
+  ]);
 
   const playBackward = useCallback(
     (rate: number) => {
@@ -267,8 +284,9 @@ export function useTimelinePlayer() {
       const initialTime = adapter.getTime() <= 0 && duration > 0 ? duration : adapter.getTime();
       adapter.pause();
       if (initialTime !== adapter.getTime()) adapter.seek(initialTime);
-      unmutePreviewMedia(iframeRef.current);
       const speed = Math.max(0.1, Math.min(4, rate));
+      applyPlaybackRate(speed);
+      applyPreviewAudioState(speed);
       let startTime = initialTime;
       let startedAt = performance.now();
 
@@ -305,7 +323,15 @@ export function useTimelinePlayer() {
       shuttleDirectionRef.current = "backward";
       reverseRafRef.current = requestAnimationFrame(tick);
     },
-    [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop],
+    [
+      getAdapter,
+      setCurrentTime,
+      setIsPlaying,
+      applyPlaybackRate,
+      applyPreviewAudioState,
+      stopRAFLoop,
+      stopReverseLoop,
+    ],
   );
 
   const pause = useCallback(() => {
@@ -321,21 +347,39 @@ export function useTimelinePlayer() {
   }, [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop]);
 
   const seek = useCallback(
-    (time: number) => {
+    (time: number, options?: { keepPlaying?: boolean }) => {
+      // Reverse shuttle is always stopped: the RAF reverse tick can't survive
+      // a seek anyway, so `keepPlaying` only preserves forward playback.
+      const wasReverseShuttle = shuttleDirectionRef.current === "backward";
       stopReverseLoop();
       const adapter = getAdapter();
-      if (!adapter) return;
+      if (!adapter) {
+        pendingSeekRef.current = Math.max(0, time);
+        return false;
+      }
       const duration = Math.max(0, adapter.getDuration());
       const nextTime = Math.max(0, duration > 0 ? Math.min(duration, time) : time);
-      adapter.seek(nextTime);
+      adapter.seek(nextTime, options);
       liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
-      stopRAFLoop();
-      if (usePlayerStore.getState().isPlaying) setIsPlaying(false);
-      shuttleDirectionRef.current = null;
-      shuttleSpeedIndexRef.current = 0;
+      if (!options?.keepPlaying || wasReverseShuttle) {
+        stopRAFLoop();
+        if (usePlayerStore.getState().isPlaying) setIsPlaying(false);
+        shuttleDirectionRef.current = null;
+        shuttleSpeedIndexRef.current = 0;
+      }
+      return true;
     },
-    [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop],
+    [
+      getAdapter,
+      pendingSeekRef,
+      setCurrentTime,
+      setIsPlaying,
+      stopRAFLoop,
+      stopReverseLoop,
+      shuttleDirectionRef,
+      shuttleSpeedIndexRef,
+    ],
   );
 
   // Handle seek requests from outside the player loop (e.g. LayersPanel).
@@ -374,6 +418,7 @@ export function useTimelinePlayer() {
       setTimelineReady,
       setIsPlaying,
       attachIframeShortcutListeners,
+      applyPreviewAudioState,
     });
 
   const saveSeekPosition = useCallback(() => {
@@ -498,6 +543,19 @@ export function useTimelinePlayer() {
     usePlayerStore.getState().reset();
   }, [stopRAFLoop, stopReverseLoop]);
 
+  useEffect(() => {
+    return usePlayerStore.subscribe((state, prev) => {
+      const playbackRateChanged = state.playbackRate !== prev.playbackRate;
+      const audioMutedChanged = state.audioMuted !== prev.audioMuted;
+      if (!playbackRateChanged && !audioMutedChanged) return;
+
+      if (playbackRateChanged) {
+        applyPlaybackRate(state.playbackRate);
+      }
+      applyPreviewAudioState();
+    });
+  }, [applyPlaybackRate, applyPreviewAudioState]);
+
   return {
     iframeRef,
     play,

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,6 +38,7 @@ 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;
@@ -52,6 +53,7 @@ interface PlayerState {
   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;
@@ -96,6 +98,7 @@ export const usePlayerStore = create<PlayerState>((set) => ({
   elements: [],
   selectedElementId: null,
   playbackRate: readStudioUiPreferences().playbackRate ?? 1,
+  audioMuted: readStudioUiPreferences().audioMuted ?? false,
   loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
@@ -111,6 +114,10 @@ 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) =>
@@ -120,6 +127,9 @@ export const usePlayerStore = create<PlayerState>((set) => ({
         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) =>
@@ -128,6 +138,7 @@ export const usePlayerStore = create<PlayerState>((set) => ({
       return {
         outPoint: t,
         inPoint: t !== null && state.inPoint !== null && t <= state.inPoint ? null : state.inPoint,
+        loopEnabled: t !== null ? true : state.loopEnabled,
       };
     }),
   setManualZoomPercent: (percent) =>
@@ -144,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({

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");