@hyperframes/studio 0.8.57 → 0.8.59

package/src/hooks/useSdkSession.ts

@@ -16,12 +16,23 @@ import { addExternalFileReloadListener } from "./externalFileReloadBus";
  *
  * Every reason lives in this union so the full surface is readable from one
  * place — `absent_or_empty` included, even though it is a 2xx.
+ *
+ * `network` is a fetch that REJECTED — the request never produced a response.
+ * It was not in this union until 2026-09-21, so it escaped `readProjectFileOptional`
+ * and was caught by the effect's outer `.catch`, landing in `stage: "open"`.
+ * That label means `openComposition` threw (unparseable composition, OOM), and
+ * it is what the largest failure class was reported as. Every `stage: open`
+ * event measured on 0.8.56 and 0.8.57 carries a fetch-rejection message —
+ * "Failed to fetch", "Load failed", "NetworkError when attempting to fetch
+ * resource." — so the class was a network problem filed under a parser one, and
+ * unaddressable in that bucket.
  */
 type ProjectFileReadFailure =
   | { ok: false; reason: "unsafe_path" }
   | { ok: false; reason: "http_error"; status: number }
   | { ok: false; reason: "missing_content" }
-  | { ok: false; reason: "absent_or_empty" };
+  | { ok: false; reason: "absent_or_empty" }
+  | { ok: false; reason: "network" };
 
 type ProjectFileReadResult = { ok: true; content: string } | ProjectFileReadFailure;
 
