@hyperframes/studio 0.8.104 → 0.8.106

package/src/player/components/TimelineClipFades.tsx

@@ -1,57 +1,151 @@
-import { useEffect, useRef, useState, type CSSProperties, type PointerEvent } from "react";
+import {
+  createContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+  type PointerEvent,
+} from "react";
 import {
   HF_AUDIO_FADE_IN_ATTR,
   HF_AUDIO_FADE_OUT_ATTR,
   clampFadesToDuration,
   formatFadeSeconds,
+  type AudioFades,
 } from "@hyperframes/core/audio-fade";
-import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { Tooltip } from "../../components/ui";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { releasedOutsideWindow } from "./timelinePointerRelease";
+import {
+  collectTimelineSnapTargets,
+  snapTimelineTime,
+  TIMELINE_SNAP_PX,
+  type TimelineSnapTarget,
+  type TimelineSnapType,
+} from "./timelineSnapping";
 
 type FadeEdge = "in" | "out";
+type FadeDraft = { edge: FadeEdge; seconds: number } | null;
 
-const HANDLE_SIZE = 10;
+const TAB_WIDTH = 4;
+const TAB_HEIGHT = 15;
 const HANDLE_HIT = 24;
+const TAB_INSET = 7;
+const TAB_CENTER_IN_HIT = 8;
 const HANDLE_Z_ABOVE_CLIP_CONTENT = 30;
 const SUPPRESS_CLIP_NATIVE_TITLE = "";
 /** Pixels of pointer travel before a press on the handle counts as a drag. */
 const DRAG_THRESHOLD_PX = 2;
+const DEFAULT_FADE_SECONDS = 0.5;
+const SNAP_LABEL: Record<TimelineSnapType, string> = {
+  playhead: "playhead",
+  "clip-edge": "clip edge",
+  beat: "beat",
+};
+
+export type ClipFadeShape = AudioFades & { duration: number };
+export const ClipFadesContext = createContext<ClipFadeShape | null>(null);
+
+// Owned by TimelineClip so the handles and the waveform share the value under the pointer;
+// the draft also bridges release until the save lands in the store.
+export function useClipFadeDraft(el: TimelineElement) {
+  const [draft, setDraft] = useState<FadeDraft>(null);
+  const authoredIn = el.fadeIn ?? 0;
+  const authoredOut = el.fadeOut ?? 0;
+  const { fadeIn, fadeOut } = clampFadesToDuration(
+    {
+      fadeIn: draft?.edge === "in" ? draft.seconds : authoredIn,
+      fadeOut: draft?.edge === "out" ? draft.seconds : authoredOut,
+    },
+    el.duration,
+  );
+  const shape = useMemo(
+    () => ({ fadeIn, fadeOut, duration: el.duration }),
+    [fadeIn, fadeOut, el.duration],
+  );
+  return { draft, setDraft, shape };
+}
 
 interface TimelineClipFadesProps {
   el: TimelineElement;
   pps: number;
   widthPx: number;
-  /** Handles show on hover/selection; the shaded ramps show whenever a fade is set. */
+  /** Handles show on hover/selection; the ramps show whenever a fade is set. */
   showHandles: boolean;
+  focusable?: boolean;
+  /** Audio clips draw the fade in their waveform; others get the shaded wedge. */
+  hasWaveform?: boolean;
+  fade: ReturnType<typeof useClipFadeDraft>;
+}
+
+type KeyedFade = (current: number, step: number, limit: number) => number | null;
+const grow: KeyedFade = (current, step) => current + step;
+const shrink: KeyedFade = (current, step) => current - step;
+const clear: KeyedFade = () => 0;
+const FADE_KEYS: Record<string, KeyedFade> = {
+  ArrowRight: grow,
+  ArrowUp: grow,
+  ArrowLeft: shrink,
+  ArrowDown: shrink,
+  Home: clear,
+  Delete: clear,
+  Backspace: clear,
+  End: (_current, _step, limit) => limit,
+  Enter: (current) => (current === 0 ? DEFAULT_FADE_SECONDS : null),
+};
+
+function keyedFadeSeconds(key: string, shift: boolean, current: number, limit: number) {
+  return FADE_KEYS[key]?.(current, shift ? 1 : 0.1, limit) ?? null;
+}
+
+function topEdgeY(x: number, widthPx: number, heightPx: number, radiusPx: number): number {
+  const r = Math.min(radiusPx, widthPx / 2, heightPx / 2);
+  const d = x < r ? r - x : x > widthPx - r ? x - (widthPx - r) : 0;
+  return d > 0 ? r - Math.sqrt(Math.max(0, r * r - d * d)) : 0;
 }
 
