@hyperframes/studio 0.7.78 → 0.7.80

package/src/hooks/useGsapTweenCache.ts

@@ -5,26 +5,21 @@ import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBrid
 import {
   clearKeyframeCacheForElement,
   pruneKeyframeCacheToFiles,
+  publishKeyframeCache,
   writeGsapAnimationsForElement,
 } from "./gsapKeyframeCacheHelpers";
-import { toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import { resolveClipTimingBasis, toAbsoluteTime, toClipPercentage } from "./gsapShared";
 import {
   deduplicateKeyframes,
   isStaticPositionHold,
   synthesizeFlatTweenKeyframes,
+  type MergeableKeyframe,
 } from "./gsapTweenSynth";
-import {
-  fetchParsedAnimations,
-  populateKeyframeCacheFromAst,
-  resolveClipTimingBasis,
-} from "./keyframeCacheAstLoad";
+import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
 
 // Re-exported so callers keep importing the GSAP cache surface from one module.
-export {
-  fetchParsedAnimations,
-  resolveClipTimingBasis,
-  resolveSelectorElementIds,
-} from "./keyframeCacheAstLoad";
+export { resolveClipTimingBasis } from "./gsapShared";
+export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
 
 /** The selected element's identity for matching tweens to it. */
 export interface GsapElementTarget {
@@ -273,13 +268,7 @@ export function useGsapAnimationsForElement(
       domClipChildren,
     );
 
-    const allKeyframes: Array<
-      GsapKeyframesData["keyframes"][0] & {
-        tweenPercentage?: number;
-        propertyGroup?: string;
-        animationId?: string;
-      }
-    > = [];
+    const allKeyframes: MergeableKeyframe[] = [];
     let format: GsapKeyframesData["format"] = "percentage";
     let ease: string | undefined;
     let easeEach: string | undefined;
@@ -325,11 +314,15 @@ export function useGsapAnimationsForElement(
       ...(ease ? { ease } : {}),
       ...(easeEach ? { easeEach } : {}),
     };
-    const { setKeyframeCache } = usePlayerStore.getState();
-    setKeyframeCache(`${sourceFile}#${elementId}`, merged);
-    // PropertyPanel reads the cache by bare elementId (without sourceFile prefix),
-    // so write a duplicate entry under the bare key for cross-component lookups.
-    setKeyframeCache(elementId, merged);
+    // PropertyPanel reads the cache by bare elementId (without sourceFile
+    // prefix), so the same entry is written under the bare key for
+    // cross-component lookups. Both keys land in one publish: a reader that woke
+    // between two separate writes saw the prefixed key updated and the bare one
+    // still stale.
+    publishKeyframeCache((draft) => {
+      draft.keyframeCache.set(`${sourceFile}#${elementId}`, merged);
+      draft.keyframeCache.set(elementId, merged);
+    });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [elementId, sourceFile, animations, domClipChildrenKey]);
 
@@ -428,29 +421,35 @@ export function usePopulateKeyframeCacheForFile(
       }
       const scanned = scanAllRuntimeKeyframes(iframe, clipById);
       if (scanned.size === 0) return false;
-      const { setKeyframeCache, keyframeCache } = usePlayerStore.getState();
-      for (const [id, data] of scanned) {
-        const cacheKey = `${sf}#${id}`;
-        const fallbackKey = `index.html#${id}`;
-        const alreadyCached =
-          keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id);
-        if (alreadyCached) continue;
-        // Skip position-only set tweens from runtime too — same filter as AST path
-        const isPosOnly =
-          data.keyframes.length === 1 &&
-          Object.keys(data.keyframes[0].properties).every((k) => k === "x" || k === "y");
-        if (isPosOnly) {
-          continue;
+      // One publish for the whole scan: a scan of a 120-clip composition used to
+      // emit up to three store notifications per element, and every subscriber
+      // in between re-rendered against a cache only partly filled in.
+      publishKeyframeCache((draft) => {
+        for (const [id, data] of scanned) {
+          const cacheKey = `${sf}#${id}`;
+          const fallbackKey = `index.html#${id}`;
+          const alreadyCached =
+            draft.keyframeCache.has(cacheKey) ||
+            draft.keyframeCache.has(fallbackKey) ||
+            draft.keyframeCache.has(id);
+          if (alreadyCached) continue;
+          // Skip position-only set tweens from runtime too, same filter as AST path
+          const isPosOnly =
+            data.keyframes.length === 1 &&
+            Object.keys(data.keyframes[0].properties).every((k) => k === "x" || k === "y");
+          if (isPosOnly) {
+            continue;
+          }
+          const entry = {
+            format: "percentage" as const,
+            keyframes: data.keyframes,
+            ...(data.easeEach ? { easeEach: data.easeEach } : {}),
+          };
+          draft.keyframeCache.set(cacheKey, entry);
+          if (sf !== "index.html") draft.keyframeCache.set(fallbackKey, entry);
+          draft.keyframeCache.set(id, entry);
         }
-        const entry = {
-          format: "percentage" as const,
-          keyframes: data.keyframes,
-          ...(data.easeEach ? { easeEach: data.easeEach } : {}),
-        };
-        setKeyframeCache(cacheKey, entry);
-        if (sf !== "index.html") setKeyframeCache(fallbackKey, entry);
-        setKeyframeCache(id, entry);
-      }
+      });
       runtimeScanDoneRef.current = `kf-cache:${projectId}:${sf}:${version}`;
       return true;
     };

