@hyperframes/studio 0.8.97 → 0.8.99

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,

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

@@ -2,7 +2,13 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  elementScroll,
+  observeElementOffset,
+  observeElementRect,
+  Virtualizer,
+} from "@tanstack/react-virtual";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import { createTimelineRowGeometry, RULER_H, TRACKS_TOP_PAD } from "./timelineLayout";
 import { extractTimelineVirtualRowRange, useTimelineVirtualRows } from "./useTimelineVirtualRows";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
@@ -203,4 +209,27 @@ describe("useTimelineVirtualRows", () => {
     expect(rows.some((row) => row.index === 500)).toBe(false);
     act(() => root.unmount());
   });
+
+  // A scroll-end timer left running fires into the torn-down test window ("window is not defined").
+  it("gets no virtualizer change after unmount from a scroll just before it", async () => {
+    const scroll = createScrollElement(0);
+    const onChange = vi.fn();
+    const virtualizer = new Virtualizer<HTMLDivElement, Element>({
+      count: 100,
+      getScrollElement: () => scroll,
+      estimateSize: () => 48,
+      scrollToFn: elementScroll,
+      observeElementRect,
+      observeElementOffset,
+      onChange,
+    });
+    const unmount = virtualizer._didMount();
+    virtualizer._willUpdate();
+    scroll.dispatchEvent(new Event("scroll"));
+    unmount();
+    onChange.mockClear();
+
+    await new Promise((settle) => setTimeout(settle, 200));
+    expect(onChange).not.toHaveBeenCalled();
+  });
 });

package/src/utils/rounding.ts

@@ -3,6 +3,11 @@ export function roundTo3(val: number): number {
   return Math.round(val * 1000) / 1000;
 }
 
+/** Whole CSS px: GSAP parses a -50% translate against the integer offsetWidth/Height. */
+export function roundToLayoutPx(val: number): number {
+  return Math.round(val);
+}
+
 /** Round to 2 decimal places (centisecond precision for timeline values). */
 export function roundToCenti(val: number): number {
   return Math.round(val * 100) / 100;

package/src/utils/sdkEditTransaction.ts

@@ -11,7 +11,7 @@ import {
 
 export type CutoverResult =
   | { status: "declined"; reason: string }
-  | { status: "committed"; version: string }
+  | { status: "committed"; version: string; before: string; after: string }
   | { status: "failed"; error: Error };
 
 export interface SdkSessionPublication {
@@ -143,7 +143,9 @@ export function failedCutover(
 }
 
 /** Only an explicit decline may enter the legacy mutation backend. */
-export function cutoverCommittedOrThrow(result: CutoverResult): boolean {
+export function cutoverCommittedOrThrow(
+  result: CutoverResult,
+): result is Extract<CutoverResult, { status: "committed" }> {
   if (result.status === "failed") throw result.error;
   return result.status === "committed";
 }
@@ -300,7 +302,12 @@ async function commitCandidateEdit(
     });
   }
   if (refreshTarget) refreshCommittedEdit(edit.after, deps, options);
-  return { status: "committed", version: hashContent(edit.after) };
+  return {
+    status: "committed",
+    version: hashContent(edit.after),
+    before: originalContent,
+    after: edit.after,
+  };
 }
 
 export async function persistSdkCandidateMutation(