@hyperframes/studio 0.8.108 → 0.8.109

package/src/player/components/ClipContextMenu.tsx

@@ -1,4 +1,4 @@
-import { memo } from "react";
+import { memo, useLayoutEffect, useState, type RefObject } from "react";
 import { createPortal } from "react-dom";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { canSplitElement } from "../../utils/timelineElementSplit";
@@ -7,6 +7,25 @@ import { useMenuKeyboardNav } from "./menuKeyboardNav";
 import type { TimelineClipMenuItem } from "./TimelineTypes";
 import { ClipMenuToolItems } from "./clipMenuToolItems";
 import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import { ClipMenuLinkItems } from "./clipMenuLinkItems";
+
+const MENU_MARGIN = 8;
+// Empty groups collapse; every non-empty group before the always-present Delete group ends in a divider.
+const GROUP_CLASS = "empty:hidden mb-1 pb-1 border-b border-neutral-700/60";
+
+function useMeasuredHeight(ref: RefObject<HTMLDivElement | null>, anchorKey: string): number {
+  const [height, setHeight] = useState(0);
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    setHeight(node.offsetHeight);
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => setHeight(node.offsetHeight));
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [ref, anchorKey]);
+  return height;
+}
 
 interface ClipContextMenuProps {
   x: number;
@@ -62,7 +81,6 @@ function HostItems({
           )}
         </button>
       ))}
-      <div className="my-1 border-t border-neutral-700/60" />
     </>
   );
 }
