@hyperframes/studio 0.8.81 → 0.8.83

package/src/player/components/timelineGroupEditing.ts

@@ -1,3 +1,4 @@
+import { clampPlaybackRate } from "@hyperframes/parsers/media-duration";
 import { roundToCenti } from "../../utils/rounding";
 import type { TimelineElement } from "../store/playerStore";
 import { getTimelineEditCapabilities } from "./timelineEditCapabilities";
@@ -19,13 +20,17 @@ function ceilTimelineTime(value: number): number {
   return Math.ceil((value - SAVED_MEDIA_OFFSET_TOLERANCE) * 100) / 100;
 }
 
+function floorTimelineTime(value: number): number {
+  return Math.floor((value + SAVED_MEDIA_OFFSET_TOLERANCE) * 100) / 100;
+}
+
 export function resolveTimelineMinDuration(minDuration?: number): number {
   return Math.max(ABSOLUTE_TIMELINE_MIN_DURATION, minDuration ?? DEFAULT_TIMELINE_MIN_DURATION);
 }
 
 /** Playback rate never drops to zero (would make media-in-point math divide by ~0). */
-function resolveTimelinePlaybackRate(rate?: number): number {
-  return Math.max(0.1, rate ?? 1);
+export function resolveTimelinePlaybackRate(rate?: number): number {
+  return clampPlaybackRate(rate ?? 1);
 }
 
 interface TimelineStartTrimClip {
@@ -38,8 +43,8 @@ interface TimelineStartTrimClip {
 /**
  * Delta bounds for trimming a clip's START edge (shared by single-clip and group
  * resize). Left-bounded by how far the start can move toward `minStart` and by the
- * media in-point (`playbackStart / playbackRate`); right-bounded by `minDuration`.
- * Returned deltas are unrounded; applyClipStartTrimDelta does the rounding.
+ * media in-point (`playbackStart / playbackRate`); right-bounded by `minDuration`, the start
+ * floored onto the centisecond grid. Otherwise unrounded; applyClipStartTrimDelta rounds.
  */
 export function clipStartTrimDeltaBounds(
   clip: TimelineStartTrimClip,
@@ -51,7 +56,7 @@ export function clipStartTrimDeltaBounds(
     clip.playbackStart != null ? clip.playbackStart / playbackRate : Number.POSITIVE_INFINITY;
   return {
     minDelta: -Math.min(clip.start - minStart, maxLeftExtensionFromMedia),
-    maxDelta: clip.duration - minDuration,
+    maxDelta: floorTimelineTime(clip.start + clip.duration - minDuration) - clip.start,
   };
 }
 
@@ -137,7 +142,9 @@ export function clampTimelineGroupResizeDelta(
   const bounds = members.map((member) => clipStartTrimDeltaBounds(member, 0, minDuration));
   const minDelta = ceilTimelineTime(Math.max(...bounds.map((b) => b.minDelta)));
   const maxDelta = Math.min(...bounds.map((b) => b.maxDelta));
-  return roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
+  const delta = roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
+  const roundedPastTightestMember = delta > maxDelta + SAVED_MEDIA_OFFSET_TOLERANCE;
+  return roundedPastTightestMember ? maxDelta - SAVED_MEDIA_OFFSET_TOLERANCE : delta;
 }
 
 export function resolveTimelineGroupResize(

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

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
+
+const x = (transform: string) => Number(/translateX\(([-\d.e]+)px\)/.exec(transform)?.[1]);
+
+describe("getTimelinePlayheadTransform", () => {
+  it("keeps fractional pixels while playing, so slow motion does not stair-step", () => {
+    // Fit zoom on a two-minute film is about 13.3px a second: 120 frames of one second of playback.
+    const frames = Array.from({ length: 121 }, (_, i) => i / 120);
+    const playing = new Set(frames.map((t) => getTimelinePlayheadTransform(t, 13.3, 80, false, 1)));
+    const resting = new Set(frames.map((t) => getTimelinePlayheadTransform(t, 13.3, 80, true, 1)));
+    expect(playing.size).toBe(121);
+    expect(resting.size).toBeLessThan(20);
+  });
+
+  it("at rest puts the line on the device pixel layout gives its ruler tick", () => {
+    // The 1px line sits 4px into the 9px wrapper; the tick is laid out at t * pps - 0.5 and rounded by layout.
+    for (const dpr of [1, 1.5, 2]) {
+      for (let i = 0; i <= 400; i += 1) {
+        const t = i * 0.0137;
+        const wrapper = x(getTimelinePlayheadTransform(t, 13.3, 80, true, dpr));
+        const lineDevicePx = Math.round((wrapper + 4) * dpr);
+        const tickDevicePx = Math.round((80 + t * 13.3 - 0.5) * dpr);
+        expect(lineDevicePx, `t=${t} dpr=${dpr}`).toBe(tickDevicePx);
+      }
+    }
+  });
+
+  it("at time zero at 1x lands the line on the tick's column", () => {
+    expect(getTimelinePlayheadTransform(0, 100, 80, true, 1)).toBe("translateX(76px)");
+    expect(Math.round(80 - 0.5)).toBe(76 + 4);
+  });
+});

package/src/player/components/timelinePlayheadTransform.ts

@@ -0,0 +1,17 @@
+import { getTimelinePlayheadLeft } from "./timelineLayout";
+
+/**
+ * Moves the playhead by transform, with no relayout. Playing, it keeps fractional pixels so slow motion stays
+ * smooth; at rest it rounds to device pixels the way layout rounds the ruler ticks, so the line sits on its tick.
+ */
+export function getTimelinePlayheadTransform(
+  time: number,
+  pixelsPerSecond: number,
+  contentOrigin: number,
+  atRest: boolean,
+  devicePixelRatio = globalThis.devicePixelRatio || 1,
+): string {
+  const left = getTimelinePlayheadLeft(time, pixelsPerSecond, contentOrigin);
+  if (!atRest) return `translateX(${left}px)`;
+  return `translateX(${Math.round(left * devicePixelRatio) / devicePixelRatio}px)`;
+}

package/src/player/components/timelinePointerRelease.ts

@@ -0,0 +1,4 @@
+export function releasedOutsideWindow(point: Pick<MouseEvent, "clientX" | "clientY">): boolean {
+  const { clientX: x, clientY: y } = point;
+  return x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight;
+}

package/src/player/components/useTimelinePlayhead.ts

@@ -4,12 +4,12 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   getTimelinePlaybackFollowScrollLeft,
-  getTimelinePlayheadLeft,
   getTimelineScrubTime,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
 } from "./timelineLayout";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
 interface UseTimelinePlayheadInput {
@@ -92,7 +92,12 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current, contentOrigin)}px`;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
+        time,
+        ppsRef.current,
+        contentOrigin,
+        !usePlayerStore.getState().isPlaying,
+      );
     },
     [playheadRef, durationRef, ppsRef, contentOrigin],
   );
@@ -122,14 +127,24 @@ export function useTimelinePlayhead({
   }, [zoomMode, scrollRef]);
 
   useMountEffect(() => {
-    const unsub = liveTime.subscribe((t) => {
-      if (!playheadRef.current || durationRef.current <= 0) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(
+    let lastLiveTime = usePlayerStore.getState().currentTime;
+    const place = (t: number, atRest: boolean) => {
+      if (!playheadRef.current || durationRef.current <= 0) return false;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
         ppsRef.current,
         contentOriginRef.current,
-      )}px`;
+        atRest,
+      );
+      return true;
+    };
+    const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
+      if (prev.isPlaying && !state.isPlaying) place(lastLiveTime, true);
+    });
+    const unsub = liveTime.subscribe((t) => {
+      lastLiveTime = t;
+      if (!place(t, !usePlayerStore.getState().isPlaying)) return;
+      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
       const scroll = scrollRef.current;
       if (
         !scroll ||
@@ -150,7 +165,10 @@ export function useTimelinePlayhead({
         scroll.scrollLeft = nextScrollLeft;
       }
     });
-    return unsub;
+    return () => {
+      unsub();
+      unsubPlaying();
+    };
   });
 
   const seekFromX = useCallback(

package/src/player/components/useTimelineProviderState.tsx

@@ -71,6 +71,8 @@ export function useTimelineProviderState({
   canPasteClip,
   theme: themeOverrides,
   sessionEpoch = 0,
+  previewIframeRef,
+  onZIndexReorder,
 }: TimelineProps = {}): TimelineContextValue {
   const {
     onMoveElement,
@@ -184,6 +186,8 @@ export function useTimelineProviderState({
   });
   const { readClipZIndex, applyStackingPatches, zSyncEnabled } = useTimelineStackingSync({
     expandedElementsRef: timelineElementsRef,
+    previewIframeRef,
+    onZIndexReorder,
   });
   const {
     draggedClip,

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

@@ -73,4 +73,50 @@ describe("useTimelineStackingSync", () => {
     mocks.actions = null;
     iframe.remove();
   });
+
+  it("uses a host's iframe and commit over Studio's own", async () => {
+    const studioCommit = vi.fn().mockResolvedValue(undefined);
+    mocks.actions = {
+      previewIframeRef: { current: null },
+      handleDomZIndexReorderCommit: studioCommit,
+    };
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const node = iframe.contentDocument!.createElement("div");
+    node.id = "a";
+    iframe.contentDocument!.body.appendChild(node);
+    const hostCommit = vi.fn().mockResolvedValue(undefined);
+    const element: TimelineElement = {
+      id: "a",
+      key: "a",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+    let sync: ReturnType<typeof useTimelineStackingSync> | null = null;
+    function Harness() {
+      sync = useTimelineStackingSync({
+        expandedElementsRef: { current: [element] },
+        previewIframeRef: { current: iframe },
+        onZIndexReorder: hostCommit,
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    await act(async () => {
+      await sync!.applyStackingPatches([{ key: "a", zIndex: 3 }]);
+    });
+
+    expect(sync!.zSyncEnabled).toBe(true);
+    expect(hostCommit).toHaveBeenCalledWith(
+      [expect.objectContaining({ element: node, zIndex: 3 })],
+      undefined,
+    );
+    expect(studioCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+    mocks.actions = null;
+    iframe.remove();
+  });
 });

package/src/player/components/useTimelineStackingSync.ts

@@ -5,23 +5,30 @@ import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { findElementForSelection } from "../../components/editor/domEditingElement";
 import { readEffectiveZIndex } from "../../components/editor/canvasContextMenuZOrder";
 import type { StackingPatch } from "./timelineStackingSync";
+import type { TimelineZIndexReorderCommit } from "../../hooks/useTimelineEditingTypes";
 
-interface UseTimelineStackingSyncInput {
+/** With both set, a lane move restacks the preview's z-index to match the rows; each overrides Studio's own. */
+export interface TimelineStackingSyncProps {
+  previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+  onZIndexReorder?: TimelineZIndexReorderCommit;
+}
+
+interface UseTimelineStackingSyncInput extends TimelineStackingSyncProps {
   expandedElementsRef: RefObject<TimelineElement[]>;
 }
 
-// Lane ↔ stacking unification (research/STAGE3-NEEDED-WIRING.md). Provision the
-// two deps commitDraggedClipMove accepts so a lane-change drag also patches the
-// edited clip's z-index. Both read the SAME preview iframe + z-order persist path
-// the canvas right-click menu / LayersPanel use, so a timeline lane move and a
-// menu z-edit produce one shared inline-style commit shape. Optional contexts:
-// outside the NLE (standalone <Timeline>) these are null ⇒ deps undefined ⇒ the
-// commit's z-sync is a no-op (backward compatible).
-export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStackingSyncInput) {
+// Lane ↔ stacking sync: the two deps commitDraggedClipMove takes so a lane-change drag also patches
+// z-index, through the same iframe + z persist path the canvas menu and LayersPanel use. Either missing ⇒ no-op.
+export function useTimelineStackingSync({
+  expandedElementsRef,
+  previewIframeRef,
+  onZIndexReorder,
+}: UseTimelineStackingSyncInput) {
   const domEditActions = useDomEditActionsContextOptional();
   const shell = useStudioShellContextOptional();
-  const zSyncPreviewIframeRef = domEditActions?.previewIframeRef ?? null;
-  const handleDomZIndexReorderCommit = domEditActions?.handleDomZIndexReorderCommit;
+  const zSyncPreviewIframeRef = previewIframeRef ?? domEditActions?.previewIframeRef ?? null;
+  const handleDomZIndexReorderCommit =
+    onZIndexReorder ?? domEditActions?.handleDomZIndexReorderCommit;
   const zSyncActiveCompPath = shell?.activeCompPath ?? null;
 
   // Resolve a TimelineElement to its live iframe HTMLElement via the same

package/src/player/hooks/timelinePlayerSync.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { timelineElementsChanged } from "./timelinePlayerSync";
+
+describe("timelineElementsChanged", () => {
+  const clip = { id: "v", tag: "video", start: 0, duration: 4, track: 1 };
+  it.each([
+    ["muted", { muted: true }],
+    ["sound", { hasAudio: true }],
+    ["volume", { volume: 0 }],
+    ["speed", { playbackRate: 2 }],
+    ["hidden", { hidden: true }],
+    ["audio group volume", { audioGroupVolume: 0 }],
+    ["audio group hidden", { audioGroupHidden: true }],
+    ["fade in", { fadeIn: 1 }],
+    ["fade out", { fadeOut: 1 }],
+  ])("sees a clip whose %s changed with no timing change", (_name, change) => {
+    expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);
+    expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);
+  });
+});

package/src/player/hooks/timelinePlayerSync.ts

@@ -1,5 +1,22 @@
 import type { TimelineElement } from "../store/playerStore";
 
+const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
+  "id",
+  "start",
+  "duration",
+  "track",
+  "sourceDuration",
+  "muted",
+  "hasAudio",
+  "volume",
+  "playbackRate",
+  "hidden",
+  "audioGroupVolume",
+  "audioGroupHidden",
+  "fadeIn",
+  "fadeOut",
+];
+
 /** Whether a derived timeline changes any field that affects rendering. */
 export function timelineElementsChanged(
   previous: TimelineElement[],
@@ -8,13 +25,6 @@ export function timelineElementsChanged(
   if (next.length !== previous.length) return true;
   return next.some((element, index) => {
     const prior = previous[index];
-    return (
-      !prior ||
-      element.id !== prior.id ||
-      element.start !== prior.start ||
-      element.duration !== prior.duration ||
-      element.track !== prior.track ||
-      element.sourceDuration !== prior.sourceDuration
-    );
+    return !prior || RENDERED_FIELDS.some((key) => element[key] !== prior[key]);
   });
 }

package/src/player/hooks/useShadowPreviewReload.ts

@@ -12,7 +12,7 @@ import {
   type PreviewIframeSlot,
   type UseTimelineSyncCallbacksParams,
 } from "./useTimelineSyncCallbacks";
-import type { PlaybackAdapter } from "../lib/playbackTypes";
+import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { usePlayerStore } from "../store/playerStore";
 
@@ -23,6 +23,11 @@ export const SHADOW_READY_TIMEOUT_MS = 15_000;
 // A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped.
 export const SHADOW_READY_BUDGETS = 3;
 
+function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise<void> | undefined {
+  const win = iframe?.contentWindow as IframeWindow | null | undefined;
+  return win?.__hfWaitForSeekCompletion?.().catch(() => {});
+}
+
 function isDocumentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
@@ -136,10 +141,16 @@ export function useShadowPreviewReload({
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
   const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
   const markAdapterReady = useCallback(
-    (_iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
+    (iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
       if (gen == null || gen !== shadowGenRef.current) return;
-      pendingCommitRef.current = { gen, commit };
-      promoteWhenReady(gen);
+      const register = () => {
+        if (gen !== shadowGenRef.current) return;
+        pendingCommitRef.current = { gen, commit };
+        promoteWhenReady(gen);
+      };
+      const painted = restoreSeekPainted(iframe);
+      if (painted) void painted.then(register);
+      else register();
     },
     [promoteWhenReady],
   );

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -325,6 +325,25 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("promotes only once the shadow's restore seek has painted its frame", async () => {
+    const { getApi, live, gen, root } = beginReload();
+    const shadow = makeShadowWithSpies();
+    let seekPainted = () => {};
+    Object.assign(shadow.iframe.contentWindow!, {
+      __hfWaitForSeekCompletion: () => new Promise<void>((resolve) => (seekPainted = resolve)),
+    });
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(live);
+
+    await act(async () => seekPainted());
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
   it("promotes when the loader clears before the adapter is ready", () => {
     const { getApi, gen, root } = beginReload();
     const shadow = makeShadowWithSpies();

package/src/player/hooks/useTimelinePlayer.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
@@ -597,3 +597,95 @@ describe("shouldIgnorePlaybackShortcutEvent", () => {
     ).toBe(false);
   });
 });
+
+describe("shouldIgnorePlaybackShortcutEvent while a modal dialog is open", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // happy-dom has no layout, so the `hidden` attribute stands in for checkVisibility.
+  function stubStudioDocument(markup: string): Document {
+    const document = createDocument(markup);
+    const elementProto = document.defaultView!.Element.prototype as {
+      checkVisibility?: (this: Element) => boolean;
+    };
+    elementProto.checkVisibility = function () {
+      return this.closest("[hidden]") === null;
+    };
+    vi.stubGlobal("document", document);
+    return document;
+  }
+
+  it("ignores playback keys with focus still on the page behind the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true"><p>Lint results</p></div>`,
+    );
+    for (const code of ["Space", "ArrowRight", "KeyL"]) {
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent(code, { target: document.body })),
+      ).toBe(true);
+    }
+  });
+
+  it("ignores playback keys with focus inside the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true" tabindex="-1"><p>Lint results</p></div>`,
+    );
+    const dialog = document.querySelector("[role='dialog']");
+    const text = document.querySelector("p");
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: dialog }))).toBe(
+      true,
+    );
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowLeft", { target: text })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys for dialogs that are hidden, inert or not modal", () => {
+    for (const markup of [
+      `<div role="dialog" aria-modal="true" hidden></div>`,
+      `<div inert><div role="dialog" aria-modal="true"></div></div>`,
+      `<div role="dialog"></div>`,
+    ]) {
+      const document = stubStudioDocument(markup);
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+      ).toBe(false);
+    }
+  });
+
+  it("counts a dialog under fullscreen only when the fullscreen element holds it", () => {
+    const document = stubStudioDocument(
+      `<div id="stage"><div id="inner" role="dialog" aria-modal="true"></div></div>` +
+        `<div id="outer" role="dialog" aria-modal="true"></div>`,
+    );
+    const space = () =>
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body }));
+    const fullscreenOn = (id: string) =>
+      Object.defineProperty(document, "fullscreenElement", {
+        configurable: true,
+        value: document.getElementById(id),
+      });
+    fullscreenOn("stage");
+    expect(space()).toBe(true);
+    document.getElementById("inner")!.remove();
+    expect(space()).toBe(false);
+  });
+
+  it("counts an aria-modal dialog where the browser has no checkVisibility", () => {
+    const document = createDocument(`<div role="dialog" aria-modal="true"></div>`);
+    delete (document.defaultView!.Element.prototype as { checkVisibility?: unknown })
+      .checkVisibility;
+    vi.stubGlobal("document", document);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys when no dialog is open", () => {
+    const document = stubStudioDocument(`<main><p>Preview</p></main>`);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(false);
+  });
+});

package/src/player/lib/playbackShortcuts.ts

@@ -41,6 +41,23 @@ export function shouldIgnorePlaybackShortcutTarget(target: EventTarget | null):
   );
 }
 
