@hyperframes/studio 0.8.81 → 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";
@@ -184,6 +157,25 @@ export type { TimelinePaneProps } from "./components/nle/TimelinePane";
 export { TimelineEditProvider } from "./contexts/TimelineEditContext";
 export type { TimelineEditCallbacks } from "./player/components/timelineCallbacks";
 export type { BlockedTimelineEditIntent } from "./player/components/timelineEditing";
+export { TimelineToolbar } from "./components/TimelineToolbar";
+export type { TimelineToolbarProps } from "./components/TimelineToolbar";
+export { TimelineHistoryButtons } from "./components/TimelineHistoryButtons";
+export type { TimelineHistoryButtonsProps } from "./components/TimelineHistoryButtons";
+export { AudioMeterStrip } from "./components/nle/AudioMeterStrip";
+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,
@@ -191,3 +183,32 @@ export {
   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/CompositionThumbnail.test.ts

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { buildCompositionThumbnailUrl, CompositionThumbnail } from "./CompositionThumbnail";
 
@@ -11,12 +12,6 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
   value: true,
 });
 
-class MockResizeObserver {
-  observe() {}
-  disconnect() {}
-  unobserve() {}
-}
-
 class MockImage {
   static instances: MockImage[] = [];
   onload: (() => void) | null = null;
@@ -146,6 +141,45 @@ describe("CompositionThumbnail", () => {
     );
   });
 