-/** Corner dots that drag `data-fade-in` / `data-fade-out`; the wedge is the faded region. */
-export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineClipFadesProps) {
+/** Slim tabs at each fade's end that drag `data-fade-in` / `data-fade-out`. */
+// fallow-ignore-next-line complexity
+export function TimelineClipFades({
+  el,
+  pps,
+  widthPx,
+  showHandles,
+  focusable = false,
+  hasWaveform = false,
+  fade,
+}: TimelineClipFadesProps) {
   const { onSetElementAttributeLive, onSetElementAttributeQuiet, onRevertElementAttributeLive } =
     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 { setDraft } = fade;
+  const fades = fade.shape;
   const [dragging, setDragging] = useState<FadeEdge | null>(null);
+  const [focused, setFocused] = useState<FadeEdge | null>(null);
+  const [snapType, setSnapType] = useState<TimelineSnapType | 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 visible =
+    fades.fadeIn > 0 || fades.fadeOut > 0 || showHandles || dragging !== null || focused !== null;
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const [clipBox, setClipBox] = useState({ height: 0, radius: 0 });
+  useLayoutEffect(() => {
+    const clip = rootRef.current?.parentElement;
+    if (!clip) return;
+    const radius = parseFloat(getComputedStyle(clip).borderTopLeftRadius) || 0;
+    const height = clip.clientHeight;
+    setClipBox((box) =>
+      box.height === height && box.radius === radius ? box : { height, radius },
+    );
+  }, [widthPx, visible]);
+
   const gesture = useRef<{
     edge: FadeEdge;
     pointerId: number;
@@ -60,11 +154,39 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
     otherSeconds: number;
     moved: boolean;
     last: number;
+    snapTargets: TimelineSnapTarget[];
   } | 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 labelFor = (edge: FadeEdge) => (edge === "in" ? "Fade in" : "Fade out");
+  const currentSeconds = (edge: FadeEdge) =>
+    fade.draft?.edge === edge ? fade.draft.seconds : edge === "in" ? authoredIn : authoredOut;
+  const limitFor = (edge: FadeEdge) =>
+    Math.max(0, el.duration - currentSeconds(edge === "in" ? "out" : "in"));
+
+  // When the other fade makes the pair overrun the clip, neither a key nor a drag lowers this one.
+  const stepLimit = (current: number, other: number) =>
+    Math.max(0, el.duration - other, other > 0 ? current : 0);
+  const startSeconds = (edge: FadeEdge) => {
+    const current = currentSeconds(edge);
+    return Math.min(current, stepLimit(current, currentSeconds(edge === "in" ? "out" : "in")));
+  };
+  const dragLimit = (g: { otherSeconds: number; originSeconds: number }) =>
+    stepLimit(g.originSeconds, g.otherSeconds);
+
+  /** Moves the fade's end onto a playhead or clip edge within the timeline's snap radius. */
+  const snapSeconds = (g: NonNullable<typeof gesture.current>, seconds: number) => {
+    const knee = g.edge === "in" ? el.start + seconds : el.start + el.duration - seconds;
+    const snapped = snapTimelineTime(knee, g.snapTargets, TIMELINE_SNAP_PX / Math.max(pps, 1e-6));
+    if (!snapped.target) return { seconds, type: null };
+    const next = g.edge === "in" ? snapped.time - el.start : el.start + el.duration - snapped.time;
+    const limit = dragLimit(g);
+    return next >= 0 && next <= limit
+      ? { seconds: next, type: snapped.target.type }
+      : { seconds, type: null };
+  };
 
   const secondsAt = (clientX: number): number => {
     const g = gesture.current;
@@ -72,7 +194,7 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
     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 limit = dragLimit(g);
     const clamped = Math.min(limit, Math.max(0, raw));
     return Math.round(clamped * 100) / 100;
   };
@@ -83,14 +205,24 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
     e.stopPropagation();
     e.preventDefault();
     e.currentTarget.setPointerCapture(e.pointerId);
+    flushKeys();
+    const store = usePlayerStore.getState();
     gesture.current = {
       edge,
       pointerId: e.pointerId,
       originClientX: e.clientX,
-      originSeconds: edge === "in" ? authoredIn : authoredOut,
-      otherSeconds: edge === "in" ? authoredOut : authoredIn,
+      originSeconds: startSeconds(edge),
+      otherSeconds: currentSeconds(edge === "in" ? "out" : "in"),
       moved: false,
-      last: edge === "in" ? authoredIn : authoredOut,
+      last: startSeconds(edge),
+      snapTargets: store.timelineSnapEnabled
+        ? collectTimelineSnapTargets({
+            elements: store.elements,
+            playheadTime: store.currentTime,
+            beatTimes: [],
+            excludeElementKey: el.key ?? el.id,
+          }).filter(({ time }) => time > el.start + 1e-3 && time < el.start + el.duration - 1e-3)
+        : [],
     };
     setDragging(edge);
   };
@@ -100,7 +232,9 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
     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);
