@hyperframes/studio 0.6.6 → 0.6.7

package/src/hooks/useManifestPersistence.ts

@@ -1,15 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useMountEffect } from "./useMountEffect";
 import {
-  STUDIO_MANUAL_EDITS_PATH,
-  applyStudioManualEditManifest,
-  emptyStudioManualEditManifest,
   installStudioManualEditSeekReapply,
-  isStudioManualEditManifestPath,
-  parseStudioManualEditManifest,
+  reapplyPositionEditsAfterSeek,
   readStudioFileChangePath,
-  serializeStudioManualEditManifest,
-  type StudioManualEditManifest,
 } from "../components/editor/manualEdits";
 import {
   STUDIO_MOTION_PATH,
@@ -41,6 +35,11 @@ interface UseManifestPersistenceParams {
   recordEdit: (entry: RecordEditInput) => Promise<void>;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   activeCompPathRef: React.MutableRefObject<string | null>;
+  /** Shared timestamp ref — written by any studio save (code tab, timeline, DOM edits).
+   *  Used to suppress SSE echoes so we don't double-reload after our own saves. */
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  /** Called to reload the preview after undo/redo or external file changes. */
+  reloadPreview: () => void;
 }
 
 // ── Hook ──
@@ -48,21 +47,19 @@ interface UseManifestPersistenceParams {
 export function useManifestPersistence({
   projectId,
   showToast,
-  readOptionalProjectFile,
+  readOptionalProjectFile: _readOptionalProjectFile,
   writeProjectFile,
   recordEdit,
   previewIframeRef,
   activeCompPathRef,
+  domEditSaveTimestampRef,
+  reloadPreview,
 }: UseManifestPersistenceParams) {
-  const [, setStudioMotionRevision] = useState(0);
+  void _readOptionalProjectFile;
 
-  const domEditSaveTimestampRef = useRef(0);
+  const [, setStudioMotionRevision] = useState(0);
   const domTextCommitVersionRef = useRef(0);
   const domEditSaveQueueRef = useRef(Promise.resolve());
-  const studioManualEditManifestRef = useRef<StudioManualEditManifest>(
-    emptyStudioManualEditManifest(),
-  );
-  const studioManualEditRevisionRef = useRef(0);
   const studioMotionManifestRef = useRef<StudioMotionManifest>(emptyStudioMotionManifest());
   const studioMotionRevisionRef = useRef(0);
   const applyStudioManualEditsToPreviewRef = useRef<
@@ -77,9 +74,7 @@ export function useManifestPersistence({
       options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
     ) => Promise<void>
   >(async () => {});
-  const manifestBootstrappedRef = useRef(false);
   const motionBootstrappedRef = useRef(false);
-  const studioManualEditProjectRef = useRef<string | null>(projectId);
 
   // Keep a ref to the latest projectId so async save callbacks always read the
   // current value, even when the callback was captured in a stale closure.
@@ -101,7 +96,7 @@ export function useManifestPersistence({
     await domEditSaveQueueRef.current.catch(() => undefined);
   }, []);
 
-  // ── Apply manual edits ──
+  // ── Apply manual edits (HTML-baked — just install seek hooks) ──
 
   const applyCurrentStudioManualEditsToPreview = useCallback(
     (iframe: HTMLIFrameElement | null = previewIframeRef.current) => {
@@ -113,68 +108,38 @@ export function useManifestPersistence({
         return;
       }
       if (!doc) return;
-      const previewDoc = doc;
 
-      const applyManifest = () => {
-        applyStudioManualEditManifest(
-          previewDoc,
-          studioManualEditManifestRef.current,
-          activeCompPathRef.current,
-        );
-      };
-      const applyAndInstallSeekHooks = () => {
-        applyManifest();
-        if (iframe.contentWindow) {
-          installStudioManualEditSeekReapply(iframe.contentWindow, applyManifest);
+      const reapply = () => {
+        let d: Document | null = null;
+        try {
+          d = iframe.contentDocument;
+        } catch {
+          return;
         }
+        if (d) reapplyPositionEditsAfterSeek(d);
+      };
+      const install = () => {
+        reapply();
+        if (iframe.contentWindow) installStudioManualEditSeekReapply(iframe.contentWindow, reapply);
       };
 
       const win = iframe.contentWindow;
-      applyAndInstallSeekHooks();
-      win?.requestAnimationFrame?.(applyAndInstallSeekHooks);
-      win?.setTimeout?.(applyAndInstallSeekHooks, 80);
-      win?.setTimeout?.(applyAndInstallSeekHooks, 250);
-      win?.setTimeout?.(applyAndInstallSeekHooks, 500);
-      win?.setTimeout?.(applyAndInstallSeekHooks, 1000);
-      win?.setTimeout?.(applyAndInstallSeekHooks, 2000);
+      install();
+      win?.requestAnimationFrame?.(install);
+      win?.setTimeout?.(install, 80);
+      win?.setTimeout?.(install, 250);
+      win?.setTimeout?.(install, 500);
+      win?.setTimeout?.(install, 1000);
+      win?.setTimeout?.(install, 2000);
     },
-    [activeCompPathRef, previewIframeRef],
+    [previewIframeRef],
   );
 
   const applyStudioManualEditsToPreview = useCallback(
-    async (
-      iframe: HTMLIFrameElement | null = previewIframeRef.current,
-      options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
-    ) => {
-      // Bootstrap from disk on first apply per session; explicit flag avoids
-      // re-reading disk after the user deletes all edits (async write race).
-      const needsBootstrap = !manifestBootstrappedRef.current;
-      if (needsBootstrap) manifestBootstrappedRef.current = true;
-      const readFromDiskFirst = Boolean(
-        options?.forceFromDisk || options?.readFromDiskFirst || needsBootstrap,
-      );
-      if (!readFromDiskFirst) {
-        applyCurrentStudioManualEditsToPreview(iframe);
-        return;
-      }
-      const readRevision = studioManualEditRevisionRef.current;
-      let content: string;
-      try {
-        content = await readOptionalProjectFile(STUDIO_MANUAL_EDITS_PATH);
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : "Failed to read manual edit manifest";
-        showToast(message);
-        applyCurrentStudioManualEditsToPreview(iframe);
-        return;
-      }
-      if (options?.forceFromDisk || readRevision === studioManualEditRevisionRef.current) {
-        studioManualEditManifestRef.current = parseStudioManualEditManifest(content);
-        if (options?.forceFromDisk) studioManualEditRevisionRef.current += 1;
-      }
+    async (iframe: HTMLIFrameElement | null = previewIframeRef.current) => {
       applyCurrentStudioManualEditsToPreview(iframe);
     },
-    [applyCurrentStudioManualEditsToPreview, previewIframeRef, readOptionalProjectFile, showToast],
+    [applyCurrentStudioManualEditsToPreview, previewIframeRef],
   );
   applyStudioManualEditsToPreviewRef.current = applyStudioManualEditsToPreview;
 
@@ -230,7 +195,7 @@ export function useManifestPersistence({
       const readRevision = studioMotionRevisionRef.current;
       let content: string;
       try {
-        content = await readOptionalProjectFile(STUDIO_MOTION_PATH);
+        content = await _readOptionalProjectFile(STUDIO_MOTION_PATH);
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to read motion manifest";
         showToast(message);
@@ -244,80 +209,11 @@ export function useManifestPersistence({
       }
       applyCurrentStudioMotionToPreview(iframe);
     },
-    [applyCurrentStudioMotionToPreview, previewIframeRef, readOptionalProjectFile, showToast],
+    [applyCurrentStudioMotionToPreview, previewIframeRef, _readOptionalProjectFile, showToast],
   );
   applyStudioMotionToPreviewRef.current = applyStudioMotionToPreview;
 
-  // ── Optimistic commits ──
-
-  const commitStudioManualEditManifestOptimistically = useCallback(
-    (
-      updateManifest: (manifest: StudioManualEditManifest) => StudioManualEditManifest,
-      options: { label: string; coalesceKey: string },
-    ) => {
-      const previousManifest = studioManualEditManifestRef.current;
-      const nextManifest = updateManifest(previousManifest);
-      const previousContent = serializeStudioManualEditManifest(previousManifest);
-      const nextContent = serializeStudioManualEditManifest(nextManifest);
-      if (nextContent === previousContent) {
-        return;
-      }
-
-      const revision = studioManualEditRevisionRef.current + 1;
-      studioManualEditRevisionRef.current = revision;
-      studioManualEditManifestRef.current = nextManifest;
-      applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
-
-      const save = async () => {
-        const originalContent = await readOptionalProjectFile(STUDIO_MANUAL_EDITS_PATH);
-        const diskManifest = parseStudioManualEditManifest(originalContent);
-        const nextDiskManifest = updateManifest(diskManifest);
-        const nextDiskContent = serializeStudioManualEditManifest(nextDiskManifest);
-        if (nextDiskContent === originalContent) {
-          return;
-        }
-
-        const pid = projectIdRef.current;
-        if (!pid) throw new Error("No active project");
-        domEditSaveTimestampRef.current = Date.now();
-        await saveProjectFilesWithHistory({
-          projectId: pid,
-          label: options.label,
-          kind: "manual",
-          coalesceKey: options.coalesceKey,
-          files: { [STUDIO_MANUAL_EDITS_PATH]: nextDiskContent },
-          readFile: async () => originalContent,
-          writeFile: writeProjectFile,
-          recordEdit,
-        });
-        domEditSaveTimestampRef.current = Date.now();
-
-        if (studioManualEditRevisionRef.current === revision) {
-          studioManualEditManifestRef.current = nextDiskManifest;
-          applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
-        }
-      };
-
-      void queueDomEditSave(save).catch((error) => {
-        if (studioManualEditRevisionRef.current === revision) {
-          studioManualEditRevisionRef.current += 1;
-          studioManualEditManifestRef.current = previousManifest;
-          applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
-        }
-        const message = error instanceof Error ? error.message : "Failed to save manual edit";
-        showToast(message);
-      });
-    },
-    [
-      applyCurrentStudioManualEditsToPreview,
-      recordEdit,
-      queueDomEditSave,
-      readOptionalProjectFile,
-      showToast,
-      writeProjectFile,
-      previewIframeRef,
-    ],
-  );
+  // ── Optimistic motion commit ──
 
   const commitStudioMotionManifestOptimistically = useCallback(
     (
@@ -339,7 +235,7 @@ export function useManifestPersistence({
       applyCurrentStudioMotionToPreview(previewIframeRef.current);
 
       const save = async () => {
-        const originalContent = await readOptionalProjectFile(STUDIO_MOTION_PATH);
+        const originalContent = await _readOptionalProjectFile(STUDIO_MOTION_PATH);
         const diskManifest = parseStudioMotionManifest(originalContent);
         const nextDiskManifest = updateManifest(diskManifest);
         const nextDiskContent = serializeStudioMotionManifest(nextDiskManifest);
@@ -384,10 +280,11 @@ export function useManifestPersistence({
       applyCurrentStudioMotionToPreview,
       recordEdit,
       queueDomEditSave,
-      readOptionalProjectFile,
+      _readOptionalProjectFile,
       showToast,
       writeProjectFile,
       previewIframeRef,
+      domEditSaveTimestampRef,
     ],
   );
 
@@ -396,69 +293,40 @@ export function useManifestPersistence({
   const syncHistoryPreviewAfterApply = useCallback(
     async (paths: string[] | undefined) => {
       const changedPaths = paths ?? [];
-      const manualManifestOnly =
-        changedPaths.length > 0 && changedPaths.every((path) => path === STUDIO_MANUAL_EDITS_PATH);
       const motionManifestOnly =
         changedPaths.length > 0 && changedPaths.every((path) => path === STUDIO_MOTION_PATH);
 
-      if (manualManifestOnly) {
-        await applyStudioManualEditsToPreview(previewIframeRef.current, { forceFromDisk: true });
-        return;
-      }
       if (motionManifestOnly) {
         await applyStudioMotionToPreview(previewIframeRef.current, { forceFromDisk: true });
         return;
       }
 
-      // Reload the iframe in-place rather than recreating the Player component.
-      // This preserves the <hyperframes-player> web component and its shader
-      // transition cache — only the iframe document reloads, so transitions that
-      // weren't touched by the undo/redo don't need to rebuild from scratch.
-      const iframe = previewIframeRef.current;
-      if (iframe?.contentWindow) {
-        try {
-          iframe.contentWindow.location.reload();
-          return;
-        } catch {
-          // Cross-origin or detached — fall through to full refresh
-        }
-      }
+      // Reload via refreshKey so NLELayout saves seek position before the iframe reloads.
+      reloadPreview();
     },
-    [applyStudioManualEditsToPreview, applyStudioMotionToPreview, previewIframeRef],
+    [applyStudioMotionToPreview, previewIframeRef, reloadPreview],
   );
 
   // ── Reset manifests when project changes ──
 
+  const projectTrackerRef = useRef<string | null>(projectId);
+
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
-    const previousProjectId = studioManualEditProjectRef.current;
-    studioManualEditProjectRef.current = projectId;
+    const previousProjectId = projectTrackerRef.current;
+    projectTrackerRef.current = projectId;
     if (!previousProjectId || previousProjectId === projectId) return;
-    studioManualEditManifestRef.current = emptyStudioManualEditManifest();
-    studioManualEditRevisionRef.current += 1;
     studioMotionManifestRef.current = emptyStudioMotionManifest();
     studioMotionRevisionRef.current += 1;
     setStudioMotionRevision((revision) => revision + 1);
-    manifestBootstrappedRef.current = motionBootstrappedRef.current = false;
+    motionBootstrappedRef.current = false;
   }, [projectId]);
 
   // ── Listen for external file changes (HMR / SSE) ──
-  // In dev: use Vite HMR. In embedded/production: use SSE from /api/events.
-  // Suppress file-change events that echo back from a recent DOM edit save —
-  // those changes are already applied to the iframe DOM and a full reload
-  // would flash the preview.
   useMountEffect(() => {
     const handler = (payload?: unknown) => {
       const changedPath = readStudioFileChangePath(payload);
       const recentDomEditSave = Date.now() - domEditSaveTimestampRef.current < 1200;
-      if (isStudioManualEditManifestPath(changedPath)) {
-        if (!recentDomEditSave) {
-          void applyStudioManualEditsToPreviewRef.current(previewIframeRef.current, {
-            forceFromDisk: true,
-          });
-        }
-        return;
-      }
       if (isStudioMotionManifestPath(changedPath)) {
         if (!recentDomEditSave) {
           void applyStudioMotionToPreviewRef.current(previewIframeRef.current, {
@@ -467,9 +335,10 @@ export function useManifestPersistence({
         }
         return;
       }
-      // Non-manifest file changes are not handled here — the caller is
-      // responsible for triggering a preview refresh via onExternalFileChange
-      // if needed. This hook only suppresses echoes and handles manifest reloads.
+      // Non-motion external file change — reload unless it's an echo of our own save.
+      if (!recentDomEditSave) {
+        reloadPreview();
+      }
     };
     if (import.meta.hot) {
       import.meta.hot.on("hf:file-change", handler);
@@ -482,23 +351,18 @@ export function useManifestPersistence({
   });
 
   return {
-    domEditSaveTimestampRef,
     domTextCommitVersionRef,
     domEditSaveQueueRef,
-    studioManualEditManifestRef,
-    studioManualEditRevisionRef,
     studioMotionManifestRef,
     studioMotionRevisionRef,
     applyStudioManualEditsToPreviewRef,
     applyStudioMotionToPreviewRef,
-    studioManualEditProjectRef,
     queueDomEditSave,
     waitForPendingDomEditSaves,
     applyCurrentStudioManualEditsToPreview,
     applyStudioManualEditsToPreview,
     applyCurrentStudioMotionToPreview,
     applyStudioMotionToPreview,
-    commitStudioManualEditManifestOptimistically,
     commitStudioMotionManifestOptimistically,
     syncHistoryPreviewAfterApply,
   };

package/src/hooks/usePanelLayout.ts

@@ -2,14 +2,21 @@ import { useState, useCallback, useRef } from "react";
 import type { RightPanelTab } from "../utils/studioHelpers";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../utils/studioUiPreferences";
 
-export function usePanelLayout() {
+export interface InitialPanelLayoutState {
+  rightCollapsed?: boolean | null;
+  rightPanelTab?: RightPanelTab | null;
+}
+
+export function usePanelLayout(initialState?: InitialPanelLayoutState) {
   const [leftWidth, setLeftWidth] = useState(240);
   const [rightWidth, setRightWidth] = useState(400);
   const [leftCollapsed, setLeftCollapsed] = useState(
     () => readStudioUiPreferences().leftCollapsed ?? false,
   );
-  const [rightCollapsed, setRightCollapsed] = useState(true);
-  const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>("renders");
+  const [rightCollapsed, setRightCollapsed] = useState(initialState?.rightCollapsed ?? true);
+  const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>(
+    initialState?.rightPanelTab ?? "renders",
+  );
   const panelDragRef = useRef<{
     side: "left" | "right";
     startX: number;

package/src/hooks/usePreviewInteraction.ts

@@ -18,7 +18,6 @@ export interface UsePreviewInteractionParams {
   captionEditMode: boolean;
   compositionLoading: boolean;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
-  activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
 
   // From useDomSelection

package/src/hooks/useStudioUrlState.ts

@@ -0,0 +1,188 @@
+import { useCallback, useEffect, useRef } from "react";
+import { usePlayerStore } from "../player";
+import { findElementForSelection, type DomEditSelection } from "../components/editor/domEditing";
+import { clampNumber, type RightPanelTab } from "../utils/studioHelpers";
+import {
+  buildStudioHash,
+  type StudioUrlSelectionState,
+  type StudioUrlState,
+} from "../utils/studioUrlState";
+
+interface UseStudioUrlStateParams {
+  projectId: string | null;
+  activeCompPath: string | null;
+  currentTime: number;
+  duration: number;
+  isPlaying: boolean;
+  compositionLoading: boolean;
+  refreshKey: number;
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  rightPanelTab: RightPanelTab;
+  rightCollapsed: boolean;
+  timelineVisible: boolean;
+  activeCompPathHydrated: boolean;
+  domEditSelection: DomEditSelection | null;
+  buildDomSelectionFromTarget: (
+    target: HTMLElement,
+    options?: { preferClipAncestor?: boolean },
+  ) => DomEditSelection | null;
+  applyDomSelection: (
+    selection: DomEditSelection | null,
+    options?: {
+      revealPanel?: boolean;
+      additive?: boolean;
+      preserveGroup?: boolean;
+    },
+  ) => void;
+  initialState: StudioUrlState;
+}
+
+function toPersistedSelection(selection: DomEditSelection | null): StudioUrlSelectionState | null {
+  if (!selection) return null;
+  if (!selection.id && !selection.selector) return null;
+  return {
+    sourceFile: selection.sourceFile || undefined,
+    id: selection.id || undefined,
+    selector: selection.selector || undefined,
+    selectorIndex: selection.selectorIndex ?? undefined,
+  };
+}
+
+function replaceHash(nextHash: string) {
+  if (typeof window === "undefined") return;
+  if (window.location.hash === nextHash) return;
+  window.history.replaceState(null, "", nextHash);
+}
+
+export function useStudioUrlState({
+  projectId,
+  activeCompPath,
+  currentTime,
+  duration,
+  isPlaying,
+  compositionLoading,
+  refreshKey,
+  previewIframeRef,
+  rightPanelTab,
+  rightCollapsed,
+  timelineVisible,
+  activeCompPathHydrated,
+  domEditSelection,
+  buildDomSelectionFromTarget,
+  applyDomSelection,
+  initialState,
+}: UseStudioUrlStateParams) {
+  const hydratedSeekRef = useRef(initialState.currentTime == null);
+  const hydratedInitialTimeRef = useRef(initialState.currentTime == null);
+  const hydratedSelectionRef = useRef(initialState.selection == null);
+  const pendingSelectionRef = useRef(initialState.selection);
+  const stableTimeRef = useRef<number | null>(initialState.currentTime);
+
+  const buildUrlState = useCallback(
+    (): StudioUrlState => ({
+      activeCompPath,
+      currentTime: stableTimeRef.current,
+      rightPanelTab,
+      rightCollapsed,
+      timelineVisible,
+      selection: hydratedSelectionRef.current
+        ? toPersistedSelection(domEditSelection)
+        : pendingSelectionRef.current,
+    }),
+    [activeCompPath, domEditSelection, rightCollapsed, rightPanelTab, timelineVisible],
+  );
+
+  useEffect(() => {
+    if (!projectId || hydratedSeekRef.current || compositionLoading) return;
+    const nextTime =
+      duration > 0
+        ? clampNumber(initialState.currentTime ?? 0, 0, duration)
+        : Math.max(0, initialState.currentTime ?? 0);
+    usePlayerStore.getState().requestSeek(nextTime);
+    stableTimeRef.current = nextTime;
+    hydratedSeekRef.current = true;
+  }, [projectId, compositionLoading, duration, initialState.currentTime]);
+
+  useEffect(() => {
+    if (!projectId || hydratedSelectionRef.current || compositionLoading) return;
+    if (!hydratedSeekRef.current) return;
+    const targetTime = initialState.currentTime;
+    if (targetTime != null && Math.abs(currentTime - stableTimeRef.current!) > 0.05) return;
+
+    const pendingSelection = pendingSelectionRef.current;
+    if (!pendingSelection) {
+      hydratedSelectionRef.current = true;
+      return;
+    }
+
+    let doc: Document | null = null;
+    try {
+      doc = previewIframeRef.current?.contentDocument ?? null;
+    } catch {
+      return;
+    }
+    if (!doc) return;
+
+    const element = findElementForSelection(
+      doc,
+      {
+        sourceFile: pendingSelection.sourceFile ?? "",
+        id: pendingSelection.id,
+        selector: pendingSelection.selector,
+        selectorIndex: pendingSelection.selectorIndex,
+      },
+      activeCompPath,
+    );
+    if (!element) {
+      applyDomSelection(null, { revealPanel: false });
+      hydratedSelectionRef.current = true;
+      pendingSelectionRef.current = null;
+      return;
+    }
+
+    const selection = buildDomSelectionFromTarget(element, { preferClipAncestor: false });
+    applyDomSelection(selection, { revealPanel: false });
+    hydratedSelectionRef.current = true;
+    pendingSelectionRef.current = null;
+  }, [
+    activeCompPath,
+    applyDomSelection,
+    buildDomSelectionFromTarget,
+    compositionLoading,
+    currentTime,
+    initialState.currentTime,
+    previewIframeRef,
+    projectId,
+    refreshKey,
+  ]);
+
+  useEffect(() => {
+    if (hydratedInitialTimeRef.current) return;
+    const targetTime = stableTimeRef.current;
+    if (targetTime == null) {
+      hydratedInitialTimeRef.current = true;
+      return;
+    }
+    if (Math.abs(currentTime - targetTime) > 0.05) return;
+    hydratedInitialTimeRef.current = true;
+  }, [currentTime]);
+
+  useEffect(() => {
+    if (!activeCompPathHydrated) return;
+    if (!hydratedSeekRef.current) return;
+    if (!hydratedInitialTimeRef.current) return;
+    if (!projectId || isPlaying) return;
+    const handle = window.setTimeout(() => {
+      stableTimeRef.current = clampNumber(currentTime, 0, Math.max(0, duration));
+      replaceHash(buildStudioHash(projectId, buildUrlState()));
+    }, 200);
+
+    return () => window.clearTimeout(handle);
+  }, [activeCompPathHydrated, buildUrlState, currentTime, duration, isPlaying, projectId]);
+
+  useEffect(() => {
+    if (!activeCompPathHydrated) return;
+    if (!projectId) return;
+    replaceHash(buildStudioHash(projectId, buildUrlState()));
+  }, [activeCompPathHydrated, buildUrlState, projectId]);
+}

package/src/player/components/Player.tsx

@@ -163,7 +163,21 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         player.style.width = "100%";
         player.style.height = "100%";
         player.style.display = "block";
+        player.style.background = "transparent";
         container.appendChild(player);
+
+        // Inject pasteboard shadow: let the shadow around the canvas bleed
+        // into the surrounding pasteboard area (overflow: visible on the container)
+        // and add a subtle outline + drop-shadow so the canvas boundary reads
+        // against the gray pasteboard, consistent with professional editors.
+        if (player.shadowRoot) {
+          const pasteboardStyle = document.createElement("style");
+          pasteboardStyle.textContent =
+            ".hfp-container{overflow:visible}" +
+            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
+          player.shadowRoot.appendChild(pasteboardStyle);
+        }
+
         enableInteractiveIframe(player);
 
         // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
@@ -309,7 +323,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
 
     return (
       <div
-        className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center"
+        className="relative w-full h-full max-w-full max-h-full overflow-hidden flex items-center justify-center"
         style={style}
       >
         <div ref={containerRef} className="w-full h-full" />

package/src/player/components/PlayerControls.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { resolveSeekPercent } from "./PlayerControls";
+import { shouldMutePreviewAudio } from "../lib/timelineIframeHelpers";
 
 describe("resolveSeekPercent", () => {
   it("returns 0 when the track width is invalid", () => {
@@ -18,3 +19,19 @@ describe("resolveSeekPercent", () => {
     expect(resolveSeekPercent(150, 100, 200)).toBe(0.25);
   });
 });
+
+describe("shouldMutePreviewAudio", () => {
+  it("mutes when the user toggled audio off", () => {
+    expect(shouldMutePreviewAudio(true, 1)).toBe(true);
+  });
+
+  it("auto-mutes above 1x playback", () => {
+    expect(shouldMutePreviewAudio(false, 1.5)).toBe(true);
+    expect(shouldMutePreviewAudio(false, 2)).toBe(true);
+  });
+
+  it("keeps audio on at 1x or slower when the user has not muted it", () => {
+    expect(shouldMutePreviewAudio(false, 1)).toBe(false);
+    expect(shouldMutePreviewAudio(false, 0.5)).toBe(false);
+  });
+});