@hyperframes/studio 0.8.56 → 0.8.58

package/src/components/editor/useVolumeAutomation.ts

@@ -1,13 +1,15 @@
 /**
- * The volume lane's state and edits for the media section.
+ * The media section's lane state and edits: volume and speed.
  *
- * Volume lives in a different panel section from the FX chain, but is automated
- * the same way, so it reads and writes through the same helper the FX group uses
+ * Both live in a different panel section from the FX chain but are automated
+ * the same way, so they read and write through the same helper the FX group uses
  * rather than a second interpretation of the attribute.
  */
 
 import {
   HF_AUDIO_AUTOMATION_DATA_KEY,
+  RATE_TARGET,
+  resolveAutomationRange,
   sampleAutomationLane,
   VOLUME_TARGET,
 } from "@hyperframes/core/audio-automation";
@@ -16,30 +18,50 @@ import {
   automationAttrValue,
   HF_AUDIO_AUTOMATION_ATTR,
   readPanelAutomation,
+  withLane,
   withoutLane,
   withPointAt,
   withSeededLane,
 } from "./propertyPanelAutomation";
 import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
+import { SPEED_PRESETS, speedPresetLane, type SpeedPresetId } from "@hyperframes/core/speed-ramp";
 import { clampNumber } from "../../utils/studioHelpers";
 
+export interface LaneBinding {
+  automated: boolean;
+  onAutomate: () => void;
+  onRemoveAutomation: () => void;
+  /** Write `v` as a keyframe at the playhead instead of the disabled fallback. */
+  onCommitAt: (v: number) => void;
+  /** The envelope's own value at the playhead, so the slider tracks it live. */
+  automatedValue: number | undefined;
+}
+
+export type RateBinding = LaneBinding & {
+  /** False while the clip has no known duration to stretch a preset over. */
+  canApplyPreset: boolean;
+  onApplyPreset: (id: SpeedPresetId) => void;
+};
+
 export interface VolumeAutomationBinding {
   volumeAutomated: boolean;
   onAutomateVolume: () => void;
   onRemoveVolumeAutomation: () => void;
-  /** Write `v` as a keyframe at the playhead instead of the disabled fallback. */
   onCommitVolumeAt: (v: number) => void;
-  /** The envelope's own value at the playhead, so the slider tracks it live. */
   automatedVolumeValue: number | undefined;
+  /** Speed: the `rate` lane, plus the CapCut-style presets that seed it. */
+  rate: RateBinding;
 }
 
+export const SPEED_PRESET_OPTIONS = SPEED_PRESETS.map(({ id, label }) => ({ value: id, label }));
+
 export function useVolumeAutomation(
   element: DomEditSelection,
   currentTime: number,
   onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
 ): VolumeAutomationBinding {
-  // The chain is not needed to resolve a volume lane — volume is always a valid
-  // target — so this deliberately does not parse it.
+  // The chain is not needed to resolve a volume or rate lane: both are always valid
+  // targets, so this deliberately does not parse it.
   const automation = readPanelAutomation(
     element.dataAttributes?.[HF_AUDIO_AUTOMATION_DATA_KEY],
     undefined,
@@ -55,21 +77,40 @@ export function useVolumeAutomation(
     // playing track, while the same click on an effect parameter did not.
     void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);
   };
+  const laneBinding = (target: string, seed: number): LaneBinding => {
+    const lane = automation.lanes.find((l) => l.target === target);
+    return {
+      automated: lane !== undefined,
+      automatedValue: lane
+        ? sampleAutomationLane(lane, clipTimeSec, resolveAutomationRange(target, undefined)?.scale)
+        : undefined,
+      // Seeded at the level the control already shows, so automating does not change it.
+      onAutomate: () => write(withSeededLane(automation, target, seed)),
+      onRemoveAutomation: () => write(withoutLane(automation, target)),
+      onCommitAt: (v: number) => write(withPointAt(automation, target, clipTimeSec, v)),
+    };
+  };
   // `??` alone would let an empty `data-volume` through as Number("") === 0, so
   // automating the track would seed its lane at silence. The engine reads the same
   // empty value as unity.
   const raw = element.dataAttributes?.["volume"];
   const parsed = raw ? Number(raw) : 1;
   const current = Number.isFinite(parsed) ? parsed : 1;
-  const volumeLane = automation.lanes.find((lane) => lane.target === VOLUME_TARGET);
+  const volume = laneBinding(VOLUME_TARGET, current);
+  const rateAttr = Number.parseFloat(element.dataAttributes?.["playback-rate"] ?? "");
+  const rate = laneBinding(RATE_TARGET, Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1);
   return {
-    volumeAutomated: volumeLane !== undefined,
-    automatedVolumeValue: volumeLane ? sampleAutomationLane(volumeLane, clipTimeSec) : undefined,
-    // Seeded at the level the slider already shows, so automating the track does
-    // not change how loud it is.
-    onAutomateVolume: () =>
-      write(withSeededLane(automation, VOLUME_TARGET, Number.isFinite(current) ? current : 1)),
-    onRemoveVolumeAutomation: () => write(withoutLane(automation, VOLUME_TARGET)),
-    onCommitVolumeAt: (v: number) => write(withPointAt(automation, VOLUME_TARGET, clipTimeSec, v)),
+    volumeAutomated: volume.automated,
+    automatedVolumeValue: volume.automatedValue,
+    onAutomateVolume: volume.onAutomate,
+    onRemoveVolumeAutomation: volume.onRemoveAutomation,
+    onCommitVolumeAt: volume.onCommitAt,
+    rate: {
+      ...rate,
+      canApplyPreset: elDuration > 0,
+      onApplyPreset: (id) => {
+        if (elDuration > 0) write(withLane(automation, speedPresetLane(id, elDuration)));
+      },
+    },
   };
 }