+    const { seconds: raw, type } = snapSeconds(g, secondsAt(e.clientX));
+    const seconds = Math.round(raw * 100) / 100;
+    setSnapType(type);
     if (seconds === g.last) return;
     g.last = seconds;
     setDraft({ edge: g.edge, seconds });
@@ -115,6 +249,7 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
     if (!g || g.pointerId !== e.pointerId) return null;
     gesture.current = null;
     setDragging(null);
+    setSnapType(null);
     if (e.currentTarget.hasPointerCapture(e.pointerId)) {
       e.currentTarget.releasePointerCapture(e.pointerId);
     }
@@ -123,35 +258,69 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
 
   /** 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));
-      onRevertElementAttributeLive?.(el, attrFor(g.edge));
-    }
+    if (!g.moved) return;
+    onSetElementAttributeLive?.(el, attrFor(g.edge), attrText(g.originSeconds));
+    onRevertElementAttributeLive?.(el, attrFor(g.edge));
     setDraft(null);
   };
 
+  // The save syncs the store before it settles, so its own draft can go then; a newer draft stays.
+  const commit = (edge: FadeEdge, seconds: number) => {
+    const draft = { edge, seconds };
+    setDraft(draft);
+    const settle = () => setDraft((current) => (current === draft ? null : current));
+    void onSetElementAttributeQuiet?.(el, attrFor(edge), attrText(seconds), labelFor(edge)).then(
+      settle,
+      settle,
+    );
+  };
+
   const finish = (e: PointerEvent<HTMLDivElement>, cancelled: boolean) => {
     const g = endGesture(e);
     if (!g) return;
-    if (cancelled || !g.moved || releasedOutsideWindow(e)) 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",
-    );
+    if (cancelled || !g.moved || g.last === g.originSeconds || releasedOutsideWindow(e)) {
+      return revertGesture(g);
+    }
+    commit(g.edge, g.last);
+  };
+
+  const onHandleDoubleClick = (edge: FadeEdge) => {
+    commit(edge, currentSeconds(edge) > 0 ? 0 : Math.min(DEFAULT_FADE_SECONDS, limitFor(edge)));
+  };
+
+  const keyBurst = useRef<{ edge: FadeEdge; seconds: number } | null>(null);
+  const flushKeys = () => {
+    const burst = keyBurst.current;
+    keyBurst.current = null;
+    if (burst) commit(burst.edge, burst.seconds);
+  };
+
+  // A held key previews live and saves once on release: one undo step per burst.
+  const onHandleKeyDown = (edge: FadeEdge) => (e: KeyboardEvent<HTMLDivElement>) => {
+    if (gesture.current || !canEdit) return;
+    const current = startSeconds(edge);
+    const limit = stepLimit(current, currentSeconds(edge === "in" ? "out" : "in"));
+    const next = keyedFadeSeconds(e.key, e.shiftKey, current, limit);
+    if (next === null) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const seconds = Math.round(Math.min(limit, Math.max(0, next)) * 100) / 100;
+    if (seconds === current) return;
+    keyBurst.current = { edge, seconds };
+    setDraft({ edge, seconds });
+    onSetElementAttributeLive?.(el, attrFor(edge), attrText(seconds));
   };
 
   useEffect(() => {
     if (dragging === null) return;
-    const cancelOnWindowEscape = (e: KeyboardEvent) => {
+    const cancelOnWindowEscape = (e: globalThis.KeyboardEvent) => {
       const g = gesture.current;
       if (e.key !== "Escape" || !g) return;
       e.preventDefault();
       e.stopPropagation();
       gesture.current = null;
       setDragging(null);
+      setSnapType(null);
       revertGesture(g);
     };
     window.addEventListener("keydown", cancelOnWindowEscape, { capture: true });
@@ -160,21 +329,43 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
 
   const showIn = fades.fadeIn > 0;
   const showOut = fades.fadeOut > 0;
-  const handlesVisible = showHandles || dragging !== null;
-  if (!showIn && !showOut && !handlesVisible) return null;
+  const handlesVisible = showHandles || dragging !== null || focused !== null;
+  if (!visible) return null;
 
   const hitWidth = Math.min(HANDLE_HIT, widthPx / 2);
-  const handleStyle = (edge: FadeEdge): CSSProperties => ({
+  const tabX = (edge: FadeEdge) => {
+    const knee = edge === "in" ? inPx : widthPx - outPx;
+    const inset = Math.min(TAB_INSET, widthPx / 2);
+    return Math.min(widthPx - inset, Math.max(inset, knee));
+  };
+  const boxLeft = (x: number) => Math.min(widthPx - hitWidth, Math.max(0, x - hitWidth / 2));
+  const [inX, outX] = [tabX("in"), tabX("out")];
+  const mid = (inX + outX) / 2;
+  // A handle with no 0.01 s step to move is not drawn, unless in use: its twin owns the spot.
+  const drawn = (edge: FadeEdge) =>
+    currentSeconds(edge) > 0 ||
+    Math.round(limitFor(edge) * 100) >= 1 ||
+    dragging === edge ||
+    focused === edge;
+  const overlap = drawn("in") && drawn("out") && boxLeft(inX) + hitWidth > boxLeft(outX);
+  const handleGeometry = (edge: FadeEdge) => {
+    const x = edge === "in" ? inX : outX;
+    // Boxes that would overlap meet at the midpoint between the two tabs.
+    const [left, right] = !overlap
+      ? [boxLeft(x), boxLeft(x) + hitWidth]
+      : edge === "in"
+        ? [Math.max(0, mid - hitWidth), mid]
+        : [mid, Math.min(widthPx, mid + hitWidth)];
+    const edgeY = topEdgeY(x, widthPx, clipBox.height, clipBox.radius);
+    return { left, width: right - left, tabLeft: x - left, top: edgeY + 1 - TAB_CENTER_IN_HIT };
+  };
+  const handleStyle = (geometry: { left: number; top: number; width: number }): CSSProperties => ({
     position: "absolute",
-    top: -(HANDLE_HIT - HANDLE_SIZE) / 2 + 1,
-    left: edge === "in" ? 0 : widthPx - hitWidth,
-    width: hitWidth,
+    top: geometry.top,
+    left: geometry.left,
+    width: geometry.width,
     height: HANDLE_HIT,
-    display: "flex",
-    alignItems: "center",
-    justifyContent: "center",
     cursor: "ew-resize",
-    zIndex: HANDLE_Z_ABOVE_CLIP_CONTENT,
     opacity: handlesVisible ? 1 : 0,
     pointerEvents: handlesVisible && canEdit ? "auto" : "none",
     touchAction: "none",
@@ -182,7 +373,16 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
   });
 
   return (
-    <>
+    <div
+      ref={rootRef}
+      style={{
+        position: "absolute",
+        inset: 0,
+        borderRadius: "inherit",
+        pointerEvents: "none",
+        zIndex: HANDLE_Z_ABOVE_CLIP_CONTENT,
+      }}
+    >
       {(showIn || showOut) && (
         <svg
           aria-hidden="true"
@@ -193,119 +393,153 @@ export function TimelineClipFades({ el, pps, widthPx, showHandles }: TimelineCli
             width: "100%",
             height: "100%",
             pointerEvents: "none",
-            zIndex: 5,
             overflow: "hidden",
             borderRadius: "inherit",
           }}
           viewBox={`0 0 ${Math.max(widthPx, 1)} 100`}
           preserveAspectRatio="none"
         >
-          {/* Keep the #4250 wedge geometry, but let the real waveform read through it. */}
           {showIn && (
-            <>
-              <polygon
-                data-testid="clip-fade-in"
-                points={`0,0 ${inPx},0 0,100`}
-                fill="var(--timeline-fade-shade)"
-                fillOpacity={0.35}
-              />
-              <line
-                x1={0}
-                y1={100}
-                x2={inPx}
-                y2={0}
-                stroke="var(--clip-handle)"
-                strokeOpacity={0.9}
-                strokeWidth={1.25}
-                vectorEffect="non-scaling-stroke"
-              />
-            </>
+            <FadeRamp
+              testId="clip-fade-in"
+              wedge={hasWaveform ? null : `0,0 ${inPx},0 0,100`}
+              line={[0, 100, inPx, 0]}
+            />
           )}
           {showOut && (
-            <>
-              <polygon
-                data-testid="clip-fade-out"
-                points={`${widthPx - outPx},0 ${widthPx},0 ${widthPx},100`}
-                fill="var(--timeline-fade-shade)"
-                fillOpacity={0.35}
-              />
-              <line
-                x1={widthPx - outPx}
-                y1={0}
-                x2={widthPx}
-                y2={100}
-                stroke="var(--clip-handle)"
-                strokeOpacity={0.9}
-                strokeWidth={1.25}
-                vectorEffect="non-scaling-stroke"
-              />
-            </>
+            <FadeRamp
+              testId="clip-fade-out"
+              wedge={hasWaveform ? null : `${widthPx - outPx},0 ${widthPx},0 ${widthPx},100`}
+              line={[widthPx - outPx, 0, widthPx, 100]}
+            />
           )}
         </svg>
       )}