package/src/hooks/useKeyframeEaseCommits.ts

@@ -0,0 +1,78 @@
+import { useCallback, type RefObject } from "react";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
+import type { AnimationKeyframeTarget } from "./gsapTweenSynth";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+interface KeyframeEaseCommitsInput {
+  gsapCommitMutation: CommitMutation;
+  domEditSelectionRef: RefObject<DomEditSelection | null>;
+}
+
+export function useKeyframeEaseCommits({
+  gsapCommitMutation,
+  domEditSelectionRef,
+}: KeyframeEaseCommitsInput) {
+  const handleUpdateSegmentEase = useCallback(
+    (targets: AnimationKeyframeTarget[], ease: string) => {
+      const selection = domEditSelectionRef.current;
+      if (!selection || targets.length === 0) return;
+      const options = {
+        label: targets.length === 1 ? "Update keyframe ease" : "Update segment ease",
+        softReload: true,
+      };
+      const calls = targets.map(({ animationId, tweenPercentage }) => ({
+        selection,
+        mutation: {
+          type: "update-keyframe",
+          animationId,
+          percentage: tweenPercentage,
+          properties: {},
+          ease,
+        },
+        options,
+      }));
+      if (calls.length === 1) {
+        const call = calls[0];
+        if (call) void gsapCommitMutation(call.selection, call.mutation, call.options);
+        return;
+      }
+      const batch = gsapCommitMutation.batch;
+      if (batch) {
+        void batch(calls, options);
+        return;
+      }
+      // A wrapped commit (a gesture transaction, say) carries no batch
+      // transport. Serial keeps the edit correct at the cost of one round trip
+      // per tween and one undo entry per tween; an optional-chained call here
+      // would silently drop the whole edit instead.
+      for (const call of calls)
+        void gsapCommitMutation(call.selection, call.mutation, call.options);
+    },
+    [gsapCommitMutation, domEditSelectionRef],
+  );
+
+  const handleUpdateKeyframeEase = useCallback(
+    (animationId: string, percentage: number, ease: string) =>
+      handleUpdateSegmentEase([{ animationId, tweenPercentage: percentage }], ease),
+    [handleUpdateSegmentEase],
+  );
+
+  const handleSetAllKeyframeEases = useCallback(
+    (animationId: string, ease: string) => {
+      const sel = domEditSelectionRef.current;
+      if (!sel) return;
+      gsapCommitMutation(
+        sel,
+        {
+          type: "update-meta",
+          animationId,
+          updates: { easeEach: ease, resetKeyframeEases: true },
+        },
+        { label: "Apply ease to all segments", softReload: true },
+      );
+    },
+    [gsapCommitMutation, domEditSelectionRef],
+  );
+
+  return { handleUpdateSegmentEase, handleUpdateKeyframeEase, handleSetAllKeyframeEases };
+}

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

