@hyperframes/studio 0.8.58 → 0.8.60

package/src/player/components/TimelineClip.tsx

@@ -1,9 +1,15 @@
 import { memo, type CSSProperties, type ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
-import { defaultTimelineTheme, getClipHandleOpacity, type TimelineTheme } from "./timelineTheme";
+import {
+  clipWidthLadder,
+  defaultTimelineTheme,
+  getClipHandleOpacity,
+  type TimelineTheme,
+} from "./timelineTheme";
 import type { TimelineEditCapabilities } from "./timelineEditing";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
+import { TimelineClipFades } from "./TimelineClipFades";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -59,9 +65,10 @@ export const TimelineClip = memo(function TimelineClip({
   const widthPx = Math.max(el.duration * pps, 4);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
   const displayLabel = el.label || el.id || el.tag;
+  const ladder = clipWidthLadder(widthPx);
   const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);
-  const showLabel = widthPx >= 40 || isSelected;
-  const showDefaultText = !hasCustomContent && (widthPx >= 40 || isSelected);
+  const showLabel = ladder === "labeled";
+  const showDefaultText = !hasCustomContent && ladder === "labeled";
   const startLabel = el.start.toFixed(1);
   const endLabel = (el.start + el.duration).toFixed(1);
   const themeVariables = {
@@ -74,6 +81,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 +89,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(" ");
@@ -90,7 +98,7 @@ export const TimelineClip = memo(function TimelineClip({
     width: widthPx,
     top: clipY,
     ...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
-    borderRadius: theme.clipRadius,
+    borderRadius: isAudioClip ? theme.audioClipRadius : theme.clipRadius,
     ...themeVariables,
     zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
     // Regular cursor over clips (CapCut-style, user preference) — no grab hand.
@@ -112,6 +120,7 @@ export const TimelineClip = memo(function TimelineClip({
       data-clip-start={el.start}
       data-clip-end={el.start + el.duration}
       data-clip-hidden={el.hidden ? "true" : undefined}
+      data-ladder={ladder}
       data-active={isActive ? "" : undefined}
       aria-hidden={isGestureActor ? "true" : undefined}
       tabIndex={isGestureActor ? undefined : tabIndex}
@@ -198,6 +207,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/TimelineClipDiamonds.test.tsx

@@ -258,7 +258,9 @@ describe("TimelineClipDiamonds", () => {
     const selectedDiamond = host.querySelector<HTMLButtonElement>('button[title="60%"]');
     expect(playheadDiamond?.dataset.keyframeAtPlayhead).toBe("true");
     expect(playheadDiamond?.dataset.keyframeSelected).toBe("false");
-    expect(playheadDiamond?.querySelector("path:last-child")?.getAttribute("fill")).toBe("#a3a3a3");
+    expect(playheadDiamond?.querySelector("path:last-child")?.getAttribute("fill")).toBe(
+      "var(--timeline-diamond-muted)",
+    );
     expect(playheadDiamond?.querySelector('path[stroke="#4ba3d2"]')).not.toBeNull();
     expect(selectedDiamond?.dataset.keyframeAtPlayhead).toBe("false");
     expect(selectedDiamond?.dataset.keyframeSelected).toBe("true");

package/src/player/components/TimelineClipDiamonds.tsx

@@ -225,7 +225,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
     isSelected && halfFramePct > 0
       ? nearestKeyframeWithin(sorted, currentPercentage, halfFramePct)
       : null;
-  const baseColor = isSelected ? accentColor : "#a3a3a3";
+  const baseColor = isSelected ? accentColor : "var(--timeline-diamond-muted)";
   const baseOpacity = isSelected ? 0.4 : 0.25;
   const canDrag = isSelected && !!onMoveKeyframe;
 
@@ -280,7 +280,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
         const isKfSelected = selectedKeyframes.has(kfKey);
         const atPlayhead = kf === playheadKeyframe;
         const isHighlighted = isKfSelected || atPlayhead;
-        const color = isKfSelected ? accentColor : "#a3a3a3";
+        const color = isKfSelected ? accentColor : "var(--timeline-diamond-muted)";
 
         const onPointerDown = (e: React.PointerEvent<HTMLButtonElement>) => {
           if (e.button !== 0) return;

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",
+      }}
+    />
+  );
+}

package/src/player/components/TimelineDiamondConnectors.tsx

@@ -213,8 +213,8 @@ function SegmentEaseControl({
           zIndex: 3,
           pointerEvents: "auto",
           padding: 0,
-          border: "1px solid rgba(255, 255, 255, 0.14)",
-          background: "#171717",
+          border: "1px solid var(--timeline-diamond-border)",
+          background: "var(--timeline-diamond-bg)",
           cursor: "pointer",
         }}
         onPointerDown={(e) => {

package/src/player/components/TimelineEmptyState.tsx

@@ -18,7 +18,7 @@ export function TimelineEmptyState({
 }: TimelineEmptyStateProps) {
   return (
     <div
-      className={`h-full border-t bg-[#0a0a0b] flex flex-col select-none transition-colors duration-150 ${
+      className={`h-full border-t bg-[var(--timeline-shell-bg)] flex flex-col select-none transition-colors duration-150 ${
         isDragOver ? "border-studio-accent/50 bg-studio-accent/3" : "border-neutral-800/50"
       }`}
       onDragOver={onDragOver}

package/src/player/components/TimelineFxButton.tsx

@@ -79,7 +79,7 @@ function GroupNameDialog({
       <div
         role="dialog"
         aria-label="This track cannot be grouped"
-        className="z-200 w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] leading-snug text-white/75 shadow-xl"
+        className="z-200 w-64 rounded-md border border-[var(--timeline-tick-major)] bg-[var(--timeline-dialog-bg)] p-3 text-[11px] leading-snug text-[var(--timeline-text-soft)] shadow-xl"
         style={{ position: "fixed", ...groupDialogPosition(anchorRect) }}
         onPointerDown={(event) => event.stopPropagation()}
         onKeyDown={(event) => {
@@ -97,7 +97,7 @@ function GroupNameDialog({
     <div
       role="dialog"
       aria-label="Name this group"
-      className="z-200 w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] text-white/75 shadow-xl"
+      className="z-200 w-64 rounded-md border border-[var(--timeline-tick-major)] bg-[var(--timeline-dialog-bg)] p-3 text-[11px] text-[var(--timeline-text-soft)] shadow-xl"
       style={{ position: "fixed", ...groupDialogPosition(anchorRect) }}
       onPointerDown={(event) => event.stopPropagation()}
       onKeyDown={(event) => {
@@ -108,14 +108,14 @@ function GroupNameDialog({
         if (event.key === "Enter") confirm();
       }}
     >
-      <p className="mb-1.5 font-medium text-white">Name this group</p>
+      <p className="mb-1.5 font-medium text-[var(--timeline-text-solid)]">Name this group</p>
       <input
         ref={inputRef}
         type="text"
         aria-label="Group name"
         value={label}
         onChange={(event) => setLabel(event.currentTarget.value)}
-        className="w-full rounded-sm border border-white/20 bg-black/30 px-1.5 py-1 text-[11px] text-white outline-hidden focus:border-[#3CE6AC]"
+        className="w-full rounded-sm border border-[var(--timeline-border-strong)] bg-[var(--timeline-input-bg)] px-1.5 py-1 text-[11px] text-[var(--timeline-text-solid)] outline-hidden focus:border-[var(--timeline-accent)]"
       />
       {/* The sentence. No jargon, and it names both things a bus does. */}
       <p className="mt-2 leading-snug">
@@ -125,14 +125,14 @@ function GroupNameDialog({
       <div className="mt-2.5 flex justify-end gap-1.5">
         <button
           type="button"
-          className="rounded-sm border border-white/20 px-2 py-1 text-[10px] text-white/75 hover:bg-white/10"
+          className="rounded-sm border border-[var(--timeline-border-strong)] px-2 py-1 text-[10px] text-[var(--timeline-text-soft)] hover:bg-[var(--timeline-tick-major)]"
           onClick={onCancel}
         >
           Cancel
         </button>
         <button
           type="button"
-          className="rounded-sm border border-[#3CE6AC] bg-[#3CE6AC]/15 px-2 py-1 text-[10px] font-semibold text-[#3CE6AC] hover:bg-[#3CE6AC]/25"
+          className="rounded-sm border border-[var(--timeline-accent)] bg-[var(--timeline-accent-button-bg)] px-2 py-1 text-[10px] font-semibold text-[var(--timeline-accent)] hover:bg-[var(--timeline-accent-hover)]"
           onClick={confirm}
         >
           Group
@@ -212,7 +212,7 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
           ref={buttonRef}
           aria-label="Effects — group these clips first"
           title="Group these clips to add effects to all of them"
-          className="flex h-6 items-center justify-center rounded-sm border-0 bg-transparent px-1 text-[10px] font-semibold text-white/35 hover:text-white/75"
+          className="flex h-6 items-center justify-center rounded-sm border-0 bg-transparent px-1 text-[10px] font-semibold text-[var(--timeline-text-faint)] hover:text-[var(--timeline-text-soft)]"
           onPointerDown={(event) => event.stopPropagation()}
           onClick={(event) => {
             event.stopPropagation();
@@ -253,7 +253,9 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
         aria-label={nodeCount > 0 ? `Effects — ${nodeCount} applied` : "Effects"}
         title="Effects"
         className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[10px] font-semibold transition-colors ${
-          open || nodeCount > 0 ? "text-[#3CE6AC]" : "text-white/35 hover:text-white/75"
+          open || nodeCount > 0
+            ? "text-[var(--timeline-accent)]"
+            : "text-[var(--timeline-text-faint)] hover:text-[var(--timeline-text-soft)]"
         }`}
         onPointerDown={(event) => event.stopPropagation()}
         onClick={(event) => {