-      {canEdit && (
-        <>
-          <FadeHandle
-            direction="in"
-            value={fades.fadeIn}
-            max={Math.max(0, el.duration - fades.fadeOut)}
-            style={handleStyle("in")}
-            dragging={dragging === "in"}
-            onPointerDown={onHandlePointerDown("in")}
-            onPointerMove={onHandlePointerMove}
-            onPointerUp={(e) => finish(e, false)}
-            onPointerCancel={(e) => finish(e, true)}
-          />
-          <FadeHandle
-            direction="out"
-            value={fades.fadeOut}
-            max={Math.max(0, el.duration - fades.fadeIn)}
-            style={handleStyle("out")}
-            dragging={dragging === "out"}
-            onPointerDown={onHandlePointerDown("out")}
-            onPointerMove={onHandlePointerMove}
-            onPointerUp={(e) => finish(e, false)}
-            onPointerCancel={(e) => finish(e, true)}
-          />
-        </>
+      {canEdit &&
+        (["in", "out"] as const).filter(drawn).map((edge) => {
+          const geometry = handleGeometry(edge);
+          return (
+            <FadeHandle
+              key={edge}
+              direction={edge}
+              clipName={el.label || el.id}
+              value={edge === "in" ? fades.fadeIn : fades.fadeOut}
+              max={Math.max(0, el.duration - (edge === "in" ? fades.fadeOut : fades.fadeIn))}
+              snapLabel={dragging === edge && snapType ? SNAP_LABEL[snapType] : null}
+              style={handleStyle(geometry)}
+              tabLeft={geometry.tabLeft}
+              tabTop={TAB_CENTER_IN_HIT - TAB_HEIGHT / 2}
+              focusable={focusable}
+              dragging={dragging === edge}
+              onPointerDown={onHandlePointerDown(edge)}
+              onPointerMove={onHandlePointerMove}
+              onPointerUp={(e) => finish(e, false)}
+              onPointerCancel={(e) => finish(e, true)}
+              onDoubleClick={() => onHandleDoubleClick(edge)}
+              onKeyDown={onHandleKeyDown(edge)}
+              onKeyUp={flushKeys}
+              onFocusChange={(on) => {
+                if (!on) flushKeys();
+                setFocused(on ? edge : null);
+              }}
+            />
+          );
+        })}
+    </div>
+  );
+}
+
+/** A 1 px dashed gain line; clips without a waveform also shade the gain they lose. */
+function FadeRamp({
+  testId,
+  wedge,
+  line,
+}: {
+  testId: string;
+  wedge: string | null;
+  line: [number, number, number, number];
+}) {
+  const [x1, y1, x2, y2] = line;
+  return (
+    <>
+      {wedge && (
+        <polygon
+          data-testid={testId}
+          points={wedge}
+          fill="var(--timeline-fade-shade)"
+          fillOpacity={0.35}
+        />
       )}
+      <line
+        data-testid={wedge ? undefined : testId}
+        x1={x1}
+        y1={y1}
+        x2={x2}
+        y2={y2}
+        stroke="var(--clip-handle)"
+        strokeOpacity={0.55}
+        strokeWidth={1}
+        strokeDasharray="2 3"
+        vectorEffect="non-scaling-stroke"
+      />
     </>
   );
 }
 
 function FadeHandle({
   direction,
+  clipName,
   value,
   max,
+  snapLabel,
   style,
+  tabLeft,
+  tabTop,
+  focusable,
   dragging,
   onPointerDown,
   onPointerMove,
   onPointerUp,
   onPointerCancel,
+  onDoubleClick,
+  onKeyDown,
+  onKeyUp,
+  onFocusChange,
 }: {
   direction: "in" | "out";
+  clipName: string;
   value: number;
   max: number;
+  snapLabel: string | null;
   style: CSSProperties;
+  tabLeft: number;
+  tabTop: number;
+  focusable: boolean;
   dragging: boolean;
   onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
   onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
   onPointerUp: (event: PointerEvent<HTMLDivElement>) => void;
   onPointerCancel: (event: PointerEvent<HTMLDivElement>) => void;
+  onDoubleClick: () => void;
+  onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+  onKeyUp: () => void;
+  onFocusChange: (focused: boolean) => void;
 }) {
   const label = direction === "in" ? "Fade in" : "Fade out";
+  const text = `${label} ${formatFadeSeconds(value)} s`;
   return (
-    <Tooltip label={`${label} ${formatFadeSeconds(value)} s`}>
+    <Tooltip label={snapLabel ? `${text}, snapped to ${snapLabel}` : text}>
       <div
         role="slider"
-        tabIndex={-1}
-        aria-label={label}
+        tabIndex={focusable ? 0 : -1}
+        aria-label={`${label}, ${clipName}`}
         aria-valuemin={0}
         aria-valuemax={max}
         aria-valuenow={value}
         aria-valuetext={`${formatFadeSeconds(value)}s`}
         data-testid={`clip-fade-handle-${direction}`}
+        data-dragging={dragging ? "" : undefined}
+        className="timeline-fade-handle"
         title={SUPPRESS_CLIP_NATIVE_TITLE}
         style={style}
         onPointerDown={onPointerDown}
@@ -313,30 +547,27 @@ function FadeHandle({
         onPointerUp={onPointerUp}
         onPointerCancel={onPointerCancel}
         onClick={(e) => e.stopPropagation()}
-        onDoubleClick={(e) => e.stopPropagation()}
+        onDoubleClick={(e) => {
+          e.stopPropagation();
+          onDoubleClick();
+        }}
+        onKeyDown={onKeyDown}
+        onKeyUp={onKeyUp}
+        onFocus={() => onFocusChange(true)}
+        onBlur={() => onFocusChange(false)}
       >
-        <FadeDot active={dragging} />
+        <span
+          aria-hidden="true"
+          className="timeline-fade-tab"
+          style={{
+            left: tabLeft - TAB_WIDTH / 2,
+            top: tabTop,
+            width: TAB_WIDTH,
+            height: TAB_HEIGHT,
+            pointerEvents: "none",
+          }}
+        />
       </div>
     </Tooltip>
   );
 }
-
-function FadeDot({ active }: { active: boolean }) {
-  return (
-    <span
-      aria-hidden="true"
-      style={{
-        display: "block",
-        flexShrink: 0,
-        pointerEvents: "none",
-        width: HANDLE_SIZE,
-        height: HANDLE_SIZE,
-        borderRadius: "50%",
-        background: "var(--timeline-fade-dot)",
-        boxShadow: "0 0 0 1.5px var(--timeline-fade-dot-ring)",
-        transform: active ? "scale(1.15)" : undefined,
-        transition: "transform 80ms ease-out",
-      }}
-    />
-  );
-}