@hyperframes/studio 0.8.46 → 0.8.48

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+function el(id: string, start: number, duration: number, track = 0): TimelineElement {
+  return { id, tag: "video", start, duration, track, domId: id };
+}
+
+describe("applyRippleShifts", () => {
+  it("returns survivors unchanged when there are no changes", () => {
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(applyRippleShifts(survivors, null)).toBe(survivors);
+  });
+
+  it("rewrites only the starts named by the changes", () => {
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    const result = applyRippleShifts(survivors, [{ element: survivors[1], start: 2 }]);
+    expect(result).toEqual([el("a", 0, 2), el("c", 2, 1)]);
+    expect(result[0]).toBe(survivors[0]);
+  });
+});
+
+describe("useTimelineDeleteOps: ripple undo label", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-hf-root data-duration="6">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+<div data-hf-id="hf-c" data-start="4" data-duration="2"></div>
+</div>
+</body></html>`;
+
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.includes("/file-mutations/remove-element/")) {
+          return new Response(JSON.stringify({ changed: true, content: html }), { status: 200 });
+        }
+        return new Response(JSON.stringify({ content: html }), { status: 200 });
+      }),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  type DeleteOpsOptions = Parameters<typeof useTimelineDeleteOps>[0];
+
+  function mountDeleteHarness(overrides: {
+    handleTimelineGroupMove: DeleteOpsOptions["handleTimelineGroupMove"];
+    showToast?: DeleteOpsOptions["showToast"];
+  }) {
+    const elements = [el("hf-a", 0, 2), el("hf-b", 2, 2), el("hf-c", 4, 2)];
+    let hook: ReturnType<typeof useTimelineDeleteOps> | null = null;
+    function Harness() {
+      hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: overrides.showToast ?? vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: null },
+        handleTimelineGroupMove: overrides.handleTimelineGroupMove,
+      });
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    return { b: elements[1], getHook: () => hook! };
+  }
+
+  // editHistory.ts's coalescing keeps the LAST recordEdit call's label, so the
+  // folded ripple move must carry the delete's label, not its own.
+  it("passes the delete's own label to the folded ripple move, not 'Move timeline clips'", async () => {
+    const handleTimelineGroupMove = vi.fn().mockResolvedValue(undefined);
+    const { b, getHook } = mountDeleteHarness({ handleTimelineGroupMove });
+
+    await act(async () => {
+      await getHook().handleTimelineElementDelete(b);
+    });
+
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ label: "Delete timeline clip" }),
+    );
+  });
+
+  it("shows exactly one toast when a ripple fails to persist after a committed delete", async () => {
+    const handleTimelineGroupMove = vi.fn().mockRejectedValue(new Error("persist failed"));
+    const showToast = vi.fn();
+    const { b, getHook } = mountDeleteHarness({ handleTimelineGroupMove, showToast });
+
+    await act(async () => {
+      await getHook().handleTimelineElementDelete(b);
+    });
+
+    // The user did one thing (delete); the generic move-failure toast is
+    // suppressed on this call so only the specific message reaches them.
+    expect(showToast).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(
+      "Clip deleted, but the gap could not be closed.",
+      "error",
+    );
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ suppressFailureToast: true }),
+    );
+  });
+});

package/src/hooks/useTimelineDeleteOps.ts

@@ -2,7 +2,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 // Timeline clip deletion: the marquee/multi path and the single-clip wrapper
 // the context menu uses. Extracted verbatim from useTimelineEditing.ts to keep
 // it under the studio 600-line cap, following useTimelineAssetDropOps.
-import { useCallback, type MutableRefObject, type RefObject } from "react";
+import { useCallback, useRef, type MutableRefObject, type RefObject } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
@@ -12,6 +12,28 @@ import { buildPatchTarget } from "./timelineEditingHelpers";
 import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
+import {
+  resolveMainTrackDeleteRippleShifts,
+  resolveShiftedElements,
+} from "../player/components/timelineGapCommit";
+import type {
+  TimelineGroupCommitOptions,
+  TimelineGroupMoveChange,
+} from "./useTimelineGroupEditing";
+
+/** Apply already-resolved ripple changes to the surviving elements for the
+ *  optimistic store update after a delete. Pure — no IO. */
+export function applyRippleShifts(
+  survivors: TimelineElement[],
+  changes: readonly TimelineGroupMoveChange[] | null,
+): TimelineElement[] {
+  if (!changes) return survivors;
+  const newStartByElement = new Map(changes.map((c) => [c.element, c.start]));
+  return survivors.map((te) => {
+    const newStart = newStartByElement.get(te);
+    return newStart != null ? { ...te, start: newStart } : te;
+  });
+}
 
 interface UseTimelineDeleteOpsOptions {
   projectIdRef: MutableRefObject<string | null>;
@@ -24,8 +46,20 @@ interface UseTimelineDeleteOpsOptions {
   isRecordingRef?: MutableRefObject<boolean>;
   forceReloadSdkSession?: () => void;
   previewIframeRef: RefObject<HTMLIFrameElement | null>;
+  /** The same atomic multi-clip move commit the track-gap menu uses, reused
+   *  to ripple the main track after a delete, folded into the delete's own
+   *  undo entry via a shared coalesceKey. */
+  handleTimelineGroupMove: (
+    changes: TimelineGroupMoveChange[],
+    options?: TimelineGroupCommitOptions,
+  ) => Promise<void>;
 }
 
+// Per-gesture-unique coalesce key — a monotonic counter, not Date.now() /
+// Math.random() (determinism rules), mirroring gapCloseGestureSeq in
+// timelineGapCommit.ts.
+let deleteGestureSeq = 0;
+
 export function useTimelineDeleteOps({
   projectIdRef,
   activeCompPath,
@@ -37,7 +71,12 @@ export function useTimelineDeleteOps({
   isRecordingRef,
   forceReloadSdkSession,
   previewIframeRef,
+  handleTimelineGroupMove,
 }: UseTimelineDeleteOpsOptions) {
+  // First-use-per-session notice for the ripple. Plain info toast: Studio's
+  // toast system has no action buttons, so Undo and the toggle location are
+  // named in words instead.
+  const rippleNoticeShownRef = useRef(false);
   // fallow-ignore-next-line complexity
   const handleTimelineElementsDelete = useCallback(
     // fallow-ignore-next-line complexity
@@ -109,11 +148,17 @@ export function useTimelineDeleteOps({
           usePlayerStore.getState().setDuration(deleteContentEnd);
         }
 
+        // Shared with the ripple move below so a folded ripple is one undo
+        // step with the delete, not two (editHistory.ts coalesces by key +
+        // window across separate recordEdit calls, not by label).
+        const coalesceKey = `main-track-ripple-delete:${deleteGestureSeq++}`;
+        const deleteHistoryLabel = "Delete timeline clip";
         try {
           await saveProjectFilesWithHistory({
             projectId: pid,
-            label: "Delete timeline clip",
+            label: deleteHistoryLabel,
             kind: "timeline",
+            coalesceKey,
             files: { [targetPath]: patchedContent },
             readFile: async () => originalContent,
             // remove-element already wrote the removal, so disk holds THAT — not the
@@ -128,17 +173,65 @@ export function useTimelineDeleteOps({
         }
 
         const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
-        usePlayerStore
-          .getState()
-          .setElements(timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id)));
+        const survivors = timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id));
+
+        // Ripple: close the gap the delete left on the main track. Pure decision
+        // first (resolveMainTrackDeleteRippleShifts — off, no main-track clip
+        // deleted, already gapless, or a locked survivor all resolve to null),
+        // then the one write, folded into the delete's undo entry above.
+        const rippleShifts = resolveMainTrackDeleteRippleShifts(
+          survivors,
+          sameFile,
+          usePlayerStore.getState().rippleEditEnabled,
+        );
+        let rippleApplied: TimelineGroupMoveChange[] | null = null;
+        let rippleFailed = false;
+        if (rippleShifts) {
+          const rippleChanges = resolveShiftedElements(survivors, rippleShifts);
+          try {
+            await handleTimelineGroupMove(rippleChanges, {
+              coalesceKey,
+              coalesceMs: Number.POSITIVE_INFINITY,
+              // Coalescing keeps the LAST entry's label; without this the undo
+              // toast reads "Undid Move timeline clips" after a delete, naming
+              // the ripple's mechanics instead of what the user actually did.
+              label: deleteHistoryLabel,
+              // This call gets its own, more specific failure toast below —
+              // the generic one would tell the user about one action twice.
+              suppressFailureToast: true,
+            });
+            rippleApplied = rippleChanges;
+          } catch (error) {
+            // The delete already committed; a failed ripple leaves the gap the
+            // toggle-off behaviour would have left anyway — not worth undoing
+            // an otherwise-successful delete over.
+            rippleFailed = true;
+            console.error("[Timeline] ripple-edit failed to persist after delete", error);
+            showToast("Clip deleted, but the gap could not be closed.", "error");
+          }
+        }
+
+        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleApplied));
         usePlayerStore.getState().setSelectedElementId(null);
         usePlayerStore.getState().setSelectedElementIds(new Set());
         forceReloadSdkSession?.();
         reloadPreview();
-        showToast(
-          `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
-          "info",
-        );
+        // A failed ripple already showed its own toast above; the user did one
+        // thing (delete), so they get one message, not this generic follow-up too.
+        if (!rippleFailed) {
+          showToast(
+            `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
+            "info",
+          );
+        }
+        if (rippleApplied && !rippleNoticeShownRef.current) {
+          rippleNoticeShownRef.current = true;
+          showToast(
+            "Ripple closed the gap on the main track. Undo (⌘Z) restores it, or turn off " +
+              "Ripple in the timeline toolbar.",
+            "info",
+          );
+        }
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
         showToast(message);
@@ -155,6 +248,7 @@ export function useTimelineDeleteOps({
       isRecordingRef,
       forceReloadSdkSession,
       previewIframeRef,
+      handleTimelineGroupMove,
     ],
   );
 

package/src/hooks/useTimelineEditing.ts

@@ -413,6 +413,7 @@ export function useTimelineEditing({
     isRecordingRef,
     forceReloadSdkSession,
     previewIframeRef,
+    handleTimelineGroupMove: groupEditing.handleTimelineGroupMove,
   });
 
   const { handleTimelineAssetDrop, handleTimelineFileDrop, handleTimelineCompositionDrop } =

package/src/hooks/useTimelineGroupEditing.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Root } from "react-dom/client";
+import type { TimelineElement } from "../player";
+import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+function el(id: string, start: number, duration: number, track = 0): TimelineElement {
+  return { id, tag: "video", start, duration, track, domId: id };
+}
+
+describe("useTimelineGroupEditing: handleTimelineGroupMove suppressFailureToast", () => {
+  let root: Root | null = null;
+
+  afterEach(() => {
+    if (root) act(() => root!.unmount());
+    root = null;
+    document.body.innerHTML = "";
+  });
+
+  type GroupEditingOptions = Parameters<typeof useTimelineGroupEditing>[0];
+
+  // No project id makes enqueueGroupOperation reject before any persist runs,
+  // exercising the move's real catch block without faking the SDK/server path.
+  function mountFailingHarness(showToast: GroupEditingOptions["showToast"]) {
+    let hook: ReturnType<typeof useTimelineGroupEditing> | null = null;
+    function Harness() {
+      hook = useTimelineGroupEditing({
+        activeCompPath: "index.html",
+        editQueueRef: { current: Promise.resolve() },
+        pendingTimelineEditPathRef: { current: new Set() },
+        previewIframeRef: { current: null },
+        projectIdRef: { current: null },
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        showToast,
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+      });
+      return null;
+    }
+    root = mountReactHarness(<Harness />);
+    return () => hook!;
+  }
+
+  const change = { element: el("a", 0, 2), start: 2 };
+
+  it("shows no toast when suppressFailureToast is set on a failed move", async () => {
+    const showToast = vi.fn();
+    const getHook = mountFailingHarness(showToast);
+
+    await act(async () => {
+      await expect(
+        getHook().handleTimelineGroupMove([change], { suppressFailureToast: true }),
+      ).rejects.toThrow();
+    });
+
+    expect(showToast).not.toHaveBeenCalled();
+  });
+
+  it("shows one toast when suppressFailureToast is not set on a failed move", async () => {
+    const showToast = vi.fn();
+    const getHook = mountFailingHarness(showToast);
+
+    await act(async () => {
+      await expect(getHook().handleTimelineGroupMove([change])).rejects.toThrow();
+    });
+
+    expect(showToast).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useTimelineGroupEditing.ts

@@ -47,6 +47,15 @@ export interface TimelineGroupCommitOptions {
   coalesceKey?: string;
   /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
   coalesceMs?: number;
+  /** Overrides the default "Move timeline clips" undo-history label. Coalescing
+   *  keeps the LAST entry's label (editHistory.ts), so a mechanical follow-up
+   *  move folded into another gesture's coalesceKey (e.g. the ripple after a
+   *  delete) should carry that gesture's own label, not its own. */
+  label?: string;
+  /** Skips this call's own generic failure toast (the error is still logged
+   *  to the console) — for a caller that shows its own more specific message
+   *  on the same failure, so the user isn't told about one action twice. */
+  suppressFailureToast?: boolean;
 }
 
 interface UseTimelineGroupEditingOptions {
@@ -272,21 +281,22 @@ export function useTimelineGroupEditing({
       syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? moveCoalesceKey(changes);
       const coalesceMs = options?.coalesceMs;
-      return enqueueGroupOperation("Move timeline clips", async (projectId) => {
+      const label = options?.label ?? "Move timeline clips";
+      return enqueueGroupOperation(label, async (projectId) => {
         await options?.beforeTiming;
         const handledBySdk = await trySdkBatchPersist({
           changes,
           sdkChanges: toSdkTimingChanges(changes, (change) => ({ start: change.start })),
           eligible: changes.every((change) => change.track == null),
           needsExtension,
-          label: "Move timeline clips",
+          label,
           coalesceKey,
           coalesceMs,
         });
         if (!handledBySdk) {
           await persistServerBatch(
             projectId,
-            "Move timeline clips",
+            label,
             changes.map((change) => ({
               element: change.element,
               buildPatches: (original, target) =>
@@ -315,7 +325,7 @@ export function useTimelineGroupEditing({
             projectId,
             iframe: previewIframeRef.current,
             reloadPreview,
-            label: "Move timeline clips",
+            label,
             errorLabel: "Failed to shift GSAP positions",
             coalesceKey,
             recordEdit,
@@ -336,7 +346,11 @@ export function useTimelineGroupEditing({
         // Failed persist: revert the optimistic duration readout + live root
         // alongside the gesture owner's store rollback.
         rollbackDuration();
-        showToast(getStudioSaveErrorMessage(error), "error");
+        if (options?.suppressFailureToast) {
+          console.error("[Timeline] group move failed to persist", error);
+        } else {
+          showToast(getStudioSaveErrorMessage(error), "error");
+        }
         throw error;
       });
     },

package/src/index.ts

@@ -27,6 +27,16 @@ export { FileTree } from "./components/editor/FileTree";
 // App
 export { StudioApp } from "./App";
 
+// Ask-agent flow
+export { AskAgentModal } from "./components/AskAgentModal";
+export type { AskAgentModalProps } from "./components/AskAgentModal";
+export type { AgentModalAnchorPoint } from "./utils/studioHelpers";
+export {
+  buildPickerAgentPrompt,
+  buildPickerAgentContextPreview,
+} from "./components/editor/domEditingAgentPrompt";
+export type { AgentPromptElementInfo } from "./components/editor/domEditingAgentPrompt";
+
 // Hooks
 export { useElementPicker } from "./hooks/useElementPicker";
 export type { PickedElement } from "./hooks/useElementPicker";

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

@@ -166,7 +166,6 @@ describe("Timeline provider boundary", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 60,
           trackOrder: [0],
         },
         1132,
@@ -282,7 +281,6 @@ describe("Timeline provider boundary", () => {
           scrollTop: 0,
           contentOrigin: LABEL_COL_W + GUTTER,
           pixelsPerSecond: 100,
-          duration: 60,
           trackOrder: [0],
         },
         100 + LABEL_COL_W + GUTTER + 1000,
@@ -1263,7 +1261,6 @@ describe("resolveTimelineAssetDrop", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 10,
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
@@ -1285,7 +1282,6 @@ describe("resolveTimelineAssetDrop", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 10,
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },

package/src/player/components/Timeline.tsx

@@ -238,7 +238,6 @@ export const Timeline = memo(function Timeline({
   const assetDrop = useTimelineAssetDrop({
     scrollRef,
     ppsRef,
-    durationRef,
     trackOrderRef,
     rowGeometryRef,
     contentOrigin,

package/src/player/components/TimelineAutomationLaneSlot.tsx

@@ -13,7 +13,7 @@ import { TimelineAutomationLane } from "./TimelineAutomationLane";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { getTimelineLaneTop } from "./timelineLayout";
 import { groupAutomationLanes, isCarveLane } from "./automationLaneData";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
 import type { UseAutomationLanesResult } from "./useAutomationLanes";
@@ -174,7 +174,9 @@ export function TimelineAutomationLaneSlot({
   currentTime,
   beatTimes,
 }: TimelineAutomationLaneSlotProps) {
-  const clips = elements.filter(isAudioTimelineElement);
+  // Broader than a raw-attribute check — a clip mid-edit (see the stale-
+  // selection test) has lanes in its live binding before the attribute commits.
+  const clips = elements.filter(isAudioOrVideoTimelineElement);
   const rowsByClip = new Map<string, ClipLaneRow[]>();
   groupAutomationLanes(clips).forEach((group, rowIndex) => {
     for (const entry of group.entries) {

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

@@ -1275,7 +1275,8 @@ describe("TimelineClipDiamonds", () => {
     expect(host.querySelectorAll("[data-keyframe-ease-segment]").length).toBe(2);
     const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]")!;
     expect(ease.getAttribute("aria-label")).toBe("Edit none easing after 10s");
-    expect(ease.classList.contains("opacity-0")).toBe(true);
+    expect(ease.getAttribute("title")).toBe("Edit none easing");
+    expect(ease.classList.contains("opacity-40")).toBe(true);
     act(() => ease.click());
     expect(onSelectSegment).toHaveBeenCalledOnce();
     expect(usePlayerStore.getState().requestedSeekTime).toBeNull();
@@ -1318,6 +1319,17 @@ describe("TimelineClipDiamonds", () => {
     act(() => root.unmount());
   });
 
+  it("keeps the ease button hover-only on a segment too narrow to show it at rest", () => {
+    // Same narrow clip as above: showing the button at rest here would sit on
+    // top of both diamonds instead of clear of them.
+    const { host, root } = renderSegmentLane(false, 40);
+    const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]");
+
+    expect(ease?.classList.contains("opacity-0")).toBe(true);
+    expect(ease?.classList.contains("opacity-40")).toBe(false);
+    act(() => root.unmount());
+  });
+
   it("hides the inline ease button on a segment with no source animation id", () => {
     // A runtime-scanned keyframe has no animationId, so there is no tween to
     // target; the segment ending on it must not render a (dead) ease button.

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { hasRoomForRestingEase } from "./TimelineDiamondConnectors";
+
+describe("hasRoomForRestingEase", () => {
+  it("is false just under the threshold", () => {
+    expect(hasRoomForRestingEase(23)).toBe(false);
+  });
+
+  it("is true exactly at the threshold", () => {
+    expect(hasRoomForRestingEase(24)).toBe(true);
+  });
+
+  it("is true well above the threshold", () => {
+    expect(hasRoomForRestingEase(78)).toBe(true);
+  });
+});

package/src/player/components/TimelineDiamondConnectors.tsx

@@ -13,6 +13,17 @@ export interface TimelineDiamondMarker {
   visualSize: number;
 }
 
+const EASE_BUTTON_PX = 16;
+const EASE_BUTTON_REST_GAP_PX = 4;
+
+/** Whether a segment is wide enough to show the ease button at rest (button
+ * box plus a clear gap each side) without overlapping either neighboring
+ * diamond. 24 coincides with roomForFullTarget's threshold below but is a
+ * separate constraint; don't assume changing one keeps the other in sync. */
+export function hasRoomForRestingEase(connectorWidth: number): boolean {
+  return connectorWidth >= EASE_BUTTON_PX + EASE_BUTTON_REST_GAP_PX * 2;
+}
+
 /**
  * The line between each pair of adjacent diamonds, plus the ease control that
  * sits at the segment's midpoint. Split out of TimelineClipDiamonds only to keep
@@ -96,6 +107,7 @@ export function TimelineDiamondConnectors({
                 // the hit test and steal their clicks at fit zoom. Grow the
                 // target only where the room exists.
                 roomForFullTarget={connectorWidth >= 24}
+                restingVisible={hasRoomForRestingEase(connectorWidth)}
                 onSelectSegment={onSelectSegment}
               />
             )}
@@ -133,6 +145,7 @@ function SegmentEaseControl({
   rovingTargetId,
   afterLabel,
   roomForFullTarget,
+  restingVisible,
   onSelectSegment,
 }: {
   left: number;
@@ -146,6 +159,9 @@ function SegmentEaseControl({
   /** Time label of the keyframe this segment starts at, for the accessible name. */
   afterLabel: string;
   roomForFullTarget: boolean;
+  /** Whether the segment is wide enough to show the button at rest; too
+   * narrow and it stays hover-only so it doesn't smear over the diamonds. */
+  restingVisible: boolean;
   onSelectSegment: (target: TimelineKeyframeTarget) => void;
 }) {
   // The ease button sits dead centre of its segment, which on a two-keyframe clip
@@ -187,7 +203,7 @@ function SegmentEaseControl({
         // for that overlay the button keeps its 16x16 hit area, which is WCAG's
         // target-spacing exception: the neighbouring diamonds are themselves the
         // reason it cannot grow, and stealing their clicks is the worse failure.
-        className={`absolute flex items-center justify-center rounded opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 ${roomForFullTarget ? "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']" : ""}`}
+        className={`absolute flex items-center justify-center rounded ${restingVisible ? "opacity-40" : "opacity-0"} transition-opacity hover:opacity-100 group-hover:opacity-100 focus-visible:opacity-100 ${roomForFullTarget ? "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']" : ""}`}
         style={{
           left: "50%",
           top: "50%",

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

@@ -406,7 +406,7 @@ describe("TimelinePropertyLanes", () => {
     expect(laneDiamonds(host, "position")).toHaveLength(3);
     const buttons = laneEaseButtons(host, "position");
     expect(buttons).toHaveLength(2);
-    expect(buttons.every((button) => button.classList.contains("opacity-0"))).toBe(true);
+    expect(buttons.every((button) => button.classList.contains("opacity-40"))).toBe(true);
     expect(buttons.every((button) => button.classList.contains("group-hover:opacity-100"))).toBe(
       true,
     );

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

@@ -260,9 +260,17 @@ describe("groupAutomationLanes", () => {
     expect(groups.map((g) => g.entries.length)).toEqual([1, 1]);
   });
 
-  it("ignores clips that are not audio, the way the reserved height does", () => {
-    const video = el({ id: "titles", key: "titles", tag: "div", automation: lanesOf("volume") });
-    expect(groupAutomationLanes([video])).toEqual([]);
+  it("draws lanes for a video element, matching the reserved height", () => {
+    // A <video>'s volume can be automated from the property panel same as an
+    // audio clip's; gating this on `isAudioTimelineElement` alone hid every
+    // keyframe the panel wrote for a video clip.
+    const video = el({ id: "titles", key: "titles", tag: "video", automation: lanesOf("volume") });
+    expect(groupAutomationLanes([video]).map((g) => g.key)).toEqual(["Volume"]);
+  });
+
+  it("ignores a clip that is neither audio nor video, the way the reserved height does", () => {
+    const div = el({ id: "titles", key: "titles", tag: "div", automation: lanesOf("volume") });
+    expect(groupAutomationLanes([div])).toEqual([]);
   });
 
   it("skips a target that does not resolve against its clip's chain", () => {