@@ -68,9 +79,20 @@ async function readProjectFileOptional(
   // and closes the CodeQL client-side-request-forgery flag). encodeURIComponent
   // already confines both values to single segments of this same-origin URL.
   if (path.includes("\0") || path.includes("..")) return { ok: false, reason: "unsafe_path" };
-  const res = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
-  );
+  let res: Response;
+  try {
+    res = await fetch(
+      `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
+    );
+  } catch {
+    // The request never produced a response: offline, the dev server gone, a
+    // CSP/Private-Network-Access block, or an extension rewriting fetch. Caught
+    // here so it is reported as a READ failure — left to propagate, the effect's
+    // outer catch reported it as `stage: "open"`, which claims the composition
+    // failed to parse. Every `stage: open` event before this change was this
+    // branch, so the label made the largest class unaddressable.
+    return { ok: false, reason: "network" };
+  }
   if (!res.ok) return { ok: false, reason: "http_error", status: res.status };
   const data = (await res.json()) as { content?: string };
   // `optional=1` answers a missing file with 200 + `content: ""`, so a
@@ -299,6 +321,11 @@ export function useSdkSession(
           // openComposition threw (unparseable composition, OOM) — same total
           // bypass as the read failure above, but this one is a real defect
           // rather than a missing file. Carry the message; it is the only clue.
+          //
+          // A rejected read no longer reaches here: `readProjectFileOptional`
+          // catches its own fetch rejection and answers `reason: "network"`, so
+          // this stage now means what it says. Before that, every event in this
+          // bucket was a network error wearing a parser's label.
           trackStudioEvent("sdk_session_unavailable", {
             stage: "open",
             error: error instanceof Error ? error.message : String(error),

package/src/hooks/useTimelineAssetDropOps.ts

@@ -18,7 +18,11 @@ import {
 } from "../utils/timelineAssetDrop";
 import { generateId } from "../utils/generateId";
 import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
-import { collectHtmlIds, resolveDroppedAssetDuration } from "../utils/studioHelpers";
+import {
+  collectHtmlIds,
+  resolveDroppedAssetDuration,
+  resolveDroppedAssetHasAudio,
+} from "../utils/studioHelpers";
 import { formatTimelineAttributeNumber } from "./timelineEditingHelpers";
 import { readFileContent } from "./timelineTimingSync";
 import { commitTimelineCompositionInsertion } from "../utils/timelineCompositionInsert";
@@ -113,6 +117,9 @@ export function useTimelineAssetDropOps({
             ? durationOverride
             : await resolveDroppedAssetDuration(pid, assetPath, kind);
         const normalizedDuration = Number(formatTimelineAttributeNumber(duration));
+        // A video with an audio stream lands audible; the mixer only hears a
+        // <video> marked data-has-audio, and a muted drop was losing the sound.
+        const hasAudio = await resolveDroppedAssetHasAudio(pid, assetPath, kind);
         const newId = buildTimelineAssetId(assetPath, collectHtmlIds(originalContent));
         const resolvedAssetSrc = resolveTimelineAssetSrc(targetPath, assetPath);
 
@@ -146,6 +153,7 @@ export function useTimelineAssetDropOps({
               duration: normalizedDuration,
               track,
               zIndex: newElementZIndex,
+              hasAudio,
               geometry: fitTimelineAssetGeometry(
                 null,
                 resolveTimelineAssetCompositionSize(originalContent),

package/src/index.ts

@@ -46,12 +46,36 @@ export {
   VideoThumbnail,
   CompositionThumbnail,
   useTimelinePlayer,
+  usePlayerHandle,
   resolveIframe,
   usePlayerStore,
   liveTime,
   formatTime,
 } from "./player";
-export type { TimelineElement, TimelineTimeRange } from "./player";
+export type {
+  PlayerHandle,
+  PlayerHandleElement,
+  PlayerHandleListener,
+  PlayerHandleTimeListener,
+  TimelineElement,
+  TimelineTimeRange,
+} from "./player";
+export {
+  TimelineFrame,
+  TimelineLanes,
+  TimelineOverlays,
+  TimelinePlayhead,
+  TimelineRazorGuide,
+  TimelineRuler,
+  TimelineEmptyStatePart,
+  TimelineEditPopover,
+  TimelineClipMenu,
+  TimelineGapMenu,
+  TimelineKeyframeMenu,
+  TimelineShortcutHint,
+} from "./player/components/TimelineParts";
+export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
+export type { TimelineTheme } from "./player/components/timelineTheme";
 
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

package/src/player/components/LayerDisclosureRow.tsx

@@ -95,9 +95,9 @@ export function LayerDisclosureRow({
       <span aria-hidden="true" className="shrink-0 text-[13px] leading-none text-white/40">
         ◇
       </span>
-      {/* Wraps rather than truncating: a truncated name needs a hover to be
-          read, which a scanned column cannot rely on. */}
-      <span className="min-w-0 flex-1 wrap-break-word font-medium leading-tight">{name}</span>
+      <span title={name} className="min-w-0 flex-1 truncate font-medium leading-tight">
+        {name}
+      </span>
       <TrackClipCount clipCount={clipCount} />
       {children}
       {/* Anchored right, on every header that has one: the lane toggle is the

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

@@ -85,6 +85,8 @@ async function mountPlayer(props: Partial<PlayerProps> = {}) {
 
 const twoFrames = () => act(async () => void (await new Promise((r) => setTimeout(r, 80))));
 
+const flushEffects = () => act(async () => await Promise.resolve());
+
 function createAudioIframe() {
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
@@ -216,6 +218,38 @@ describe("ready to show", () => {
   const painted = (player: TestHyperframesPlayer) =>
     act(() => void player.dispatchEvent(new Event("painted")));
 
+  it("waits two animation frames before notifying that the preview can show", async () => {
+    const callbacks: FrameRequestCallback[] = [];
+    const requestAnimationFrame = vi
+      .spyOn(window, "requestAnimationFrame")
+      .mockImplementation((callback) => {
+        callbacks.push(callback);
+        return callbacks.length;
+      });
+    try {
+      const onReadyToShowChange = vi.fn();
+      const { player } = await mountPlayer({ onReadyToShowChange });
+      const el = player as TestHyperframesPlayer;
+
+      loadAndReady(el);
+      painted(el);
+      await flushEffects();
+      expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+      expect(callbacks).toHaveLength(1);
+
+      act(() => callbacks.shift()?.(0));
+      await flushEffects();
+      expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+      expect(callbacks).toHaveLength(1);
+
+      act(() => callbacks.shift()?.(16));
+      await flushEffects();
+      expect(onReadyToShowChange).toHaveBeenLastCalledWith(true);
+    } finally {
+      requestAnimationFrame.mockRestore();
+    }
+  });
+
   it("promotes only once the player reports painted, not at ready or assetsready", async () => {
     const onReadyToShowChange = vi.fn();
     const { player } = await mountPlayer({ onReadyToShowChange });

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

@@ -135,6 +135,26 @@ function renderBasicTimeline() {
   return { host, root };
 }
 
+function renderSharedAutomationTimeline(selectedElementId?: string) {
+  const host = createSizedTimelineHost(720);
+  const automation = JSON.stringify({
+    version: 1,
+    lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
+  });
+  usePlayerStore.setState({
+    duration: 8,
+    timelineReady: true,
+    ...(selectedElementId ? { selectedElementId } : {}),
+    elements: [
+      { id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
+      { id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
+    ],
+  });
+  const root = createRoot(host);
+  act(() => root.render(React.createElement(Timeline)));
+  return { host, root };
+}
+
 describe("Timeline provider boundary", () => {
   it("keeps all-collapsed horizontal positions at the gutter plus the pre-t=0 pad", () => {
     usePlayerStore.setState({
@@ -621,21 +641,7 @@ describe("Timeline provider boundary", () => {
   // clip left the row's state depending on the selection, and a collapse that
   // only dropped the active clip left the row stuck open.
   it("expands and collapses every clip on a shared track together", () => {
-    const host = createSizedTimelineHost(720);
-    const automation = JSON.stringify({
-      version: 1,
-      lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
-    });
-    usePlayerStore.setState({
-      duration: 8,
-      timelineReady: true,
-      elements: [
-        { id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
-        { id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
-      ],
-    });
-    const root = createRoot(host);
-    act(() => root.render(React.createElement(Timeline)));
+    const { host, root } = renderSharedAutomationTimeline();
 
     const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
       ?.parentElement;
@@ -668,22 +674,7 @@ describe("Timeline provider boundary", () => {
   // a lane to select its clip therefore made the handles vanish under the
   // pointer, which is the one gesture the read-only lane exists to support.
   it("keeps the automation lanes mounted when the selection moves along the row", () => {
-    const host = createSizedTimelineHost(720);
-    const automation = JSON.stringify({
-      version: 1,
-      lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
-    });
-    usePlayerStore.setState({
-      duration: 8,
-      timelineReady: true,
-      selectedElementId: "narration-2",
-      elements: [
-        { id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
-        { id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
-      ],
-    });
-    const root = createRoot(host);
-    act(() => root.render(React.createElement(Timeline)));
+    const { host, root } = renderSharedAutomationTimeline("narration-2");
     act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]')?.click());
 
     const before = [...host.querySelectorAll(".hf-automation-lane")];

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());
+  });
+});