@hyperframes/studio 0.8.138 → 0.8.140

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

@@ -0,0 +1,164 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StyleSections } from "./propertyPanelStyleSections";
+import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
+import type { DomEditSelection } from "./domEditing";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function mount(
+  Panel: typeof StyleSections | typeof FlatStyleSection,
+  tag = "img",
+  sourceFile = "index.html",
+  src = "assets/old.png",
+) {
+  const selected = document.createElement(tag);
+  selected.id = "picture";
+  selected.setAttribute("src", src);
+  document.body.append(selected);
+  const element: DomEditSelection = {
+    element: selected,
+    id: "picture",
+    selector: "#picture",
+    label: "Picture",
+    tagName: tag,
+    sourceFile,
+    compositionPath: sourceFile,
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 320, height: 180 },
+    textContent: "",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const onSetStyle = vi.fn((prop: string, value: string) =>
+    selected.style.setProperty(prop, value),
+  );
+  const onSetHtmlAttribute = vi.fn((attr: string, value: string | null) => {
+    if (value !== null) selected.setAttribute(attr, value);
+  });
+  act(() =>
+    root.render(
+      <Panel
+        projectId="fixture"
+        element={element}
+        styles={{}}
+        assets={["assets/old.png", "assets/new.png"]}
+        onSetStyle={onSetStyle}
+        onSetHtmlAttribute={onSetHtmlAttribute}
+      />,
+    ),
+  );
+  const image = Array.from(host.querySelectorAll("button")).find(
+    (button) => button.textContent === "Image",
+  );
+  if (!image) throw new Error("Image control must exist");
+  act(() => image.click());
+  // The Image asset select is the one whose options include the fixture asset.
+  const assetSelect = Array.from(host.querySelectorAll("select")).find((node) =>
+    Array.from(node.options).some((option) => option.value === "assets/new.png"),
+  );
+  if (!assetSelect) throw new Error("Project asset control must exist");
+  function choose(value: string) {
+    const control = assetSelect;
+    if (!control) throw new Error("Asset control must exist");
+    act(() => {
+      control.value = value;
+      control.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+  }
+  return { host, selected, root, choose, assetSelect, onSetStyle, onSetHtmlAttribute };
+}
+
+describe.each([
+  ["classic", StyleSections],
+  ["flat", FlatStyleSection],
+] as const)("%s Image fill", (_name, Panel) => {
+  it("shows the img source as the current project asset", () => {
+    const view = mount(Panel);
+    expect(view.assetSelect.value).toBe("assets/old.png");
+    act(() => view.root.unmount());
+  });
+  it.each([
+    "assets/100%.png",
+    'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="100%"></svg>',
+  ])("shows an authored source containing a literal percent: %s", (src) => {
+    const view = mount(Panel, "img", "index.html", src);
+    const input = Array.from(view.host.querySelectorAll("label"))
+      .find((node) => node.querySelector("span")?.textContent === "External URL")
+      ?.querySelector("input");
+    expect(input?.value).toBe(src);
+    act(() => view.root.unmount());
+  });
+  it("replaces the img source rather than writing a hidden background", () => {
+    const view = mount(Panel);
+    view.choose("assets/new.png");
+    expect(view.selected.getAttribute("src")).toBe("assets/new.png");
+    expect(view.onSetHtmlAttribute).toHaveBeenCalledExactlyOnceWith("src", "assets/new.png");
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("replaces an img with an external URL without CSS wrapping", () => {
+    const view = mount(Panel);
+    const row = Array.from(view.host.querySelectorAll("label")).find(
+      (node) =>
+        node.querySelector("span")?.textContent === "External URL" && node.querySelector("input"),
+    );
+    const input = row?.querySelector("input");
+    if (!input) throw new Error("External URL input must exist");
+    act(() => {
+      Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(
+        input,
+        "https://example.com/new.png",
+      );
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    act(() => input.dispatchEvent(new FocusEvent("focusout", { bubbles: true })));
+    expect(view.selected.getAttribute("src")).toBe("https://example.com/new.png");
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("keeps the img source when cleared", () => {
+    const view = mount(Panel);
+    view.choose("");
+    expect(view.selected.getAttribute("src")).toBe("assets/old.png");
+    expect(view.onSetHtmlAttribute).not.toHaveBeenCalled();
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("uses source-relative image paths in nested compositions", () => {
+    const view = mount(Panel, "img", "compositions/scene.html");
+    view.choose("assets/new.png");
+    expect(view.selected.getAttribute("src")).toBe("../assets/new.png");
+    act(() => view.root.unmount());
+  });
+  it("keeps background-image replacement and clearing for ordinary elements", () => {
+    const view = mount(Panel, "div");
+    view.choose("assets/new.png");
+    expect(view.selected.style.backgroundImage).toBe('url("assets/new.png")');
+    view.choose("");
+    expect(view.selected.style.backgroundImage).toBe("none");
+    expect(view.onSetHtmlAttribute).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+});

package/src/components/editor/propertyPanelStyleSections.tsx

@@ -45,6 +45,7 @@ export function StyleSections({
   styles,
   assets,
   onSetStyle,
+  onSetHtmlAttribute,
   onImportAssets,
   gsapBorderRadius,
   hideFlex = false,
@@ -54,6 +55,7 @@ export function StyleSections({
   styles: Record<string, string>;
   assets: string[];
   onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
+  onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
   onImportAssets?: (files: FileList) => Promise<string[]>;
   gsapBorderRadius?: { tl: number; tr: number; br: number; bl: number } | null;
   // When true, the Flex `Section` is suppressed. The flat inspector renders
@@ -108,12 +110,12 @@ export function StyleSections({
   const backgroundImage = styles["background-image"] ?? "none";
   const hasTextControls = isTextEditableSelection(element);
 
-  const fillMode =
-    backgroundImage && backgroundImage !== "none"
-      ? backgroundImage.includes("gradient")
-        ? "Gradient"
-        : "Image"
-      : "Solid";
+  let fillMode = "Solid";
+  if (element.tagName === "img") {
+    fillMode = "Image";
+  } else if (backgroundImage && backgroundImage !== "none") {
+    fillMode = backgroundImage.includes("gradient") ? "Gradient" : "Image";
+  }
   const [preferredFillMode, setPreferredFillMode] = useState(fillMode);
   const imageUrl = extractBackgroundImageUrl(backgroundImage);
   // Remember the last authored gradient so an exploratory Solid↔Gradient
@@ -488,7 +490,8 @@ export function StyleSections({
           ) : (
             <ImageFillField
               projectId={projectId}
-              sourceFile={element.sourceFile}
+              element={element}
+              onSetHtmlAttribute={onSetHtmlAttribute}
               value={imageUrl}
               assets={assets}
               disabled={styleEditingDisabled}

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

@@ -62,6 +62,7 @@ async function rotateWord(before: (word: HTMLElement) => void = () => {}) {
     gestureRef: ref<GestureState | null>(null),
     groupGestureRef: ref(null),
     blockedMoveRef: ref(null),
+    waitingPressRef: ref(null),
     rafPausedRef: ref(false),
     suppressNextBoxClickRef: ref(false),
     setOverlayRect: () => {},

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

@@ -19,6 +19,7 @@ function gestureHarness(gesture: Partial<GestureState> | null, group: GroupGestu
     hoverSelectionRef: { current: null },
     boxRef: { current: null },
     blockedMoveRef: { current: null },
+    waitingPressRef: { current: null },
     rafPausedRef: { current: false },
     suppressNextBoxClickRef: { current: false },
     snapGuidesRef: { current: null },

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -1,3 +1,4 @@
+import { createPreviewGestureStarts } from "./previewGestureStarts";
 import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
 // fallow-ignore-file code-duplication
 /**
@@ -28,13 +29,12 @@ import {
   type GroupOverlayItem,
   type OverlayRect,
   orientedOverlayRect,
+  shiftedOverlayRect,
 } from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
-  type GestureKind,
   type GestureState,
   type GroupGestureState,
-  type ResizeHandle,
   type UseDomEditOverlayGesturesOptions,
   ROTATED_SNAP_BYPASS_DEGREES,
   hasDomEditRotationChanged,
@@ -44,11 +44,7 @@ import {
 } from "./domEditOverlayGestures";
 import { resolveCenterResizeSize } from "./domEditResizeLocal";
 import { resolveResizeDraftRect } from "./resizeDraft";
-import {
-  notifyBlockedPress,
-  startGesture as _startGesture,
-  startGroupDrag as _startGroupDrag,
-} from "./domEditOverlayStartGesture";
+import { notifyBlockedPress } from "./domEditOverlayStartGesture";
 import { hugRectForElement } from "./domEditOverlayCrop";
 import {
   resolveSnapAdjustment,
@@ -76,7 +72,7 @@ function logGestureCommitFailure(message: string, error: unknown): void {
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
-    opts.setOverlayRect(next);
+    if (!opts.waitingPressRef.current) opts.setOverlayRect(next);
   };
   const restoreGestureOverlayRect = (g: GestureState) => {
     setDraftOverlayRect({
@@ -86,14 +82,12 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       height: g.originHeight,
       editScaleX: g.editScaleX,
       editScaleY: g.editScaleY,
-      // Every draft rect must carry the element's rotation: the rotation wrapper
-      // renders rotate(overlayRect.angle), so an omitted angle straightens the
-      // chrome for the duration of the draft (the "straightens while moving" bug).
+      // Rotation keeps the chrome aligned with the element during its draft.
       angle: g.actualRotation,
     });
   };
   const setDraftGroupOverlayItems = (next: GroupOverlayItem[]) => {
-    opts.setGroupOverlayItems(next);
+    if (!opts.waitingPressRef.current) opts.setGroupOverlayItems(next);
   };
 
   const restoreGroupPathOffsets = (g: GroupGestureState) => {
@@ -101,16 +95,12 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     setDraftGroupOverlayItems(g.originItems);
   };
 
-  const startGroupDrag = (e: React.PointerEvent<HTMLElement>) => _startGroupDrag(e, opts);
-  const startGesture = (
-    kind: GestureKind,
-    e: React.PointerEvent<HTMLElement>,
-    options?: {
-      selection?: DomEditSelection;
-      rect?: OverlayRect | null;
-      resizeHandle?: ResizeHandle;
-    },
-  ) => _startGesture(kind, e, opts, options);
+  const { startGesture, startGroupDrag, endWaitingPress, endHeldPress, releaseWaitingPress } =
+    createPreviewGestureStarts(
+      opts,
+      (event) => moveActiveGesture(event),
+      (event) => releaseActiveGesture(event),
+    );
 
   // A press on a box that cannot move says why at once.
   const startBlockedMove = (e: React.PointerEvent<HTMLElement>, selection: DomEditSelection) => {
@@ -123,12 +113,23 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
 
   const moveGroupDrag = createGroupDragMover(opts, setDraftGroupOverlayItems);
 
-  // fallow-ignore-next-line complexity
   const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const waiting = opts.waitingPressRef.current;
+    if (waiting && waiting.pointerId === e.pointerId) {
+      if (waiting.released || !movesGesture(waiting, e)) return;
+      waiting.moved = e;
+      waiting.draw?.(e.clientX - waiting.startX, e.clientY - waiting.startY);
+      return;
+    }
+    moveActiveGesture(e);
+  };
+
+  // fallow-ignore-next-line complexity
+  const moveActiveGesture = (e: React.PointerEvent<HTMLDivElement>) => {
     const g = opts.gestureRef.current;
     const groupG = opts.groupGestureRef.current;
     const sel = g?.selection ?? opts.selectionRef.current;
-    const box = opts.boxRef.current;
+    const box = opts.waitingPressRef.current ? null : opts.boxRef.current;
     const blockedMove = opts.blockedMoveRef.current;
     if (!blockedMove && !g && !groupG) {
       opts.onCanvasPointerMoveRef.current(e, { preferClipAncestor: false });
@@ -248,18 +249,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       }
       if (g.pathOffsetMember) applyManualOffsetDragDraft(g.pathOffsetMember, dx, dy);
     } else {
-      if (!box) return;
-
-      // CENTER-ANCHORED size (CapCut model): the element scales proportionally
-      // about its CENTER — the scale is the pointer's RADIAL distance from the
-      // element center now over its distance at gesture start. Rotation-invariant
-      // (a distance ignores the angle) and continuous, so all four corners behave
-      // identically and there is no per-axis projection or edge-snapping. Base size
-      // is the element-local px size at gesture start (actualWidth/Height,
-      // GSAP-scale-aware). Corner drag is ALWAYS proportional; there is no
-      // free-form stretch gesture. Edge-snapping is intentionally NOT applied:
-      // with center anchoring both edges move symmetrically, so the corner-anchored
-      // snap math no longer holds — CapCut does not edge-snap during scale either.
+      // Corner resize scales proportionally about the center, without edge snapping.
       const nextSize = resolveCenterResizeSize({
         baseWidth: g.actualWidth,
         baseHeight: g.actualHeight,
@@ -288,33 +278,41 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         draftRect,
         liveInlineStyle: sel.element.getAttribute("style"),
       });
-      box.style.left = `${draftRect.left}px`;
-      box.style.top = `${draftRect.top}px`;
-      box.style.width = `${draftRect.width}px`;
-      box.style.height = `${draftRect.height}px`;
+      if (box) {
+        box.style.left = `${draftRect.left}px`;
+        box.style.top = `${draftRect.top}px`;
+        box.style.width = `${draftRect.width}px`;
+        box.style.height = `${draftRect.height}px`;
+      }
       setDraftOverlayRect(draftRect);
     }
   };
 
-  // fallow-ignore-next-line complexity
   const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const waiting = opts.waitingPressRef.current;
+    if (waiting && waiting.pointerId === e.pointerId) {
+      releaseWaitingPress(waiting, e);
+      opts.suppressNextBoxClickRef.current = true;
+      return;
+    }
+    releaseActiveGesture(e);
+  };
+
+  // fallow-ignore-next-line complexity
+  const releaseActiveGesture = (e: React.PointerEvent<HTMLDivElement>) => {
     opts.snapGuidesRef.current = null;
     const g = opts.gestureRef.current;
     const groupG = opts.groupGestureRef.current;
     const sel = g?.selection ?? opts.selectionRef.current;
-    const box = opts.boxRef.current;
+    const box = opts.waitingPressRef.current ? null : opts.boxRef.current;
     opts.blockedMoveRef.current = null;
+    opts.rafPausedRef.current = opts.waitingPressRef.current !== null;
 
     if (groupG) {
       opts.groupGestureRef.current = null;
-      opts.rafPausedRef.current = false;
       const rawDx = e.clientX - groupG.startX;
       const rawDy = e.clientY - groupG.startY;
-      // The click that trails every pointerup has to be eaten either way. The
-      // gesture ref is already cleared above, so by the time it arrives the box
-      // no longer looks busy, and handleBoxClick hands it to the canvas as an
-      // ordinary click — which lands between the members, resolves to nothing,
-      // and deselects the group the drag just moved.
+      // Consume the release click so it cannot deselect the moved group.
       opts.suppressNextBoxClickRef.current = true;
       if (isTap(groupG, e)) {
         restoreGroupPathOffsets(groupG);
@@ -331,7 +329,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       setDraftGroupOverlayItems(
         groupG.originItems.map((item) => ({
           ...item,
-          rect: { ...item.rect, left: item.rect.left + dx, top: item.rect.top + dy },
+          rect: shiftedOverlayRect(item.rect, dx, dy),
         })),
       );
       const updates = groupG.members.map((member) => ({
@@ -367,23 +365,15 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         .finally(() => {
           logDrag("committed", { at: readDragPositions(groupG.members) });
           endManualOffsetDragMembers(groupG.members);
-          // The gesture teardown resumes the paused timelines and re-seeks the
-          // player, which re-renders from whatever the preview currently holds.
-          // If the reloaded source has not landed yet that is the OLD position,
-          // so this is where a snap-back would show.
+          // Teardown re-seeks the player, exposing any stale preview position.
           logDragSettle("settle", groupG.members);
         });
       groupEdit.settle(groupSaved);
       return;
     }
 
-    if (!g || !sel) {
-      opts.gestureRef.current = null;
-      opts.rafPausedRef.current = false;
-      return;
-    }
     opts.gestureRef.current = null;
-    opts.rafPausedRef.current = false;
+    if (!g || !sel) return;
     const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
 
     if (g.kind === "drag" && isTap(g, e)) {
@@ -457,10 +447,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
       edit.settle(saved);
     } else if (g.kind === "drag") {
-      // A moved drag (taps returned earlier) must not let the release click
-      // re-select whatever now sits under the pointer — dropping over a
-      // higher-z element should keep the dragged element selected, not select
-      // the drop target. Mirrors the resize branch below.
+      // A release over another layer must keep this dragged layer selected.
       opts.suppressNextBoxClickRef.current = true;
       const dx = g.lastSnappedDx ?? e.clientX - g.startX;
       const dy = g.lastSnappedDy ?? e.clientY - g.startY;
@@ -509,12 +496,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       opts.suppressNextBoxClickRef.current = true;
       const finalSize = readStudioBoxSize(sel.element);
       applyStudioBoxSize(sel.element, finalSize);
-      // Anchored corner resize (NW/NE/SW) also moved the element to keep the
-      // center planted. Land the size AND the anchor offset in a SINGLE
-      // box-size commit (one persist, one undo entry). The prior two-commit
-      // sequence re-stamped the element from source after the size-only persist
-      // but before the offset persist landed — that one frame (new size, old
-      // offset) was the release "jump". SE has no anchor member → size only.
+      // Save size and center-preserving offset together under one undo entry.
       const member = g.pathOffsetMember;
       const anchor = g.lastResizeAnchor;
       const finalOffset =
@@ -554,8 +536,14 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
   };
 
+  /** `dropQueued`: released presses still waiting go too, as when the overlay leaves or turns read-only. */
   // fallow-ignore-next-line complexity
-  const clearPointerState = (selectionRef: RefObject<DomEditSelection | null>) => {
+  const clearPointerState = (
+    selectionRef: RefObject<DomEditSelection | null>,
+    dropQueued = false,
+  ) => {
+    if (dropQueued) endWaitingPress();
+    else endHeldPress();
     opts.snapGuidesRef.current = null;
     const groupG = opts.groupGestureRef.current;
     if (groupG) restoreGroupPathOffsets(groupG);
@@ -586,7 +574,14 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     opts.blockedMoveRef.current = null;
     opts.groupGestureRef.current = null;
     opts.gestureRef.current = null;
-    opts.rafPausedRef.current = false;
+    opts.rafPausedRef.current = opts.waitingPressRef.current !== null;
+  };
+
+  const onLostPointerCapture = (e: React.PointerEvent<HTMLDivElement>) => {
+    const waiting = opts.waitingPressRef.current;
+    // Pointerup releases capture normally; the queued edit still has to land.
+    if (waiting?.pointerId === e.pointerId && waiting.released) return;
+    clearPointerState(opts.selectionRef);
   };
 
   return {
@@ -595,6 +590,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     startBlockedMove,
     onPointerMove,
     onPointerUp,
+    onLostPointerCapture,
     clearPointerState,
   };
 }

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

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { shouldDisableTimelineWhileCompositionLoading, NLEProvider } from "./NLEContext";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
+import { isPreviewChanging, requestPreviewReload } from "../../player/previewReloading";
 
 installReactActEnvironment();
 
@@ -143,3 +144,28 @@ describe("NLEProvider — composition source-map scoping", () => {
     host.remove();
   });
 });
+
+describe("NLEProvider — a requested reload", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => Promise.reject(new Error("no network in tests"))),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("stops counting as a preview change once the refresh begins, so later presses do not wait", async () => {
+    const { host, root } = await mountNleProvider({ projectId: "p", refreshKey: 0 });
+    requestPreviewReload();
+    expect(isPreviewChanging()).toBe(true);
+
+    await renderNleProvider(root, { projectId: "p", refreshKey: 1 });
+    expect(isPreviewChanging()).toBe(false);
+
+    act(() => root.unmount());
+    host.remove();
+  });
+});

package/src/components/nle/NLEContext.tsx

@@ -10,6 +10,7 @@ import { ensureMotionPathPluginLoaded } from "../../utils/gsapSoftReload";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { createStableContext } from "../../utils/hmrStableContext";
 import { studioApiFetch } from "../../utils/studioApiFetch";
+import { previewReloadBegun } from "../../player/previewReloading";
 
 export function shouldDisableTimelineWhileCompositionLoading(compositionLoading: boolean): boolean {
   return compositionLoading;
@@ -130,9 +131,13 @@ export function NLEProvider({
   // Lightweight reload: change iframe src instead of destroying the Player.
   const prevRefreshKeyRef = useRef(refreshKey);
   useEffect(() => {
-    if (refreshKey === prevRefreshKeyRef.current) return;
-    prevRefreshKeyRef.current = refreshKey;
-    refreshPlayer();
+    try {
+      if (refreshKey === prevRefreshKeyRef.current) return;
+      prevRefreshKeyRef.current = refreshKey;
+      refreshPlayer();
+    } finally {
+      previewReloadBegun();
+    }
   }, [refreshKey, refreshPlayer]);
 
   // Steps that follow every load of the live iframe, including a reload promoted in place.

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

@@ -12,6 +12,12 @@ globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 const playerMounts: string[] = [];
 let livePlayerProps: { onReadyToShowChange?: (ready: boolean) => void } = {};
 
+const measured = vi.hoisted(() => ({ size: null as { width: number; height: number } | null }));
+vi.mock("../../utils/previewCompositionSize", async (original) => ({
+  ...(await original<typeof import("../../utils/previewCompositionSize")>()),
+  readPreviewCompositionSize: () => measured.size,
+}));
+
 vi.mock("../../player", async () => {
   const React = await import("react");
 
@@ -81,7 +87,12 @@ function renderPreview(
   {
     box = { width: 800, height: 600 },
     fillBox,
-  }: { box?: { width: number; height: number }; fillBox?: boolean } = {},
+    compositionSizeHint,
+  }: {
+    box?: { width: number; height: number };
+    fillBox?: boolean;
+    compositionSizeHint?: { width: number; height: number };
+  } = {},
 ) {
   resizeCallbacks = [];
   const host = document.createElement("div");
@@ -103,6 +114,7 @@ function renderPreview(
           setShadowIframeNode: () => {},
           resetPreviewSlots: () => {},
           fillBox,
+          compositionSizeHint,
         }),
       );
     });
@@ -378,6 +390,37 @@ describe("NLEPreview", () => {
     filled.cleanup();
   });
 
+  it("takes the host's composition size as the stage's shape until the preview measures its own", () => {
+    const box = { width: 800, height: 600 };
+    const plain = renderPreview(undefined, { box });
+    expect([plain.stage.style.width, plain.stage.style.height]).toEqual(["784px", "441px"]);
+    plain.cleanup();
+
+    const hinted = renderPreview(undefined, {
+      box,
+      compositionSizeHint: { width: 1276, height: 1078 },
+    });
+    const shape = parseFloat(hinted.stage.style.width) / parseFloat(hinted.stage.style.height);
+    expect(shape).toBeCloseTo(1276 / 1078, 3);
+    expect(hinted.stage.style.height).toBe("584px");
+    hinted.cleanup();
+  });
+
+  it("lets the size the preview measures win over the host's hint", () => {
+    measured.size = { width: 1920, height: 1080 };
+    try {
+      const box = { width: 800, height: 600 };
+      const hinted = renderPreview(undefined, {
+        box,
+        compositionSizeHint: { width: 1276, height: 1078 },
+      });
+      expect([hinted.stage.style.width, hinted.stage.style.height]).toEqual(["784px", "441px"]);
+      hinted.cleanup();
+    } finally {
+      measured.size = null;
+    }
+  });
+
   it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
     const view = renderPreview([
       { gen: 0, role: "live" },