@hyperframes/studio 0.8.58 → 0.8.59

package/src/player/components/Timeline.tsx

@@ -1,9 +1,20 @@
 import { memo } from "react";
 import type { TimelineProps } from "./TimelineTypes";
-import { TimelineEmptyState } from "./TimelineEmptyState";
-import { TimelineCanvas } from "./TimelineCanvas";
-import { TimelineOverlays } from "./TimelineOverlays";
 import { TimelineProvider, useTimelineContext } from "./TimelineProvider";
+import {
+  TimelineEmptyStatePart,
+  TimelineEditPopover,
+  TimelineClipMenu,
+  TimelineFrame,
+  TimelineGapMenu,
+  TimelineKeyframeMenu,
+  TimelineLanes,
+  TimelineOverlays,
+  TimelinePlayhead,
+  TimelineRazorGuide,
+  TimelineRuler,
+  TimelineShortcutHint,
+} from "./TimelineParts";
 
 export * from "./TimelineProvider";
 export {
@@ -28,23 +39,39 @@ function TimelineView() {
   const { state, meta } = useTimelineContext();
   const { timelineReady, elements } = state;
   if (!timelineReady || elements.length === 0) {
-    return <TimelineEmptyState {...meta.emptyState} />;
+    return <TimelineEmptyStatePart />;
   }
   return (
     <div {...meta.containerProps}>
       <div {...meta.viewportProps}>
-        <TimelineCanvas />
-        {meta.razorGuide}
+        <TimelineFrame />
+        <TimelineRazorGuide />
       </div>
       <TimelineOverlays />
     </div>
   );
 }
 
-export const Timeline = memo(function Timeline(props: TimelineProps = {}) {
+const TimelineComposed = memo(function TimelineComposed(props: TimelineProps = {}) {
   return (
     <TimelineProvider {...props}>
       <TimelineView />
     </TimelineProvider>
   );
 });
+
+export const Timeline = Object.assign(TimelineComposed, {
+  Provider: TimelineProvider,
+  Frame: TimelineFrame,
+  Ruler: TimelineRuler,
+  Lanes: TimelineLanes,
+  Playhead: TimelinePlayhead,
+  RazorGuide: TimelineRazorGuide,
+  ShortcutHint: TimelineShortcutHint,
+  EditPopover: TimelineEditPopover,
+  ClipMenu: TimelineClipMenu,
+  KeyframeMenu: TimelineKeyframeMenu,
+  GapMenu: TimelineGapMenu,
+  EmptyState: TimelineEmptyStatePart,
+  Overlays: TimelineOverlays,
+});

package/src/player/components/TimelineCanvas.tsx

@@ -1,5 +1,5 @@
 import { memo } from "react";
-import { TimelineRuler } from "./TimelineRuler";
+import { TimelineRulerPart } from "./TimelineRulerPart";
 import { PlayheadIndicator } from "./PlayheadIndicator";
 import {
   RULER_H,
@@ -12,12 +12,8 @@ import {
   getTimelineRowTop,
   getTimelineRowHeight,
 } from "./timelineLayout";
-import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
-import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { TimelineLanes } from "./TimelineLanes";
-import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
-import { resolveSnapGuide } from "./timelineSnapping";
 import { useTimelineContext } from "./TimelineProvider";
 
 // A dropped clip's length is unknown until it lands; the preview shows a default.
@@ -26,8 +22,7 @@ const DROP_PREVIEW_SECONDS = 3;
 export const TimelineCanvas = memo(function TimelineCanvas() {
   const { state, actions } = useTimelineContext();
   const props = state.canvas;
-  const { draggedClip, resizingClip, scrollRef, selectedElementIds, displayTrackOrder } = props;
-  const snapGuide = resolveSnapGuide(draggedClip, resizingClip);
+  const { draggedClip, scrollRef, displayTrackOrder } = props;
   const draggedRowIndex =
     draggedClip?.started === true ? displayTrackOrder.indexOf(draggedClip.previewTrack) : -1;
   const dropTrackIndex = props.dropPreview
@@ -43,55 +38,14 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
   // ghost and drop placeholder must clamp to it or they stretch to the full
   // expanded row height and stop matching the clip being dragged.
   const draggedClipHeight = Math.min(draggedRowHeight, TRACK_H) - CLIP_Y * 2;
-  const {
-    onResizeElement,
-    onMoveElement,
-    onToggleTrackHidden,
-    onTogglePropertyGroupKeyframe,
-    onRazorSplit,
-    onRazorSplitAll,
-  } = useTimelineEditContextOptional();
   const beatDragging = props.beatDragging;
-  const draggedElement = draggedClip?.element ?? null;
-  const draggedElementIdentity = draggedElement ? getTimelineElementIdentity(draggedElement) : null;
-  // The drag ghost follows the cursor freely (both axes) — CapCut-style. The
-  // "magnetic" affordance is a highlight on the destination lane (draggedRowIndex),
-  // which flips at the MAGNETIC_TRACK_THRESHOLD point; the clip drops into it.
-  // Live multi-selection drag: while a selected clip is dragged, ALL selected
-  // clips move together as one rigid formation. The GRABBED clip is the free
-  // ghost below; its co-selected "passengers" slide by the SAME group-clamped
-  // delta (cheap translateX, no re-layout) — the delta is derived from the
-  // grabbed clip's ALREADY-clamped previewStart, so the whole formation stops at
-  // the wall together and never deforms. Matches what the commit will do — see
-  // timelineMultiDragPreview + commit.
-  const multiDragPreview: MultiDragPreviewInput | null =
-    draggedClip?.started === true && draggedElement && draggedElementIdentity
-      ? {
-          dragStarted: true,
-          draggedKey: draggedElementIdentity,
-          draggedOriginStart: draggedElement.start,
-          draggedPreviewStart: draggedClip.previewStart,
-          selectedKeys: selectedElementIds,
-        }
-      : null;
+  const { draggedElement, snapGuide, multiDragPreview } = props;
   return (
     <div
       className="relative"
       style={{ height: props.totalH, width: props.contentOrigin + props.trackContentWidth }}
     >
-      <TimelineRuler
-        major={props.major}
-        minor={props.minor}
-        pps={props.pps}
-        trackContentWidth={props.trackContentWidth}
-        totalH={props.totalH}
-        effectiveDuration={props.effectiveDuration}
-        majorTickInterval={props.majorTickInterval}
-        theme={props.theme}
-        beatAnalysis={props.beatAnalysis}
-        contentOrigin={props.contentOrigin}
-        renderTimeRange={props.rowsVirtualized ? props.renderTimeRange : undefined}
-      />
+      <TimelineRulerPart />
 
       {/* Breathing room between the sticky ruler and the first track lane — the
           top half of the CapCut-style padding (see TRACKS_TOP_PAD). */}
@@ -104,12 +58,12 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         snapGuide={snapGuide}
         draggedElement={draggedElement}
         multiDragPreview={multiDragPreview}
-        onToggleTrackHidden={onToggleTrackHidden}
-        onTogglePropertyGroupKeyframe={onTogglePropertyGroupKeyframe}
-        onResizeElement={onResizeElement}
-        onMoveElement={onMoveElement}
-        onRazorSplit={onRazorSplit}
-        onRazorSplitAll={onRazorSplitAll}
+        onToggleTrackHidden={props.onToggleTrackHidden}
+        onTogglePropertyGroupKeyframe={props.onTogglePropertyGroupKeyframe}
+        onResizeElement={props.onResizeElement}
+        onMoveElement={props.onMoveElement}
+        onRazorSplit={props.onRazorSplit}
+        onRazorSplitAll={props.onRazorSplitAll}
       />
 
       {/* Breathing room below the last track lane (~1.5 track heights) — a real

package/src/player/components/TimelineClip.tsx

@@ -4,6 +4,7 @@ import { defaultTimelineTheme, getClipHandleOpacity, type TimelineTheme } from "
 import type { TimelineEditCapabilities } from "./timelineEditing";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
+import { TimelineClipFades } from "./TimelineClipFades";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -74,6 +75,7 @@ export const TimelineClip = memo(function TimelineClip({
     "--clip-border-active": theme.clipBorderActive,
     "--clip-handle": theme.handleColor,
   } as CSSProperties;
+  const isAudioClip = isAudioTimelineElement(el);
   const clipClassName = [
     "timeline-clip",
     "absolute",
@@ -81,7 +83,7 @@ export const TimelineClip = memo(function TimelineClip({
     isSelected ? "is-selected" : "",
     isHovered ? "is-hovered" : "",
     isDragging ? "is-dragging" : "",
-    isAudioTimelineElement(el) ? "is-audio" : "",
+    isAudioClip ? "is-audio" : "",
   ]
     .filter((className) => className.length > 0)
     .join(" ");
@@ -198,6 +200,17 @@ export const TimelineClip = memo(function TimelineClip({
         </span>
       )}
       {children}
+      {/* Fade handles + ramps for anything the mixer hears — audio clips and
+          videos marked data-has-audio. They write data-fade-in/out on the clip
+          and are the timeline half of the inspector's Fade rows. */}
+      {(isAudioClip || el.hasAudio) && !isGestureActor && (
+        <TimelineClipFades
+          el={el}
+          pps={pps}
+          widthPx={widthPx}
+          showHandles={(isHovered || isSelected) && !isDragging}
+        />
+      )}
     </button>
   );
 });

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

@@ -0,0 +1,171 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { TimelineClipFades } from "./TimelineClipFades";
+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const clip: TimelineElement = {
+  id: "music",
+  tag: "audio",
+  src: "assets/music.wav",
+  start: 2,
+  duration: 10,
+  track: 1,
+  fadeIn: 1,
+  fadeOut: 2,
+};
+
+function render(
+  el: TimelineElement,
+  options: { showHandles?: boolean; provide?: boolean; onClipPointerDown?: () => void } = {},
+) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const onSetElementAttributeLive = vi.fn();
+  const onSetElementAttributeQuiet = vi.fn().mockResolvedValue(undefined);
+  // Stands in for the TimelineClip button the handles live inside.
+  const node = (
+    <div data-testid="clip" onPointerDown={options.onClipPointerDown}>
+      <TimelineClipFades
+        el={el}
+        pps={100}
+        widthPx={el.duration * 100}
+        showHandles={options.showHandles ?? true}
+      />
+    </div>
+  );
+  act(() => {
+    root.render(
+      options.provide === false ? (
+        node
+      ) : (
+        <TimelineEditProvider value={{ onSetElementAttributeLive, onSetElementAttributeQuiet }}>
+          {node}
+        </TimelineEditProvider>
+      ),
+    );
+  });
+  return { host, root, onSetElementAttributeLive, onSetElementAttributeQuiet };
+}
+
+function pointer(type: string, clientX: number, pointerId = 1) {
+  const event = new MouseEvent(type, { bubbles: true, clientX, button: 0 });
+  Object.defineProperty(event, "pointerId", { value: pointerId });
+  return event;
+}
+
+function armCapture(handle: HTMLElement) {
+  let captured = false;
+  Object.defineProperty(handle, "setPointerCapture", { value: () => (captured = true) });
+  Object.defineProperty(handle, "releasePointerCapture", { value: () => (captured = false) });
+  Object.defineProperty(handle, "hasPointerCapture", { value: () => captured });
+}
+
+describe("TimelineClipFades", () => {
+  it("shades the fade-in and fade-out as ramps sized by pps", () => {
+    const { host, root } = render(clip, { showHandles: false, provide: false });
+    const fadeIn = host.querySelector('[data-testid="clip-fade-in"]');
+    const fadeOut = host.querySelector('[data-testid="clip-fade-out"]');
+    // 1 s in at 100 px/s: the wedge spans 0..100; 2 s out on a 1000 px clip: 800..1000.
+    expect(fadeIn?.getAttribute("points")).toBe("0,0 100,0 0,100");
+    expect(fadeOut?.getAttribute("points")).toBe("800,0 1000,0 1000,100");
+    // Outside a provider there is nothing to write to, so no handles either.
+    expect(host.querySelector('[data-testid="clip-fade-handle-in"]')).toBeNull();
+    act(() => root.unmount());
+  });
+
+  it("renders nothing for a clip without fades when the handles are hidden", () => {
+    const { host, root } = render(
+      { ...clip, fadeIn: undefined, fadeOut: undefined },
+      {
+        showHandles: false,
+      },
+    );
+    expect(host.querySelector('[data-testid="clip"]')?.innerHTML).toBe("");
+    act(() => root.unmount());
+  });
+
+  it("drags the fade-in dot to the right, previewing live and committing once on release", () => {
+    const { host, root, onSetElementAttributeLive, onSetElementAttributeQuiet } = 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);
+    // The handle sits at the 1 s mark (x=100). Drag 150 px right → 2.5 s.
+    act(() => handle.dispatchEvent(pointer("pointerdown", 100)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 200)));
+    act(() => handle.dispatchEvent(pointer("pointermove", 250)));
+    expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-in", "2.5");
+    expect(onSetElementAttributeQuiet).not.toHaveBeenCalled();
+    // The ramp follows the pointer before anything is persisted.
+    expect(host.querySelector('[data-testid="clip-fade-in"]')?.getAttribute("points")).toBe(
+      "0,0 250,0 0,100",
+    );
+    act(() => handle.dispatchEvent(pointer("pointerup", 250)));
+    expect(onSetElementAttributeQuiet).toHaveBeenCalledTimes(1);
+    expect(onSetElementAttributeQuiet).toHaveBeenCalledWith(clip, "data-fade-in", "2.5", "Fade in");
+    act(() => root.unmount());
+  });
+
+  it("drags the fade-out dot to the left, growing the fade, and never past the fade-in", () => {
+    const { host, root, onSetElementAttributeLive, onSetElementAttributeQuiet } = render(clip);
+    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)));
+    expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-out", "5");
+    // Way past the start: clamps to duration − fadeIn = 9 s.
+    act(() => handle.dispatchEvent(pointer("pointermove", -500)));
+    expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-out", "9");
+    act(() => handle.dispatchEvent(pointer("pointerup", -500)));
+    expect(onSetElementAttributeQuiet).toHaveBeenCalledWith(clip, "data-fade-out", "9", "Fade out");
+    act(() => root.unmount());
+  });
+
+  it("removes the attribute when dragged back to zero", () => {
+    const { host, root, onSetElementAttributeQuiet } = 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", -40)));
+    act(() => handle.dispatchEvent(pointer("pointerup", -40)));
+    expect(onSetElementAttributeQuiet).toHaveBeenCalledWith(clip, "data-fade-in", null, "Fade in");
+    act(() => root.unmount());
+  });
+
+  it("puts the live value back and writes nothing when the gesture is cancelled", () => {
+    const { host, root, onSetElementAttributeLive, onSetElementAttributeQuiet } = 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("pointercancel", 300)));
+    expect(onSetElementAttributeLive).toHaveBeenLastCalledWith(clip, "data-fade-in", "1");
+    expect(onSetElementAttributeQuiet).not.toHaveBeenCalled();
+    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 });
+    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)));
+    expect(outer).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+});

