@flamingo-stack/openframe-frontend-core 0.0.396 → 0.0.397-snapshot.20260710044003

package/src/components/features/cards-strip.tsx

@@ -284,6 +284,11 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
   // modulo the copy width each frame, so warps are invisible to it.
   const marqueePosRef = useRef(0);
   const glideRemainingRef = useRef(0);
+  // Velocity envelope (px/s): the marquee EASES between 0 and autoScrollSpeed
+  // (~250ms time constant) instead of binary stop/start — pause decelerates,
+  // resume accelerates from the current position (GSAP-marquee behavior;
+  // hard cuts read as jank).
+  const speedEnvRef = useRef(0);
   useEffect(() => {
     if (!marqueeActive) return;
     const scroller = scrollerRef.current;
@@ -301,11 +306,21 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
     const tick = (now: number) => {
       const dt = Math.min(now - last, 100) / 1000; // clamp tab-wake jumps
       last = now;
+      // Container-level pause (industry-standard marquee behavior): the
+      // marquee freezes whenever a hover-capable pointer is ANYWHERE over the
+      // cards row — content must never move under a pointing cursor. Per-card
+      // activeKey still pauses for keyboard focus (no pointer involved).
       const paused =
-        (pauseOnHover && activeKeyRef.current !== null) ||
+        (pauseOnHover && (hoverPointerRef.current.inside || activeKeyRef.current !== null)) ||
         !nearViewportRef.current ||
         document.visibilityState === 'hidden' ||
         now < Math.max(chevronSuppressUntilRef.current, userScrollSuppressUntilRef.current);
+      // Ease the marquee velocity toward its target (0 when paused) — smooth
+      // decel on hover, smooth accel on leave, always from the CURRENT position.
+      const targetSpeed = paused ? 0 : autoScrollSpeed;
+      speedEnvRef.current += (targetSpeed - speedEnvRef.current) * Math.min(1, dt / 0.25);
+      if (targetSpeed === 0 && speedEnvRef.current < 0.5) speedEnvRef.current = 0;
+
       const glide = glideRemainingRef.current;
       if (glide !== 0) {
         // Ease-out toward the chevron target; runs even while "paused"
@@ -318,20 +333,26 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
         glideRemainingRef.current = Math.abs(glide - step) < 0.5 ? 0 : glide - step;
         marqueePosRef.current = wrap(marqueePosRef.current + step);
         scroller.scrollLeft = marqueePosRef.current;
-      } else if (!paused) {
+      } else if (speedEnvRef.current > 0) {
         // Resync after external movement (user scroll, seam warp).
         if (Math.abs(scroller.scrollLeft - marqueePosRef.current) > 1.5) {
           marqueePosRef.current = scroller.scrollLeft;
         }
-        marqueePosRef.current = wrap(marqueePosRef.current + autoScrollSpeed * dt);
+        marqueePosRef.current = wrap(marqueePosRef.current + speedEnvRef.current * dt);
         scroller.scrollLeft = marqueePosRef.current;
       } else {
         marqueePosRef.current = scroller.scrollLeft;
       }
+      // Track moved under a possibly-stationary pointer → re-resolve which
+      // card is hovered (declared below; stable useCallback identity, called
+      // lazily per frame so source order is irrelevant — deliberately NOT a
+      // dep, same as the activeKeyRef read above).
+      syncHoverIfScrolled();
       raf = requestAnimationFrame(tick);
     };
     raf = requestAnimationFrame(tick);
     return () => cancelAnimationFrame(raf);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- syncHoverIfScrolled is identity-stable
   }, [marqueeActive, autoScrollSpeed, pauseOnHover]);
 
   // ---- hover / overlay state -----------------------------------------------------
@@ -357,6 +378,72 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
     setActiveKey(current => (current === key ? null : current));
   }, []);
 
