@hyperframes/studio 0.8.82 → 0.8.83

package/src/index.ts

@@ -1,35 +1,5 @@
 // UI primitives
-export { Button, buttonBase, buttonSizes, buttonVariants } from "./components/ui/Button";
-export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
-export { HyperframesLogo } from "./components/StudioHeader";
-export { IconButton } from "./components/ui/IconButton";
-export { Tab, TabPanel, Tabs, TabsList } from "./components/ui/Tabs";
-export { HyperframesLoader } from "./components/ui/HyperframesLoader";
-export type { HyperframesLoaderProps } from "./components/ui/HyperframesLoader";
-export { Tooltip } from "./components/ui/Tooltip";
-export { cn } from "./components/ui/cn";
-export {
-  ContextMenu,
-  Menu,
-  MenuItem,
-  MenuRadioGroup,
-  MenuRadioItem,
-  MenuSeparator,
-  MenuShortcut,
-  popupSurface,
-} from "./components/ui/Menu";
-export type { MenuItemTone, PopupPreviewState } from "./components/ui/Menu";
-export { Popover } from "./components/ui/Popover";
-export { Input, fieldBase, fieldText } from "./components/ui/Input";
-export type { InputProps } from "./components/ui/Input";
-export { NumberField } from "./components/ui/NumberField";
-export type { NumberFieldProps } from "./components/ui/NumberField";
-export { Select } from "./components/ui/Select";
-export type { SelectOption, SelectProps } from "./components/ui/Select";
-export { Slider } from "./components/ui/Slider";
-export type { SliderProps } from "./components/ui/Slider";
-export { Toggle } from "./components/ui/Toggle";
-export type { ToggleProps } from "./components/ui/Toggle";
+export * from "./ui";
 
 // NLE Layout
 export { EditorShell } from "./components/EditorShell";
