@hyperframes/studio 0.8.97 → 0.8.98

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -3,13 +3,8 @@ import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
 
-// A cold parse is the initial-load race: the endpoint is reachable but its parse
-// isn't warm yet (zero total animations). It's worth waiting out (~600ms).
-const COLD_PARSE_RETRIES = 5;
-const COLD_PARSE_DELAY_MS = 120;
 // A hard fetch error (404/403/network/JSON failure → `fetchParsedAnimations`
-// returns null) is NOT a parse-warming race, so it shouldn't burn the full
-// cold-parse budget. One short retry covers a transient blip; beyond that the
+// returns null) gets one short retry for a transient blip; beyond that the
 // endpoint genuinely isn't serving this file, so fall through to "no animation".
 const FETCH_ERROR_RETRIES = 1;
 const FETCH_ERROR_DELAY_MS = 120;
@@ -18,17 +13,14 @@ const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 
 /**
  * Outcome of resolving an element's animations from a single parse result.
- * - `resolved`: a definitive answer (matched animations, or `[]` when the parse
- *   is warm but this element has no animation — create a new one, don't retry).
+ * - `resolved`: a definitive answer. The endpoint parses the file on disk per request,
+ *   so no match, or a file with no tweens at all, means the element has no animation.
  * - `fetch-error`: `fetchParsedAnimations` returned null (HTTP/network/JSON
- *   failure) — retry briefly, not for the full cold-parse budget.
- * - `cold`: the parse came back reachable but with zero total animations — the
- *   initial-load warming race, worth the full cold-parse retry budget.
+ *   failure) — retry briefly.
  */
 export type ElementAnimationsOutcome =
   | { kind: "resolved"; animations: GsapAnimation[] }
-  | { kind: "fetch-error" }
-  | { kind: "cold" };
+  | { kind: "fetch-error" };
 
 export interface GsapAnimationFetchOptions {
   /** Refuse the edit when the parse endpoint is unavailable instead of treating it as no motion. */
@@ -41,26 +33,19 @@ export function gsapSourceFileForSelection(selection: DomEditSelection): string
   return selection.sourceFile || "index.html";
 }
 
-/**
- * Classify a parse result for one element. Differentiates a hard fetch failure
- * (`parsed === null`) from a warm-but-empty cold parse (`animations.length === 0`)
- * so the caller can apply the right retry budget to each.
- */
+/** Classify a parse result for one element: a hard fetch failure (`parsed === null`) or its animations. */
 export function selectElementAnimationsOrRetry(
   parsed: Pick<ParsedGsap, "animations"> | null,
   target: { id: string | null; selector: string | null },
   element?: Element | null,
 ): ElementAnimationsOutcome {
   if (!parsed) return { kind: "fetch-error" };
-  if (parsed.animations.length === 0) return { kind: "cold" };
   return {
     kind: "resolved",
     animations: getAnimationsForElement(parsed.animations, target, element),
   };
 }
 