@@ -66,4 +66,25 @@ describe("KeyframeDiamondContextMenu", () => {
     expect(onDelete).toHaveBeenCalledWith("box", target);
     expect(onMoveToPlayhead).toHaveBeenCalledWith(element, target);
   });
+
+  // An arc waypoint on a two-anchor path cannot be dropped on its own, so the
+  // caller withholds onDelete rather than offering an entry that does nothing.
+  it("hides the single-node delete when no handler is given", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    act(() =>
+      root.render(
+        <KeyframeDiamondContextMenu state={state} onClose={() => {}} onDeleteAll={vi.fn()} />,
+      ),
+    );
+
+    const labels = Array.from(document.body.querySelectorAll("button")).map(
+      (button) => button.textContent,
+    );
+    expect(labels).toEqual(["Delete All Keyframes"]);
+
+    act(() => root.unmount());
+    host.remove();
+  });
 });

package/src/player/components/KeyframeDiamondContextMenu.tsx

@@ -19,7 +19,10 @@ export interface KeyframeDiamondContextMenuState {
 interface KeyframeDiamondContextMenuProps {
   state: KeyframeDiamondContextMenuState;
   onClose: () => void;
-  onDelete: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
+  /** Omitted where this node cannot be deleted on its own (see the arc-waypoint
+   *  floor in removeMotionPathPointInScript): an entry that silently no-ops is
+   *  worse than no entry. */
+  onDelete?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
   onDeleteAll: (element: TimelineElement) => void;
   /** Retime the keyframe to the current playhead, preserving its value + ease. */
   onMoveToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;
@@ -43,7 +46,9 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
   };
 
   const menuWidth = 200;
-  const menuHeight = onMoveToPlayhead ? 100 : 70;
+  // Measured off the rendered rows, so the flip-up test below stays right as
+  // optional entries drop out.
+  const menuHeight = 10 + (1 + (onMoveToPlayhead ? 1 : 0) + (onDelete ? 1 : 0)) * 30;
   const overflowY = state.y + menuHeight - window.innerHeight;
   const adjustedX = state.x + menuWidth > window.innerWidth ? state.x - menuWidth : state.x;
   const adjustedY = overflowY > 0 ? state.y - overflowY - 8 : state.y;
@@ -71,16 +76,18 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
       )}
 
       {/* Delete */}
-      <button
-        type="button"
-        className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-red-400 hover:bg-neutral-800 cursor-pointer text-left"
-        onClick={() => {
-          onDelete(state.elementId, keyframe);
-          onClose();
-        }}
-      >
-        Delete Keyframe
-      </button>
+      {onDelete && (
+        <button
+          type="button"
+          className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-red-400 hover:bg-neutral-800 cursor-pointer text-left"
+          onClick={() => {
+            onDelete(state.elementId, keyframe);
+            onClose();
+          }}
+        >
+          Delete Keyframe
+        </button>
+      )}
 
       <button
         type="button"

package/src/player/components/LayerDisclosureRow.tsx

