@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/features/video.tsx

@@ -30,7 +30,7 @@
  *   layout="native"   → intrinsic aspect ratio. Bites grid, blog cards.
  */
 
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import MuxPlayer from '@mux/mux-player-react';
 import { VideoPlayBadge, VideoUnmuteGlyph } from './video-center-badge';
 import { fetchPriorityProp } from '../../utils/fetch-priority';
@@ -214,7 +214,33 @@ export function extractYouTubeId(url: string): string | null {
 // Props
 // =============================================================================
 
-export type VideoLayout = 'centered' | 'fill' | 'native';
+export type VideoLayout = 'centered' | 'fill' | 'native' | 'wide';
+
+/**
+ * Imperative snapshot/control handle for playback-handoff surfaces (the
+ * floating walkthrough widget's mini-player continuation). Getters power
+ * close-time snapshots; the mutators let a close/reopen gesture drive the
+ * player without remounting. `getDuration` exists so an "ended" predicate
+ * (`duration - time < 1s`) is evaluable at close time.
+ */
+export interface VideoPlayerHandle {
+  getCurrentTime(): number;
+  getDuration(): number;
+  getPaused(): boolean;
+  getMuted(): boolean;
+  play(): Promise<void>;
+  pause(): void;
+  setMuted(muted: boolean): void;
+}
+
+/** Muted-fallback state reported to hosts that own their own unmute control
+ *  (`onMutedFallbackChange`). `blocked` is true when even the muted play()
+ *  retry was rejected (iOS Low Power Mode) — the host's control is really
+ *  a "play" affordance in that state, not an "unmute" one. */
+export interface VideoMutedFallbackState {
+  muted: boolean;
+  blocked: boolean;
+}
 
 interface VideoCommonProps {
   /** Layout wrapper. Detail pages pass `"centered"`. Default `"native"`. */
@@ -237,9 +263,14 @@ interface VideoCommonProps {
   minimalControls?: boolean;
 }
 
-interface VideoFileProps extends VideoCommonProps {
-  kind: 'file';
-  url: string;
+/**
+ * File-playback options. Declared ONCE and mixed into the public prop unions
+ * AND the internal player, because these were hand-copied into four places and
+ * every new prop had to be added to all of them (18 props x 4 sites before this
+ * collapse). The dispatcher forwards them with a spread, so a prop added here
+ * reaches FilePlayer for free.
+ */
+interface VideoFilePlaybackProps {
   /**
    * SRT raw content. Deprecated: pass `captionsUrl` (VTT) instead.
    * Native `<track>` requires a URL; raw SRT can't be rendered without
@@ -249,60 +280,117 @@ interface VideoFileProps extends VideoCommonProps {
   srtContent?: string | null;
   /** HTTPS URL to a VTT captions file. Rendered as a native `<track>`. */
   captionsUrl?: string | null;
-  /** Autoplay muted on mount (forwarded as MuxPlayer `autoPlay="muted"`) — hover-preview surfaces. */
+  /** Autoplay muted on mount (forwarded as MuxPlayer `autoPlay="muted"`). */
   autoPlay?: boolean;
   /** Loop playback — short bite previews. */
   loop?: boolean;
-  /** Hide all player chrome (MuxPlayer `--controls: none`) — chromeless preview mode. */
+  /** Hide all player chrome (MuxPlayer `--controls: none`). */
   chromeless?: boolean;
-  /** Play while the pointer hovers the player, pause on leave. Tries WITH
-   *  sound at 50% volume first (bite-strip behavior); falls back to muted when
-   *  the browser's autoplay policy rejects unmuted hover playback. */
+  /** Play while the pointer hovers, pause on leave. Tries WITH sound at 50%
+   *  first; falls back to muted when autoplay policy rejects unmuted. */
   playOnHover?: boolean;
-  /** CONTROLLED variant of playOnHover: the host owns the hover state (e.g.
-   *  the bite-strip card, whose overlay also counts as "hovering the card").
-   *  true → start hover playback, false → pause. When provided, the internal
-   *  pointer handlers are disabled. */
+  /** CONTROLLED variant of playOnHover: the host owns the hover state. */
   playWhenHovered?: boolean;
-  /** Render ONLY a lightweight first-frame preview — a metadata-only element
-   *  seeked to `#t=0.1` (media-fragment trick; paints on iOS Safari where a
-   *  fragmentless metadata load stays blank). No chrome, no playback, no
-   *  MuxPlayer cost — the resting facade layer under strip cards when no
-   *  poster asset exists. `poster`/`fit`/`className` are honored; all other
-   *  player props are ignored. */
-  firstFrameOnly?: boolean;
-  /** Media preload hint. When omitted, the SSOT default applies:
-   *  `'metadata'` (manifest + ~1 segment buffered on mount — instant
-   *  hover/click start, bounded by playback-core's maxBufferLength=1 clamp),
-   *  downgraded to `'none'` on Save-Data connections. Pass a value only to
-   *  override the policy deliberately. */
+  /** Media preload hint. When omitted the SSOT default applies. */
   preload?: 'none' | 'metadata' | 'auto';
-  /** Object-fit for the media inside the player box. Default `'contain'`
-   *  (MuxPlayer default); `'cover'` crops to fill — aspect-cropped grid
-   *  cells and social-post mockups. */
+  /** object-fit for the media element. */
   fit?: 'contain' | 'cover';
+  /** Start position in seconds (applied at LOAD time). */
+  startTime?: number;
+  /** Imperative handle for snapshot/control (mini-player continuation). */
+  playerHandleRef?: React.Ref<VideoPlayerHandle>;
+  /** Attempt UNMUTED autoplay on mount; falls back to muted on rejection. */
+  autoPlayUnmuted?: boolean;
+  /** Arm the muted-fallback state (host renders its own unmute affordance). */
+  startMuted?: boolean;
+  /** Host's standing mute intent — hover playback must not override it. */
+  mutedIntent?: boolean;
+  /** Suppress the INTERNAL center unmute glyph. Hosts whose own overlay
+   *  button sits above the media render their own reachable control. */
+  hideMutedBadge?: boolean;
+  /** Reports muted-fallback state changes — see `VideoMutedFallbackState`. */
+  onMutedFallbackChange?: (state: VideoMutedFallbackState) => void;
+  /** Fired on the media element's `ended` event. */
+  onEnded?: () => void;
+}
+
+/** The keys above, for the dispatcher's spread. `satisfies` rejects an EXTRA
+ *  or misspelled key; the assertion below rejects a MISSING one (which would
+ *  otherwise compile fine and silently stop forwarding that prop). */
+const VIDEO_FILE_PLAYBACK_KEYS = [
+  'srtContent', 'captionsUrl', 'autoPlay', 'loop', 'chromeless', 'playOnHover',
+  'playWhenHovered', 'preload', 'fit', 'startTime', 'playerHandleRef',
+  'autoPlayUnmuted', 'startMuted', 'mutedIntent', 'hideMutedBadge',
+  'onMutedFallbackChange', 'onEnded',
+] as const satisfies readonly (keyof VideoFilePlaybackProps)[];
+
+/** Build-time proof that a key list covers EVERY key of its interface — the
+ *  `satisfies` on the list itself only rejects extra/misspelled keys, so
+ *  without this a newly added prop compiles fine and silently stops being
+ *  forwarded. Instantiate once per (interface, key-list) pair. */
+type AllKeysForwarded<TProps, TKeys extends readonly (keyof TProps)[]> =
+  Exclude<keyof TProps, TKeys[number]> extends never ? true : never;
+
+/** Copy only the declared keys that are actually PRESENT on the union member,
+ *  so an absent optional prop stays absent rather than becoming `undefined`. */
+function pickForwardedKeys<TProps>(
+  props: VideoProps,
+  keys: readonly (keyof TProps)[],
+): TProps {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) {
+    if ((k as string) in props) out[k as string] = (props as unknown as Record<string, unknown>)[k as string];
+  }
+  return out as TProps;
+}
+
+const _filePlaybackForwarded: AllKeysForwarded<VideoFilePlaybackProps, typeof VIDEO_FILE_PLAYBACK_KEYS> = true;
+void _filePlaybackForwarded;
+
+const pickFilePlayback = (props: VideoProps): VideoFilePlaybackProps =>
+  pickForwardedKeys<VideoFilePlaybackProps>(props, VIDEO_FILE_PLAYBACK_KEYS);
+
+interface VideoFileProps extends VideoCommonProps, VideoFilePlaybackProps {
+  kind: 'file';
+  url: string;
+  firstFrameOnly?: boolean;
 }
 
-interface VideoYouTubeProps extends VideoCommonProps {
+/** YouTube-facade behavior props, declared ONCE and reused by every layer that
+ *  forwards them (the two union members, the facade, its inner). Same reason as
+ *  `VideoFilePlaybackProps`: four hand-kept copies drift silently. */
+interface VideoYouTubeFacadeProps {
+  /** Activate the facade (mount the iframe) immediately — for surfaces whose
+   *  opening interaction IS the play gesture (the walkthrough theater). The
+   *  embed URL already carries `autoplay=1`. */
+  autoActivate?: boolean;
+  /** Edge-triggered pause signal: when this flips false→true while activated,
+   *  the facade posts a `pauseVideo` command over its existing
+   *  `enablejsapi=1` postMessage channel. Lets a closing dialog stop iframe
+   *  audio BEFORE the exit animation finishes unmounting it. */
+  suspended?: boolean;
+}
+
+const VIDEO_YOUTUBE_FACADE_KEYS = [
+  'autoActivate', 'suspended',
+] as const satisfies readonly (keyof VideoYouTubeFacadeProps)[];
+
+const _youTubeForwarded: AllKeysForwarded<VideoYouTubeFacadeProps, typeof VIDEO_YOUTUBE_FACADE_KEYS> = true;
+void _youTubeForwarded;
+
+const pickYouTube = (props: VideoProps): VideoYouTubeFacadeProps =>
+  pickForwardedKeys<VideoYouTubeFacadeProps>(props, VIDEO_YOUTUBE_FACADE_KEYS);
+
+interface VideoYouTubeProps extends VideoCommonProps, VideoYouTubeFacadeProps {
   kind: 'youtube';
   /** Either a full YT URL or just the video id. */
   url: string;
 }
 
-interface VideoAutoProps extends VideoCommonProps {
+interface VideoAutoProps extends VideoCommonProps, VideoFilePlaybackProps, VideoYouTubeFacadeProps {
   kind?: 'auto';
   url: string;
-  srtContent?: string | null;
-  captionsUrl?: string | null;
-  /** See VideoFileProps — no-ops when the URL resolves to the YouTube branch. */
-  autoPlay?: boolean;
-  loop?: boolean;
-  chromeless?: boolean;
-  playOnHover?: boolean;
-  playWhenHovered?: boolean;
   firstFrameOnly?: boolean;
-  preload?: 'none' | 'metadata' | 'auto';
-  fit?: 'contain' | 'cover';
 }
 
 export type VideoProps = VideoFileProps | VideoYouTubeProps | VideoAutoProps;
@@ -326,6 +414,7 @@ export function Video(props: VideoProps): React.ReactElement | null {
         priority={props.priority}
         className={props.className}
         minimalControls={props.minimalControls}
+        {...pickYouTube(props)}
       />
     ) : 'firstFrameOnly' in props && props.firstFrameOnly ? (
       <FirstFramePreview
@@ -339,15 +428,7 @@ export function Video(props: VideoProps): React.ReactElement | null {
         url={url}
         poster={props.poster}
         muted={props.muted}
-        srtContent={'srtContent' in props ? props.srtContent : null}
-        captionsUrl={'captionsUrl' in props ? props.captionsUrl : null}
-        autoPlay={'autoPlay' in props ? props.autoPlay : undefined}
-        loop={'loop' in props ? props.loop : undefined}
-        chromeless={'chromeless' in props ? props.chromeless : undefined}
-        playOnHover={'playOnHover' in props ? props.playOnHover : undefined}
-        playWhenHovered={'playWhenHovered' in props ? props.playWhenHovered : undefined}
-        preload={'preload' in props ? props.preload : undefined}
-        fit={'fit' in props ? props.fit : undefined}
+        {...pickFilePlayback(props)}
         className={props.className}
       />
     );
@@ -402,6 +483,17 @@ function wrapWithLayout(
       );
     case 'fill':
       return <div className="absolute inset-0 w-full h-full">{inner}</div>;
+    case 'wide':
+      // In-flow 16:9 at full width, no max-width cap. The theater surface:
+      // the video sizes the box (contributes height, unlike `fill`), and any
+      // following siblings (the AI summary in EntityVideoSection) flow beneath
+      // it. `max-w-3xl` (centered) would strand a small video in a wide dialog.
+      // `bg-ods-bg` (the darkest neutral surface) gives the theater a proper
+      // near-black video stage — letterbox bars and the pre-play frame read as
+      // a video player, not a gray card. Border dropped: a stage has no chrome.
+      return (
+        <div className="w-full aspect-video rounded-lg overflow-hidden bg-ods-bg">{inner}</div>
+      );
     case 'native':
     default:
       // `native` callers (blog cards etc.) are
@@ -458,22 +550,10 @@ function FirstFramePreview({
 // File branch — MuxPlayer (handles both .m3u8 HLS and plain .mp4)
 // -----------------------------------------------------------------------------
 
-interface FilePlayerProps {
+interface FilePlayerProps extends VideoFilePlaybackProps {
   url: string;
   poster?: string | null;
   muted?: boolean;
-  srtContent?: string | null;
-  captionsUrl?: string | null;
-  autoPlay?: boolean;
-  loop?: boolean;
-  chromeless?: boolean;
-  playOnHover?: boolean;
-  playWhenHovered?: boolean;
-  /** Media preload hint — see the public `VideoFileProps.preload` JSDoc.
-   *  When omitted, defaults to 'metadata' ('none' under Save-Data). */
-  preload?: 'none' | 'metadata' | 'auto';
-  /** Object-fit — 'cover' maps to media-chrome's `--media-object-fit`. */
-  fit?: 'contain' | 'cover';
   className?: string;
 }
 
@@ -490,6 +570,14 @@ function FilePlayer({
   playWhenHovered,
   preload,
   fit,
+  startTime,
+  playerHandleRef,
+  autoPlayUnmuted,
+  startMuted,
+  mutedIntent = false,
+  hideMutedBadge,
+  onMutedFallbackChange,
+  onEnded,
   className,
 }: FilePlayerProps): React.ReactElement {
   // Explicit preload policy — never rely on the browser/MuxPlayer implicit
@@ -519,9 +607,18 @@ function FilePlayer({
     pause?: () => void;
     muted?: boolean;
     volume?: number;
+    currentTime?: number;
+    duration?: number;
+    paused?: boolean;
     addEventListener?: (type: string, listener: () => void) => void;
     removeEventListener?: (type: string, listener: () => void) => void;
   } | null>(null);
+  // True while the muted fallback is ALSO a blocked-autoplay state (even muted
+  // play() was rejected — iOS Low Power). Lets the host label its control
+  // "play" vs "unmute". MUST be state, not a ref: the blocked transition often
+  // lands while `hoverMutedFallback` is already true (a ref write wouldn't
+  // re-run the reporting effect, so hosts would never see blocked: true).
+  const [mutedFallbackBlocked, setMutedFallbackBlocked] = useState(false);
   // Dev/opt-in hover→'playing' latency metric (see videoPerfDebugEnabled).
   // One listener at a time — re-entering hover replaces it; hover-leave and
   // unmount clear it so no stale listener survives across generations.
@@ -575,11 +672,14 @@ function FilePlayer({
     try {
       el.volume = 0.5;
       if (userHasInteracted) {
-        // Post-activation: unmuted playback is allowed — play with sound.
+        // Post-activation: unmuted playback is allowed — play with sound,
+        // UNLESS the host holds a standing mute intent. Force-unmuting here
+        // audibly undid an explicit mute on the next hover, while the host's
+        // toggle still rendered "muted".
         // The NotAllowedError guard stays as a belt-and-suspenders fallback;
         // a fast hover-out's pause() rejects with AbortError and must not
         // restart playback (name mismatch + cleared hoverActiveRef).
-        el.muted = false;
+        el.muted = mutedIntentRef.current;
         (el.play?.() as Promise<void> | undefined)?.catch?.((err: unknown) => {
           const name = (err as { name?: string } | null)?.name;
           if (
@@ -589,7 +689,15 @@ function FilePlayer({
           ) {
             try {
               el.muted = true;
-              (el.play?.() as Promise<void> | undefined)?.catch?.(() => {});
+              (el.play?.() as Promise<void> | undefined)?.catch?.(() => {
+                // Even MUTED playback was rejected (iOS Low Power, Firefox
+                // media.autoplay.default=5, enterprise policy). Report it, or
+                // the host renders a "Pause"/"Unmute" control over a video
+                // that never started and the first press is a no-op.
+                if (hoverActiveRef.current && generation === hoverGenerationRef.current) {
+                  setMutedFallbackBlocked(true);
+                }
+              });
               setHoverMutedFallback(true);
             } catch { /* give up silently */ }
           }
@@ -600,7 +708,14 @@ function FilePlayer({
         // rejection round-trip, and UNMUTE LIVE the instant the user's first
         // click/keydown lands anywhere while this hover is still active.
         el.muted = true;
-        (el.play?.() as Promise<void> | undefined)?.catch?.(() => {});
+        (el.play?.() as Promise<void> | undefined)?.catch?.(() => {
+          // Same as the post-activation retry above: a rejected MUTED play is
+          // "blocked", not "muted", and the host's control label depends on
+          // the difference.
+          if (hoverActiveRef.current && generation === hoverGenerationRef.current) {
+            setMutedFallbackBlocked(true);
+          }
+        });
         setHoverMutedFallback(true);
         clearActivationWaiter();
         const waiter = () => {
@@ -652,6 +767,146 @@ function FilePlayer({
 
   const handleHoverEnter = playOnHover && !hoverControlled ? startHoverPlayback : undefined;
   const handleHoverLeave = playOnHover && !hoverControlled ? stopHoverPlayback : undefined;
+
+  // Report muted-fallback transitions to hosts that render their own control
+  // (hideMutedBadge). Emitted on every change to hoverMutedFallback so the
+  // host's card-level unmute/play affordance stays in sync.
+  // Read through a ref, NOT the closure: startHoverPlayback is memoized on
+  // empty-dep callbacks, so it would capture render-0's value forever (that is
+  // why threading the prop through three layers still did nothing). Adding it
+  // to the deps instead would re-run hover playback on every mute toggle and
+  // play() over an explicit pause.
+  const mutedIntentRef = useRef(mutedIntent);
+  mutedIntentRef.current = mutedIntent;
+  const onMutedFallbackChangeRef = useRef(onMutedFallbackChange);
+  onMutedFallbackChangeRef.current = onMutedFallbackChange;
+  useEffect(() => {
+    onMutedFallbackChangeRef.current?.({
+      muted: hoverMutedFallback,
+      blocked: hoverMutedFallback && mutedFallbackBlocked,
+    });
+  }, [hoverMutedFallback, mutedFallbackBlocked]);
+
+  // Autoplay-on-mount for handoff surfaces (theater open / resume card). Runs
+  // once. `autoPlayUnmuted` tries sound (the mount is gesture-adjacent) and
+  // falls back to muted + fallback state on rejection; `startMuted` (used with
+  // MuxPlayer's own muted autoPlay) just arms the fallback state so the host's
+  // unmute control shows from the first frame.
+  const autoPlayKickedRef = useRef(false);
+  useEffect(() => {
+    if (autoPlayKickedRef.current) return;
+    if (startMuted) {
+      // Actually mute the element. Previously this only armed the UI state, so
+      // a paused+muted resume (no autoPlay to carry `muted`) sat unmuted and
+      // the first Play press blasted full volume while every label said muted.
+      const mutedEl = hoverPlayerRef.current;
+      if (!mutedEl) return;   // latch AFTER the ref read — see the branch below
+      autoPlayKickedRef.current = true;
+      try { mutedEl.muted = true; } catch { /* ignore */ }
+      setMutedFallbackBlocked(false);
+      setHoverMutedFallback(true);
+      // When this surface is ALSO autoplaying, MuxPlayer issues its own muted
+      // play() whose rejection we never see. Issue a parallel one purely to
+      // OBSERVE the outcome: a redundant play on an already-playing element is
+      // a no-op, but a rejection is the only signal that the host must render
+      // "Play" instead of "Pause" over a video that never started.
+      if (autoPlay) {
+        try {
+          (mutedEl.play?.() as Promise<void> | undefined)?.catch?.(() => setMutedFallbackBlocked(true));
+        } catch { setMutedFallbackBlocked(true); }
+      }
+      return;
+    }
+    if (!autoPlayUnmuted) return;
+    const el = hoverPlayerRef.current;
+    // Latch AFTER the ref check: setting it first meant a null player on the
+    // first run burned the one-shot kick with no retry (the deps never change).
+    if (!el) return;
+    autoPlayKickedRef.current = true;
+    try {
+      el.muted = false;
+      el.volume = typeof el.volume === 'number' ? el.volume : 1;
+      (el.play?.() as Promise<void> | undefined)?.catch?.((err: unknown) => {
+        const name = (err as { name?: string } | null)?.name;
+        if (name !== 'NotAllowedError') return;
+        // Unmuted rejected — retry muted; if THAT rejects too, mark blocked.
+        try {
+          el.muted = true;
+          (el.play?.() as Promise<void> | undefined)?.catch?.(() => {
+            setMutedFallbackBlocked(true);
+            setHoverMutedFallback(true);
+          });
+          setMutedFallbackBlocked(false);
+          setHoverMutedFallback(true);
+        } catch {
+          setMutedFallbackBlocked(true);
+          setHoverMutedFallback(true);
+        }
+      });
+    } catch { /* ignore */ }
+  }, [autoPlayUnmuted, startMuted, autoPlay]);
+
+  // volumechange listener — clears the muted-fallback state when the media is
+  // unmuted by ANY path (MuxPlayer's own chrome in the theater, or the host
+  // control). Without this a stale glyph/state can persist after a chrome unmute.
+  useEffect(() => {
+    const el = hoverPlayerRef.current;
+    if (!el?.addEventListener) return;
+    const onVolumeChange = () => {
+      if (el.muted === false) {
+        setMutedFallbackBlocked(false);
+        setHoverMutedFallback(false);
+      }
+    };
+    try { el.addEventListener('volumechange', onVolumeChange); } catch { /* ignore */ }
+    return () => { try { el.removeEventListener?.('volumechange', onVolumeChange); } catch { /* ignore */ } };
+  }, []);
+
+  // `playing` clears the blocked-autoplay flag. Without this, once a muted
+  // retry had been rejected (iOS Low Power) the host's centre glyph read "Play"
+  // over a playing video forever — the flag was only cleared by an unmute.
+  useEffect(() => {
+    const el = hoverPlayerRef.current;
+    if (!el?.addEventListener) return;
+    const onPlaying = () => setMutedFallbackBlocked(false);
+    try { el.addEventListener('playing', onPlaying); } catch { /* ignore */ }
+    return () => { try { el.removeEventListener?.('playing', onPlaying); } catch { /* ignore */ } };
+  }, []);
+
+  // ended listener — host clears its handoff (mini-player continuation).
+  const onEndedRef = useRef(onEnded);
+  onEndedRef.current = onEnded;
+  useEffect(() => {
+    const el = hoverPlayerRef.current;
+    if (!el?.addEventListener) return;
+    const handler = () => onEndedRef.current?.();
+    try { el.addEventListener('ended', handler); } catch { /* ignore */ }
+    return () => { try { el.removeEventListener?.('ended', handler); } catch { /* ignore */ } };
+  }, []);
+
+  // Imperative handle — snapshot getters + control mutators for handoff.
+  useImperativeHandle(playerHandleRef, (): VideoPlayerHandle => ({
+    getCurrentTime: () => hoverPlayerRef.current?.currentTime ?? 0,
+    getDuration: () => {
+      const d = hoverPlayerRef.current?.duration;
+      return typeof d === 'number' && isFinite(d) ? d : 0;
+    },
+    getPaused: () => hoverPlayerRef.current?.paused ?? true,
+    getMuted: () => hoverPlayerRef.current?.muted ?? false,
+    play: async () => { await hoverPlayerRef.current?.play?.(); },
+    pause: () => { try { hoverPlayerRef.current?.pause?.(); } catch { /* ignore */ } },
+    setMuted: (m: boolean) => {
+      const el = hoverPlayerRef.current;
+      if (!el) return;
+      try {
+        el.muted = m;
+        if (!m) {
+          setMutedFallbackBlocked(false);
+          setHoverMutedFallback(false);
+        }
+      } catch { /* ignore */ }
+    },
+  }), [playerHandleRef]);
   // Raw SRT text is unusable without a custom overlay — and we just deleted
   // the 900-LOC custom-controls layer that owned that overlay. Consumers
   // pass `captionsUrl` (the API-side VTT conversion) alongside `srtContent`
@@ -683,7 +938,11 @@ function FilePlayer({
       // is ever undefined on a `data-app-type` we haven't themed yet.
       // NEVER let Mux pink leak onto a non-Flamingo platform.
       accentColor="var(--ods-accent, var(--color-accent-primary))"
-      autoPlay={autoPlay ? 'muted' : undefined}
+      // `startMuted` only ARMS the muted-fallback state (so a host can render
+      // its own unmute control); it must not imply autoplay, or a resume that
+      // closed PAUSED would start playing while the toggle still reads "Play".
+      autoPlay={autoPlay ? 'muted' : autoPlayUnmuted ? 'any' : undefined}
+      startTime={typeof startTime === 'number' ? startTime : undefined}
       loop={loop}
       className={className}
       // Fill the wrapping aspect-ratio container instead of MuxPlayer's
@@ -725,7 +984,7 @@ function FilePlayer({
   // Styled to match media-chrome's center controls exactly (the play glyph in
   // the same slot): plain large white glyph, no circle/border/background,
   // slight dim on hover — so unmute reads as just another center control.
-  const unmuteBadge = hoverMutedFallback ? (
+  const unmuteBadge = hoverMutedFallback && !hideMutedBadge ? (
     <button
       type="button"
       aria-label="Unmute"
@@ -763,6 +1022,18 @@ function FilePlayer({
       </div>
     );
   }
+  // Handoff surfaces (autoPlayUnmuted / startMuted) need the relative wrapper so
+  // the internal center unmute badge can dock — the bare branch has none. Hosts
+  // that render their OWN control pass hideMutedBadge (unmuteBadge is null then,
+  // but the wrapper is harmless).
+  if (autoPlayUnmuted || startMuted) {
+    return (
+      <div className="relative w-full h-full">
+        {player}
+        {unmuteBadge}
+      </div>
+    );
+  }
   return player;
 }
 
@@ -770,7 +1041,7 @@ function FilePlayer({
 // YouTube facade — inlined lite-youtube-embed pattern
 // -----------------------------------------------------------------------------
 
-interface YouTubeFacadeProps {
+interface YouTubeFacadeProps extends VideoYouTubeFacadeProps {
   url: string;
   title?: string;
   priority?: boolean;
@@ -784,16 +1055,20 @@ function YouTubeFacade({
   priority,
   className,
   minimalControls,
+  // `...facade` rather than naming each one: this hop is invisible to the
+  // build-time forwarding proof, so a prop added to VideoYouTubeFacadeProps
+  // would reach here and silently stop before Inner.
+  ...facade
 }: YouTubeFacadeProps): React.ReactElement | null {
   // `extractYouTubeId` handles both bare 11-char ids AND full URLs in a
   // single call site, so the resolution logic lives in exactly one place.
   const videoId = extractYouTubeId(url);
   if (!videoId) return null;
 
-  return <YouTubeFacadeInner videoId={videoId} title={title} priority={priority} className={className} minimalControls={minimalControls} />;
+  return <YouTubeFacadeInner videoId={videoId} title={title} priority={priority} className={className} minimalControls={minimalControls} {...facade} />;
 }
 
-interface YouTubeFacadeInnerProps {
+interface YouTubeFacadeInnerProps extends VideoYouTubeFacadeProps {
   videoId: string;
   title: string;
   priority?: boolean;
@@ -836,8 +1111,10 @@ function YouTubeFacadeInner({
   priority,
   className,
   minimalControls,
+  autoActivate,
+  suspended,
 }: YouTubeFacadeInnerProps): React.ReactElement {
-  const [activated, setActivated] = useState(false);
+  const [activated, setActivated] = useState(Boolean(autoActivate));
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
 
   // Embed URL + poster URLs only change when `videoId` or `minimalControls`
@@ -976,6 +1253,24 @@ function YouTubeFacadeInner({
     };
   }, [activated]);
 
+  // Close-side pause: a closing dialog flips `suspended` false→true. Post the
+  // pauseVideo command over the same enablejsapi channel so the iframe stops
+  // BEFORE the Radix exit animation unmounts it (an unmount-cleanup post would
+  // fire too late). Edge-triggered: only acts on the false→true transition
+  // while activated (prev seeded false, so the initial render never pauses).
+  const prevSuspendedRef = useRef(false);
+  useEffect(() => {
+    const wasSuspended = prevSuspendedRef.current;
+    prevSuspendedRef.current = Boolean(suspended);
+    if (!activated) return;
+    if (suspended && !wasSuspended) {
+      iframeRef.current?.contentWindow?.postMessage(
+        '{"event":"command","func":"pauseVideo","args":[]}',
+        YT_NOCOOKIE_ORIGIN,
+      );
+    }
+  }, [suspended, activated]);
+
   const wrapperClass = `relative w-full ${className ?? ''}`;
   const wrapperStyle = { paddingBottom: '56.25%' as const };
 

package/src/components/help-center-pages/.delivery-page.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 64f9480271adbe15fe1f799c4d66f96a -->
+Thin wrapper page component that composes `DevSectionPage` chrome with `DeliveryLists` to render the full bug-fixes & enhancements delivery view, exposing only the API endpoint configuration and layout props to host applications.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `DeliveryPage` | `React.FC` | Main page component wrapping `DevSectionPage` + `DeliveryLists` |
+| `DeliveryPageProps` | `interface` | Configuration props for endpoints, layout, and content slots |
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `completedEndpoint` | `string` | `/api/delivery/completed` | GET endpoint for "Recently Completed" bucket |
+| `inProgressEndpoint` | `string` | `/api/delivery/in-progress` | GET endpoint for "Active Tasks" bucket |
+| `backButton` | `{ label?, href? } \| false` | `{ href: '/' }` | Back-button config; pass `false` to hide |
+| `title` | `string` | — | Override page title |
+| `subtitle` | `string` | — | Override page subtitle |
+| `belowContent` | `ReactNode` | — | Optional slot rendered below the lists, inside page chrome |
+| `shell` | `boolean` | `true` | Set `false` when host layout already provides the page container |
+
+## Usage Example
+
+```typescript
+import { DeliveryPage } from './delivery-page'
+
+// Minimal usage — defaults apply
+export default function Page() {
+  return <DeliveryPage />
+}
+
+// Custom endpoints + embedded layout (no standalone shell)
+export default function EmbeddedDelivery() {
+  return (
+    <DeliveryPage
+      completedEndpoint="/api/ops/delivery/done"
+      inProgressEndpoint="/api/ops/delivery/active"
+      backButton={{ label: 'Back to Dashboard', href: '/dashboard' }}
+      title="Bug Fixes & Enhancements"
+      subtitle="Current sprint delivery status"
+      shell={false}
+      belowContent={<DeliveryFootnote />}
+    />
+  )
+}
+```
+
+## Source
+
+[`delivery-page.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/delivery-page.tsx)