@hyperframes/studio 0.7.78 → 0.7.79

package/src/hooks/timelineTrackVisibility.ts

@@ -1,6 +1,11 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import {
+  timelineTrackOrder,
+  trackDisplayNumber,
+  trackDisplaySuffix,
+} from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
 import {
@@ -208,12 +213,17 @@ export async function toggleTimelineTrackHidden({
   domEditSaveTimestampRef,
   pendingTimelineEditPathRef,
 }: ToggleTimelineTrackHiddenInput): Promise<string[]> {
+  // `track` is the fractional sort key the callback needs; the history entry is
+  // read by a human, so it gets the display row instead.
+  const suffix = trackDisplaySuffix(
+    trackDisplayNumber(timelineTrackOrder(timelineElements), track),
+  );
   return setElementsHidden({
     projectId,
     activeCompPath,
     elements: timelineElements.filter((element) => element.track === track),
     hidden,
-    label: hidden ? `Hide track ${track}` : `Show track ${track}`,
+    label: hidden ? `Hide track${suffix}` : `Show track${suffix}`,
     previewIframe,
     writeProjectFile,
     recordEdit,

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -14,7 +14,13 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
 import type { SetPatchProps } from "./gsapRuntimePatch";
-import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
+import {
+  selectorFromSelection,
+  computeElementPercentage,
+  isInstantHold,
+  writeTargetSelector,
+  tweenTargetsElement,
+} from "./gsapShared";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
@@ -185,7 +191,9 @@ async function commitStaticSet(
     batch.push(entry);
     byGroup.set(group, batch);
   }
-  const staticWrites = animations.filter((a) => isInstantHold(a) && a.targetSelector === selector);
+  const staticWrites = animations.filter(
+    (a) => isInstantHold(a) && tweenTargetsElement(a.targetSelector, selector, selection.element),
+  );
   // Resolve every group's target BEFORE committing anything, and coalesce
   // groups that land on the SAME write into one commit: the snapshot is captured
   // once, so if two groups resolved to one legacy mixed write, a first
@@ -206,7 +214,7 @@ async function commitStaticSet(
   }
   // Fresh adds don't reshape existing sets, so their ids can't go stale.
   for (const batch of newSetBatches) {
-    await addGlobalStaticSet(selection, batch, selector, commit);
+    await addGlobalStaticSet(selection, batch, commit);
   }
 }
 
@@ -236,18 +244,22 @@ function findGroupOwningStaticWrite(
 async function addGlobalStaticSet(
   selection: DomEditSelection,
   batch: [string, number | string][],
-  selector: string,
   commit: Commit,
 ): Promise<void> {
   const numericProps: SetPatchProps = {};
   for (const [k, v] of batch) {
     if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
   }
+  // A brand-new write, so it must address ONE element: the selection's own
+  // selector is the bare class an id-less element yields, which would hold every
+  // sibling. No one-element form means no write at all (see writeTargetSelector).
+  const target = writeTargetSelector(selection);
+  if (!target) return;
   await commit(
     selection,
     {
       type: "add",
-      targetSelector: selector,
+      targetSelector: target,
       method: "set",
       position: 0,
       properties: Object.fromEntries(batch),
@@ -259,7 +271,7 @@ async function addGlobalStaticSet(
       ...(Object.keys(numericProps).length > 0
         ? {
             instantPatch: {
-              selector,
+              selector: target,
               change: { kind: "global-set" as const, props: numericProps },
             },
           }
@@ -482,7 +494,11 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         // contaminating a foreign-group tween. Mirror an existing keyframed tween's
         // time range so the new group animates over the same span. The 0% baseline is
         // an `_auto` endpoint so it tracks the nearest keyframe as you add more.
-        if (selector) {
+        // A fresh tween, so its target must address ONE element; with no
+        // one-element form the edit is dropped rather than written onto every
+        // class sibling (see writeTargetSelector).
+        const newTweenTarget = writeTargetSelector(selection);
+        if (selector && newTweenTarget) {
           const template = selectedGsapAnimations.find((a) => !!a.keyframes);
           const tStart = template ? (resolveTweenStart(template) ?? 0) : 0;
           const tDur = template ? resolveTweenDuration(template) || 1 : 1;
@@ -503,7 +519,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
             selection,
             {
               type: "add-with-keyframes",
-              targetSelector: selector,
+              targetSelector: newTweenTarget,
               position: roundTo3(tStart),
               duration: roundTo3(tDur),
               keyframes,

package/src/hooks/useEnableKeyframes.test.ts

@@ -466,3 +466,47 @@ describe("useEnableKeyframes — flat tween transaction", () => {
     });
   });
 });
+
+describe("useEnableKeyframes — new tween on a class-only element", () => {
+  it("targets the selected sibling alone, not every element sharing its class", async () => {
+    window.location.hash = "#/project/test-project";
+    usePlayerStore.setState({ currentTime: 1 });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, json: async () => ({ animations: [] }) })),
+    );
+    const scene = document.body.appendChild(document.createElement("div"));
+    scene.id = "scene";
+    scene.innerHTML = '<i class="group"></i>'.repeat(5);
+    const groups = Array.from(scene.querySelectorAll<HTMLElement>(".group"));
+    const commitMutation = vi.fn(async () => undefined);
+    const enable = renderEnableKeyframes({
+      // A bare `.group` here writes `tl.to(".group", …)`, which animates all five
+      // siblings and reads back as all five — one add wiped the timeline.
+      domEditSelection: {
+        selector: ".group",
+        selectorIndex: 3,
+        sourceFile: "index.html",
+        element: groups[3],
+        dataAttributes: { start: "0", duration: "2" },
+      } as unknown as DomEditSelection,
+      selectedGsapAnimations: [],
+      previewIframeRef: {
+        current: {
+          contentWindow: { gsap: { getProperty: () => 7 } },
+        } as unknown as HTMLIFrameElement,
+      },
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: vi.fn(),
+      handleGsapRemoveKeyframe: vi.fn(),
+      commitMutation,
+    });
+
+    await act(async () => enable());
+
+    const mutation = commitMutation.mock.calls[0]?.[0] as { targetSelector: string };
+    expect(mutation?.targetSelector).toBeTruthy();
+    expect(document.querySelectorAll(mutation.targetSelector)).toHaveLength(1);
+    expect(document.querySelector(mutation.targetSelector)).toBe(groups[3]);
+  });
+});

package/src/hooks/useEnableKeyframes.ts

@@ -13,11 +13,12 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
 import {
-  selectorFromSelection,
+  existingTweenTargetSelector,
   computeElementPercentage,
   KEYFRAME_PCT_MATCH,
   isInstantHold,
   resolveEditableTweenDuration,
+  writeTargetSelector,
 } from "./gsapShared";
 import {
   absoluteToPercentage,
@@ -250,7 +251,10 @@ async function extendKeyframedTweenToPlayhead(
   iframe: HTMLIFrameElement | null,
   commitOverrides?: Partial<CommitMutationOptions>,
 ): Promise<void> {
-  const selector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const selector = existingTweenTargetSelector(anim, sel);
   const position = readElementPosition(iframe, sel, anim);
   if (!selector || Object.keys(position).length === 0 || !session.commitMutation) return;
   const extended = buildExtendedKeyframes(anim, currentTime, position, duration);
@@ -335,7 +339,10 @@ export async function promoteSetToKeyframes(
   t: number,
   iframe: HTMLIFrameElement | null,
 ): Promise<void> {
-  const selector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const selector = existingTweenTargetSelector(setAnim, sel);
   const setStart = resolveTweenStart(setAnim) ?? 0;
   if (!selector || !session.commitMutation) return;
   // Playhead at or before the set → there's no forward range to promote into.
@@ -389,7 +396,10 @@ export async function applyArcKeyframeAtPlayhead(
   iframe: HTMLIFrameElement | null,
 ): Promise<void> {
   if (!session.commitMutation) return;
-  const targetSelector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const targetSelector = existingTweenTargetSelector(arcAnim, sel);
   if (!targetSelector) return;
   const start = resolveTweenStart(arcAnim) ?? 0;
   const duration = resolveEditableTweenDuration(arcAnim, sel);
@@ -523,7 +533,10 @@ export function useEnableKeyframes(
         sel.dataAttributes?.duration,
         t,
       );
-      const selector = selectorFromSelection(sel);
+      // A brand-new tween: author it against the one element the user selected.
+      // The bare class selectorFromSelection hands back for an id-less element
+      // animates every sibling sharing the class (see writeTargetSelector).
+      const selector = writeTargetSelector(sel);
 
       if (!selector) {
         session.handleGsapAddAnimation("to");

package/src/hooks/useGestureCommit.ts

@@ -13,7 +13,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isInstantHold, idSelector } from "./gsapShared";
+import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -168,11 +168,24 @@ export function useGestureCommit({
         if (!sortedPcts.includes(0)) sortedPcts.unshift(0);
       }
 
+      // Two different jobs, two different selectors. `selector` is the string an
+      // ALREADY-AUTHORED tween is matched against (and retargeted with, so a
+      // tween aimed at a whole group stays aimed at it). `writeSelector` is what
+      // a NEW tween is authored with: the bare class the id-less case yields here
+      // would record the gesture onto every sibling sharing it.
       const selector = sel.id ? idSelector(sel.id) : sel.selector;
       if (!selector) {
         showToast("Cannot save — element has no selector", "error");
         return;
       }
+      // A recorded gesture becomes a NEW tween, so its target must address one
+      // element; the selection's own selector would record the motion onto
+      // every sibling sharing its class (see writeTargetSelector).
+      const writeSelector = writeTargetSelector(sel);
+      if (!writeSelector) {
+        showToast("Cannot save: element has no unique selector", "error");
+        return;
+      }
       if (liveSession.commitMutation) {
         const recStart = recordingStartTimeRef.current;
         const rawKeyframes = sortedPcts.map((pct) => ({
@@ -186,7 +199,11 @@ export function useGestureCommit({
         );
         const allAnims = liveSession.selectedGsapAnimations ?? [];
         const existingPositionTween = hasPositionProps
-          ? allAnims.find((a) => a.propertyGroup === "position" && a.targetSelector === selector)
+          ? allAnims.find(
+              (a) =>
+                a.propertyGroup === "position" &&
+                tweenTargetsElement(a.targetSelector, selector, sel.element),
+            )
           : undefined;
         if (existingPositionTween) {
           if (isInstantHold(existingPositionTween)) {
@@ -261,7 +278,7 @@ export function useGestureCommit({
                 await liveSession.commitMutation(
                   {
                     type: "add-with-keyframes",
-                    targetSelector: selector,
+                    targetSelector: writeSelector,
                     position: roundTo3(recStart),
                     duration: roundTo3(duration),
                     keyframes: groupKfs,
@@ -287,7 +304,7 @@ export function useGestureCommit({
             await liveSession.commitMutation(
               {
                 type: "add-with-keyframes",
-                targetSelector: selector,
+                targetSelector: writeSelector,
                 position: roundTo3(recStart),
                 duration: roundTo3(duration),
                 keyframes: groupKfs,

package/src/hooks/useGsapScriptCommits.ts

@@ -186,6 +186,9 @@ function syncCommittedGsapMutation({
       targetPath,
       selection.id ?? undefined,
       mutation,
+      // The live preview document is what resolves a class / descendant tween to
+      // the elements it really animates; without it only whole-id selectors do.
+      iframe?.contentDocument,
     );
   }
   refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate);

package/src/hooks/useGsapTweenCache.test.ts

@@ -86,16 +86,24 @@ describe("resolveSelectorElementIds", () => {
     expect(resolveSelectorElementIds(".a, .b", doc).sort()).toEqual(["x", "y"]);
   });
 
-  it("falls back to a leading #id when there is no DOM", () => {
-    expect(resolveSelectorElementIds("#card .label", null)).toEqual(["card"]);
+  // A DOM-less LEADING-id fallback attributed `#card .label` to `#card`, the
+  // ancestor it merely scopes to. Without a DOM there is nothing to resolve the
+  // descendant against, so the honest answer is no element at all.
+  it("resolves nothing for a compound selector when there is no DOM", () => {
+    expect(resolveSelectorElementIds("#card .label", null)).toEqual([]);
     expect(resolveSelectorElementIds(".dot", null)).toEqual([]);
   });
 
+  it("still resolves every whole-id part of a group selector without a DOM", () => {
+    expect(resolveSelectorElementIds("#a, #b", null)).toEqual(["a", "b"]);
+  });
+
   // The `[id="…"]` form is what writers emit for a CSS-unsafe id (digit-leading,
   // dotted). The old local `#id`-only regex read no id at all for those, so they
   // silently dropped out of both DOM-less paths.
   it("falls back to a bracketed id when there is no DOM", () => {
-    expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual(["01-hook"]);
+    expect(resolveSelectorElementIds('[id="01-hook"]', null)).toEqual(["01-hook"]);
+    expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual([]);
   });
 
   it("falls back to a bracketed id when querySelectorAll rejects the selector", () => {

package/src/hooks/useGsapTweenCache.ts

@@ -7,24 +7,17 @@ import {
   pruneKeyframeCacheToFiles,
   writeGsapAnimationsForElement,
 } from "./gsapKeyframeCacheHelpers";
-import { toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import { resolveClipTimingBasis, toAbsoluteTime, toClipPercentage } from "./gsapShared";
 import {
   deduplicateKeyframes,
   isStaticPositionHold,
   synthesizeFlatTweenKeyframes,
 } 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 {

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);
@@ -660,7 +660,7 @@ describe("TimelineClipDiamonds", () => {
             format: "percentage",
             keyframes: [kf(0), kf(50), kf(100, { easeAmbiguous: lastAmbiguous })],
           }}
-          clipWidthPx={200}
+          clipWidthPx={clipWidthPx}
           clipHeightPx={48}
           accentColor="#4ba3d2"
           isSelected
@@ -698,6 +698,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());
   });