+  // ---- container-level hover pause + pointer-tracked activation sync ---------
+  // TWO separate concerns, deliberately decoupled (matches how production
+  // marquees — react-fast-marquee, GSAP — behave):
+  //
+  // 1. MARQUEE PAUSE is container-level: `hoverPointerRef.inside` is true
+  //    whenever a hover-capable pointer is over the SCROLLER (the cards row).
+  //    The rAF freezes on it, so content NEVER auto-moves under a pointing
+  //    cursor — which is what made per-card boundary pausing feel flaky
+  //    (cards sliding under/away from a stationary pointer don't emit
+  //    pointerenter/leave, gaps caused stutter-steps, seam warps swapped the
+  //    hovered card's identity mid-playback).
+  //
+  // 2. CARD ACTIVATION (overlay + video playback) stays per-card: the card/
+  //    cell pointer handlers are the zero-latency path, and the
+  //    elementFromPoint sync below re-resolves the card under the pointer
+  //    whenever the track moves WHILE the pointer is inside (user wheel
+  //    scroll, chevron glide, seam warp) — scoped to THIS strip's scroller so
+  //    stacked strips can never activate/pause each other.
+  const hoverPointerRef = useRef<{ x: number; y: number; inside: boolean }>({ x: 0, y: 0, inside: false });
+  const lastHoverSyncScrollRef = useRef(-1);
+  const syncHoverToPointer = useCallback(() => {
+    const p = hoverPointerRef.current;
+    if (!p.inside) return;
+    const el = typeof document !== 'undefined' ? document.elementFromPoint(p.x, p.y) : null;
+    const cardEl = el?.closest?.('[data-strip-card-key]') as HTMLElement | null;
+    // Strip-scoped: a card from ANOTHER CardsStrip under the tracked point
+    // must read as "no card here" (stacked strips share the viewport).
+    const scoped = cardEl && scrollerRef.current?.contains(cardEl) ? cardEl : null;
+    const key = scoped?.getAttribute('data-strip-card-key') ?? null;
+    const current = activeKeyRef.current;
+    if (key === current) return;
+    if (current !== null) deactivate(current);
+    if (key !== null) activate(key);
+  }, [activate, deactivate]);
+  // Hover-capable pointers only (mouse/pen) — touch drags must not fake hover.
+  const onHoverPointerEnter = useCallback((e: React.PointerEvent) => {
+    if (e.pointerType === 'touch') return;
+    hoverPointerRef.current = { x: e.clientX, y: e.clientY, inside: true };
+  }, []);
+  const onHoverPointerMove = useCallback((e: React.PointerEvent) => {
+    if (e.pointerType === 'touch') return;
+    hoverPointerRef.current = { x: e.clientX, y: e.clientY, inside: true };
+  }, []);
+  const onHoverPointerLeave = useCallback((e: React.PointerEvent) => {
+    if (e.pointerType === 'touch') return;
+    hoverPointerRef.current.inside = false;
+    // The pointer left the whole scroller — no card can be hovered anymore
+    // (covers leave events swallowed by DOM churn under the cursor).
+    const current = activeKeyRef.current;
+    if (current !== null) deactivate(current);
+  }, [deactivate]);
+  /** Re-sync hover only when the track actually moved under the pointer.
+   *  KNOWN HOT-PATH COST (intentional): while the marquee runs with the
+   *  pointer parked over strip whitespace (no card → not paused), scrollLeft
+   *  changes every frame, so this invokes `document.elementFromPoint` ~60×/s
+   *  — a synchronous hit-test. It's inherent to detecting a card sliding
+   *  under a stationary cursor; any throttle trades hover latency for it.
+   *  Revisit only if profiling flags it on pages with many stacked strips. */
+  const syncHoverIfScrolled = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+    if (scroller.scrollLeft === lastHoverSyncScrollRef.current) return;
+    lastHoverSyncScrollRef.current = scroller.scrollLeft;
+    syncHoverToPointer();
+  }, [syncHoverToPointer]);
+
   // ---- shared card-mount gate (by ITEM index, across both copies) -------------
   // A card and its clone show identical content half a copy-width apart. If
   // each card gated its own expensive content (e.g. video players), a seam warp
