feat(core): add scheduleTransitionSettle for menu viewport sync

Introduce the helper alongside menu viewport sizing so the transition
lifecycle PR stays focused on createTransition while viewport code can
wait for layout and animation settle.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sampotts

packages/core/src/dom/ui/transition.ts

@@ -1,5 +1,5 @@
 import { createState, type State } from '@videojs/store';
-import { getMaxCSSTransitionTime } from '@videojs/utils/dom';
+import { afterDoubleAnimationFrame, getMaxCSSTransitionTime } from '@videojs/utils/dom';
 import { noop } from '@videojs/utils/function';
 import type { TransitionState } from '../../core/ui/transition';
 
@@ -16,6 +16,57 @@ export interface WaitForAnimationsOptions {
   includeCSSTransitions?: boolean;
 }
 
+export interface ScheduleTransitionSettleOptions {
+  includeCSSTransitions?: boolean;
+  isVisuallyComplete?: (element: HTMLElement) => boolean;
+}
+
+/** After double-RAF, optionally poll visual completion, then wait for animations to settle. */
+export function scheduleTransitionSettle(
+  element: HTMLElement,
+  isCurrent: () => boolean,
+  onSettled: () => void,
+  options: ScheduleTransitionSettleOptions = {}
+): () => void {
+  let pollRaf = 0;
+  let settled = false;
+
+  function settle(): void {
+    if (settled || !isCurrent()) return;
+    settled = true;
+    cancelAnimationFrame(pollRaf);
+    pollRaf = 0;
+    onSettled();
+  }
+
+  function pollVisualComplete(): void {
+    pollRaf = 0;
+    if (settled || !isCurrent()) return;
+
+    if (options.isVisuallyComplete?.(element)) {
+      settle();
+      return;
+    }
+
+    pollRaf = requestAnimationFrame(pollVisualComplete);
+  }
+
+  afterDoubleAnimationFrame(isCurrent, () => {
+    pollVisualComplete();
+
+    waitForAnimations(element, {
+      includeCSSTransitions: options.includeCSSTransitions ?? false,
+    }).then(() => {
+      settle();
+    });
+  });
+
+  return () => {
+    settled = true;
+    cancelAnimationFrame(pollRaf);
+  };
+}
+
 /**
  * Manages open/close transition lifecycle via `createState`.
  *