-// Retry policy deliberately distinguishes cold parses from hard fetch errors.
-// fallow-ignore-next-line complexity
 async function fetchElementAnimationsWithRetry(
   projectId: string,
   gsapSourceFile: string,
@@ -69,25 +54,16 @@ async function fetchElementAnimationsWithRetry(
   failOnFetchError: boolean,
   fresh: boolean,
 ): Promise<GsapAnimation[]> {
-  let coldAttempts = 0;
-  let errorAttempts = 0;
-  for (;;) {
+  for (let errorAttempts = 0; ; errorAttempts++) {
     const parsed = await fetchParsedAnimations(projectId, gsapSourceFile, { fresh });
     fresh = false;
     const outcome = selectElementAnimationsOrRetry(parsed, target, element);
     if (outcome.kind === "resolved") return outcome.animations;
-    if (outcome.kind === "fetch-error") {
-      if (errorAttempts >= FETCH_ERROR_RETRIES) {
-        if (failOnFetchError) throw new Error("GSAP animation ownership could not be verified");
-        return [];
-      }
-      errorAttempts++;
-      await delay(FETCH_ERROR_DELAY_MS);
-      continue;
+    if (errorAttempts >= FETCH_ERROR_RETRIES) {
+      if (failOnFetchError) throw new Error("GSAP animation ownership could not be verified");
+      return [];
     }
-    if (coldAttempts >= COLD_PARSE_RETRIES) return [];
-    coldAttempts++;
-    await delay(COLD_PARSE_DELAY_MS);
+    await delay(FETCH_ERROR_DELAY_MS);
   }
 }
 

package/src/hooks/useGsapTweenCache.element.test.tsx

@@ -16,9 +16,10 @@ const dotTween = {
 } as GsapAnimation;
 vi.mock("./keyframeCacheAstLoad", async (importOriginal) => ({
   ...(await importOriginal<typeof import("./keyframeCacheAstLoad")>()),
-  fetchParsedAnimations: async () => ({ animations: [dotTween] }),
+  fetchParsedAnimations: vi.fn(async () => ({ animations: [dotTween] })),
 }));
 const { useGsapAnimationsForElement } = await import("./useGsapTweenCache");
+const { fetchParsedAnimations } = await import("./keyframeCacheAstLoad");
 
 it("attributes a class tween by the selected element, not an earlier same-id copy in a sub-composition", async () => {
   document.body.innerHTML =
@@ -37,3 +38,24 @@ it("attributes a class tween by the selected element, not an earlier same-id cop
   expect(animations.map((animation) => animation.id)).toEqual(["dots"]);
   act(() => root.unmount());
 });
+
+it("reads a file with no tweens once: the parse endpoint answers from the file on disk", async () => {
+  vi.useFakeTimers();
+  vi.mocked(fetchParsedAnimations)
+    .mockClear()
+    .mockResolvedValue({ animations: [] } as never);
+  const selection = { id: "card", sourceFile: "index.html" } as DomEditSelection;
+  function Harness() {
+    useGsapAnimationsForElement("p", "index.html", selection, 0);
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  try {
+    await act(async () => {});
+    await act(async () => vi.advanceTimersByTime(2000));
+    expect(fetchParsedAnimations).toHaveBeenCalledTimes(1);
+  } finally {
+    act(() => root.unmount());
+    vi.useRealTimers();
+  }
+});

package/src/hooks/useGsapTweenCache.ts

@@ -41,7 +41,6 @@ export function useGsapAnimationsForElement(
   const [multipleTimelines, setMultipleTimelines] = useState(false);
   const [unsupportedTimelinePattern, setUnsupportedTimelinePattern] = useState(false);
   const lastFetchKeyRef = useRef("");
-  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   // Re-run the per-element cache populate when sub-comp DOM children appear, so a
   // sub-comp element gets its host-relative keyframe percentages (not elDuration=1).
   const domClipChildrenKey = usePlayerStore((s) =>
@@ -54,11 +53,6 @@ export function useGsapAnimationsForElement(
     if (fetchKey === lastFetchKeyRef.current) return;
     lastFetchKeyRef.current = fetchKey;
 
-    if (retryTimerRef.current) {
-      clearTimeout(retryTimerRef.current);
-      retryTimerRef.current = null;
-    }
-
     if (!projectId) {
       setAllAnimations([]);
       setMultipleTimelines(false);
@@ -80,28 +74,10 @@ export function useGsapAnimationsForElement(
       setAllAnimations(parsed.animations);
       setMultipleTimelines(parsed.multipleTimelines === true);
       setUnsupportedTimelinePattern(parsed.unsupportedTimelinePattern === true);
-
-      // Retry once if initial fetch returned 0 animations — handles
-      // cold-load race where the sourceFile isn't resolved yet.
-      if (parsed.animations.length === 0 && targetKey) {
-        retryTimerRef.current = setTimeout(() => {
-          if (cancelled) return;
-          fetchParsedAnimations(projectId, sourceFile).then((retryParsed) => {
-            if (cancelled) return;
-            if (retryParsed && retryParsed.animations.length > 0) {
-              setAllAnimations(retryParsed.animations);
-            }
-          });
-        }, 800);
-      }
     });
 
     return () => {
       cancelled = true;
-      if (retryTimerRef.current) {
-        clearTimeout(retryTimerRef.current);
-        retryTimerRef.current = null;
-      }
     };
   }, [projectId, sourceFile, version, target?.id, target?.selector]);
 

package/src/index.ts

@@ -62,7 +62,10 @@ export type { ImageThumbnailProps } from "./player/components/ImageThumbnail";
 export { useRenderClipContent } from "./hooks/useRenderClipContent";
 export type { UseRenderClipContentOptions } from "./hooks/useRenderClipContent";
 export type { ThumbnailPriority } from "./player/lib/thumbnailScheduler";
-export type { TimelineClipRenderContext } from "./player/components/TimelineTypes";
+export type {
+  TimelineClipMenuItem,
+  TimelineClipRenderContext,
+} from "./player/components/TimelineTypes";
 
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

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

@@ -0,0 +1,182 @@
+// @vitest-environment happy-dom
+import { act, StrictMode, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { ClipContextMenu } from "./ClipContextMenu";
+import type { TimelineClipMenuItem } from "./TimelineTypes";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const element = {
+  id: "title",
+  tag: "div",
+  start: 0,
+  duration: 2,
+  track: 0,
+} as unknown as TimelineElement;
+
+function renderMenu(hostItems: readonly TimelineClipMenuItem[], onClose = vi.fn()) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  act(() =>
+    root.render(
+      <ClipContextMenu
+        x={10}
+        y={10}
+        element={element}
+        currentTime={1}
+        onClose={onClose}
+        onSplit={vi.fn()}
+        onDelete={vi.fn()}
+        onCopy={() => true}
+        hostItems={hostItems}
+      />,
+    ),
+  );
+  const items = () =>
+    Array.from(document.body.querySelectorAll<HTMLButtonElement>("[role=menuitem]"));
+  return { items, unmount: () => act(() => root.unmount()) };
+}
+
+describe("ClipContextMenu host items", () => {
+  it("lists the host's items first, with their icon and shortcut, and closes on a pick", () => {
+    const onSelect = vi.fn();
+    const onClose = vi.fn();
+    const { items, unmount } = renderMenu(
+      [{ id: "ask", label: "Ask", icon: <svg data-testid="ask-icon" />, shortcut: "A", onSelect }],
+      onClose,
+    );
+    expect(items().map((item) => item.textContent)).toEqual(["AskA", "Copy⌘C", "Delete⌫"]);
+    expect(items()[0]!.querySelector("[data-testid=ask-icon]")).not.toBeNull();
+    act(() => items()[0]!.click());
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(onClose).toHaveBeenCalledOnce();
+    unmount();
+  });
+
+  it("counts host rows and their divider when keeping the menu inside the window", () => {
+    const innerHeight = Object.getOwnPropertyDescriptor(window, "innerHeight");
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 600 });
+    try {
+      const host = document.createElement("div");
+      document.body.appendChild(host);
+      const root = createRoot(host);
+      const ask = { label: "Ask", onSelect: vi.fn() };
+      act(() =>
+        root.render(
+          <ClipContextMenu
+            x={10}
+            y={550}
+            element={element}
+            currentTime={1}
+            onClose={vi.fn()}
+            onSplit={vi.fn()}
+            onDelete={vi.fn()}
+            onCopy={() => true}
+            hostItems={[
+              { id: "a", ...ask },
+              { id: "b", ...ask },
+            ]}
+          />,
+        ),
+      );
+      // Four 30 px rows, two 9 px dividers and 8 px of padding end 96 px below the window.
+      expect(document.body.querySelector<HTMLElement>("[role=menu]")!.style.top).toBe("446px");
+      act(() => root.unmount());
+    } finally {
+      if (innerHeight) Object.defineProperty(window, "innerHeight", innerHeight);
+    }
+  });
+
+  it("keeps a disabled host item inert", () => {
+    const onSelect = vi.fn();
+    const { items, unmount } = renderMenu([{ id: "ask", label: "Ask", disabled: true, onSelect }]);
+    expect(items()[0]!.disabled).toBe(true);
+    act(() => items()[0]!.click());
+    expect(onSelect).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("shows only Studio's items when the host adds none", () => {
+    const { items, unmount } = renderMenu([]);
+    expect(items().map((item) => item.textContent)).toEqual(["Copy⌘C", "Delete⌫"]);
+    expect(document.body.querySelectorAll(".border-t")).toHaveLength(1);
+    unmount();
+  });
+});
+
+/** A clip button that opens the real menu, whose Ask moves the focus the way `focus` says. */
+function FocusHost({ focus }: { focus: "existing" | "mounted" }) {
+  const [open, setOpen] = useState(false);
+  const [asked, setAsked] = useState(false);
+  const existing = useRef<HTMLInputElement>(null);
+  const ask = () => (focus === "existing" ? existing.current!.focus() : setAsked(true));
+  return (
+    <>
+      <button type="button" data-testid="clip" onClick={() => setOpen(true)} />
+      <input ref={existing} data-testid="existing" />
+      {asked && <input data-testid="mounted" autoFocus />}
+      {open && (
+        <ClipContextMenu
+          x={10}
+          y={10}
+          element={element}
+          currentTime={1}
+          onClose={() => setOpen(false)}
+          onSplit={vi.fn()}
+          onDelete={vi.fn()}
+          hostItems={[{ id: "ask", label: "Ask", onSelect: ask }]}
+        />
+      )}
+    </>
+  );
+}
+
+function openFrom(focus: "existing" | "mounted") {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  // StrictMode runs the menu's effect cleanup once while it is still mounted, as Studio's dev build does.
+  act(() =>
+    root.render(
+      <StrictMode>
+        <FocusHost focus={focus} />
+      </StrictMode>,
+    ),
+  );
+  const clip = document.body.querySelector<HTMLButtonElement>("[data-testid=clip]")!;
+  clip.focus();
+  act(() => clip.click());
+  const menuItem = () => document.body.querySelector<HTMLButtonElement>("[role=menuitem]");
+  expect(document.activeElement).toBe(menuItem());
+  return { menuItem, unmount: () => act(() => root.unmount()) };
+}
+
+const focusedId = () => (document.activeElement as HTMLElement | null)?.dataset.testid;
+
+describe("ClipContextMenu focus on close", () => {
+  it.each(["existing", "mounted"] as const)(
+    "leaves the focus where a host item put it (%s field)",
+    (focus) => {
+      const { menuItem, unmount } = openFrom(focus);
+      act(() => menuItem()!.click());
+      expect(menuItem()).toBeNull();
+      expect(focusedId()).toBe(focus);
+      unmount();
+    },
+  );
+
+  it("gives the focus back to the clip when the menu closes without moving it", () => {
+    const { menuItem, unmount } = openFrom("existing");
+    act(() => document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
+    expect(menuItem()).toBeNull();
+    expect(focusedId()).toBe("clip");
+    unmount();
+  });
+});

package/src/player/components/ClipContextMenu.tsx

@@ -4,6 +4,7 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { canSplitElement } from "../../utils/timelineElementSplit";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 import { useMenuKeyboardNav } from "./menuKeyboardNav";
+import type { TimelineClipMenuItem } from "./TimelineTypes";
 
 interface ClipContextMenuProps {
   x: number;
@@ -17,6 +18,51 @@ interface ClipContextMenuProps {
   onPaste?: () => Promise<void>;
   onDuplicate?: () => Promise<boolean>;
   canPaste?: boolean;
+  hostItems?: readonly TimelineClipMenuItem[] | undefined;
+}
+
+// Same enabled/disabled menu-item pattern as the sibling TrackGapContextMenu.
+const itemClass = (enabled: boolean) =>
+  `w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none${
+    enabled
+      ? " focus-visible:bg-neutral-800 text-neutral-300 hover:bg-neutral-800 cursor-pointer"
+      : " text-neutral-600 cursor-not-allowed"
+  }`;
+
+/** The host's items, above Studio's. A pick closes the menu; focus the item moves stays where it went. */
+function HostItems({
+  items,
+  onClose,
+}: {
+  items: readonly TimelineClipMenuItem[];
+  onClose: () => void;
+}) {
+  return (
+    <>
+      {items.map((item) => (
+        <button
+          key={item.id}
+          type="button"
+          role="menuitem"
+          className={itemClass(!item.disabled)}
+          disabled={item.disabled}
+          onClick={() => {
+            onClose();
+            item.onSelect();
+          }}
+        >
+          <span className="flex items-center gap-2">
+            {item.icon}
+            {item.label}
+          </span>
+          {item.shortcut && (
+            <span className="text-neutral-500 text-[10px] ml-3">{item.shortcut}</span>
+          )}
+        </button>
+      ))}
+      <div className="my-1 border-t border-neutral-700/60" />
+    </>
+  );
 }
 
 // A menu with many independently gated items (Split/Delete/Copy/Paste/Duplicate).
@@ -33,6 +79,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
   onPaste,
   onDuplicate,
   canPaste,
+  hostItems = [],
 }: ClipContextMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
   useMenuKeyboardNav(menuRef);
@@ -57,22 +104,16 @@ export const ClipContextMenu = memo(function ClipContextMenu({
       : "Split (move playhead inside clip)";
 
   const clipboardItemCount = [onCopy, onPaste, onDuplicate].filter(Boolean).length;
-  const rowCount = (splitLabel ? 1 : 0) + clipboardItemCount + 1; // + Delete, always present
-  const dividerCount = (splitLabel ? 1 : 0) + (clipboardItemCount > 0 ? 1 : 0);
+  const hostRows = hostItems.length;
+  const rowCount = hostRows + (splitLabel ? 1 : 0) + clipboardItemCount + 1; // + Delete, always present
+  const dividerCount =
+    (hostRows > 0 ? 1 : 0) + (splitLabel ? 1 : 0) + (clipboardItemCount > 0 ? 1 : 0);
   const menuWidth = 200;
   const menuHeight = rowCount * 30 + dividerCount * 9 + 8;
   const overflowY = y + menuHeight - window.innerHeight;
   const adjustedX = x + menuWidth > window.innerWidth ? x - menuWidth : x;
   const adjustedY = overflowY > 0 ? y - overflowY - 8 : y;
 
-  // Same enabled/disabled menu-item pattern as the sibling TrackGapContextMenu.
-  const itemClass = (enabled: boolean) =>
-    `w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none${
-      enabled
-        ? " focus-visible:bg-neutral-800 text-neutral-300 hover:bg-neutral-800 cursor-pointer"
-        : " text-neutral-600 cursor-not-allowed"
-    }`;
-
   return createPortal(
     <div
       ref={menuRef}
@@ -81,6 +122,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
       className="fixed z-200 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
       style={{ left: adjustedX, top: adjustedY }}
     >
+      {hostRows > 0 && <HostItems items={hostItems} onClose={onClose} />}
       {splitLabel && (
         <>
           <button

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

@@ -71,11 +71,12 @@ describe("resolveTimelineContextElement", () => {
   });
 });
 
-function renderKeyframeOverlay(options: {
+function renderOverlay(options: {
   capturedElement: TimelineElement;
   currentElement: TimelineElement;
   setKfContextMenu?: ReturnType<typeof vi.fn>;
   onDeleteAllKeyframes?: ReturnType<typeof vi.fn>;
+  overlays?: Partial<TimelineOverlaysState>;
 }) {
   const container = document.createElement("div");
   document.body.appendChild(container);
@@ -117,6 +118,7 @@ function renderKeyframeOverlay(options: {
     onCloseTrackGap: vi.fn(),
     onCloseAllTrackGaps: vi.fn(),
     onHoverGapAction: vi.fn(),
+    ...options.overlays,
   } satisfies TimelineOverlaysState;
   const contextValue = {
     state: {
@@ -151,22 +153,24 @@ function renderKeyframeOverlay(options: {
     );
   }
 
+  const render = () =>
+    root.render(
+      createElement(TestTimelineContext, { value: contextValue }, createElement(TimelineOverlays)),
+    );
   act(() => {
     usePlayerStore.setState({
       selectedElementId: options.capturedElement.key ?? options.capturedElement.id,
       timelineSessionEpoch: 2,
     });
-    root.render(
-      createElement(TestTimelineContext, { value: contextValue }, createElement(TimelineOverlays)),
-    );
+    render();
   });
-  return { setKfContextMenu, onDeleteAllKeyframes };
+  return { setKfContextMenu, onDeleteAllKeyframes, rerender: () => act(render) };
 }
 
 describe("TimelineOverlays context lifecycle", () => {
   it("dismisses a keyframe menu when its selected target becomes stale", () => {
     const setKfContextMenu = vi.fn();
-    renderKeyframeOverlay({
+    renderOverlay({
       capturedElement: captured,
       currentElement: captured,
       setKfContextMenu,
@@ -180,7 +184,7 @@ describe("TimelineOverlays context lifecycle", () => {
   it("dispatches a menu action with the current model element", () => {
     const current = { ...captured, start: 4, track: 7 };
     const onDeleteAllKeyframes = vi.fn();
-    renderKeyframeOverlay({
+    renderOverlay({
       capturedElement: captured,
       currentElement: current,
       onDeleteAllKeyframes,
@@ -193,4 +197,23 @@ describe("TimelineOverlays context lifecycle", () => {
 
     expect(onDeleteAllKeyframes).toHaveBeenCalledExactlyOnceWith(current, "child-position");
   });
+
+  it("builds the host's clip menu items once for the current model element and lists them first", () => {
+    const current = { ...captured, start: 4, track: 7 };
+    const clipMenuItems = vi.fn(() => [{ id: "ask", label: "Ask", onSelect: vi.fn() }]);
+    const { rerender } = renderOverlay({
+      capturedElement: captured,
+      currentElement: current,
+      overlays: {
+        kfContextMenu: null,
+        clipContextMenu: { x: 10, y: 10, sessionEpoch: 2, element: captured },
+        clipMenuItems,
+      },
+    });
+
+    rerender();
+
+    expect(clipMenuItems).toHaveBeenCalledExactlyOnceWith(current);
+    expect(document.body.querySelector('[role="menuitem"]')?.textContent).toBe("Ask");
+  });
 });

package/src/player/components/TimelineOverlays.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
 import type { TimelineElement } from "../store/playerStore";
 import { EditPopover } from "./EditModal";
 import { KeyframeDiamondContextMenu } from "./KeyframeDiamondContextMenu";
@@ -152,6 +152,11 @@ export function TimelineClipMenuOverlay() {
   useEffect(() => {
     if (clipContextMenu && !element) setClipContextMenu(null);
   }, [element, clipContextMenu, setClipContextMenu]);
+  const { clipMenuItems } = overlay;
+  const hostItems = useMemo(
+    () => (element ? clipMenuItems?.(element) : undefined),
+    [clipMenuItems, element],
+  );
   if (!clipContextMenu || !element) return null;
   const readCurrentElement = () =>
     resolveTimelineContextElement({
@@ -183,6 +188,7 @@ export function TimelineClipMenuOverlay() {
       onPaste={overlay.onPasteClip}
       onDuplicate={overlay.onDuplicateClip}
       canPaste={overlay.canPasteClip?.() ?? false}
+      hostItems={hostItems}
     />
   );
 }

package/src/player/components/TimelineProvider.tsx

@@ -111,6 +111,7 @@ export interface TimelineOverlaysState {
   onPasteClip?: () => Promise<void>;
   onDuplicateClip?: () => Promise<boolean>;
   canPasteClip?: () => boolean;
+  clipMenuItems?: TimelineProps["clipMenuItems"];
   gapContextMenu: TrackGapContextMenuState | null;
   onDismissGapContextMenu: () => void;
   onCloseTrackGap: () => void;

package/src/player/components/TimelineTypes.ts

@@ -12,6 +12,15 @@ export interface TimelineClipRenderContext {
   rich: boolean;
 }
 
+export interface TimelineClipMenuItem {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  shortcut?: string;
+  disabled?: boolean;
+  onSelect: () => void;
+}
+
 export interface TimelineProps
   extends TimelineDropCallbacks, TimelineEditOverrides, TimelineStackingSyncProps {
   /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
@@ -33,6 +42,7 @@ export interface TimelineProps
   onPasteClip?: () => Promise<void>;
   onDuplicateClip?: () => Promise<boolean>;
   canPasteClip?: () => boolean;
+  clipMenuItems?: (element: TimelineElement) => readonly TimelineClipMenuItem[];
   theme?: Partial<TimelineTheme>;
   showAudioEffects?: boolean;
   showKeyframes?: boolean;

package/src/player/components/menuKeyboardNav.ts

@@ -2,10 +2,10 @@ import { useEffect, type RefObject } from "react";
 
 /**
  * APG menu keyboard basics for the timeline context menus: focuses the first
- * menu item on open, moves focus with ArrowUp/ArrowDown/Home/End, and restores
- * focus to the previously focused element when the menu unmounts. Pair with
- * `role="menu"` on the container and `role="menuitem"` on the buttons
- * (dismiss/Escape handling stays in useContextMenuDismiss).
+ * menu item on open, moves focus with ArrowUp/ArrowDown/Home/End, and gives
+ * focus back to the element that held it at open, on unmount, unless an item moved
+ * it elsewhere. Pair with `role="menu"` on the container and `role="menuitem"`
+ * on the buttons (dismiss/Escape handling stays in useContextMenuDismiss).
  */
 export function useMenuKeyboardNav(menuRef: RefObject<HTMLDivElement | null>): void {
   useEffect(() => {
@@ -39,7 +39,14 @@ export function useMenuKeyboardNav(menuRef: RefObject<HTMLDivElement | null>): v
 
     return () => {
       menu.removeEventListener("keydown", onKeyDown);
-      if (previouslyFocused instanceof HTMLElement && document.contains(previouslyFocused)) {
+      const active = document.activeElement;
+      const focusLeftWithMenu =
+        active === null || active === document.body || menu.contains(active);
+      if (
+        focusLeftWithMenu &&
+        previouslyFocused instanceof HTMLElement &&
+        document.contains(previouslyFocused)
+      ) {
         previouslyFocused.focus();
       }
     };

package/src/player/components/useTimelineProviderState.tsx

@@ -71,6 +71,7 @@ export function useTimelineProviderState({
   onPasteClip,
   onDuplicateClip,
   canPasteClip,
+  clipMenuItems,
   theme: themeOverrides,
   showAudioEffects = true,
   showKeyframes = true,
@@ -379,6 +380,7 @@ export function useTimelineProviderState({
     onPasteClip,
     onDuplicateClip,
     canPasteClip,
+    clipMenuItems,
     onSelectElement,
     selectedElementId,
     setRangeSelectionRef,