@@ -433,6 +520,15 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
   const onUserScrollIntent = useCallback(() => {
     userScrollSuppressUntilRef.current = performance.now() + USER_SCROLL_SUPPRESS_MS;
   }, []);
+  // Suppress ONLY on genuine horizontal-scroll intent. Vertical page-scroll
+  // wheel events over the strip and plain clicks (pointerdown) used to arm the
+  // 3s suppression — the "marquee resumes only after a delay" bug.
+  const onWheelIntent = useCallback((e: React.WheelEvent) => {
+    if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) onUserScrollIntent();
+  }, [onUserScrollIntent]);
+  const onPointerDownIntent = useCallback((e: React.PointerEvent) => {
+    if (e.pointerType === 'touch') onUserScrollIntent();
+  }, [onUserScrollIntent]);
 
   // Never-ending strip: warp across the clone seam on EVERY scroll (manual
   // wheel/drag/chevron included — the rAF only wraps while the marquee runs,
@@ -445,7 +541,12 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
   marqueeActiveRef.current = marqueeActive;
   const onSeamWarp = useCallback(() => {
     const scroller = scrollerRef.current;
-    if (!scroller || !marqueeActiveRef.current) return;
+    if (!scroller) return;
+    // Every scroll (native wheel/drag, smooth chevron scroll, marquee) moves
+    // cards under a possibly-stationary pointer — re-resolve hover regardless
+    // of marquee state (pointerenter/leave never fire for track motion).
+    syncHoverIfScrolled();
+    if (!marqueeActiveRef.current) return;
     const half = singleCopyWidthRef.current;
     if (half <= 0) return;
     let sl = scroller.scrollLeft;
@@ -459,7 +560,7 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
       marqueePosRef.current = sl;
     }
     lastScrollLeftRef.current = sl;
-  }, []);
+  }, [syncHoverIfScrolled]);
 
   // ---- render ----------------------------------------------------------------
 
@@ -468,6 +569,15 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
       // Seam assertion (see normalization comment above).
       return (props.renderCard as (item: unknown, ctx: CardStripRenderCtx) => React.ReactNode)(item, ctx);
     }