+  it.each([
+    { name: "a wide", width: 2700, height: 1000, tileWidth: 108 },
+    { name: "a square", width: 1000, height: 1000, tileWidth: 48 },
+    { name: "a portrait", width: 1080, height: 1920, tileWidth: 48 },
+  ])(
+    "shows $name picture whole at the clip's measured height",
+    async ({ width, height, tileWidth }) => {
+      Object.defineProperty(host, "clientWidth", { configurable: true, value: 500 });
+      Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+      const probe = await renderThumbnail();
+
+      await act(async () => {
+        probe.naturalWidth = width;
+        probe.naturalHeight = height;
+        probe.onload?.();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+
+      const img = host.querySelector("img")!;
+      expect(img.parentElement?.style.width).toBe(`${tileWidth}px`);
+      // A tile held at its minimum width letterboxes the picture instead of cropping it.
+      expect(img.classList.contains("object-contain")).toBe(true);
+    },
+  );
+
+  it("re-tiles at the height the resize observer reports", async () => {
+    const probe = await renderThumbnail();
+    await act(async () => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    act(() => reportResize(500, 40));
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
   it("aborts its scheduled off-DOM image probe when unmounted", async () => {
     const probe = await renderThumbnail();
     expect(host.querySelector("img")).toBeNull();

package/src/player/components/CompositionThumbnail.tsx

@@ -1,6 +1,6 @@
-import { memo, useCallback, useMemo, useRef, useState, type CSSProperties } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
+import { memo, useMemo, type CSSProperties } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
 import { computeThumbnailStrip, probeImageAspect } from "./thumbnailUtils";
@@ -22,7 +22,6 @@ interface CompositionThumbnailProps {
   rich?: boolean;
 }
 
-const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v3";
 export const THUMBNAIL_SEEK_TIME_SECONDS = 3;
 
@@ -122,8 +121,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   contentRevision = 0,
   priority = "visible",
 }: CompositionThumbnailProps) {
-  const [containerWidth, setContainerWidth] = useState(0);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [container, setContainerRef] = useThumbnailStripSize();
   const url = buildCompositionThumbnailUrl({
     previewUrl,
     seekTime,
@@ -149,25 +147,12 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   const value =
     snapshot.status === "ready" && snapshot.value.kind === "image" ? snapshot.value : null;
   const { frameW, frameCount } = computeThumbnailStrip(
-    containerWidth,
+    container.width,
     value?.aspect ?? 16 / 9,
-    CLIP_HEIGHT,
+    container.height,
     48,
   );
 
-  const setContainerRef = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
-    if (!element) return;
-    const target = element.parentElement ?? element;
-    setContainerWidth(target.clientWidth);
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setContainerWidth(entry.contentRect.width),
-    );
-    observerRef.current.observe(target);
-  }, []);
-
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       {value && (
@@ -189,7 +174,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
                 src={value.url}
                 alt=""
                 draggable={false}
-                className="absolute inset-0 h-full w-full object-cover"
+                className="absolute inset-0 h-full w-full object-contain"
                 style={{ opacity: "var(--timeline-composition-thumbnail-opacity)" }}
               />
             </div>

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

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { ImageThumbnail } from "./ImageThumbnail";
 
@@ -30,12 +31,6 @@ class MockIntersectionObserver {
   }
 }
 
-class MockResizeObserver {
-  observe() {}
-  disconnect() {}
-  unobserve() {}
-}
-
 // --- Image stub: captures instances so tests fire load/error deterministically ---
 class MockImage {
   static instances: MockImage[] = [];
@@ -171,6 +166,32 @@ describe("ImageThumbnail", () => {
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
+  it("tiles a wide picture at the clip's measured height, whole", async () => {
+    Object.defineProperty(host, "clientWidth", { configurable: true, value: 500 });
+    Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+    render({ imageSrc: "/api/projects/p/preview/assets/wide.png" });
+    await resolveProbe((probe) => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+    });
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
+  it("re-tiles at the height the resize observer reports", async () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/wide.png" });
+    await resolveProbe((probe) => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+    });
+
+    act(() => reportResize(500, 40));
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
   it("renders the label above the strip when provided", async () => {
     render({ imageSrc: "/x.png", label: "hero", labelColor: "#abc" });
     await resolveProbe((probe) => {

package/src/player/components/ImageThumbnail.tsx

@@ -1,6 +1,6 @@
-import { memo, useCallback, useMemo, useRef, useState } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
+import { memo, useMemo } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decodeImageThumbnail } from "../lib/thumbnailImageDecoder";
 import { computeThumbnailStrip } from "./thumbnailUtils";
@@ -25,8 +25,7 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   priority = "visible",
   rich = false,
 }: ImageThumbnailProps) {
-  const [containerWidth, setContainerWidth] = useState(0);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [container, setContainerRef] = useThumbnailStripSize();
   const request = useMemo(
     () => ({
       key: createThumbnailKey({ kind: "image", source: imageSrc, rich: Number(rich) }),
@@ -42,20 +41,7 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   const snapshot = useThumbnailLease(request);
   const value = snapshot.status === "ready" ? snapshot.value : null;
   const aspect = value?.kind === "image" ? value.aspect : 16 / 9;
-  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect);
-
-  const setContainerRef = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
-    if (!element) return;
-    const target = element.parentElement ?? element;
-    setContainerWidth(target.clientWidth);
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setContainerWidth(entry.contentRect.width),
-    );
-    observerRef.current.observe(target);
-  }, []);
-
-  useMountEffect(() => () => observerRef.current?.disconnect());
+  const { frameW, frameCount } = computeThumbnailStrip(container.width, aspect, container.height);
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">

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

@@ -0,0 +1,52 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import { PlayerControls } from "./PlayerControls";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let host: HTMLDivElement;
+let root: Root;
+
+beforeEach(async () => {
+  usePlayerStore.setState({
+    isPlaying: true,
+    currentTime: 2,
+    duration: 30,
+    timeDisplayMode: "time",
+  });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () =>
+    root.render(React.createElement(PlayerControls, { onTogglePlay: () => {}, onSeek: () => {} })),
+  );
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+});
+
+describe("PlayerControls timecode", () => {
+  it("rewrites the timecode only when the shown text changes", async () => {
+    const timecode = host.querySelector("button.font-mono > span");
+    expect(timecode?.textContent).toBe("00:02");
+    const writes: MutationRecord[] = [];
+    const observer = new MutationObserver((records) => writes.push(...records));
+    observer.observe(timecode as Node, { childList: true, characterData: true, subtree: true });
+
+    for (let frame = 1; frame <= 30; frame++) liveTime.notify(2 + frame / 120);
+    await Promise.resolve();
+    expect(writes).toHaveLength(0);
+
+    liveTime.notify(3.01);
+    await Promise.resolve();
+    expect(timecode?.textContent).toBe("00:03");
+    expect(writes.length).toBeGreaterThan(0);
+    observer.disconnect();
+  });
+});

package/src/player/components/PlayerControls.tsx

@@ -213,10 +213,11 @@ export const PlayerControls = memo(function PlayerControls({
       currentTimeRef.current = time;
       if (!timeDisplayRef.current) return;
       const currentDuration = durationRef.current;
-      timeDisplayRef.current.textContent =
+      const text =
         timeDisplayModeRef.current === "frame"
           ? formatFrameTime(time, currentDuration)
           : formatTime(time);
+      if (timeDisplayRef.current.textContent !== text) timeDisplayRef.current.textContent = text;
     };
     const unsubscribe = liveTime.subscribe(updateTime);
     updateTime(usePlayerStore.getState().currentTime);

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

@@ -39,7 +39,7 @@ import {
 } from "./timelineLayout";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { formatTime } from "../lib/time";
-import { usePlayerStore } from "../store/playerStore";
+import { liveTime, usePlayerStore } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
 
 vi.mock("./timelineRowVirtualizationFlag", () => ({
@@ -153,6 +153,27 @@ function renderSharedAutomationTimeline(selectedElementId?: string) {
   return { host, root };
 }
 
+describe("Timeline playhead motion", () => {
+  it("moves by fractional pixels while playing and snaps to device pixels once paused", () => {
+    usePlayerStore.setState({
+      duration: 11,
+      timelineReady: true,
+      currentTime: 10,
+      isPlaying: true,
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      elements: [{ id: "clip-1", tag: "div", start: 10, duration: 1, track: 0 }],
+    });
+    const { root, playhead } = renderTimelineGeometry("clip-1");
+    const wrapperLeft = GUTTER + TRACKS_LEFT_PAD + 1000.3 - PLAYHEAD_HEAD_W / 2;
+    act(() => liveTime.notify(10.003));
+    expect(playhead.style.transform).toBe(`translateX(${wrapperLeft}px)`);
+    act(() => usePlayerStore.setState({ isPlaying: false }));
+    expect(playhead.style.transform).toBe(`translateX(${Math.round(wrapperLeft)}px)`);
+    act(() => root.unmount());
+  });
+});
+
 describe("Timeline provider boundary", () => {
   it("keeps all-collapsed horizontal positions at the gutter plus the pre-t=0 pad", () => {
     usePlayerStore.setState({
@@ -173,7 +194,9 @@ describe("Timeline provider boundary", () => {
     expect(clip.style.bottom).toBe(`${CLIP_Y}px`);
     expect(rulerOrigin.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
     expect(rulerTick.style.left).toBe("999.5px");
-    expect(playhead.style.left).toBe(`${GUTTER + TRACKS_LEFT_PAD + 1000 - PLAYHEAD_HEAD_W / 2}px`);
+    expect(playhead.style.transform).toBe(
+      `translateX(${Math.round(GUTTER + TRACKS_LEFT_PAD + 1000 - PLAYHEAD_HEAD_W / 2)}px)`,
+    );
     expect(playhead.style.width).toBe(`${PLAYHEAD_HEAD_W}px`);
     expect(
       resolveTimelineAssetDrop(
@@ -283,7 +306,9 @@ describe("Timeline provider boundary", () => {
     expect(semanticRows[2]?.hasAttribute("aria-expanded")).toBe(false);
     expect(trackHeader.style.width).toBe(`${LABEL_COL_W}px`);
     expect(rulerOrigin.style.width).toBe(`${LABEL_COL_W + GUTTER}px`);
-    expect(playhead.style.left).toBe(`${LABEL_COL_W + GUTTER + 1000 - PLAYHEAD_HEAD_W / 2}px`);
+    expect(playhead.style.transform).toBe(
+      `translateX(${Math.round(LABEL_COL_W + GUTTER + 1000 - PLAYHEAD_HEAD_W / 2)}px)`,
+    );
     expect(diamondX).toBe(rulerX);
     expect(rulerX).toBe(LABEL_COL_W + GUTTER + 1000);
     expect(collapsedHeader.textContent).toContain("Outro");

package/src/player/components/TimelineCanvas.tsx

@@ -9,10 +9,10 @@ import {
   TRACKS_BOTTOM_PAD,
   TRACK_H,
   PLAYHEAD_HEAD_W,
-  getTimelinePlayheadLeft,
   getTimelineRowTop,
   getTimelineRowHeight,
 } from "./timelineLayout";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { TimelineLanes } from "./TimelineLanes";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
 import { useTimelineContext } from "./TimelineProvider";
@@ -234,7 +234,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
 
       {/* Playhead — hidden while dragging a beat so its guideline doesn't
           track the scrub and clutter the beat being moved. Explicit width +
-          the half-head offset baked into getTimelinePlayheadLeft keep the
+          the half-head offset baked into getTimelinePlayheadTransform keep the
           inner 1px line's CENTER exactly on contentOrigin + t * pps (the ruler
           ticks' center), instead of relying on shrink-wrap sizing. */}
       <TimelinePlayheadLayer scrollRef={props.scrollRef} contentOrigin={props.contentOrigin}>
@@ -242,7 +242,9 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           ref={props.playheadRef}
           className="absolute top-0 bottom-0 pointer-events-none"
           style={{
-            left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
+            left: 0,
+            transform: getTimelinePlayheadTransform(0, 0, props.contentOrigin, true),
+            willChange: "transform",
             width: PLAYHEAD_HEAD_W,
             display: beatDragging ? "none" : undefined,
           }}

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 },