+const MODAL_DIALOG_SELECTOR = "[role=dialog][aria-modal=true]";
+
+// An open modal owns the keyboard wherever focus sits, preview iframe included. It counts only
+// when shown: visible, not inert, and not behind a fullscreen element that leaves it out.
+function isModalDialogOpen(): boolean {
+  const doc = globalThis.document;
+  if (!doc) return false;
+  const fullscreen = doc.fullscreenElement;
+  return Array.from(doc.querySelectorAll(MODAL_DIALOG_SELECTOR)).some(
+    (dialog) =>
+      (!fullscreen || fullscreen.contains(dialog)) &&
+      !dialog.closest("[inert]") &&
+      (typeof dialog.checkVisibility !== "function" ||
+        dialog.checkVisibility({ visibilityProperty: true })),
+  );
+}
+
 interface PlaybackShortcutCaptionState {
   isCaptionEditMode: boolean;
   selectedCaptionSegmentCount: number;
@@ -60,6 +77,7 @@ export function shouldIgnorePlaybackShortcutEvent(
 ): boolean {
   if (event.metaKey || event.ctrlKey || event.altKey) return true;
   if (shouldIgnorePlaybackShortcutTarget(event.target)) return true;
+  if (isModalDialogOpen()) return true;
   return (
     PLAYBACK_FRAME_STEP_CODES.has(event.code) &&
     captionState.isCaptionEditMode &&

package/src/player/lib/playbackTypes.ts

@@ -62,6 +62,7 @@ export type IframeWindow = Window & {
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;
+  __hfWaitForSeekCompletion?: () => Promise<void>;
   /** Declared runtime-side in core's window.d.ts, which this package cannot see.
    *  Every member stays optional and is optional-called, so a runtime that
    *  predates the hook degrades to a no-op instead of throwing. */