package/src/components/nle/NLEContext.tsx

@@ -1,7 +1,8 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
-import { useTimelinePlayer, usePlayerStore } from "../../player";
-import type { TimelineElement } from "../../player";
+import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
+import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
 import { setCompositionSourceMap } from "../editor/domEditingDom";
@@ -17,10 +18,20 @@ export interface NLEContextValue {
   projectId: string;
   // player (from useTimelinePlayer — single instance for the whole shell)
   iframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  play: () => void;
+  pause: () => void;
   togglePlay: () => void;
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
   onIframeLoad: () => void;
+  // The hidden reload iframe NLEPreview renders next to the live one during a full reload.
+  previewSlots: PreviewIframeSlot[];
+  onShadowIframeLoad: (gen: number) => void;
+  onShadowReadyChange: (gen: number, ready: boolean) => void;
+  onShadowError: (gen: number, message: string) => void;
+  setShadowIframeNode: (node: HTMLIFrameElement | null) => void;
+  resetPreviewSlots: () => void;
+  containerRef: React.MutableRefObject<HTMLDivElement | null>;
   // composition stack (from useCompositionStack)
   compositionStack: CompositionLevel[];
   updateCompositionStack: React.Dispatch<React.SetStateAction<CompositionLevel[]>>;
@@ -55,6 +66,8 @@ export interface NLEProviderProps {
   onCompositionChange?: (compositionPath: string | null) => void;
   onCompIdToSrcChange?: (map: Map<string, string>) => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
+  /** A preview reload was abandoned; the previous preview is still showing. */
+  onPreviewReloadFailed?: (message: string) => void;
   children: ReactNode;
 }
 
@@ -66,15 +79,29 @@ export function NLEProvider({
   onCompositionChange,
   onCompIdToSrcChange,
   onCompositionLoadingChange,
+  onPreviewReloadFailed,
   children,
 }: NLEProviderProps) {
+  const shadowPromotedRef = useRef<() => void>(() => {});
+  const containerRef = useRef<HTMLDivElement>(null);
   const {
     iframeRef,
+    play,
+    pause,
     togglePlay,
     seek,
     onIframeLoad: baseOnIframeLoad,
     refreshPlayer,
-  } = useTimelinePlayer();
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
+  } = useTimelinePlayer({
+    onShadowPromoted: () => shadowPromotedRef.current(),
+    onPreviewReloadFailed,
+  });
 
   // Reset timeline state when the project changes. Done in an effect, not during
   // render: reset() updates the player store, and updating another store/component
@@ -107,14 +134,20 @@ export function NLEProvider({
     refreshPlayer();
   }, [refreshKey, refreshPlayer]);
 
-  const onIframeLoad = useCallback(() => {
-    baseOnIframeLoad();
+  // Steps that follow every load of the live iframe, including a reload promoted in place.
+  const afterLiveIframeLoad = useCallback(() => {
     // Pre-load + register MotionPathPlugin once so adding a motion path in the
     // studio doesn't take the async plugin-load flash path on the first soft
     // reload (the comp may not ship the plugin until it actually uses one).
     ensureMotionPathPluginLoaded(iframeRef.current);
     onIframeRef?.(iframeRef.current);
-  }, [baseOnIframeLoad, iframeRef, onIframeRef]);
+  }, [iframeRef, onIframeRef]);
+  shadowPromotedRef.current = afterLiveIframeLoad;
+
+  const onIframeLoad = useCallback(() => {
+    baseOnIframeLoad();
+    afterLiveIframeLoad();
+  }, [baseOnIframeLoad, afterLiveIframeLoad]);
 
   const {
     compositionStack,
@@ -269,10 +302,19 @@ export function NLEProvider({
   const value: NLEContextValue = {
     projectId,
     iframeRef,
+    play,
+    pause,
+    containerRef,
     togglePlay,
     seek,
     refreshPlayer,
     onIframeLoad,
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
     compositionStack,
     updateCompositionStack,
     handleNavigateComposition,

package/src/components/nle/NLEPreview.test.ts

@@ -3,10 +3,14 @@
 import React, { act, createRef } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
 import { NLEPreview, getPreviewPlayerKey, resolvePreviewStageSize } from "./NLEPreview";
+import { readPreviewComplexity } from "../../player/hooks/usePreviewFirstFrameTelemetry";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
+const playerMounts: string[] = [];
+
 vi.mock("../../player", async () => {
   const React = await import("react");
 
@@ -14,6 +18,7 @@ vi.mock("../../player", async () => {
     Player: React.forwardRef(function MockPlayer(
       props: {
         onLoad?: () => void;
+        suppressLoadingOverlay?: boolean;
         style?: React.CSSProperties;
       },
       ref: React.ForwardedRef<HTMLIFrameElement>,
@@ -21,6 +26,7 @@ vi.mock("../../player", async () => {
       React.useEffect(() => {
         props.onLoad?.();
       }, [props]);
+      React.useState(() => playerMounts.push(props.suppressLoadingOverlay ? "shadow" : "live"));
 
       return React.createElement("div", {
         ref: ref as React.ForwardedRef<HTMLDivElement>,
@@ -70,7 +76,11 @@ function setRect(node: Element, rect: { width: number; height: number }) {
   });
 }
 
-function renderPreview() {
+function renderPreview(
+  previewSlots: Array<{ gen: number; role: "live" | "shadow"; url?: string }> = [
+    { gen: 0, role: "live" },
+  ],
+) {
   resizeCallbacks = [];
   const host = document.createElement("div");
   document.body.append(host);
@@ -83,6 +93,12 @@ function renderPreview() {
         projectId: "timeline-edit-playground",
         iframeRef,
         onIframeLoad: () => {},
+        previewSlots,
+        onShadowIframeLoad: () => {},
+        onShadowReadyChange: () => {},
+        onShadowError: () => {},
+        setShadowIframeNode: () => {},
+        resetPreviewSlots: () => {},
       }),
     );
   });
@@ -163,6 +179,13 @@ describe("resolvePreviewStageSize", () => {
 });
 
 describe("NLEPreview", () => {
+  it("counts timeline clips and media clips from the painted document", () => {
+    const doc = new DOMParser().parseFromString(
+      '<div data-composition-id="main" data-duration="10"><video data-start="0" data-duration="2"></video><audio data-start="2" data-duration="3"></audio><div data-start="5" data-duration="1"></div></div>',
+      "text/html",
+    );
+    expect(readPreviewComplexity(doc)).toEqual({ clip_count: 3, media_clip_count: 2 });
+  });
   beforeEach(() => {
     globalThis.ResizeObserver = MockResizeObserver as typeof ResizeObserver;
   });
@@ -227,4 +250,47 @@ describe("NLEPreview", () => {
     expect(view.stage.style.transform).toContain("translate3d(30px, -24px, 0)");
     view.cleanup();
   });
+
+  it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
+    const view = renderPreview([
+      { gen: 0, role: "live" },
+      { gen: 1, role: "shadow", url: "/api/projects/p/preview?_t=1" },
+    ]);
+    const players = [...view.stage.querySelectorAll<HTMLElement>('[data-testid="mock-player"]')];
+    expect(players).toHaveLength(2);
+    expect(players[0].style.clipPath).toBe("");
+    expect(players[1].style.clipPath).toBe("inset(100%)");
+    expect(players[1].style.visibility).toBe("hidden");
+    expect(players[1].style.pointerEvents).toBe("none");
+    view.cleanup();
+  });
+
+  it("mounts the live player once when the composition switches", () => {
+    playerMounts.length = 0;
+    const Harness = ({ projectId }: { projectId: string }) => {
+      const api = useTimelinePlayer();
+      return React.createElement(NLEPreview, {
+        projectId,
+        iframeRef: api.iframeRef,
+        onIframeLoad: api.onIframeLoad,
+        previewSlots: api.previewSlots,
+        onShadowIframeLoad: api.onShadowIframeLoad,
+        onShadowReadyChange: api.onShadowReadyChange,
+        onShadowError: api.onShadowError,
+        setShadowIframeNode: api.setShadowIframeNode,
+        resetPreviewSlots: api.resetPreviewSlots,
+      });
+    };
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Harness, { projectId: "a" })));
+    expect(playerMounts).toEqual(["live"]);
+
+    act(() => root.render(React.createElement(Harness, { projectId: "b" })));
+    expect(playerMounts).toEqual(["live", "live"]);
+
+    act(() => root.unmount());
+    host.remove();
+  });
 });

package/src/components/nle/NLEPreview.tsx

@@ -1,5 +1,10 @@
+import {
+  readPreviewCompositionSize,
+  type PreviewCompositionSize,
+} from "../../utils/previewCompositionSize";
 import { memo, useCallback, useEffect, useRef, useState, type RefObject } from "react";
 import { Player } from "../../player";
+import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import {
   DEFAULT_PREVIEW_ZOOM,
   canStartPreviewPan,
@@ -13,10 +18,17 @@ import {
 } from "./previewZoom";
 import { RULER_GUTTER_PX, usePreviewGuidesStore } from "../editor/previewGuidesStore";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { usePreviewFirstFrameTelemetry } from "../../player/hooks/usePreviewFirstFrameTelemetry";
 interface NLEPreviewProps {
   projectId: string;
   iframeRef: RefObject<HTMLIFrameElement | null>;
   onIframeLoad: () => void;
+  previewSlots: PreviewIframeSlot[];
+  onShadowIframeLoad: (gen: number) => void;
+  onShadowReadyChange: (gen: number, ready: boolean) => void;
+  onShadowError: (gen: number, message: string) => void;
+  setShadowIframeNode: (node: HTMLIFrameElement | null) => void;
+  resetPreviewSlots: () => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   directUrl?: string;
@@ -40,10 +52,15 @@ const ZOOM_HUD_TIMEOUT_MS = 1200;
 const ZOOM_SETTLE_MS = 200;
 const PREVIEW_STAGE_INSET_PX = 16;
 
-interface PreviewCompositionSize {
-  width: number;
-  height: number;
-}
+// clip-path as well as visibility: the player's loading overlay sets its own
+// visibility:visible and would otherwise paint over the live frame.
+const SHADOW_IFRAME_STYLE: React.CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  visibility: "hidden",
+  clipPath: "inset(100%)",
+  pointerEvents: "none",
+};
 
 function isPreviewAtFit(state: PreviewZoomState): boolean {
   return (
@@ -64,27 +81,6 @@ function loadInitialZoom(): PreviewZoomState {
     : DEFAULT_PREVIEW_ZOOM;
 }
 
-// fallow-ignore-next-line complexity
-function readPreviewCompositionSize(
-  iframe: HTMLIFrameElement | null,
-): PreviewCompositionSize | null {
-  try {
-    const doc = iframe?.contentDocument;
-    const root =
-      doc?.querySelector("[data-composition-id][data-width][data-height]") ??
-      doc?.querySelector("[data-width][data-height]");
-    if (!root) return null;
-    const width = Number.parseInt(root.getAttribute("data-width") ?? "", 10);
-    const height = Number.parseInt(root.getAttribute("data-height") ?? "", 10);
-    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
-      return null;
-    }
-    return { width, height };
-  } catch {
-    return null;
-  }
-}
-
 export function resolvePreviewStageSize(
   viewportWidth: number,
   viewportHeight: number,
@@ -122,6 +118,12 @@ export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
   onIframeLoad,
+  previewSlots,
+  onShadowIframeLoad,
+  onShadowReadyChange,
+  onShadowError,
+  setShadowIframeNode,
+  resetPreviewSlots,
   onCompositionLoadingChange,
   portrait,
   directUrl,
@@ -136,6 +138,17 @@ export const NLEPreview = memo(function NLEPreview({
   useEffect(() => {
     onStageRef?.(stageRef);
   }, [onStageRef]);
+
+  // Composition switch: drop any in-flight shadow reload (skipped on first mount).
+  const previousActiveKeyRef = useRef(activeKey);
+  useEffect(() => {
+    if (previousActiveKeyRef.current === activeKey) return;
+    previousActiveKeyRef.current = activeKey;
+    resetPreviewSlots();
+  }, [activeKey, resetPreviewSlots]);
+
+  const liveGenRef = useRef<number | null>(null);
+  const reportPreviewFirstFrame = usePreviewFirstFrameTelemetry(previewSlots);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
@@ -299,6 +312,18 @@ export const NLEPreview = memo(function NLEPreview({
     }
   }, [writeTransform]);
 
+  // A promotion does not re-fire Player.onLoad: re-sync the local iframe ref, size and zoom.
+  useEffect(() => {
+    const live = previewSlots.find((slot) => slot.role === "live");
+    if (!live || live.gen === liveGenRef.current) return;
+    const isPromotion = liveGenRef.current !== null;
+    liveGenRef.current = live.gen;
+    if (!isPromotion) return;
+    previewIframeRef.current = iframeRef.current;
+    updateCompositionSizeFromPreview();
+    applyInitialZoom();
+  }, [previewSlots, iframeRef, updateCompositionSizeFromPreview, applyInitialZoom]);
+
   useEffect(() => {
     const viewport = viewportRef.current;
     if (!viewport) return;
@@ -469,25 +494,44 @@ export const NLEPreview = memo(function NLEPreview({
                 style={{ position: "absolute", inset: 0, zIndex: 0 }}
               />
             )}
-            <Player
-              key={activeKey}
-              ref={setPreviewIframeRef}
-              projectId={directUrl ? undefined : projectId}
-              directUrl={directUrl}
-              onLoad={() => {
-                updateCompositionSizeFromPreview();
-                onIframeLoad();
-                applyInitialZoom();
-              }}
-              onCompositionLoadingChange={onCompositionLoadingChange}
-              portrait={portrait}
-              suppressLoadingOverlay={suppressLoadingOverlay}
-              style={
-                directUrl?.includes("/components/")
-                  ? { position: "absolute", inset: 0, zIndex: 1 }
-                  : undefined
-              }
-            />
+            {previewSlots.map((slot) =>
+              slot.role === "live" ? (
+                <Player
+                  key={`${activeKey}-${slot.gen}`}
+                  ref={setPreviewIframeRef}
+                  projectId={directUrl ? undefined : projectId}
+                  directUrl={directUrl}
+                  onLoad={() => {
+                    updateCompositionSizeFromPreview();
+                    onIframeLoad();
+                    applyInitialZoom();
+                  }}
+                  onCompositionLoadingChange={onCompositionLoadingChange}
+                  onPainted={(details) => reportPreviewFirstFrame(slot, details)}
+                  portrait={portrait}
+                  suppressLoadingOverlay={suppressLoadingOverlay}
+                  style={
+                    directUrl?.includes("/components/")
+                      ? { position: "absolute", inset: 0, zIndex: 1 }
+                      : undefined
+                  }
+                />
+              ) : (
+                // Loads hidden behind the live slot until promoted.
+                <Player
+                  key={`${activeKey}-${slot.gen}`}
+                  ref={setShadowIframeNode}
+                  directUrl={slot.url}
+                  onLoad={() => onShadowIframeLoad(slot.gen)}
+                  onReadyToShowChange={(ready) => onShadowReadyChange(slot.gen, ready)}
+                  onPainted={(details) => reportPreviewFirstFrame(slot, details)}
+                  onPreviewError={(message) => onShadowError(slot.gen, message)}
+                  portrait={portrait}
+                  suppressLoadingOverlay
+                  style={SHADOW_IFRAME_STYLE}
+                />
+              ),
+            )}
           </div>
         </div>
         <div

package/src/components/nle/PreviewOverlays.tsx

@@ -1,10 +1,11 @@
-import { useCallback, useState } from "react";
+import { useCallback } from "react";
 import { CaptionOverlay } from "../../captions/components/CaptionOverlay";
 import { useCaptionStore } from "../../captions/store";
 import { DomEditOverlay } from "../editor/DomEditOverlay";
 import { TopologyLens } from "../editor/TopologyLens";
 import { MotionPathOverlay } from "../editor/MotionPathOverlay";
 import { SnapToolbar } from "../editor/SnapToolbar";
+import { GridOverlay } from "../editor/GridOverlay";
 import { usePreviewReadOnly } from "../editor/previewReadOnlyContext";
 import { useCompositionDimensions } from "../../hooks/useCompositionDimensions";
 import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
@@ -12,7 +13,6 @@ import {
   useDomEditActionsContext,
   useDomEditSelectionContext,
 } from "../../contexts/DomEditContext";
-import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { readHfId, type DomEditSelection } from "../editor/domEditing";
 import { buildStableSelector } from "../editor/domEditingDom";
 import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
@@ -182,17 +182,6 @@ export function PreviewOverlays({
   } = useDomEditActionsContext();
   const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
 
-  // fallow-ignore-next-line complexity
-  const [snapPrefs, setSnapPrefs] = useState(() => {
-    const p = readStudioUiPreferences();
-    return {
-      snapEnabled: p.snapEnabled ?? true,
-      gridVisible: p.gridVisible ?? false,
-      gridSpacing: p.gridSpacing ?? 50,
-      snapToGrid: p.snapToGrid ?? false,
-    };
-  });
-
   if (blockPreview) {
     return (
       <>
@@ -266,6 +255,7 @@ export function PreviewOverlays({
   return (
     <>
       <TopologyLens iframeRef={previewIframeRef} activeCompositionPath={activeCompPath} />
+      <GridOverlay />
       <DomEditOverlay
         iframeRef={previewIframeRef}
         activeCompositionPath={activeCompPath}
@@ -325,13 +315,11 @@ export function PreviewOverlays({
               }),
           }).catch(() => undefined);
         }}
-        gridVisible={snapPrefs.gridVisible}
-        gridSpacing={snapPrefs.gridSpacing}
         recordingState={recordingState}
         onToggleRecording={onToggleRecording}
         onMarqueeSelect={applyMarqueeSelection}
       />
-      <SnapToolbar onSnapChange={setSnapPrefs} />
+      <SnapToolbar />
       {!readOnly && (
         <MotionPathOverlay
           iframeRef={previewIframeRef}

package/src/components/nle/PreviewPane.tsx

@@ -7,6 +7,7 @@ import { usePreviewBlockDrop } from "./usePreviewBlockDrop";
 import { useNLEContext } from "./NLEContext";
 import { AssetPreviewOverlay } from "./AssetPreviewOverlay";
 import { PreviewGuides } from "../editor/PreviewGuides";
+import { PreviewOverlayProvider } from "../editor/PreviewOverlayProvider";
 
 function subscribeFullscreen(cb: () => void) {
   document.addEventListener("fullscreenchange", cb);
@@ -60,6 +61,12 @@ export function PreviewPane({
     togglePlay,
     seek,
     onIframeLoad,
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
     compositionStack,
     handleNavigateComposition,
     setCompositionLoading,
@@ -131,6 +138,12 @@ export function PreviewPane({
             projectId={projectId}
             iframeRef={iframeRef}
             onIframeLoad={onIframeLoad}
+            previewSlots={previewSlots}
+            onShadowIframeLoad={onShadowIframeLoad}
+            onShadowReadyChange={onShadowReadyChange}
+            onShadowError={onShadowError}
+            setShadowIframeNode={setShadowIframeNode}
+            resetPreviewSlots={resetPreviewSlots}
             onCompositionLoadingChange={setCompositionLoading}
             portrait={portrait}
             directUrl={directUrl}
@@ -143,8 +156,10 @@ export function PreviewPane({
           )}
           <AssetPreviewOverlay />
         </div>
-        <PreviewGuides iframeRef={iframeRef} />
-        {!isFullscreen && previewOverlay}
+        <PreviewOverlayProvider>
+          <PreviewGuides />
+          {!isFullscreen && previewOverlay}
+        </PreviewOverlayProvider>
       </div>
       {/* Transport row: no own background or border — the controls sit flat on
           the preview panel's surface (CapCut-style). */}

package/src/components/nle/previewReadOnly.test.tsx

@@ -32,6 +32,7 @@ vi.mock("../editor/MotionPathOverlay", () => ({
   MotionPathOverlay: () => <i data-testid="motion-path" />,
 }));
 vi.mock("../editor/SnapToolbar", () => ({ SnapToolbar: () => null }));
+vi.mock("../editor/GridOverlay", () => ({ GridOverlay: () => null }));
 
 let root: Root;
 let host: HTMLDivElement;

package/src/components/nle/useCompositionStack.ts

@@ -1,7 +1,7 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 // Composition drill-down stack management for NLEContext/EditorShell
 import { useState, useCallback, useRef, useEffect } from "react";
-import { usePlayerStore } from "../../player";
+import { usePlayerStore } from "../../player/store/playerStore";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { encodePreviewPath } from "../../player/components/thumbnailUtils";