@hyperframes/studio 0.8.75 → 0.8.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.75",
+  "version": "0.8.76",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,11 +52,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.75",
-    "@hyperframes/player": "0.8.75",
-    "@hyperframes/parsers": "0.8.75",
-    "@hyperframes/sdk": "0.8.75",
-    "@hyperframes/studio-server": "0.8.75"
+    "@hyperframes/parsers": "0.8.76",
+    "@hyperframes/core": "0.8.76",
+    "@hyperframes/sdk": "0.8.76",
+    "@hyperframes/studio-server": "0.8.76",
+    "@hyperframes/player": "0.8.76"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -72,7 +72,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.75"
+    "@hyperframes/producer": "0.8.76"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/StudioRightPanels.types.ts

@@ -9,7 +9,6 @@
 import type { StudioEditPersistenceProps } from "./panels/VariablesPanel";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { Composition } from "@hyperframes/sdk";
-import type { EditHistoryKind } from "../utils/editHistory";
 import type { UseSlideshowPersistParams } from "../hooks/useSlideshowPersist";
 import type { AddMediaOverlayHandler } from "./editor/propertyPanelTypes";
 import type { ToggleHiddenHandler } from "../utils/studioHelpers";
@@ -46,7 +45,6 @@ export interface StudioRightPanelsProps extends StudioEditPersistenceProps {
   reloadPreview: () => void;
   recordEdit: (entry: {
     label: string;
-    kind: EditHistoryKind;
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;
   onToggleElementHidden?: ToggleHiddenHandler;

package/src/components/editor/DomEditOverlay.test.ts

@@ -18,6 +18,7 @@ import {
   hoverCacheDescribesPoint,
   resolveResizeCenterAnchorOffset,
 } from "./domEditOverlayGestures";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 // React 19 warns unless the test environment opts into act().
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -242,6 +243,10 @@ function dispatchOverlayPointerDown(target: Element, clientX = 120, clientY = 80
   });
 }
 
+beforeEach(() => {
+  usePlayerStore.setState({ previewBooted: true });
+});
+
 describe("focusDomEditOverlayElement", () => {
   it("focuses the canvas overlay without scrolling", () => {
     const calls: Array<FocusOptions | undefined> = [];

package/src/components/editor/LayersPanel.tsx

@@ -3,6 +3,7 @@ import { memo, useState, useCallback, useEffect, useRef } from "react";
 import {
   collectDomEditLayerItems,
   getDomEditLayerKey,
+  liveLayerElement,
   resolveDomEditSelection,
   type DomEditLayerItem,
 } from "./domEditing";
@@ -190,20 +191,8 @@ export const LayersPanel = memo(function LayersPanel() {
 
   const resolveSelection = useCallback(
     (layer: DomEditLayerItem) => {
-      // Re-find the element from the live DOM — layer.element may be stale
-      // after soft reload (which replaces scripts without reloading the iframe).
-      let el = layer.element;
-      if (!el.isConnected) {
-        const iframe = previewIframeRef.current;
-        const doc = iframe?.contentDocument;
-        if (doc) {
-          const found =
-            (layer.id ? doc.getElementById(layer.id) : null) ??
-            (layer.hfId ? doc.querySelector(`[data-hf-id="${CSS.escape(layer.hfId)}"]`) : null) ??
-            doc.getElementById(layer.key);
-          if (found instanceof HTMLElement) el = found;
-        }
-      }
+      const doc = previewIframeRef.current?.contentDocument;
+      const el = liveLayerElement(layer, doc, activeCompPath);
       return resolveDomEditSelection(el, {
         activeCompositionPath: activeCompPath,
         isMasterView,

package/src/components/editor/PreviewOverlayProvider.test.tsx

@@ -2,10 +2,11 @@
 
 import { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { GridOverlay } from "./GridOverlay";
 import { PreviewOverlayProvider } from "./PreviewOverlayProvider";
 import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -27,6 +28,10 @@ function compositionFrame() {
   return iframe;
 }
 
+beforeEach(() => {
+  usePlayerStore.setState({ previewBooted: true });
+});
+
 describe("PreviewOverlayProvider", () => {
   it("derives grid geometry after the iframe prop becomes available", async () => {
     window.localStorage.setItem(

package/src/components/editor/domEditing.ts

@@ -37,6 +37,7 @@ export {
   getDomEditNonEditableReason,
   getDomEditTargetKey,
   isTextEditableSelection,
+  liveLayerElement,
   readHfId,
   refreshDomEditSelection,
   resolveDomEditCapabilities,

package/src/components/editor/domEditingLayers.test.ts

@@ -6,6 +6,7 @@ import {
   buildDomEditPatchTarget,
   buildTextFieldChildLocator,
   readHfId,
+  liveLayerElement,
 } from "./domEditingLayers";
 import type { DomEditTextField } from "./domEditingTypes";
 
@@ -305,3 +306,29 @@ describe("collectDomEditLayerItems selector-index cost", () => {
     expect(classSelectorQueries(12)).toBe(1);
   });
 });
+
+describe("liveLayerElement", () => {
+  it("finds a replaced layer again in its own file when a sub-composition repeats its id", () => {
+    document.body.innerHTML =
+      '<div data-composition-id="main">' +
+      '<div data-composition-id="strip" data-composition-src="compositions/strip.html">' +
+      '<div id="card-1">strip</div></div><div id="card-1">root</div></div>';
+    const stale = document.createElement("div");
+    const layer = {
+      key: "index.html:card-1:0",
+      element: stale,
+      label: "card-1",
+      tagName: "div",
+      depth: 0,
+      childCount: 0,
+      id: "card-1",
+      sourceFile: "index.html",
+    };
+
+    expect(liveLayerElement(layer, document, "index.html").textContent).toBe("root");
+    expect(
+      liveLayerElement({ ...layer, sourceFile: "compositions/strip.html" }, document, "index.html")
+        .textContent,
+    ).toBe("strip");
+  });
+});

package/src/components/editor/domEditingLayers.ts

@@ -491,6 +491,15 @@ export function collectDomEditLayerItems(
   return items;
 }
 
+export function liveLayerElement(
+  layer: DomEditLayerItem,
+  doc: Document | null | undefined,
+  activeCompositionPath: string | null,
+): HTMLElement {
+  if (layer.element.isConnected || !doc) return layer.element;
+  return findElementForSelection(doc, layer, activeCompositionPath) ?? layer.element;
+}
+
 // ─── Patch operations ────────────────────────────────────────────────────────
 
 export function buildDomEditStylePatchOperation(

package/src/components/editor/offCanvasIndicatorRefresh.test.tsx

@@ -2,9 +2,10 @@
 
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { DomEditOverlay } from "./DomEditOverlay";
 import { RECOMPUTE_INTERVAL_MS } from "./offCanvasIndicatorRefresh";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -59,6 +60,30 @@ async function flushAnimationFrames(): Promise<void> {
   });
 }
 
+// The refresh waits on MutationObserver delivery and then on its own throttle, so no fixed
+// number of frames is guaranteed to be enough on a loaded runner. Flush until the indicator
+// reaches the state under test.
+async function untilIndicator(host: HTMLElement, check: (indicator: Element | null) => void) {
+  await vi.waitFor(
+    async () => {
+      await act(async () => {
+        await flushAnimationFrames();
+      });
+      check(host.querySelector(INDICATOR));
+    },
+    { timeout: 4000, interval: 0 },
+  );
+}
+
+// Delivers each batch of mutation records `ms` late, as a busy runner can.
+function lateObserver(Base: typeof MutationObserver, ms: number): typeof MutationObserver {
+  return class extends Base {
+    constructor(callback: MutationCallback) {
+      super((records, observer) => setTimeout(() => callback(records, observer), ms));
+    }
+  };
+}
+
 interface OverlayHarness {
   host: HTMLElement;
   movedElement: HTMLElement;
@@ -68,7 +93,7 @@ interface OverlayHarness {
 // Mount DomEditOverlay over an iframe whose #headline sits at `initialLeft`, with a
 // getBoundingClientRect stub that reads the element's live inline geometry (so a
 // style mutation moves it) and reports the composition/overlay as 800x450 at origin.
-function mountOverlayWithHeadline(initialLeft: number): OverlayHarness {
+function mountOverlayWithHeadline(initialLeft: number, observerDelayMs = 0): OverlayHarness {
   const originalGetBoundingClientRect = Element.prototype.getBoundingClientRect;
   const host = document.createElement("div");
   document.body.append(host);
@@ -85,6 +110,9 @@ function mountOverlayWithHeadline(initialLeft: number): OverlayHarness {
   `;
   const movedElement = doc.getElementById("headline");
   if (!movedElement) throw new Error("Expected test element");
+  const view = doc.defaultView?.MutationObserver ? doc.defaultView : globalThis;
+  const RealObserver = view.MutationObserver;
+  if (observerDelayMs > 0) view.MutationObserver = lateObserver(RealObserver, observerDelayMs);
 
   Element.prototype.getBoundingClientRect = function (): DOMRect {
     if (this === movedElement) {
@@ -125,58 +153,52 @@ function mountOverlayWithHeadline(initialLeft: number): OverlayHarness {
     cleanup: () => {
       act(() => root.unmount());
       Element.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+      view.MutationObserver = RealObserver;
       iframe.remove();
       host.remove();
     },
   };
 }
 
-describe("off-canvas indicator refresh", () => {
-  it("removes the indicator when an off-canvas element moves in-canvas (off->on)", async () => {
-    const h = mountOverlayWithHeadline(760);
-    try {
-      await act(async () => {
-        await flushAnimationFrames();
-      });
-      expect(h.host.querySelector(INDICATOR)).toBeTruthy();
-
-      act(() => {
-        h.movedElement.style.left = "120px";
-      });
-      await act(async () => {
-        await Promise.resolve();
-        await flushAnimationFrames();
-      });
+beforeEach(() => {
+  usePlayerStore.setState({ previewBooted: true });
+});
 
-      expect(h.host.querySelector(INDICATOR)).toBeNull();
-    } finally {
-      h.cleanup();
-    }
-  });
+describe("off-canvas indicator refresh", () => {
+  for (const [label, delayMs] of [
+    ["", 0],
+    [" when mutation delivery lags past a fixed wait", 300],
+  ] as const) {
+    it(`removes the indicator when an off-canvas element moves in-canvas (off->on)${label}`, async () => {
+      const h = mountOverlayWithHeadline(760, delayMs);
+      try {
+        await untilIndicator(h.host, (indicator) => expect(indicator).toBeTruthy());
+
+        act(() => {
+          h.movedElement.style.left = "120px";
+        });
+        await untilIndicator(h.host, (indicator) => expect(indicator).toBeNull());
+      } finally {
+        h.cleanup();
+      }
+    });
+  }
 
   it("tracks the indicator to the new position when it stays off-canvas (off->off)", async () => {
     const h = mountOverlayWithHeadline(760);
     try {
-      await act(async () => {
-        await flushAnimationFrames();
-      });
+      await untilIndicator(h.host, (indicator) => expect(indicator).toBeTruthy());
       const before = h.host.querySelector(INDICATOR);
-      expect(before).toBeTruthy();
       const leftBefore = (before!.parentElement as HTMLElement).style.left;
 
       // Move further off-canvas (still outside the 800px-wide composition).
       act(() => {
         h.movedElement.style.left = "1200px";
       });
-      await act(async () => {
-        await Promise.resolve();
-        await flushAnimationFrames();
+      await untilIndicator(h.host, (indicator) => {
+        expect(indicator).toBeTruthy();
+        expect((indicator!.parentElement as HTMLElement).style.left).not.toEqual(leftBefore);
       });
-
-      const after = h.host.querySelector(INDICATOR);
-      expect(after).toBeTruthy();
-      const leftAfter = (after!.parentElement as HTMLElement).style.left;
-      expect(leftAfter).not.toEqual(leftBefore);
     } finally {
       h.cleanup();
     }

package/src/components/editor/overlayFrameLoop.test.ts

@@ -7,6 +7,7 @@ import {
   resetOverlayFrameLoopForTests,
   subscribeOverlayFrame,
 } from "./overlayFrameLoop";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 /**
  * The editor's overlay polls run on one shared, parkable frame loop. The two
@@ -37,6 +38,7 @@ describe("overlay frame loop", () => {
   };
 
   beforeEach(() => {
+    usePlayerStore.setState({ previewBooted: true });
     vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance", "Date"] });
     queued = [];
     window.requestAnimationFrame = ((callback: FrameRequestCallback) => {
@@ -55,6 +57,20 @@ describe("overlay frame loop", () => {
     window.cancelAnimationFrame = originalCancelRaf;
   });
 
+  it("does not poll the preview before it boots, and wakes when it does", () => {
+    usePlayerStore.setState({ previewBooted: false });
+    let runs = 0;
+    subscribeOverlayFrame(() => {
+      runs += 1;
+    });
+    framesOver(1000);
+    expect(runs).toBe(0);
+
+    usePlayerStore.getState().markPreviewBooted();
+    framesOver(32);
+    expect(runs).toBeGreaterThan(0);
+  });
+
   it("runs every subscriber on one frame, not one frame each", () => {
     const calls: string[] = [];
     subscribeOverlayFrame(() => calls.push("a"));

package/src/components/editor/overlayFrameLoop.ts

@@ -25,6 +25,8 @@
  * the next couple of hundred milliseconds, and no further event is dispatched
  * while it does.
  */
+import { usePlayerStore } from "../../player/store/playerStore";
+
 const AWAKE_MS = 400;
 /** How often a parked loop runs one frame anyway, in case a wake was missed. */
 export const IDLE_POLL_MS = 250;
@@ -35,6 +37,7 @@ let frameId: number | null = null;
 let idleTimerId: ReturnType<typeof setTimeout> | null = null;
 let awakeUntil = 0;
 let listenersAttached = false;
+let stopBootWake: (() => void) | null = null;
 
 /** Wake sources. All passive reads; none of them can be cancelled by us. */
 const WINDOW_EVENTS = [
@@ -111,6 +114,9 @@ function runFrame(): void {
   // it — and a shared loop makes that failure four overlays wide plus the
   // idle-poll safety net, permanently, rather than one overlay's own problem.
   schedule();
+  // Nothing to track until the live preview boots, and a poll before then forces layout
+  // on a document that is still loading, on the thread the boot runs on.
+  if (!usePlayerStore.getState().previewBooted) return;
   for (const subscriber of subscribers) {
     try {
       subscriber();
@@ -154,6 +160,9 @@ function attachListeners(): void {
     window.addEventListener(type, requestOverlayFrames, { capture: true, passive: true });
   }
   window.addEventListener("message", onPreviewMessage, { capture: true, passive: true });
+  stopBootWake = usePlayerStore.subscribe((state, prev) => {
+    if (state.previewBooted && !prev.previewBooted) requestOverlayFrames();
+  });
 }
 
 function detachListeners(): void {
@@ -163,6 +172,8 @@ function detachListeners(): void {
     window.removeEventListener(type, requestOverlayFrames, { capture: true });
   }
   window.removeEventListener("message", onPreviewMessage, { capture: true });
+  stopBootWake?.();
+  stopBootWake = null;
 }
 
 /**

package/src/components/editor/usePreviewCompositionRect.test.tsx

@@ -2,12 +2,13 @@
 
 import { act, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { resetOverlayFrameLoopForTests } from "./overlayFrameLoop";
 import {
   usePreviewCompositionRect,
   type PreviewCompositionRect,
 } from "./usePreviewCompositionRect";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -59,6 +60,10 @@ function compositionFrame(box: [number, number, number, number], width: number,
 
 const settle = () => new Promise((r) => setTimeout(r, 400));
 
+beforeEach(() => {
+  usePlayerStore.setState({ previewBooted: true });
+});
+
 describe("usePreviewCompositionRect", () => {
   it("reports the live preview iframe's box relative to the overlay, scaled to the composition", async () => {
     const probe = mountProbe();

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

@@ -10,6 +10,7 @@ import { readPreviewComplexity } from "../../player/hooks/usePreviewFirstFrameTe
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
 const playerMounts: string[] = [];
+let livePlayerProps: { onReadyToShowChange?: (ready: boolean) => void } = {};
 
 vi.mock("../../player", async () => {
   const React = await import("react");
@@ -18,11 +19,13 @@ vi.mock("../../player", async () => {
     Player: React.forwardRef(function MockPlayer(
       props: {
         onLoad?: () => void;
+        onReadyToShowChange?: (ready: boolean) => void;
         suppressLoadingOverlay?: boolean;
         style?: React.CSSProperties;
       },
       ref: React.ForwardedRef<HTMLIFrameElement>,
     ) {
+      if (!props.suppressLoadingOverlay) livePlayerProps = props;
       React.useEffect(() => {
         props.onLoad?.();
       }, [props]);
@@ -90,23 +93,25 @@ function renderPreview(
   document.body.append(host);
   const root = createRoot(host);
   const iframeRef = createRef<HTMLIFrameElement>();
-
-  act(() => {
-    root.render(
-      React.createElement(NLEPreview, {
-        projectId: "timeline-edit-playground",
-        iframeRef,
-        onIframeLoad: () => {},
-        previewSlots,
-        onShadowIframeLoad: () => {},
-        onShadowReadyChange: () => {},
-        onShadowError: () => {},
-        setShadowIframeNode: () => {},
-        resetPreviewSlots: () => {},
-        fillBox,
-      }),
-    );
-  });
+  const render = (directUrl?: string) =>
+    act(() => {
+      root.render(
+        React.createElement(NLEPreview, {
+          projectId: "timeline-edit-playground",
+          directUrl,
+          iframeRef,
+          onIframeLoad: () => {},
+          previewSlots,
+          onShadowIframeLoad: () => {},
+          onShadowReadyChange: () => {},
+          onShadowError: () => {},
+          setShadowIframeNode: () => {},
+          resetPreviewSlots: () => {},
+          fillBox,
+        }),
+      );
+    });
+  render();
 
   const viewport = host.querySelector('[aria-label="Composition preview"]') as HTMLDivElement;
   const stage = host.querySelector('[data-testid="preview-zoom-stage"]') as HTMLDivElement;
@@ -121,6 +126,7 @@ function renderPreview(
   return {
     host,
     root,
+    render,
     viewport,
     stage,
     cleanup() {
@@ -283,6 +289,77 @@ describe("NLEPreview", () => {
     view.cleanup();
   });
 
+  it("covers the live preview with the cached frame-0 poster until it is ready to show", () => {
+    const view = renderPreview();
+    const poster = () =>
+      view.stage.querySelector<HTMLImageElement>('[data-testid="preview-poster"]');
+    expect(poster()?.getAttribute("src")).toBe(
+      "/api/projects/timeline-edit-playground/thumbnail/index.html?t=0&output=source&cached=1",
+    );
+    expect(poster()?.style.zIndex).toBe("2");
+
+    act(() => livePlayerProps.onReadyToShowChange?.(false));
+    expect(poster()?.hidden).toBe(false);
+    act(() => livePlayerProps.onReadyToShowChange?.(true));
+    expect(poster()?.hidden).toBe(true);
+    act(() => poster()?.dispatchEvent(new Event("load")));
+    expect(poster()).toBeNull();
+    view.cleanup();
+  });
+
+  describe("a missing poster", () => {
+    const renderUrl =
+      "/api/projects/timeline-edit-playground/thumbnail/index.html?t=0&output=source";
+    const fetchSpy = vi.fn(() => Promise.resolve(new Response()));
+    beforeEach(() => {
+      fetchSpy.mockClear();
+      vi.stubGlobal("fetch", fetchSpy);
+    });
+    afterEach(() => vi.unstubAllGlobals());
+
+    const settle = (
+      view: ReturnType<typeof renderPreview>,
+      steps: Array<"ready" | "missing" | "loaded">,
+    ) => {
+      for (const step of steps) {
+        const poster = view.stage.querySelector('[data-testid="preview-poster"]');
+        act(() =>
+          step === "ready"
+            ? livePlayerProps.onReadyToShowChange?.(true)
+            : poster?.dispatchEvent(new Event(step === "missing" ? "error" : "load")),
+        );
+      }
+    };
+
+    it("is rendered for the next open when the live frame is ready first", () => {
+      const view = renderPreview();
+      settle(view, ["ready", "missing"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      expect(view.stage.querySelector('[data-testid="preview-poster"]')).toBeNull();
+      view.cleanup();
+    });
+
+    it("is rendered once the live frame is ready when it is missing first", () => {
+      const view = renderPreview();
+      settle(view, ["missing"]);
+      expect(fetchSpy).not.toHaveBeenCalled();
+      settle(view, ["ready", "ready"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      view.cleanup();
+    });
+
+    it("is rendered on a return from a sub-composition when the live frame is ready first", () => {
+      const view = renderPreview();
+      settle(view, ["loaded", "ready"]);
+      view.render("/api/projects/timeline-edit-playground/preview/comp/compositions/intro.html");
+      settle(view, ["ready"]);
+      view.render();
+      settle(view, ["ready", "missing"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      view.cleanup();
+    });
+  });
+
   it("mounts the live player once when the composition switches", () => {
     playerMounts.length = 0;
     const Harness = ({ projectId }: { projectId: string }) => {

package/src/components/nle/NLEPreview.tsx

@@ -19,6 +19,7 @@ import {
 import { RULER_GUTTER_PX, usePreviewGuidesStore } from "../editor/previewGuidesStore";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { usePreviewFirstFrameTelemetry } from "../../player/hooks/usePreviewFirstFrameTelemetry";
+import { PreviewPoster, usePreviewPoster } from "./PreviewPoster";
 interface NLEPreviewProps {
   projectId: string;
   iframeRef: RefObject<HTMLIFrameElement | null>;
@@ -154,6 +155,7 @@ export const NLEPreview = memo(function NLEPreview({
   const liveGenRef = useRef<number | null>(null);
   const reportPreviewFirstFrame = usePreviewFirstFrameTelemetry(previewSlots);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
+  const poster = usePreviewPoster(projectId, activeKey, directUrl);
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
   const insetPx = fillBox ? 0 : PREVIEW_STAGE_INSET_PX;
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
@@ -522,6 +524,8 @@ export const NLEPreview = memo(function NLEPreview({
                     applyInitialZoom();
                   }}
                   onCompositionLoadingChange={onCompositionLoadingChange}
+                  onReadyToShowChange={poster.onLiveReadyToShowChange}
+                  onPreviewError={poster.onPreviewError}
                   onPainted={(details) => reportPreviewFirstFrame(slot, details)}
                   portrait={portrait}
                   suppressLoadingOverlay={suppressLoadingOverlay}
@@ -547,6 +551,16 @@ export const NLEPreview = memo(function NLEPreview({
                 />
               ),
             )}
+            {poster.mountPoster && (
+              <PreviewPoster
+                key={activeKey}
+                projectId={projectId}
+                hidden={poster.hidePoster}
+                onSize={(size) => setCompositionSize((prev) => prev ?? size)}
+                onLoaded={poster.onPosterLoaded}
+                onMissing={poster.onPosterMissing}
+              />
+            )}
           </div>
         </div>
         <div