@@ -154,7 +124,10 @@ export { parseStyleString, mergeStyleIntoTag, findElementBlock } from "./utils/h
 export { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
 export type { UsePersistentEditHistoryOptions } from "./hooks/usePersistentEditHistory";
 export { useTimelineEditing } from "./hooks/useTimelineEditing";
-export type { UseTimelineEditingOptions } from "./hooks/useTimelineEditingTypes";
+export type {
+  TimelineZIndexReorderCommit,
+  UseTimelineEditingOptions,
+} from "./hooks/useTimelineEditingTypes";
 // A host's own waitForPendingDomEditSaves must also call this, or undo/redo
 // can race a write still in flight (see useTrackPendingTimelineEdit.ts).
 export { flushStudioPendingEdits } from "./utils/studioPendingEdits";
@@ -193,9 +166,49 @@ export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
 export { useClipboard } from "./hooks/useClipboard";
 export type { UseClipboardOptions } from "./hooks/useClipboard";
 
+// DOM editing: the canvas session, persistence and overlay, for a host outside EditorShell.
+export { useDomEditSession } from "./hooks/useDomEditSession";
+export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
+export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
+export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";
+export { DomEditProvider, useDomEditSelectionContext } from "./contexts/DomEditContext";
+export { PreviewReadOnlyProvider } from "./components/editor/previewReadOnlyContext";
+export { ConnectedDomEditOverlay } from "./components/editor/ConnectedDomEditOverlay";
+export type { ConnectedDomEditOverlayProps } from "./components/editor/ConnectedDomEditOverlay";
+export type { DomEditCapabilities, DomEditSelection } from "./components/editor/domEditingTypes";
+
 export {
   playSeamTransitionLoop,
   type SeamTransitionFrameSource,
   type SeamTransitionLoopHandle,
   type SeamTransitionLoopOptions,
 } from "@hyperframes/shader-transitions";
+
+// Editor gestures for a host's own preview overlay: snapping and the marquee
+export {
+  SNAP_THRESHOLD_PX,
+  snapEngagedForTravel,
+  extractSnapTargets,
+  buildCompositionSnapTarget,
+  buildGridSnapEdges,
+  resolveSnapAdjustment,
+  resolveGuideLineRect,
+  resolveEquidistanceGuides,
+} from "./components/editor/snapEngine";
+export type {
+  SnapEdge,
+  SnapTarget,
+  SnapGuide,
+  SpacingGuide,
+  SnapResult,
+  Rect as SnapRect,
+} from "./components/editor/snapEngine";
+export { collectSnapContext } from "./components/editor/snapTargetCollection";
+export type { SnapContext } from "./components/editor/snapTargetCollection";
+export { SnapGuideOverlay } from "./components/editor/SnapGuideOverlay";
+export type { SnapGuideOverlayProps, SnapGuidesState } from "./components/editor/SnapGuideOverlay";
+export { useMarqueeGestures } from "./components/editor/marqueeCommit";
+export type { MarqueeGestures, MarqueeGesturesDeps } from "./components/editor/marqueeCommit";
+export { MarqueeOverlay } from "./components/editor/MarqueeOverlay";
+export type { MarqueeOverlayProps } from "./components/editor/MarqueeOverlay";
+export type { Rect as MarqueeRect } from "./utils/marqueeGeometry";

package/src/lightEntries.test.ts

@@ -0,0 +1,32 @@
+// @vitest-environment happy-dom
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+
+const packageDir = resolve(import.meta.dirname, "..");
+const { subpaths } = JSON.parse(readFileSync(resolve(packageDir, "package-subpaths.json"), "utf8"));
+
+function refuse(name: string): never {
+  throw new Error(`a light entry loaded ${name}`);
+}
+vi.mock("@hyperframes/core", () => refuse("@hyperframes/core"));
+vi.mock("@hyperframes/shader-transitions", () => refuse("@hyperframes/shader-transitions"));
+vi.mock("@codemirror/view", () => refuse("@codemirror/view"));
+vi.mock("@codemirror/state", () => refuse("@codemirror/state"));
+vi.mock("mediabunny", () => refuse("mediabunny"));
+vi.mock("gsap", () => refuse("gsap"));
+vi.mock("@hyperframes/parsers", () => refuse("@hyperframes/parsers"));
+vi.mock("@hyperframes/parsers/hf-ids", () => refuse("@hyperframes/parsers/hf-ids"));
+vi.mock("@hyperframes/sdk", () => refuse("@hyperframes/sdk"));
+vi.mock("dockview-react", () => refuse("dockview-react"));
+
+describe("entries a host imports for its first screen", () => {
+  it.each(["./ui", "./player"])(
+    "%s loads without the editor, the parsers, gsap or media decoding",
+    async (entry) => {
+      await expect(import(resolve(packageDir, subpaths[entry].source))).resolves.toBeDefined();
+    },
+    // The icon set alone is thousands of modules to transform on a cold run.
+    30_000,
+  );
+});

package/src/player/components/TimelineClipFades.test.tsx

@@ -71,8 +71,8 @@ function render(
   };
 }
 
-function pointer(type: string, clientX: number, pointerId = 1) {
-  const event = new MouseEvent(type, { bubbles: true, clientX, button: 0 });
+function pointer(type: string, clientX: number, pointerId = 1, clientY = 0) {
+  const event = new MouseEvent(type, { bubbles: true, clientX, clientY, button: 0 });
   Object.defineProperty(event, "pointerId", { value: pointerId });
   return event;
 }
@@ -134,14 +134,14 @@ describe("TimelineClipFades", () => {
     const handle = host.querySelector<HTMLElement>('[data-testid="clip-fade-handle-out"]');
     if (!handle) throw new Error("expected a fade-out handle");
     armCapture(handle);
-    // Handle at x=800 (2 s before the end). 300 px left → 5 s.
-    act(() => handle.dispatchEvent(pointer("pointerdown", 800)));
-    act(() => handle.dispatchEvent(pointer("pointermove", 500)));
+    // Pressed at x=1000 with a 2 s fade-out. 300 px left → 5 s.
+    act(() => handle.dispatchEvent(pointer("pointerdown", 1000)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 700)));
     expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-out", "5");
     // Way past the start: clamps to duration − fadeIn = 9 s.
-    act(() => handle.dispatchEvent(pointer("pointermove", -500)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 0)));
     expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-out", "9");
-    act(() => handle.dispatchEvent(pointer("pointerup", -500)));
+    act(() => handle.dispatchEvent(pointer("pointerup", 0)));
     expect(onSetElementAttributeQuiet).toHaveBeenCalledWith(clip, "data-fade-out", "9", "Fade out");
     act(() => root.unmount());
   });