@@ -105,16 +123,11 @@ export const ClipContextMenu = memo(function ClipContextMenu({
       ? `Split at ${currentTime.toFixed(2)}s`
       : "Split (move playhead inside clip)";
 
-  const clipboardItemCount = [onCopy, onPaste, onDuplicate].filter(Boolean).length;
-  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;
+  const menuHeight = useMeasuredHeight(menuRef, `${x},${y},${element.key ?? element.id}`);
+  const overflowY = y + menuHeight - window.innerHeight;
+  const adjustedY = overflowY > 0 ? Math.max(MENU_MARGIN, y - overflowY - MENU_MARGIN) : y;
 
   return createPortal(
     <div
@@ -124,9 +137,13 @@ 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 && (
-        <>
+      {hostItems.length > 0 && (
+        <div role="group" aria-label="Host" className={GROUP_CLASS}>
+          <HostItems items={hostItems} onClose={onClose} />
+        </div>
+      )}
+      <div role="group" aria-label="Time" className={GROUP_CLASS}>
+        {splitLabel && (
           <button
             type="button"
             role="menuitem"
@@ -146,92 +163,100 @@ export const ClipContextMenu = memo(function ClipContextMenu({
             <span>{splitLabel}</span>
             <span className="text-neutral-500 text-[10px] ml-3">S</span>
           </button>
+        )}
+        {splitLabel && (
           <ClipMenuToolItems
             group="time"
             element={element}
             currentTime={currentTime}
             onClose={onClose}
           />
-          <div className="my-1 border-t border-neutral-700/60" />
-        </>
-      )}
+        )}
+      </div>
 
-      <ClipMenuAudioItems element={element} onClose={onClose} />
+      <div role="group" aria-label="Sound" className={GROUP_CLASS}>
+        <ClipMenuAudioItems part="normalize" element={element} onClose={onClose} />
+        <ClipMenuToolItems
+          group="sound"
+          element={element}
+          currentTime={currentTime}
+          onClose={onClose}
+        />
+        <ClipMenuLinkItems part="link" element={element} onClose={onClose} />
+        <ClipMenuAudioItems part="duck" element={element} onClose={onClose} />
+      </div>
 
-      {(onCopy || onPaste || onDuplicate) && (
-        <>
-          {onCopy && (
-            <button
-              type="button"
-              role="menuitem"
-              className={itemClass(true)}
-              onClick={() => {
-                onCopy();
-                onClose();
-              }}
-            >
-              <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>
-              <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>
-            </button>
-          )}
-          {onPaste && (
-            <button
-              type="button"
-              role="menuitem"
-              className={itemClass(!!canPaste)}
-              disabled={!canPaste}
-              onClick={() => {
-                if (!canPaste) return;
-                void onPaste();
-                onClose();
-              }}
-            >
-              <span>Paste</span>
-              <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>
-            </button>
-          )}
-          {onDuplicate && (
-            <button
-              type="button"
-              role="menuitem"
-              className={itemClass(true)}
-              onClick={() => {
-                void onDuplicate();
-                onClose();
-              }}
-            >
-              <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>
-              <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>
-            </button>
-          )}
-          <div className="my-1 border-t border-neutral-700/60" />
-        </>
-      )}
+      <div role="group" aria-label="Picture" className={GROUP_CLASS}>
+        <ClipMenuToolItems
+          group="picture"
+          element={element}
+          currentTime={currentTime}
+          onClose={onClose}
+        />
+      </div>
+
+      <div role="group" aria-label="Clipboard" className={GROUP_CLASS}>
+        {onCopy && (
+          <button
+            type="button"
+            role="menuitem"
+            className={itemClass(true)}
+            onClick={() => {
+              onCopy();
+              onClose();
+            }}
+          >
+            <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>
+            <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>
+          </button>
+        )}
+        {onPaste && (
+          <button
+            type="button"
+            role="menuitem"
+            className={itemClass(!!canPaste)}
+            disabled={!canPaste}
+            onClick={() => {
+              if (!canPaste) return;
+              void onPaste();
+              onClose();
+            }}
+          >
+            <span>Paste</span>
+            <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>
+          </button>
+        )}
+        {onDuplicate && (
+          <button
+            type="button"
+            role="menuitem"
+            className={itemClass(true)}
+            onClick={() => {
+              void onDuplicate();
+              onClose();
+            }}
+          >
+            <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>
+            <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>
+          </button>
+        )}
+      </div>
 
-      <ClipMenuToolItems
-        group="sound"
-        element={element}
-        currentTime={currentTime}
-        onClose={onClose}
-      />
-      <ClipMenuToolItems
-        group="picture"
-        element={element}
-        currentTime={currentTime}
-        onClose={onClose}
-      />
-      <button
-        type="button"
-        role="menuitem"
-        className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"
-        onClick={() => {
-          onDelete(element);
-          onClose();
-        }}
-      >
-        <span>Delete</span>
-        <span className="text-neutral-500 text-[10px] ml-3">⌫</span>
-      </button>
+      <div role="group" aria-label="Delete">
+        <button
+          type="button"
+          role="menuitem"
+          className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"
+          onClick={() => {
+            onDelete(element);
+            onClose();
+          }}
+        >
+          <span>Delete</span>
+          <span className="text-neutral-500 text-[10px] ml-3">⌫</span>
+        </button>
+        <ClipMenuLinkItems part="delete" element={element} onClose={onClose} />
+      </div>
     </div>,
     document.body,
   );

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

@@ -0,0 +1,91 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { OutOfSyncBadge } from "./OutOfSyncBadge";
+import { createHappyDomRootHarness } from "./testRootHarness";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const harness = createHappyDomRootHarness();
+const clip = (id: string, tag: string, start: number): TimelineElement => ({
+  id,
+  domId: id,
+  tag,
+  start,
+  duration: 4,
+  track: 0,
+  playbackStart: 0,
+  syncOrigin: "lk-1",
+});
+const video = clip("talk", "video", 1);
+const lateAudio = clip("talk-audio", "audio", 1 + 51 / 30);
+
+afterEach(() =>
+  useLinkedClipPreferences.setState({ syncIndicatorsVisible: true, compositionFps: 30 }),
+);
+
+function render(el: TimelineElement, onLinkEdit = vi.fn()) {
+  usePlayerStore.getState().setElements([video, lateAudio]);
+  const host = document.body.appendChild(document.createElement("div"));
+  act(() =>
+    harness.mount(host).render(
+      <TimelineEditProvider value={{ onLinkEdit }}>
+        <OutOfSyncBadge el={el} />
+      </TimelineEditProvider>,
+    ),
+  );
+  const badge = () => document.querySelector('[data-testid="out-of-sync-badge"]');
+  return { badge, onLinkEdit };
+}
+
+describe("OutOfSyncBadge", () => {
+  it("shows the signed offset on both halves", () => {
+    useLinkedClipPreferences.setState({ compositionFps: 30 });
+    expect(render(lateAudio).badge()?.textContent).toBe("+1:21");
+    document.body.innerHTML = "";
+    expect(render(video).badge()?.textContent).toBe("-1:21");
+  });
+
+  it("hides when the preference is off", () => {
+    useLinkedClipPreferences.setState({ syncIndicatorsVisible: false });
+    expect(render(lateAudio).badge()).toBeNull();
+  });
+
+  it("opens Move / Slip into Sync from a click anywhere on the badge", () => {
+    const { badge, onLinkEdit } = render(lateAudio);
+    act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    const items = Array.from(document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]'));
+    expect(items.map((item) => item.textContent)).toEqual(["Move into Sync", "Slip into Sync"]);
+    act(() => items[0]?.click());
+    expect(onLinkEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "move-into-sync", element: lateAudio, start: 1 }),
+    );
+  });
+
+  it("slips from a right-click, and the click never reaches the clip", () => {
+    const clipClick = vi.fn();
+    document.body.addEventListener("contextmenu", clipClick);
+    const { badge, onLinkEdit } = render(lateAudio);
+    act(() => badge()?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));
+    expect(clipClick).not.toHaveBeenCalled();
+    const slip = document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')[1];
+    act(() => slip?.click());
+    const edit = onLinkEdit.mock.calls[0]?.[0];
+    expect(edit.kind).toBe("slip-into-sync");
+    expect(edit.mediaStart).toBeCloseTo(51 / 30);
+    document.body.removeEventListener("contextmenu", clipClick);
+  });
+
+  it("flips the menu above the pointer near the bottom edge", () => {
+    const { badge } = render(lateAudio);
+    const y = window.innerHeight - 10;
+    act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true, clientY: y })));
+    const menu = document.querySelector<HTMLElement>('[role="menu"]');
+    const top = Number.parseFloat(menu?.style.top ?? "");
+    expect(top).toBeLessThan(y);
+    expect(top).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/player/components/OutOfSyncBadge.tsx

@@ -0,0 +1,119 @@
+import { memo, useCallback, useState, type SyntheticEvent } from "react";
+import { createPortal } from "react-dom";
+import { formatSyncOffset } from "@hyperframes/core/media-link";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { clipSyncState, type ClipSyncState } from "./clipSync";
+import { useMenuKeyboardNav } from "./menuKeyboardNav";
+
+const stop = (e: SyntheticEvent) => e.stopPropagation();
+
+const MENU_ROW =
+  "block w-full px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800 disabled:opacity-40";
+
+function SyncMenu({
+  x,
+  y,
+  el,
+  sync,
+  onClose,
+}: {
+  x: number;
+  y: number;
+  el: TimelineElement;
+  sync: ClipSyncState<TimelineElement>;
+  onClose: () => void;
+}) {
+  const menuRef = useContextMenuDismiss(onClose);
+  useMenuKeyboardNav(menuRef);
+  const { onLinkEdit } = useTimelineEditContextOptional();
+  const { moveStart, slipMediaStart } = sync;
+  const menuWidth = 170;
+  const menuHeight = 66;
+  const left = x + menuWidth > window.innerWidth ? x - menuWidth : x;
+  const top = y + menuHeight > window.innerHeight ? Math.max(0, y - menuHeight) : y;
+  return createPortal(
+    <div
+      ref={menuRef}
+      role="menu"
+      aria-label="Out of sync"
+      className="fixed z-200 min-w-[170px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"
+      style={{ left, top }}
+    >
+      <button
+        type="button"
+        role="menuitem"
+        className={MENU_ROW}
+        disabled={!onLinkEdit || moveStart === null}
+        title={moveStart === null ? "Would move the clip before 0:00" : undefined}
+        onClick={() => {
+          if (moveStart !== null)
+            void onLinkEdit?.({ kind: "move-into-sync", element: el, start: moveStart });
+          onClose();
+        }}
+      >
+        Move into Sync
+      </button>
+      <button
+        type="button"
+        role="menuitem"
+        className={MENU_ROW}
+        disabled={!onLinkEdit || slipMediaStart === null}
+        title={slipMediaStart === null ? "Would slip before the start of the file" : undefined}
+        onClick={() => {
+          if (slipMediaStart !== null) {
+            void onLinkEdit?.({ kind: "slip-into-sync", element: el, mediaStart: slipMediaStart });
+          }
+          onClose();
+        }}
+      >
+        Slip into Sync
+      </button>
+    </div>,
+    document.body,
+  );
+}
+
+/**
+ * Premiere's red out-of-sync number, at the start of each half of a source pair
+ * that drifted. The whole badge opens Move / Slip into Sync (Premiere's own hit
+ * target is a sliver at the badge edge, a known complaint).
+ */
+export const OutOfSyncBadge = memo(function OutOfSyncBadge({ el }: { el: TimelineElement }) {
+  const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);
+  const fps = useLinkedClipPreferences((s) => s.compositionFps);
+  const elements = usePlayerStore((s) => s.elements);
+  const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
+  const closeMenu = useCallback(() => setMenuAt(null), []);
+  const sync = visible ? clipSyncState(el, elements, fps) : null;
+  if (!sync) return null;
+  const label = formatSyncOffset(sync.frames, fps);
+  const partnerName = sync.partner.label || sync.partner.id;
+  const open = (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setMenuAt({ x: e.clientX, y: e.clientY });
+  };
+  return (
+    <>
+      <span
+        role="button"
+        tabIndex={-1}
+        aria-haspopup="menu"
+        aria-label={`Out of sync with ${partnerName} by ${label} frames`}
+        title={`Out of sync with ${partnerName} by ${label} — click for Move or Slip into Sync`}
+        data-testid="out-of-sync-badge"
+        className="absolute bottom-0.5 left-1 z-[7] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"
+        onPointerDown={stop}
+        onDoubleClick={stop}
+        onClick={open}
+        onContextMenu={open}
+      >
+        {label}
+      </span>
+      {menuAt && <SyncMenu x={menuAt.x} y={menuAt.y} el={el} sync={sync} onClose={closeMenu} />}
+    </>
+  );
+});

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

@@ -105,6 +105,23 @@ describe("TimelineClip", () => {
     expect(seen).toEqual([{ fadeIn: 1, fadeOut: 0.5, duration: 4 }, null]);
   });
 
+  it("gives both halves of a link group the same label colour, and unlinked clips none", () => {
+    const colorOf = (element: TimelineElement) => {
+      const { host, root } = renderClip({ element });
+      const clip = host.querySelector<HTMLElement>(".timeline-clip");
+      const color = clip?.getAttribute("data-link-color") ?? null;
+      expect(clip?.style.getPropertyValue("--clip-link-color") || null).toBe(color);
+      act(() => root.unmount());
+      return color;
+    };
+    const base = { start: 0, duration: 2, track: 0 };
+    const video = colorOf({ id: "v", tag: "video", link: "lk-3", ...base });
+    expect(video).not.toBeNull();
+    expect(colorOf({ id: "a", tag: "audio", link: "lk-3", ...base })).toBe(video);
+    expect(colorOf({ id: "b", tag: "audio", link: "lk-4", ...base })).not.toBe(video);
+    expect(colorOf({ id: "c", tag: "audio", ...base })).toBeNull();
+  });
+
   it("renders the clip label above custom content without showing default timecode", () => {
     const { host, root } = renderClip({
       element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 1, track: 0 },

package/src/player/components/TimelineClip.tsx

@@ -12,6 +12,8 @@ import { timelineClipFocusId } from "./timelineNavigationIdentity";
 import { ClipFadesContext, TimelineClipFades, useClipFadeDraft } from "./TimelineClipFades";
 import { rendersWaveform } from "./AudioWaveform";
 import { ClipBadges } from "./ClipBadges";
+import { linkLabelColor } from "./linkLabelColor";
+import { OutOfSyncBadge } from "./OutOfSyncBadge";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -83,6 +85,8 @@ export const TimelineClip = memo(function TimelineClip({
     "--clip-border-active": theme.clipBorderActive,
     "--clip-handle": theme.handleColor,
   } as CSSProperties;
+  const linkColor = linkLabelColor(el.link);
+  if (linkColor) Object.assign(themeVariables, { "--clip-link-color": linkColor });
   const isAudioClip = isAudioTimelineElement(el);
   const hasFades = (isAudioClip || Boolean(el.hasAudio)) && !isGestureActor;
   const fade = useClipFadeDraft(el);
@@ -124,6 +128,7 @@ export const TimelineClip = memo(function TimelineClip({
       data-clip-start={el.start}
       data-clip-end={el.start + el.duration}
       data-clip-hidden={el.hidden ? "true" : undefined}
+      data-link-color={linkColor ?? undefined}
       data-ladder={ladder}
       data-active={isActive ? "" : undefined}
       aria-hidden={isGestureActor ? "true" : undefined}
@@ -206,6 +211,7 @@ export const TimelineClip = memo(function TimelineClip({
       )}
       {showLabel && <span className="timeline-clip__label">{displayLabel}</span>}
       {showLabel && !isGestureActor && <ClipBadges el={el} />}
+      {!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}
       {showDefaultText && (
         <span className="timeline-clip__timecode">
           {startLabel}-{endLabel}s