@@ -22,7 +22,10 @@ export function LayerDisclosureRow({
   /** Same adaptive width the lane rows use: a narrowed header column must not
    *  leave this row hanging over the clips it labels. */
   columnWidth: number;
-  /** Id of the element holding the lanes this row's caret expands. */
+  /** Id of the CANVAS-side element holding the diamond lanes this row's caret
+   *  expands (see TimelinePropertyLanes). The caret also reveals the per-lane
+   *  control rows in this column, but the diamonds are what following the
+   *  reference should land on. */
   lanesId: string;
   onToggleClipExpanded: () => void;
   /** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */

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

@@ -0,0 +1,158 @@
+// @vitest-environment happy-dom
+
+import React, { act, Profiler } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ShortcutsPanel } from "./ShortcutsPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const roots: Root[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) act(() => root.unmount());
+  document.body.innerHTML = "";
+});
+
+function renderPanel(onRender = vi.fn()) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  roots.push(root);
+  act(() => {
+    root.render(
+      <Profiler id="shortcuts-panel" onRender={onRender}>
+        <ShortcutsPanel
+          disabled={false}
+          duration={10}
+          inPoint={null}
+          outPoint={null}
+          setInPoint={vi.fn()}
+          setOutPoint={vi.fn()}
+          onSeek={vi.fn()}
+        />
+      </Profiler>,
+    );
+  });
+
+  const trigger = host.querySelector<HTMLButtonElement>(
+    'button[aria-label="Shortcuts and tools"]',
+  )!;
+  return { host, trigger, onRender };
+}
+
+function pressAndClick(target: HTMLElement): void {
+  target.dispatchEvent(
+    new PointerEvent("pointerdown", { bubbles: true, cancelable: true, button: 0 }),
+  );
+  target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+  target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+  target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }));
+}
+
+function openPanel(trigger: HTMLButtonElement): void {
+  act(() => pressAndClick(trigger));
+  expect(trigger.getAttribute("aria-expanded")).toBe("true");
+}
+
+describe("ShortcutsPanel", () => {
+  it.each(["page", "button", "panel"] as const)(
+    "closes with Escape from the %s-focused position",
+    (focusPosition) => {
+      const { host, trigger } = renderPanel();
+      openPanel(trigger);
+
+      let eventTarget: Document | HTMLElement;
+      if (focusPosition === "page") {
+        document.body.tabIndex = -1;
+        document.body.focus();
+        eventTarget = document;
+        expect(document.activeElement).toBe(document.body);
+      } else if (focusPosition === "button") {
+        trigger.focus();
+        eventTarget = trigger;
+        expect(document.activeElement).toBe(trigger);
+      } else {
+        const panelInput = host.querySelector<HTMLInputElement>('[aria-label="Jump to frame"]')!;
+        panelInput.focus();
+        eventTarget = panelInput;
+        expect(document.activeElement).toBe(panelInput);
+      }
+
+      act(() => {
+        eventTarget.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+      });
+
+      expect(trigger.getAttribute("aria-expanded")).toBe("false");
+      expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+    },
+  );
+
+  it("closes on capture-phase pointerdown even when its default is prevented", () => {
+    const preventDefault = (event: Event) => event.preventDefault();
+    document.addEventListener("pointerdown", preventDefault, true);
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const outside = document.createElement("div");
+    document.body.append(outside);
+    const pointerDown = new PointerEvent("pointerdown", {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+    });
+
+    act(() => outside.dispatchEvent(pointerDown));
+
+    document.removeEventListener("pointerdown", preventDefault, true);
+    expect(pointerDown.defaultPrevented).toBe(true);
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+  });
+
+  it("does not close on a click inside the panel", () => {
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const panelInput = host.querySelector<HTMLInputElement>('[aria-label="Jump to frame"]')!;
+
+    act(() => pressAndClick(panelInput));
+
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    expect(host.querySelector('[aria-label="Jump to frame"]')).not.toBeNull();
+  });
+
+  it("toggles once per trigger click", () => {
+    const { trigger } = renderPanel();
+
+    act(() => pressAndClick(trigger));
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+
+    act(() => pressAndClick(trigger));
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("does not re-render when Escape is pressed while closed", () => {
+    const { trigger, onRender } = renderPanel();
+    expect(onRender).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    });
+
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(onRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("connects the trigger to the dialog with aria-controls", () => {
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const panelId = trigger.getAttribute("aria-controls");
+    const panel = panelId ? host.querySelector<HTMLElement>(`#${CSS.escape(panelId)}`) : null;
+
+    expect(panelId).not.toBeNull();
+    expect(panel?.getAttribute("role")).toBe("dialog");
+    // Non-modal on purpose: focus is not trapped and the editor behind stays
+    // operable, so aria-modal would lie to assistive tech about inertness.
+    expect(panel?.getAttribute("aria-modal")).toBeNull();
+    expect(panel?.id).toBe(panelId);
+  });
+});

package/src/player/components/ShortcutsPanel.tsx

@@ -1,6 +1,7 @@
-import { useState, useCallback, useRef, useEffect, memo } from "react";
+import { useState, useCallback, useId, memo } from "react";
 import { formatTime, frameToSeconds } from "../lib/time";
 import { Tooltip } from "../../components/ui";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 
 const SHORTCUT_SECTIONS = [
   {
@@ -108,20 +109,9 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
 }: ShortcutsPanelProps) {
   const [showShortcuts, setShowShortcuts] = useState(false);
   const [jumpFrame, setJumpFrame] = useState("");
-  const shortcutsPanelRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!showShortcuts) return;
-    const handleMouseDown = (e: MouseEvent) => {
-      if (shortcutsPanelRef.current && !shortcutsPanelRef.current.contains(e.target as Node)) {
-        setShowShortcuts(false);
-      }
-    };
-    document.addEventListener("mousedown", handleMouseDown);
-    return () => {
-      document.removeEventListener("mousedown", handleMouseDown);
-    };
-  }, [showShortcuts]);
+  const shortcutsPanelId = useId();
+  const closeShortcuts = useCallback(() => setShowShortcuts(false), []);
+  const shortcutsPanelRef = useContextMenuDismiss(closeShortcuts);
 
   const commitJumpFrame = useCallback(() => {
     if (disabled) return;
@@ -158,6 +148,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
           }`}
           aria-label="Shortcuts and tools"
           aria-expanded={showShortcuts}
+          aria-controls={shortcutsPanelId}
         >
           <svg
             width="11"
@@ -177,6 +168,11 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
       </Tooltip>
       {showShortcuts && (
         <div
+          id={shortcutsPanelId}
+          role="dialog"
+          // Deliberately NOT aria-modal. This is a non-modal disclosure: focus is
+          // not trapped and the rest of the editor stays operable, so claiming
+          // modality would make assistive tech treat the whole app as inert.
           className="absolute bottom-full right-0 mb-2 z-50 rounded-lg shadow-xl min-w-[220px] overflow-y-auto"
           style={{
             background: "#161618",

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

@@ -293,7 +293,9 @@ describe("Timeline provider boundary", () => {
     // mounted before we query it.
     act(() => {});
 
-    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 0"]');
+    // "1", not "0": the label carries the 1-based display row, while the
+    // callback below still routes by the track's own key.
+    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 1"]');
     expect(button).not.toBeNull();
     if (!button) throw new Error("Expected a track visibility toggle");
 

package/src/player/components/TimelineCanvas.tsx

@@ -20,7 +20,8 @@ import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import type { Rect } from "../../utils/marqueeGeometry";
 import { TimelineClip } from "./TimelineClip";
-import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
+import { TimelineLanes } from "./TimelineLanes";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import { renderClipChildren } from "./timelineClipChildren";
 import { useTimelineRevealClip } from "./useTimelineRevealClip";
 import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";

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

@@ -641,7 +641,7 @@ describe("TimelineClipDiamonds", () => {
     act(() => root.unmount());
   });
 
-  const renderSegmentLane = (lastAmbiguous: boolean) => {
+  const renderSegmentLane = (lastAmbiguous: boolean, clipWidthPx = 200) => {
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -658,9 +658,20 @@ describe("TimelineClipDiamonds", () => {
         <TimelineDiamondLane
           keyframesData={{
             format: "percentage",
-            keyframes: [kf(0), kf(50), kf(100, { easeAmbiguous: lastAmbiguous })],
+            keyframes: [
+              kf(0),
+              kf(50),
+              kf(100, {
+                collidingAnimationTargets: lastAmbiguous
+                  ? [
+                      { animationId: "anim-1", tweenPercentage: 100 },
+                      { animationId: "anim-2", tweenPercentage: 75 },
+                    ]
+                  : undefined,
+              }),
+            ],
           }}
-          clipWidthPx={200}
+          clipWidthPx={clipWidthPx}
           clipHeightPx={48}
           accentColor="#4ba3d2"
           isSelected
@@ -675,15 +686,16 @@ describe("TimelineClipDiamonds", () => {
     return { host, root };
   };
 
-  it("hides the inline ease button on an ambiguous merged segment", () => {
-    // Segments 0->50 and 50->100; the 50->100 segment ends on the ambiguous
-    // keyframe, so its hover/ease-button area is not rendered.
+  it("shows the inline ease button on a colliding merged segment (bulk edit)", () => {
+    // Both segments (0->50, 50->100) render their ease button; the 50->100
+    // segment ends on a keyframe shared by two animations and the button now
+    // bulk-edits both rather than being hidden.
     const { host, root } = renderSegmentLane(true);
-    expect(host.querySelectorAll("[data-keyframe-ease-segment]").length).toBe(1);
+    expect(host.querySelectorAll("[data-keyframe-ease-segment]").length).toBe(2);
     act(() => root.unmount());
   });
 
-  it("keeps the inline ease button on unambiguous merged segments", () => {
+  it("shows the inline ease button on single-animation merged segments", () => {
     const { host, root } = renderSegmentLane(false);
     expect(host.querySelectorAll("[data-keyframe-ease-segment]").length).toBe(2);
     act(() => root.unmount());
@@ -698,6 +710,21 @@ describe("TimelineClipDiamonds", () => {
     expect(segment?.style.pointerEvents).toBe("none");
     expect(ease?.style.pointerEvents).toBe("auto");
     expect(Number(segment?.style.zIndex)).toBeGreaterThan(Number(diamond?.style.zIndex));
+    // Room to spare here, so the button carries the 24x24 WCAG 2.5.8 overlay.
+    expect(ease?.className).toContain("before:h-6");
+    act(() => root.unmount());
+  });
+
+  it("drops the 24x24 ease overlay when the segment is too narrow to hold it", () => {
+    // The segment wrapper outranks the diamonds, so an overlay wider than the
+    // clear span between them would steal their clicks at fit zoom. 40px of clip
+    // across three keyframes leaves well under 24px of clear span per segment.
+    const { host, root } = renderSegmentLane(false, 40);
+    const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]");
+
+    expect(ease).not.toBeNull();
+    expect(ease?.className).not.toContain("before:h-6");
+    expect(ease?.style.width).toBe("16px");
     act(() => root.unmount());
   });
 

package/src/player/components/TimelineClipDiamonds.tsx

@@ -27,6 +27,12 @@ export type { TimelineDiamondKeyframe } from "./timelineDiamondTypes";
 // stops there: at the zoom floor the gap alone left a ~7px target, which is
 // neither hittable nor selectable with any accuracy. Boxes may overlap slightly
 // below this width; each diamond still owns the half-gap around its own centre.
+//
+// Deliberately below the 24px WCAG 2.2 (2.5.8) minimum, under that criterion's
+// own spacing exception: at normal keyframe density the neighbour gap is under
+// 24px, so a 24px floor would make adjacent diamonds' hit boxes OVERLAP — one
+// diamond swallowing its neighbour's clicks is a worse 2.5.8 failure than a
+// small target. Do not "fix" this to 24.
 const KF_MIN_HIT_W = 12;
 
 /** A clip-% is a float division, so a raw tooltip reads `25.032499999999995%`. */
@@ -141,6 +147,10 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
     ? Math.round(clipHeightPx * 0.45)
     : Math.round(LANE_H * DIAMOND_RATIO);
   const centerY = beatsActive ? BEAT_BAND_H + (clipHeightPx - BEAT_BAND_H) / 2 : clipHeightPx / 2;
+  // Hit-box height only — the glyph keeps `marker.visualSize`. 24 is the WCAG 2.2
+  // (2.5.8) minimum and still fits the 28px lane. Beat-strip lanes keep the
+  // shrunken box: 24px there would reach up into the beat strip.
+  const hitHeight = beatsActive ? diamondSize : 24;
   const sorted = keyframesData.keyframes
     .filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT)
     .sort((a, b) => a.percentage - b.percentage);
@@ -412,7 +422,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
               top: centerY,
               transform: "translateY(-50%)",
               width: marker.hitWidth,
-              height: diamondSize,
+              height: hitHeight,
               zIndex: isHighlighted ? 2 : 1,
               pointerEvents: "auto",
               background: "none",