+    // Per-child DESKTOP cell-width hint: heterogeneous card designs need
+    // heterogeneous cells (wide horizontal cards vs 400px vertical cards —
+    // variable widths are native to the engine, exactly like bite ratios).
+    // Read from the child ELEMENT's `data-strip-cell-width` prop; mobile keeps
+    // the strip-level width (wide cards stack vertically below md anyway).
+    const hintedWidth = React.isValidElement(item)
+      ? (item.props as Record<string, unknown>)['data-strip-cell-width']
+      : undefined;
+    const desktopWidth = typeof hintedWidth === 'number' ? hintedWidth : cardWidthDesktop;
     // Managed cell — the ONLY place cell width / activation / clone a11y are
     // encoded for children mode.
     return (
@@ -476,7 +586,8 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
       // clones).
       <div
         className="shrink-0 self-stretch"
-        style={{ width: ctx.isMobile ? cardWidthMobile : cardWidthDesktop, maxWidth: STRIP_CELL_MAX_WIDTH }}
+        style={{ width: ctx.isMobile ? cardWidthMobile : desktopWidth, maxWidth: STRIP_CELL_MAX_WIDTH }}
+        data-strip-card-key={ctx.cardKey}
         onPointerEnter={ctx.isTouch ? undefined : () => ctx.onActivate(ctx.cardKey)}
         onPointerLeave={ctx.isTouch ? undefined : () => ctx.onDeactivate(ctx.cardKey)}
         // Keyboard pause parity (focus bubbles from the card's anchor; WCAG 2.2.2).
@@ -520,9 +631,12 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
         <div
           ref={scrollerRef}
           className="overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
-          onWheel={onUserScrollIntent}
+          onWheel={onWheelIntent}
           onTouchStart={onUserScrollIntent}
-          onPointerDown={onUserScrollIntent}
+          onPointerDown={onPointerDownIntent}
+          onPointerEnter={onHoverPointerEnter}
+          onPointerMove={onHoverPointerMove}
+          onPointerLeave={onHoverPointerLeave}
           onScroll={onSeamWarp}
         >
           <div ref={trackRef} data-copies={copies} className="flex w-max items-stretch gap-4">

package/src/components/features/index.ts

@@ -60,6 +60,7 @@ export * from './warning-block'
 // `video-bites-shared` is the SERVER-SAFE leaf (also its own published subpath).
 export * from './cards-strip'
 export * from './video'
+export * from './video-center-badge'
 export * from './video-ratio-tabs'
 export * from './video-bites-shared'
 export * from './video-bites-strip'

package/src/components/features/video-bites-strip.tsx

@@ -36,9 +36,12 @@ import {
   sortBitesByCreatedAtDesc,
   type VideoBiteStripProfile,
 } from './video-bites-shared';
+import Image from '../../embed-shims/next-image';
 import { CardsStrip, STRIP_CELL_MAX_WIDTH } from './cards-strip';
+import { useCoverImageFallback } from '../chat/entity-cards/use-cover-image-fallback';
 import { UserDisplay } from '../user-display';
 import { Chevron02RightIcon } from '../icons-v2-generated/arrows/chevron-02-right-icon';
+import { VideoPlayBadge } from './video-center-badge';
 
 // NOTE: the title constant / profile adapter / sort comparator live in the
 // server-safe leaf `video-bites-shared.ts` (its own published subpath). The
@@ -252,7 +255,23 @@ export function VideoBiteCard({
     io.observe(el);
     return () => io.disconnect();
   }, [gateControlled]);
-  const showPlayer = gateControlled ? playerMounted : isNear;
+  const showMedia = gateControlled ? playerMounted : isNear;
+
+  // Player mounts at NEAR-VIEWPORT (not on first hover) so hover playback is
+  // INSTANT for any card the user can reach — mounting on activation made
+  // freshly-scrolled cards stall for seconds while MuxPlayer initialized and
+  // buffered. Always-mounted players are visually safe now that every bite
+  // carries a poster: the player renders with a transparent media background
+  // over the card's poster layer, so a not-yet-decoded player never shows as
+  // a black rectangle (the original wrap-seam flash came from POSTERLESS
+  // mounted players, not from mounting itself).
+  const showPlayer = showMedia;
+
+  // Poster resolution — THE shared entity-card cover fallback chain
+  // (use-cover-image-fallback): the bite's real thumbnail_url, dropped on
+  // load error. When it resolves to null (no thumbnail yet, or it failed)
+  // the media zone falls back to the first-frame <video> facade below.
+  const { src: posterSrc, onError: onPosterError } = useCoverImageFallback(bite.thumbnail_url);
 
   const navigate = () => {
     if (bite.onNavigate) bite.onNavigate();
@@ -342,26 +361,65 @@ export function VideoBiteCard({
       // same as the old single-box layout). Editor mode: width-driven.
       style={{ aspectRatio: cssAspect, ...(height !== undefined ? { height, maxWidth: STRIP_CELL_MAX_WIDTH } : {}) }}
     >
-      {showPlayer ? (
+      {showMedia ? (
         // Clones: `inert` (not just the wrapper's aria-hidden) — the player's
         // shadow-DOM center control is otherwise still tab-reachable inside a
         // hidden subtree (axe aria-hidden-focus). Hover preview on clones
         // keeps working: playback is driven imperatively from the CARD's own
         // pointer handlers, never from focus/clicks on the player chrome.
         <div className="absolute inset-0" inert={isClone || undefined}>
-          {/* CONTROLLED hover playback keyed to CARD hover (`isActive`): the
-              detail overlay is part of the card, so moving the pointer onto
-              it keeps playing. Sound at 50% (pre-activation: muted start +
-              live unmute on the user's first gesture); chrome = center
-              play/pause only (Figma card look). */}
-          <Video
-            kind="file"
-            url={bite.url}
-            poster={bite.thumbnail_url}
-            playWhenHovered={isActive}
-            centerControlsOnly
-            layout="fill"
-          />
+          {/* Poster layer. Preferred: the bite's REAL thumbnail (generated at
+              Vizard-ingestion time by vizard-persistence-utils via Shotstack
+              capture — the provider sends no cover), resolved through the
+              shared cover fallback chain. Fallback when it's absent or fails
+              to load: the <Video> component's `firstFrameOnly` facade paints
+              the `#t=0.1` frame. Either way the box is never a black
+              rectangle, and original + clone paint the IDENTICAL image so the
+              marquee's wrap seam stays pixel-invisible. */}
+          {posterSrc ? (
+            <Image
+              src={posterSrc}
+              alt=""
+              fill
+              unoptimized
+              onError={onPosterError}
+              className="object-cover"
+            />
+          ) : (
+            <Video kind="file" url={bite.url} firstFrameOnly layout="fill" />
+          )}
+
+          {/* Play affordance for every non-playing state (resting poster,
+              facade, mounted-but-paused): <VideoPlayBadge> — a pixel replica
+              of MuxPlayer's pre-play center button (media-chrome's own PAUSED
+              center control is a different, smaller bare glyph, so the
+              mounted player runs chromeless and the replica keeps all states
+              identical to the mux button). Hidden while playing. */}
+          {!isActive && <VideoPlayBadge className="absolute inset-0 z-10 m-auto" />}
+          {showPlayer && (
+            // `--media-background-color: transparent` (inherited into
+            // media-chrome) — the freshly-mounted player must not blank the
+            // facade behind it with its default black fill while it loads.
+            <div
+              className="absolute inset-0"
+              style={{ '--media-background-color': 'transparent' } as React.CSSProperties}
+            >
+              {/* CONTROLLED hover playback keyed to CARD hover (`isActive`): the
+                  detail overlay is part of the card, so moving the pointer onto
+                  it keeps playing. Sound at 50% (pre-activation: muted start +
+                  live unmute on the user's first gesture); CHROMELESS — the
+                  card's mux-replica badge above is the play affordance for
+                  every non-playing state. */}
+              <Video
+                kind="file"
+                url={bite.url}
+                poster={bite.thumbnail_url}
+                playWhenHovered={isActive}
+                chromeless
+                layout="fill"
+              />
+            </div>
+          )}
         </div>
       ) : (
         // Aspect-matched placeholder until the card nears the viewport (CLS-free).
@@ -391,6 +449,10 @@ export function VideoBiteCard({
         return rootRef?.(node);
       }}
       aria-hidden={isClone || undefined}
+      // Hit-test marker for the strip engine's pointer-tracked hover re-sync
+      // (cards move under a stationary pointer — see cards-strip.tsx). The
+      // hover area is exactly this card root: media + overlay + toolbar.
+      data-strip-card-key={key}
       className={cn(
         'relative rounded-md border border-ods-border bg-ods-card overflow-hidden group/card',
         height !== undefined ? 'shrink-0' : 'w-full',

package/src/components/features/video-center-badge.tsx

@@ -0,0 +1,77 @@
+'use client'
+
+/**
+ * THE center media glyphs — the single visual identity for every play/unmute
+ * affordance over video, across the whole project: a SOLID WHITE GLYPH
+ * (`text-ods-text-primary`), NO background disc, with a soft drop-shadow for
+ * legibility over arbitrary frames. Accent color appears ONLY while the
+ * icon's own control is hovered (hosts pass `group-hover:text-ods-accent`;
+ * mux-player controls get the same via `::part(button):hover` in
+ * styles/app-globals.css).
+ *
+ * Glyphs come from THE icon system — never inline SVG paths here:
+ * PlayFilledIcon / VolumeOffFilledIcon (components/icons — the FILLED
+ * media-chrome-matching glyphs, so custom affordances are pixel-identical to
+ * MuxPlayer's native center button on real players).
+ *
+ * Consumers:
+ *   - <VideoBiteCard> resting/paused posters (md)
+ *   - <YouTubeFacade> poster (lg)
+ *   - <MediaCarousel> video thumbnails (sm)
+ *   - <FilePlayer>'s unmute chip (VideoUnmuteGlyph, md)
+ *   - MuxPlayer's native center pre-play button is stripped to the same bare
+ *     glyph language via CSS (see styles/app-globals.css).
+ */
+
+import React from 'react'
+import { PlayFilledIcon } from '../icons/play-filled-icon'
+import { VolumeOffFilledIcon } from '../icons/volume-off-filled-icon'
+import { cn } from '../../utils/cn'
+
+export type VideoCenterBadgeSize = 'sm' | 'md' | 'lg'
+
+const SIZES: Record<VideoCenterBadgeSize, number> = {
+  sm: 20, // gallery thumbnails
+  md: 56, // strip cards + unmute chip
+  lg: 64, // hero facades
+}
+
+/** Soft legibility shadow — NOT a background (per design: bare glyphs). */
+const GLYPH_SHADOW = 'drop-shadow(0 1px 4px rgba(0,0,0,0.5))'
+
+export interface VideoPlayBadgeProps {
+  size?: VideoCenterBadgeSize
+  className?: string
+}
+
+/** Bare play glyph (the icon system's PlayIcon). Decorative
+ *  (`pointer-events-none`) — the host surface owns activation. */
+export function VideoPlayBadge({ size = 'md', className }: VideoPlayBadgeProps): React.ReactElement {
+  return (
+    <div
+      className={cn('pointer-events-none flex items-center justify-center text-ods-text-primary transition-colors', className)}
+      style={{ filter: GLYPH_SHADOW }}
+    >
+      <PlayFilledIcon size={SIZES[size]} color="currentColor" />
+    </div>
+  )
+}
+
+export interface VideoUnmuteGlyphProps {
+  size?: VideoCenterBadgeSize
+  className?: string
+}
+
+/** Bare muted-volume glyph (the icon system's VolumeOffFilledIcon). Rendered
+ *  by FilePlayer's unmute button; exported here so play + unmute share one
+ *  identity. */
+export function VideoUnmuteGlyph({ size = 'md', className }: VideoUnmuteGlyphProps): React.ReactElement {
+  return (
+    <VolumeOffFilledIcon
+      size={SIZES[size]}
+      color="currentColor"
+      className={className}
+      style={{ filter: GLYPH_SHADOW }}
+    />
+  )
+}

package/src/components/features/video.tsx

@@ -32,8 +32,7 @@
 
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import MuxPlayer from '@mux/mux-player-react';
-import { PlayIcon } from '../icons-v2-generated/media-playback/play-icon';
-import { VolumeXmarkIcon } from '../icons-v2-generated/audio-and-visual/volume-xmark-icon';
+import { VideoPlayBadge, VideoUnmuteGlyph } from './video-center-badge';
 import { fetchPriorityProp } from '../../utils/fetch-priority';
 
 // =============================================================================
@@ -250,9 +249,12 @@ interface VideoFileProps extends VideoCommonProps {
    *  true → start hover playback, false → pause. When provided, the internal
    *  pointer handlers are disabled. */
   playWhenHovered?: boolean;
-  /** Hide the bottom control bar, keep only the CENTER play/pause control
-   *  (bite-strip cards per Figma). */
-  centerControlsOnly?: 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. All player props are ignored. */
+  firstFrameOnly?: boolean;
 }
 
 interface VideoYouTubeProps extends VideoCommonProps {
@@ -272,7 +274,7 @@ interface VideoAutoProps extends VideoCommonProps {
   chromeless?: boolean;
   playOnHover?: boolean;
   playWhenHovered?: boolean;
-  centerControlsOnly?: boolean;
+  firstFrameOnly?: boolean;
 }
 
 export type VideoProps = VideoFileProps | VideoYouTubeProps | VideoAutoProps;
@@ -297,6 +299,8 @@ export function Video(props: VideoProps): React.ReactElement | null {
         className={props.className}
         minimalControls={props.minimalControls}
       />
+    ) : 'firstFrameOnly' in props && props.firstFrameOnly ? (
+      <FirstFramePreview url={url} className={props.className} />
     ) : (
       <FilePlayer
         url={url}
@@ -309,7 +313,6 @@ export function Video(props: VideoProps): React.ReactElement | null {
         chromeless={'chromeless' in props ? props.chromeless : undefined}
         playOnHover={'playOnHover' in props ? props.playOnHover : undefined}
         playWhenHovered={'playWhenHovered' in props ? props.playWhenHovered : undefined}
-        centerControlsOnly={'centerControlsOnly' in props ? props.centerControlsOnly : undefined}
         className={props.className}
       />
     );
@@ -373,6 +376,35 @@ function wrapWithLayout(
   }
 }
 
+// -----------------------------------------------------------------------------
+// First-frame preview — the `firstFrameOnly` facade branch
+// -----------------------------------------------------------------------------
+
+/** First-frame paint through the SAME FilePlayer/MuxPlayer pipeline as
+ *  playback (one rendering path for every file source — HLS included, which a
+ *  plain `<video>` couldn't decode in Chromium): a chromeless, muted,
+ *  metadata-only instance whose `#t=0.1` media fragment seeks-and-paints the
+ *  first frame (also fixes iOS Safari, which stays blank on a fragmentless
+ *  metadata load). The transparent media background keeps the box showing the
+ *  card surface (never black) until the frame decodes. */
+function FirstFramePreview({ url, className }: { url: string; className?: string }): React.ReactElement {
+  return (
+    <div
+      aria-hidden
+      className="h-full w-full"
+      style={{ '--media-background-color': 'transparent' } as React.CSSProperties}
+    >
+      <FilePlayer
+        url={`${url}#t=0.1`}
+        preload="metadata"
+        muted
+        chromeless
+        className={className}
+      />
+    </div>
+  );
+}
+
 // -----------------------------------------------------------------------------
 // File branch — MuxPlayer (handles both .m3u8 HLS and plain .mp4)
 // -----------------------------------------------------------------------------
@@ -388,7 +420,8 @@ interface FilePlayerProps {
   chromeless?: boolean;
   playOnHover?: boolean;
   playWhenHovered?: boolean;
-  centerControlsOnly?: boolean;
+  /** Media preload hint — the firstFrameOnly facade passes 'metadata'. */
+  preload?: 'none' | 'metadata' | 'auto';
   className?: string;
 }
 
@@ -403,12 +436,9 @@ function FilePlayer({
   chromeless,
   playOnHover,
   playWhenHovered,
-  centerControlsOnly,
+  preload,
   className,
 }: FilePlayerProps): React.ReactElement {
-  // centerControlsOnly: the center play button shows at REST only — while
-  // playing, ALL chrome hides (no pause sign over the hover-preview).
-  const [isPlaying, setIsPlaying] = useState(false);
   // True while hover playback is running MUTED because the browser's autoplay
   // policy blocked sound (no user activation yet). Drives the center unmute
   // control — the industry pattern (muted autoplay + explicit unmute button)
@@ -546,11 +576,10 @@ function FilePlayer({
   const player = (
     <MuxPlayer
       ref={hoverPlayerRef as React.Ref<never>}
-      onPlay={centerControlsOnly ? () => setIsPlaying(true) : undefined}
-      onPause={centerControlsOnly ? () => setIsPlaying(false) : undefined}
       src={url}
       poster={poster || undefined}
       streamType="on-demand"
+      preload={preload}
       playsInline
       muted={muted}
       preferCmcd="header"
@@ -581,15 +610,6 @@ function FilePlayer({
         width: '100%',
         height: '100%',
         ...(chromeless ? ({ '--controls': 'none' } as React.CSSProperties) : {}),
-        ...(centerControlsOnly && !chromeless
-          ? ({
-              '--bottom-controls': 'none',
-              '--top-controls': 'none',
-              // While playing, hide the center control too — no pause sign
-              // over the hover-preview; it reappears when playback pauses.
-              ...(isPlaying ? { '--center-controls': 'none' } : {}),
-            } as React.CSSProperties)
-          : {}),
       }}
     >
       {captionsUrl ? (
@@ -616,9 +636,11 @@ function FilePlayer({
       aria-label="Unmute"
       title="Unmute"
       onClick={unmuteNow}
-      className="absolute inset-0 z-10 m-auto flex h-14 w-14 items-center justify-center text-ods-text-primary transition-opacity hover:opacity-75"
+      // White at rest, ACCENT while the icon itself is hovered — the same
+      // hover language as every mux control icon (see app-globals.css).
+      className="absolute inset-0 z-10 m-auto flex h-14 w-14 items-center justify-center text-ods-text-primary transition-colors hover:text-ods-accent"
     >
-      <VolumeXmarkIcon size={56} />
+      <VideoUnmuteGlyph />
     </button>
   ) : null;
 
@@ -882,9 +904,10 @@ function YouTubeFacadeInner({
           />
         </picture>
         <div className="absolute inset-0 flex items-center justify-center bg-ods-bg-inverse bg-opacity-20 transition-opacity duration-200 group-hover:bg-opacity-30">
-          <span className="flex items-center justify-center w-16 h-16 rounded-full bg-ods-accent text-ods-text-on-accent shadow-lg transition-transform duration-200 group-hover:scale-110">
-            <PlayIcon size={24} color="currentColor" className="ml-1" />
-          </span>
+          {/* THE shared center play badge (video-center-badge.tsx) — same disc
+              as strip cards / carousel thumbs / unmute chip; hero size + the
+              facade's hover-scale affordance. */}
+          <VideoPlayBadge size="lg" className="transition-transform duration-200 group-hover:scale-110 group-hover:text-ods-accent" />
         </div>
       </button>
     </div>

package/src/components/icons/index.ts

@@ -35,6 +35,8 @@ export { VendorDirectoryIcon } from './vendor-directory-icon';
 export { OpenSourceIcon } from './open-source-icon';
 export { CommunityHubIcon } from './community-hub-icon';
 export { AboutIcon } from './about-icon';
+export { PlayFilledIcon } from './play-filled-icon';
+export { VolumeOffFilledIcon } from './volume-off-filled-icon';
 export { UserIcon } from './user-icon';
 export { HamburgerIcon } from './hamburger-icon';
 export { MenuIcon } from './menu-icon';

package/src/components/icons/play-filled-icon.tsx

@@ -0,0 +1,36 @@
+import type { SVGProps } from "react";
+
+export interface PlayFilledIconProps
+  extends Omit<SVGProps<SVGSVGElement>, "width" | "height"> {
+  className?: string;
+  size?: number;
+  color?: string;
+}
+
+/**
+ * Solid play triangle — the SAME glyph media-chrome/MuxPlayer renders in its
+ * native center play button, so custom video affordances (strip cards,
+ * facades, carousels) stay pixel-consistent with real player chrome.
+ * Hand-maintained (not in the Figma-generated set, which has only the
+ * outline `PlayIcon`).
+ */
+export function PlayFilledIcon({
+  className = "",
+  size = 24,
+  color = "currentColor",
+  ...props
+}: PlayFilledIconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      fill="none"
+      viewBox="0 0 24 24"
+      className={className}
+      {...props}
+    >
+      <path fill={color} d="m6 21 15-9L6 3v18Z" />
+    </svg>
+  );
+}