package/src/player/components/TimelineClipFades.tsx

@@ -0,0 +1,302 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+  type PointerEvent,
+} from "react";
+import {
+  HF_AUDIO_FADE_IN_ATTR,
+  HF_AUDIO_FADE_OUT_ATTR,
+  clampFadesToDuration,
+  formatFadeSeconds,
+} from "@hyperframes/core/audio-fade";
+import type { TimelineElement } from "../store/playerStore";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+
+type FadeEdge = "in" | "out";
+
+const HANDLE_SIZE = 10;
+const HANDLE_HIT = 16;
+/** Pixels of pointer travel before a press on the handle counts as a drag. */
+const DRAG_THRESHOLD_PX = 2;
+
+interface TimelineClipFadesProps {
+  el: TimelineElement;
+  pps: number;
+  widthPx: number;
+  /** Handles show on hover/selection; the shaded ramps show whenever a fade is set. */
+  showHandles: boolean;
+}
+
+/** Corner dots that drag `data-fade-in` / `data-fade-out`; the wedge is the faded region. */
+export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineClipFadesProps) {
+  const { onSetElementAttributeLive, onSetElementAttributeQuiet } =
+    useTimelineEditContextOptional();
+  const canEdit = Boolean(onSetElementAttributeLive && onSetElementAttributeQuiet);
+
+  // Draft holds the value under the pointer during a drag; it also bridges
+  // the gap between release and the store re-reading the file, so the ramp
+  // does not snap back for a frame.
+  const [draft, setDraft] = useState<{ edge: FadeEdge; seconds: number } | null>(null);
+  const [dragging, setDragging] = useState<FadeEdge | null>(null);
+  const authoredIn = el.fadeIn ?? 0;
+  const authoredOut = el.fadeOut ?? 0;
+  useEffect(() => setDraft(null), [authoredIn, authoredOut]);
+
+  const fades = clampFadesToDuration(
+    {
+      fadeIn: draft?.edge === "in" ? draft.seconds : authoredIn,
+      fadeOut: draft?.edge === "out" ? draft.seconds : authoredOut,
+    },
+    el.duration,
+  );
+  const inPx = Math.min(widthPx, fades.fadeIn * pps);
+  const outPx = Math.min(widthPx, fades.fadeOut * pps);
+
+  const gesture = useRef<{
+    edge: FadeEdge;
+    pointerId: number;
+    originClientX: number;
+    originSeconds: number;
+    otherSeconds: number;
+    moved: boolean;
+    last: number;
+  } | null>(null);
+
+  const attrFor = (edge: FadeEdge) =>
+    edge === "in" ? HF_AUDIO_FADE_IN_ATTR : HF_AUDIO_FADE_OUT_ATTR;
+  const attrText = (seconds: number) => (seconds > 0 ? formatFadeSeconds(seconds) : null);
+
+  const secondsAt = (clientX: number): number => {
+    const g = gesture.current;
+    if (!g) return 0;
+    const deltaSeconds = (clientX - g.originClientX) / Math.max(pps, 1e-6);
+    // Fade-in grows to the right, fade-out grows to the left.
+    const raw = g.edge === "in" ? g.originSeconds + deltaSeconds : g.originSeconds - deltaSeconds;
+    const limit = Math.max(0, el.duration - g.otherSeconds);
+    const clamped = Math.min(limit, Math.max(0, raw));
+    return Math.round(clamped * 100) / 100;
+  };
+
+  const onHandlePointerDown = (edge: FadeEdge) => (e: PointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0 || !canEdit) return;
+    // Ours, not the clip's: a press here must not start a move or trim.
+    e.stopPropagation();
+    e.preventDefault();
+    e.currentTarget.setPointerCapture(e.pointerId);
+    gesture.current = {
+      edge,
+      pointerId: e.pointerId,
+      originClientX: e.clientX,
+      originSeconds: edge === "in" ? authoredIn : authoredOut,
+      otherSeconds: edge === "in" ? authoredOut : authoredIn,
+      moved: false,
+      last: edge === "in" ? authoredIn : authoredOut,
+    };
+    setDragging(edge);
+  };
+
+  const onHandlePointerMove = (e: PointerEvent<HTMLDivElement>) => {
+    const g = gesture.current;
+    if (!g || g.pointerId !== e.pointerId) return;
+    if (!g.moved && Math.abs(e.clientX - g.originClientX) < DRAG_THRESHOLD_PX) return;
+    g.moved = true;
+    const seconds = secondsAt(e.clientX);
+    if (seconds === g.last) return;
+    g.last = seconds;
+    setDraft({ edge: g.edge, seconds });
+    onSetElementAttributeLive?.(el, attrFor(g.edge), attrText(seconds));
+  };
+
+  type Gesture = NonNullable<typeof gesture.current>;
+
+  /** Ends the pointer gesture and returns it, or null when the event is not ours. */
+  const endGesture = (e: PointerEvent<HTMLDivElement>): Gesture | null => {
+    const g = gesture.current;
+    if (!g || g.pointerId !== e.pointerId) return null;
+    gesture.current = null;
+    setDragging(null);
+    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+    return g;
+  };
+
+  /** Puts the live document back where the file has it and drops the draft. */
+  const revertGesture = (g: Gesture) => {
+    if (g.moved) onSetElementAttributeLive?.(el, attrFor(g.edge), attrText(g.originSeconds));
+    setDraft(null);
+  };
+
+  const finish = (e: PointerEvent<HTMLDivElement>, cancelled: boolean) => {
+    const g = endGesture(e);
+    if (!g) return;
+    if (cancelled || !g.moved) return revertGesture(g);
+    setDraft({ edge: g.edge, seconds: g.last });
+    void onSetElementAttributeQuiet?.(
+      el,
+      attrFor(g.edge),
+      attrText(g.last),
+      g.edge === "in" ? "Fade in" : "Fade out",
+    );
+  };
+
+  const onHandleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    const g = gesture.current;
+    if (e.key !== "Escape" || !g) return;
+    e.preventDefault();
+    gesture.current = null;
+    setDragging(null);
+    revertGesture(g);
+  };
+
+  const showIn = fades.fadeIn > 0;
+  const showOut = fades.fadeOut > 0;
+  const handlesVisible = showHandles || dragging !== null;
+  if (!showIn && !showOut && !handlesVisible) return null;
+
+  const handleStyle = (leftPx: number): CSSProperties => ({
+    position: "absolute",
+    top: -(HANDLE_HIT - HANDLE_SIZE) / 2 + 1,
+    left: leftPx - HANDLE_HIT / 2,
+    width: HANDLE_HIT,
+    height: HANDLE_HIT,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    cursor: "ew-resize",
+    zIndex: 6,
+    opacity: handlesVisible ? 1 : 0,
+    pointerEvents: handlesVisible && canEdit ? "auto" : "none",
+    touchAction: "none",
+    outline: "none",
+  });
+
+  return (
+    <>
+      {(showIn || showOut) && (
+        <svg
+          aria-hidden="true"
+          data-testid="clip-fade-ramps"
+          style={{
+            position: "absolute",
+            inset: 0,
+            width: "100%",
+            height: "100%",
+            pointerEvents: "none",
+            zIndex: 5,
+            overflow: "visible",
+          }}
+          viewBox={`0 0 ${Math.max(widthPx, 1)} 100`}
+          preserveAspectRatio="none"
+        >
+          {/* The shaded wedge is the gain that is NOT there: above the ramp. */}
+          {showIn && (
+            <>
+              <polygon
+                data-testid="clip-fade-in"
+                points={`0,0 ${inPx},0 0,100`}
+                fill="var(--timeline-fade-shade)"
+              />
+              <line
+                x1={0}
+                y1={100}
+                x2={inPx}
+                y2={0}
+                stroke="var(--clip-handle)"
+                strokeOpacity={0.9}
+                strokeWidth={1.25}
+                vectorEffect="non-scaling-stroke"
+              />
+            </>
+          )}
+          {showOut && (
+            <>
+              <polygon
+                data-testid="clip-fade-out"
+                points={`${widthPx - outPx},0 ${widthPx},0 ${widthPx},100`}
+                fill="var(--timeline-fade-shade)"
+              />
+              <line
+                x1={widthPx - outPx}
+                y1={0}
+                x2={widthPx}
+                y2={100}
+                stroke="var(--clip-handle)"
+                strokeOpacity={0.9}
+                strokeWidth={1.25}
+                vectorEffect="non-scaling-stroke"
+              />
+            </>
+          )}
+        </svg>
+      )}
+      {canEdit && (
+        <>
+          <div
+            role="slider"
+            tabIndex={-1}
+            aria-label="Fade in"
+            aria-valuemin={0}
+            aria-valuemax={Math.max(0, el.duration - fades.fadeOut)}
+            aria-valuenow={fades.fadeIn}
+            aria-valuetext={`${formatFadeSeconds(fades.fadeIn)}s`}
+            data-testid="clip-fade-handle-in"
+            title={`Fade in: ${formatFadeSeconds(fades.fadeIn)}s — drag to change`}
+            style={handleStyle(inPx)}
+            onPointerDown={onHandlePointerDown("in")}
+            onPointerMove={onHandlePointerMove}
+            onPointerUp={(e) => finish(e, false)}
+            onPointerCancel={(e) => finish(e, true)}
+            onKeyDown={onHandleKeyDown}
+            onClick={(e) => e.stopPropagation()}
+            onDoubleClick={(e) => e.stopPropagation()}
+          >
+            <FadeDot active={dragging === "in"} />
+          </div>
+          <div
+            role="slider"
+            tabIndex={-1}
+            aria-label="Fade out"
+            aria-valuemin={0}
+            aria-valuemax={Math.max(0, el.duration - fades.fadeIn)}
+            aria-valuenow={fades.fadeOut}
+            aria-valuetext={`${formatFadeSeconds(fades.fadeOut)}s`}
+            data-testid="clip-fade-handle-out"
+            title={`Fade out: ${formatFadeSeconds(fades.fadeOut)}s — drag to change`}
+            style={handleStyle(widthPx - outPx)}
+            onPointerDown={onHandlePointerDown("out")}
+            onPointerMove={onHandlePointerMove}
+            onPointerUp={(e) => finish(e, false)}
+            onPointerCancel={(e) => finish(e, true)}
+            onKeyDown={onHandleKeyDown}
+            onClick={(e) => e.stopPropagation()}
+            onDoubleClick={(e) => e.stopPropagation()}
+          >
+            <FadeDot active={dragging === "out"} />
+          </div>
+        </>
+      )}
+    </>
+  );
+}
+
+function FadeDot({ active }: { active: boolean }) {
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        display: "block",
+        width: HANDLE_SIZE,
+        height: HANDLE_SIZE,
+        borderRadius: "50%",
+        background: active ? "var(--timeline-fade-dot-active)" : "var(--clip-handle)",
+        boxShadow: "0 0 0 1.5px var(--timeline-fade-dot-ring)",
+        transform: active ? "scale(1.15)" : undefined,
+        transition: "transform 80ms ease-out",
+      }}
+    />
+  );
+}