@@ -151,9 +151,9 @@ describe("TimelineClipFades", () => {
     const handle = host.querySelector<HTMLElement>('[data-testid="clip-fade-handle-in"]');
     if (!handle) throw new Error("expected a fade-in handle");
     armCapture(handle);
-    act(() => handle.dispatchEvent(pointer("pointerdown", 100)));
-    act(() => handle.dispatchEvent(pointer("pointermove", -40)));
-    act(() => handle.dispatchEvent(pointer("pointerup", -40)));
+    act(() => handle.dispatchEvent(pointer("pointerdown", 200)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 0)));
+    act(() => handle.dispatchEvent(pointer("pointerup", 0)));
     expect(onSetElementAttributeQuiet).toHaveBeenCalledWith(clip, "data-fade-in", null, "Fade in");
     act(() => root.unmount());
   });
@@ -179,6 +179,27 @@ describe("TimelineClipFades", () => {
     act(() => root.unmount());
   });
 
+  it.each([
+    ["above the window", 300, -40],
+    ["on the window's right edge", window.innerWidth, 10],
+  ])("restores the fade and saves nothing when released %s", (_, clientX, clientY) => {
+    const { host, root, onSetElementAttributeLive, onRevertElementAttributeLive, ...rest } =
+      render(clip);
+    const handle = host.querySelector<HTMLElement>('[data-testid="clip-fade-handle-in"]');
+    if (!handle) throw new Error("expected a fade-in handle");
+    armCapture(handle);
+    act(() => handle.dispatchEvent(pointer("pointerdown", 100)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 300)));
+    act(() => handle.dispatchEvent(pointer("pointerup", clientX, 1, clientY)));
+    expect(rest.onSetElementAttributeQuiet).not.toHaveBeenCalled();
+    expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-in", "1");
+    expect(onRevertElementAttributeLive).toHaveBeenCalledWith(clip, "data-fade-in");
+    expect(host.querySelector('[data-testid="clip-fade-in"]')?.getAttribute("points")).toBe(
+      "0,0 100,0 0,100",
+    );
+    act(() => root.unmount());
+  });
+
   it("does not let a press on the dot start the clip's own move gesture", () => {
     const outer = vi.fn();
     const { host, root } = render(clip, { onClipPointerDown: outer });

package/src/player/components/TimelineClipFades.tsx

@@ -14,6 +14,7 @@ import {
 } from "@hyperframes/core/audio-fade";
 import type { TimelineElement } from "../store/playerStore";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { releasedOutsideWindow } from "./timelinePointerRelease";
 
 type FadeEdge = "in" | "out";
 
@@ -136,7 +137,7 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
   const finish = (e: PointerEvent<HTMLDivElement>, cancelled: boolean) => {
     const g = endGesture(e);
     if (!g) return;
-    if (cancelled || !g.moved) return revertGesture(g);
+    if (cancelled || !g.moved || releasedOutsideWindow(e)) return revertGesture(g);
     setDraft({ edge: g.edge, seconds: g.last });
     void onSetElementAttributeQuiet?.(
       el,

package/src/player/components/TimelineTypes.ts

@@ -4,18 +4,20 @@ import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
+import type { TimelineStackingSyncProps } from "./useTimelineStackingSync";
 
 export interface TimelineClipRenderContext {
   priority: "overscan" | "visible" | "interaction";
   rich: boolean;
 }
 
-export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
+export interface TimelineProps
+  extends TimelineDropCallbacks, TimelineEditOverrides, TimelineStackingSyncProps {
   /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
   sessionEpoch?: number;
-  /** keepPlaying: true preserves the current play state across the seek. */
   onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
   onDrillDown?: (element: TimelineElement) => void;
+  /** Picture only: takes no pointer input. Interactive content goes in renderClipOverlay. */
   renderClipContent?: (
     element: TimelineElement,
     style: { clip: string; label: string },

package/src/player/components/studioShortcuts.ts

@@ -1,5 +1,10 @@
-/** Bare keys Studio's app hotkeys bind; the shortcuts list names them from here. */
-export const STUDIO_PLAIN_KEYS = { fullscreen: "f", split: "s", record: "r" } as const;
+/** Bare keys Studio's hotkeys bind; the shortcuts list names them from here. */
+export const STUDIO_PLAIN_KEYS = {
+  fullscreen: "f",
+  split: "s",
+  record: "r",
+  addKeyframe: "k",
+} as const;
 
 export interface ShortcutHint {
   key: string;
@@ -32,10 +37,8 @@ export const DEFAULT_SHORTCUT_SECTIONS: readonly ShortcutSection[] = [
   {
     title: "Keyframes (when an element is selected)",
     hints: [
-      { key: "K", label: "Add keyframe at playhead" },
+      { key: hintKey(STUDIO_PLAIN_KEYS.addKeyframe), label: "Add / remove keyframe at playhead" },
       { key: "Del", label: "Delete selected keyframe" },
-      { key: "H", label: "Toggle hold / bezier" },
-      { key: "U", label: "Expand / collapse properties" },
       { key: hintKey(STUDIO_PLAIN_KEYS.record), label: "Record gesture" },
     ],
   },

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

@@ -1,7 +1,17 @@
+// @vitest-environment happy-dom
+
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
 import { describe, expect, it } from "vitest";
-import { resolveClipRenderContext } from "./timelineClipChildren";
+import { renderClipChildren, resolveClipRenderContext } from "./timelineClipChildren";
+import { getTrackStyle } from "./timelineIcons";
 import type { TimelineElement } from "../store/playerStore";
 
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
 const clip: TimelineElement = {
   id: "clip",
   tag: "video",
@@ -29,3 +39,26 @@ describe("resolveClipRenderContext", () => {
     });
   });
 });
+
+describe("renderClipChildren", () => {
+  // happy-dom cannot hit-test, so this pins what decides the hit: the picture takes no input.
+  it("lets a press on a picture stacked above the trim handles fall through to them", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const picture = () =>
+      createElement("div", { "data-picture": "", style: { position: "absolute", zIndex: 10 } });
+
+    act(() => {
+      root.render(renderClipChildren(clip, getTrackStyle("video"), picture, undefined));
+    });
+
+    // happy-dom does not inherit pointer-events, so walk up to the layer that turns input off.
+    let node = host.querySelector<HTMLElement>("[data-picture]");
+    expect(node).not.toBeNull();
+    while (node && node !== host && node.style.pointerEvents !== "none") node = node.parentElement;
+    expect(node?.style.pointerEvents).toBe("none");
+    act(() => root.unmount());
+    host.remove();
+  });
+});

package/src/player/components/timelineClipChildren.tsx

@@ -57,10 +57,13 @@ export function renderClipChildren(
       {renderClipOverlay?.(element)}
       {!renderClipContent && <ClipLintDot element={element} />}
       {renderClipContent && (
-        // borderRadius: inherit — the clip itself is overflow-visible (keyframe
-        // diamonds hang outside its bounds), so the thumbnail layer must clip
-        // itself to the clip's rounded corners or sharp corners poke out.
-        <div className="absolute inset-0 overflow-hidden" style={{ borderRadius: "inherit" }}>
+        // The picture can paint above the trim handles, so it takes no input and presses reach them.
+        // borderRadius: inherit clips it to the clip's rounded corners; the clip itself is
+        // overflow-visible because keyframe diamonds hang outside its bounds.
+        <div
+          className="absolute inset-0 overflow-hidden"
+          style={{ borderRadius: "inherit", pointerEvents: "none" }}
+        >
           {renderClipContent(element, clipStyle, context)}
         </div>
       )}

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

@@ -11,86 +11,108 @@ afterEach(() => {
   usePlayerStore.getState().reset();
 });
 
+const element: TimelineElement = {
+  id: "clip-1",
+  tag: "div",
+  start: 0,
+  duration: 2,
+  track: 0,
+};
+
+function mountGesture(kind: "drag" | "resize") {
+  const drag: DraggedClipState = {
+    pointerId: 0,
+    element,
+    originClientX: 0,
+    originClientY: 0,
+    originScrollLeft: 0,
+    originScrollTop: 0,
+    pointerClientX: 0,
+    pointerClientY: 0,
+    pointerOffsetX: 0,
+    pointerOffsetY: 0,
+    previewStart: 1,
+    previewTrack: 0,
+    desiredTrack: 0,
+    insertRow: null,
+    snapTime: null,
+    snapType: null,
+    started: true,
+  };
+  const resize: ResizingClipState = {
+    pointerId: 0,
+    element,
+    edge: "end",
+    originClientX: 0,
+    previewStart: 0,
+    previewDuration: 3,
+    started: true,
+  };
+  const draggedClipRef = { current: kind === "drag" ? drag : null };
+  const resizingClipRef = { current: kind === "resize" ? resize : null };
+  const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
+    draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
+  };
+  const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
+    ...previous,
+    previewStart: 3,
+  }));
+  const onMoveElement = vi.fn();
+  const onResizeElement = vi.fn();
+  const updateElement = vi.fn();
+  const stopAutoScroll = vi.fn();
+  const cancelGestureRef = { current: () => false };
+  const dispose = mountTimelineClipDragGestureLifecycle({
+    lifecycleRef: { current: { kind, phase: "active", pointerId: null, sessionEpoch: 0 } },
+    sessionEpochRef: { current: 0 },
+    cancelGestureRef,
+    scrollRef: { current: null },
+    draggedClipRef,
+    resizingClipRef,
+    blockedClipRef: { current: null },
+    groupResizeRef: { current: null },
+    suppressClickRef: { current: false },
+    gestureSelectedKeysRef: { current: new Set() },
+    elementsRef: { current: [element] },
+    trackOrderRef: { current: [0] },
+    setDraggedClipState: setDraggedClip,
+    setResizingClipState: () => {},
+    setShowPopover: () => {},
+    setRangeSelectionRef: { current: null },
+    applyResizePointerRef: { current: () => {} },
+    syncClipDragAutoScrollRef: { current: () => {} },
+    stopClipDragAutoScrollRef: { current: stopAutoScroll },
+    updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
+    publishDraggedClip: setDraggedClip,
+    updateElement,
+    onMoveElementRef: { current: onMoveElement },
+    onMoveElementsRef: { current: undefined },
+    onResizeElementRef: { current: onResizeElement },
+    onResizeElementsRef: { current: undefined },
+    onBlockedEditAttemptRef: { current: undefined },
+    readZIndexRef: { current: undefined },
+    onStackingPatchesRef: { current: undefined },
+    refreshAfterLaneMoveRef: { current: undefined },
+  });
+  return {
+    draggedClipRef,
+    resizingClipRef,
+    updateDraggedClipPreview,
+    onMoveElement,
+    onResizeElement,
+    updateElement,
+    stopAutoScroll,
+    cancelGestureRef,
+    dispose,
+  };
+}
+
+const release = (clientX: number, clientY: number) =>
+  window.dispatchEvent(new MouseEvent("pointerup", { clientX, clientY }));
+
 describe("timeline clip drag gesture lifecycle", () => {
   it("finishes a drag after virtualization unmounts its source row", () => {
-    const element: TimelineElement = {
-      id: "clip-1",
-      tag: "div",
-      start: 0,
-      duration: 2,
-      track: 0,
-    };
-    const drag: DraggedClipState = {
-      pointerId: 0,
-      element,
-      originClientX: 0,
-      originClientY: 0,
-      originScrollLeft: 0,
-      originScrollTop: 0,
-      pointerClientX: 0,
-      pointerClientY: 0,
-      pointerOffsetX: 0,
-      pointerOffsetY: 0,
-      previewStart: 1,
-      previewTrack: 0,
-      desiredTrack: 0,
-      insertRow: null,
-      snapTime: null,
-      snapType: null,
-      started: true,
-    };
-    const draggedClipRef = { current: drag as DraggedClipState | null };
-    const resizingClipRef = { current: null as ResizingClipState | null };
-    const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
-      draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
-    };
-    const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
-      ...previous,
-      previewStart: 3,
-    }));
-    const onMoveElement = vi.fn();
-    const stopAutoScroll = vi.fn();
-    const cancelGestureRef = { current: () => false };
-    const dispose = mountTimelineClipDragGestureLifecycle({
-      lifecycleRef: {
-        current: {
-          kind: "drag",
-          phase: "active",
-          pointerId: null,
-          sessionEpoch: 0,
-        },
-      },
-      sessionEpochRef: { current: 0 },
-      cancelGestureRef,
-      scrollRef: { current: null },
-      draggedClipRef,
-      resizingClipRef,
-      blockedClipRef: { current: null },
-      groupResizeRef: { current: null },
-      suppressClickRef: { current: false },
-      gestureSelectedKeysRef: { current: new Set() },
-      elementsRef: { current: [element] },
-      trackOrderRef: { current: [0] },
-      setDraggedClipState: setDraggedClip,
-      setResizingClipState: () => {},
-      setShowPopover: () => {},
-      setRangeSelectionRef: { current: null },
-      applyResizePointerRef: { current: () => {} },
-      syncClipDragAutoScrollRef: { current: () => {} },
-      stopClipDragAutoScrollRef: { current: stopAutoScroll },
-      updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
-      publishDraggedClip: setDraggedClip,
-      updateElement: vi.fn(),
-      onMoveElementRef: { current: onMoveElement },
-      onMoveElementsRef: { current: undefined },
-      onResizeElementRef: { current: undefined },
-      onResizeElementsRef: { current: undefined },
-      onBlockedEditAttemptRef: { current: undefined },
-      readZIndexRef: { current: undefined },
-      onStackingPatchesRef: { current: undefined },
-      refreshAfterLaneMoveRef: { current: undefined },
-    });
-
+    const g = mountGesture("drag");
     const sourceRow = document.createElement("div");
     sourceRow.dataset.timelineRow = "";
     sourceRow.append(document.createElement("div"));
@@ -98,15 +120,49 @@ describe("timeline clip drag gesture lifecycle", () => {
     sourceRow.remove();
 
     window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
-    expect(updateDraggedClipPreview).toHaveBeenCalledTimes(1);
-    expect(draggedClipRef.current?.previewStart).toBe(3);
+    expect(g.updateDraggedClipPreview).toHaveBeenCalledTimes(1);
+    expect(g.draggedClipRef.current?.previewStart).toBe(3);
 
     window.dispatchEvent(new MouseEvent("pointerup"));
-    expect(onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
-    expect(draggedClipRef.current).toBeNull();
-    expect(stopAutoScroll).toHaveBeenCalledTimes(1);
+    expect(g.onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
+    expect(g.draggedClipRef.current).toBeNull();
+    expect(g.stopAutoScroll).toHaveBeenCalledTimes(1);
+
+    g.dispose();
+    expect(g.cancelGestureRef.current()).toBe(false);
+  });
+
+  it.each([
+    ["above the window", 20, -40],
+    ["past the window's right edge", window.innerWidth + 40, 10],
+    ["on the window's right edge", window.innerWidth, 10],
+    ["on the window's bottom edge", 20, window.innerHeight],
+  ])("cancels a drag released %s and leaves the clip where it was", (_, clientX, clientY) => {
+    const g = mountGesture("drag");
+    window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
+    release(clientX, clientY);
+    expect(g.onMoveElement).not.toHaveBeenCalled();
+    expect(g.updateElement).not.toHaveBeenCalled();
+    expect(g.draggedClipRef.current).toBeNull();
+    // The cancel ended the gesture, so a later release has nothing to commit.
+    release(20, 10);
+    expect(g.onMoveElement).not.toHaveBeenCalled();
+    g.dispose();
+  });
+
+  it("cancels a trim released outside the window", () => {
+    const g = mountGesture("resize");
+    release(20, -40);
+    expect(g.onResizeElement).not.toHaveBeenCalled();
+    expect(g.updateElement).not.toHaveBeenCalled();
+    expect(g.resizingClipRef.current).toBeNull();
+    g.dispose();
+  });
 
-    dispose();
-    expect(cancelGestureRef.current()).toBe(false);
+  it("still commits a drag released on the window's last pixel", () => {
+    const g = mountGesture("drag");
+    release(window.innerWidth - 1, window.innerHeight - 1);
+    expect(g.onMoveElement).toHaveBeenCalledWith(element, { start: 1, track: 0 });
+    g.dispose();
   });
 });

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -8,6 +8,7 @@ import type {
 } from "./timelineClipDragTypes";
 import type { TimelineGroupResizeSession } from "./timelineGroupEditing";
 import { commitTimelineGroupResize } from "./timelineGroupResizeCommit";
+import { releasedOutsideWindow } from "./timelinePointerRelease";
 import {
   beginTimelineOptimisticGesture,
   rollbackLatestTimelineOptimisticGesture,
@@ -349,6 +350,7 @@ export function mountTimelineClipDragGestureLifecycle({
   };
 
   const handleWindowPointerUp = (event: PointerEvent) => {
+    if (releasedOutsideWindow(event)) return handleWindowPointerCancel(event);
     const claimed = claimActiveGesture(event);
     if (claimed === "ignored") return;
     if (claimed) {

package/src/player/components/timelinePointerRelease.ts

@@ -0,0 +1,4 @@
+export function releasedOutsideWindow(point: Pick<MouseEvent, "clientX" | "clientY">): boolean {
+  const { clientX: x, clientY: y } = point;
+  return x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight;
+}

package/src/player/components/useTimelineProviderState.tsx

@@ -71,6 +71,8 @@ export function useTimelineProviderState({
   canPasteClip,
   theme: themeOverrides,
   sessionEpoch = 0,
+  previewIframeRef,
+  onZIndexReorder,
 }: TimelineProps = {}): TimelineContextValue {
   const {
     onMoveElement,
@@ -184,6 +186,8 @@ export function useTimelineProviderState({
   });
   const { readClipZIndex, applyStackingPatches, zSyncEnabled } = useTimelineStackingSync({
     expandedElementsRef: timelineElementsRef,
+    previewIframeRef,
+    onZIndexReorder,
   });
   const {
     draggedClip,

package/src/player/components/useTimelineStackingSync.test.tsx

@@ -73,4 +73,50 @@ describe("useTimelineStackingSync", () => {
     mocks.actions = null;
     iframe.remove();
   });
+
+  it("uses a host's iframe and commit over Studio's own", async () => {
+    const studioCommit = vi.fn().mockResolvedValue(undefined);
+    mocks.actions = {
+      previewIframeRef: { current: null },
+      handleDomZIndexReorderCommit: studioCommit,
+    };
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const node = iframe.contentDocument!.createElement("div");
+    node.id = "a";
+    iframe.contentDocument!.body.appendChild(node);
+    const hostCommit = vi.fn().mockResolvedValue(undefined);
+    const element: TimelineElement = {
+      id: "a",
+      key: "a",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+    let sync: ReturnType<typeof useTimelineStackingSync> | null = null;
+    function Harness() {
+      sync = useTimelineStackingSync({
+        expandedElementsRef: { current: [element] },
+        previewIframeRef: { current: iframe },
+        onZIndexReorder: hostCommit,
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    await act(async () => {
+      await sync!.applyStackingPatches([{ key: "a", zIndex: 3 }]);
+    });
+
+    expect(sync!.zSyncEnabled).toBe(true);
+    expect(hostCommit).toHaveBeenCalledWith(
+      [expect.objectContaining({ element: node, zIndex: 3 })],
+      undefined,
+    );
+    expect(studioCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+    mocks.actions = null;
+    iframe.remove();
+  });
 });