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

package/src/components/chat/entity-cards/program-card.tsx

@@ -2,8 +2,18 @@
 
 /**
  * ProgramCard (pure presentation). Generic card for podcasts / webinars /
- * events. Two densities — `default` (vertical detail) and `sm` (compact
- * horizontal for chat-inline).
+ * events. Three densities — `default` (wide horizontal detail, archive
+ * pages), `sm` (compact horizontal for chat-inline), and `portrait`
+ * (vertical rail/strip card).
+ *
+ * `portrait` exists because mixed-content rails MUST share ONE card anatomy
+ * (2026 card-UI practice: a rail mixes content types, never card layouts —
+ * mixing orientations/aspects in one scroller is the anti-pattern). It
+ * renders the SAME three zones as the other portrait entity cards
+ * (CaseStudyCard et al.): wide media slot → fixed 72px title zone → fixed
+ * 60px person/meta footer, p-6 / gap-6. The program's identity lives in the
+ * Azeret Mono title and the date · duration meta line — not in a different
+ * layout.
  *
  * The card writes NO click logic — callers wrap with their own anchor
  * and pass the resolved detail URL via `href`.
@@ -34,16 +44,19 @@ import {
   COMPACT_CARD_TITLE,
   COMPACT_CARD_TITLE_ROW,
 } from '../utils/compact-card-classes'
-import type {
-  BaseProgramItem,
-  ProgramConfig,
-  ProgramMedia,
-  ProgramHost,
+import {
+  programItemToStripProfile,
+  type BaseProgramItem,
+  type ProgramAuthorRef,
+  type ProgramConfig,
+  type ProgramMedia,
+  type ProgramHost,
 } from '../types/entities/program-types'
+import { EntityPortraitCard } from './entity-portrait-card'
 import { useEntityCardLink } from './use-entity-card-link'
 import { useEntityCardPlaceholder } from './use-entity-card-placeholder'
 
-type CardSize = 'default' | 'sm'
+type CardSize = 'default' | 'sm' | 'portrait'
 
 /**
  * Format a Date with date-fns pinned to UTC. `date-fns` `format()` reads the
@@ -115,6 +128,8 @@ export interface ProgramCardProps<T extends BaseProgramItem> {
   media?: ProgramMedia[]
   renderMeta?: (item: T) => React.ReactNode
   size?: CardSize
+  /** Portrait density: render the content-type chip. Mixed rails only; single-type rails pass false. Default true. */
+  showTypeBadge?: boolean
   /** Detail URL resolved by the caller. */
   href: string
   /** When `_blank`, opens in a new tab. Set by chat dispatch via
@@ -212,6 +227,7 @@ export function ProgramCard<T extends BaseProgramItem>({
   media = [],
   renderMeta,
   size = 'default',
+  showTypeBadge = true,
   href,
   target: targetProp,
   rel: relProp,
@@ -237,24 +253,60 @@ export function ProgramCard<T extends BaseProgramItem>({
   const accentColor = 'var(--color-accent-primary)'
   const isScheduled = 'status' in item && (item as any).status === 'scheduled'
 
-  if (size === 'sm') {
-    const itemDate = (() => {
-      try { return formatUtc(new Date(item.date), 'MMM d, yyyy') } catch { return '' }
-    })()
-    const compactCover = coverImage || placeholderUrl || null
-    let typeMeta: string | null = null
+  // Compact per-type meta (duration / location / start time) — shared by the
+  // `sm` and `portrait` densities.
+  const compactTypeMeta = (): string | null => {
     if (config.type === 'podcast' && 'duration_seconds' in item && !isScheduled) {
       const dur = (item as any).duration_seconds
-      if (typeof dur === 'number' && dur > 0) typeMeta = formatDurationCompact(dur)
+      if (typeof dur === 'number' && dur > 0) return formatDurationCompact(dur)
     } else if (config.type === 'event' && 'location_name' in item) {
       const loc = (item as any).location_name
-      if (typeof loc === 'string' && loc.trim().length > 0) typeMeta = loc
+      if (typeof loc === 'string' && loc.trim().length > 0) return loc
     } else if (config.type === 'webinar' && 'start_at' in item) {
       const w = item as any
       const time = formatTimeWithTimezone(w.start_at, w.timezone ?? null)
       const dur = formatDurationFromRange(w.start_at, w.end_at)
-      typeMeta = dur ? `${time} · ${dur}` : time
+      return dur ? `${time} · ${dur}` : time
     }
+    return null
+  }
+  const compactDate = (() => {
+    try { return formatUtc(new Date(item.date), 'MMM d, yyyy') } catch { return '' }
+  })()
+
+  if (size === 'portrait') {
+    // Rail/strip density — mapped onto the shared <EntityPortraitCard> shell
+    // (media aspect-[1200/630] → h-[72px] title → h-[60px] footer, p-6/gap-6).
+    // Person = author-first via programItemToStripProfile (author → primary
+    // host); the date · duration meta line fills the subtitle when the
+    // profile has no job title.
+    const profile = programItemToStripProfile(item as { author?: ProgramAuthorRef | null; hosts?: ProgramHost[] | null })
+    const dateMeta = [compactDate, compactTypeMeta()].filter(Boolean).join(' · ')
+    return (
+      <EntityPortraitCard
+        href={href}
+        target={target}
+        rel={rel}
+        typeLabel={showTypeBadge ? config.labels.singular : undefined}
+        imageUrl={coverImage}
+        placeholderUrl={placeholderUrl}
+        imageAlt={item.title}
+        title={item.title}
+        titleClassName="font-['Azeret_Mono'] font-semibold text-lg leading-6"
+        person={
+          profile
+            ? { name: profile.name, avatarUrl: profile.avatarUrl, subtitle: profile.subtitle || dateMeta }
+            : { name: config.labels.singular, subtitle: dateMeta }
+        }
+        className={className}
+      />
+    )
+  }
+
+  if (size === 'sm') {
+    const itemDate = compactDate
+    const compactCover = coverImage || placeholderUrl || null
+    const typeMeta = compactTypeMeta()
     const subtitleParts = [itemDate, typeMeta, config.labels?.singular].filter(
       (s): s is string => typeof s === 'string' && s.length > 0,
     )

package/src/components/chat/entity-cards/use-cover-image-fallback.ts

@@ -0,0 +1,50 @@
+'use client'
+
+/**
+ * THE common cover-image fallback chain for entity cards:
+ *   real cover → branded placeholder → nothing (hide the media element).
+ *
+ * One hook so no card hand-rolls its own `imageError` state / `displayImage`
+ * ternary (they drift: the pre-hook BlogCard chain couldn't recover from a
+ * FAILING placeholder, EntityPortraitCard duplicated the same logic with
+ * different state). Cards wire `src` + `onError` and render their own
+ * empty-state when `src` is null.
+ *
+ * Implementation note: state is the SET of candidate URLs that failed, and
+ * `src` is derived — so a prop change (new cover URL) re-resolves instantly
+ * with no reset effect, and a URL that failed once isn't retried in a loop.
+ */
+
+import { useCallback, useState, type SyntheticEvent } from 'react'
+
+export interface CoverImageFallback {
+  /** Resolved source: first non-failed of [imageUrl, placeholderUrl], else null. */
+  src: string | null
+  /** Wire to the media element's `onError`. */
+  onError: () => void
+}
+
+export function useCoverImageFallback(
+  imageUrl?: string | null,
+  placeholderUrl?: string | null,
+): CoverImageFallback {
+  const [failed, setFailed] = useState<ReadonlySet<string>>(() => new Set())
+
+  const src =
+    imageUrl && !failed.has(imageUrl) ? imageUrl
+    : placeholderUrl && !failed.has(placeholderUrl) ? placeholderUrl
+    : null
+
+  const onError = useCallback(() => {
+    if (!src) return
+    setFailed(prev => new Set(prev).add(src))
+  }, [src])
+
+  return { src, onError }
+}
+
+/** Fallback for cards with NO placeholder chain (compact/sm image slots):
+ *  a broken cover simply disappears, leaving the slot's background. */
+export const hideOnError = (e: SyntheticEvent<HTMLImageElement>) => {
+  ;(e.currentTarget as HTMLImageElement).style.display = 'none'
+}

package/src/components/chat/types/entities/program-types.ts

@@ -17,6 +17,10 @@
  */
 
 import type { ReactNode } from 'react';
+import {
+  toStripProfile,
+  type VideoBiteStripProfile,
+} from '../../../features/video-bites-shared';
 
 // ============================================================================
 // HOST TYPES
@@ -34,6 +38,36 @@ export interface ProgramHost {
   role?: string; // e.g., "Host", "Speaker", "Guest"
 }
 
+/**
+ * Client-safe author subset hydrated onto program items from the entity's
+ * `author_id → profiles` FK join (podcast episodes / webinars). Deliberately
+ * excludes `email` — this shape is serialized into public payloads.
+ */
+export interface ProgramAuthorRef {
+  id?: string | null;
+  full_name?: string | null;
+  avatar_url?: string | null;
+  job_title?: string | null;
+}
+
+/**
+ * Video-bites overlay profile for a program item: internal author first
+ * (`author_id → profiles`), then the provider-synced primary host (Livestorm
+ * speakers / Podbean hosts). Host `role` is a raw provider enum (e.g.
+ * `team_member`) — never display copy, so it is not used as the subtitle.
+ * Routes through `toStripProfile` (the SSoT — null on missing names).
+ */
+export function programItemToStripProfile(item: {
+  author?: ProgramAuthorRef | null;
+  hosts?: ProgramHost[] | null;
+}): VideoBiteStripProfile | null {
+  const fromAuthor = toStripProfile(item.author);
+  if (fromAuthor) return fromAuthor;
+  const host = Array.isArray(item.hosts) ? item.hosts[0] : null;
+  if (!host?.name) return null;
+  return toStripProfile({ full_name: host.name, avatar_url: host.avatar_url ?? null });
+}
+
 // ============================================================================
 // DATABASE ROW TYPES
 // ============================================================================

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,76 @@
+'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.
+ *
+ * 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
+ *     white glyph via CSS (`mux-player::part(center play button)` in
+ *     styles/app-globals.css) so full players match too.
+ *
+ * Glyph paths are media-chrome's own (filled triangle / filled volume-off) so
+ * the replica and the real player chrome stay pixel-consistent.
+ */
+
+import React from 'react'
+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 white play glyph (media-chrome's filled triangle). 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 }}
+    >
+      <svg aria-hidden viewBox="0 0 24 24" fill="currentColor" style={{ width: SIZES[size], height: SIZES[size] }}>
+        <path d="m6 21 15-9L6 3v18Z" />
+      </svg>
+    </div>
+  )
+}
+
+export interface VideoUnmuteGlyphProps {
+  size?: VideoCenterBadgeSize
+  className?: string
+}
+
+/** Bare white muted-volume glyph (filled, material volume_off — the same
+ *  family as media-chrome's mute icon). Rendered by FilePlayer's unmute
+ *  button; exported here so play + unmute share one identity. */
+export function VideoUnmuteGlyph({ size = 'md', className }: VideoUnmuteGlyphProps): React.ReactElement {
+  return (
+    <svg
+      aria-hidden
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      className={className}
+      style={{ width: SIZES[size], height: SIZES[size], filter: GLYPH_SHADOW }}
+    >
+      <path d="M16.5 12A4.5 4.5 0 0 0 14 7.97v2.21l2.45 2.45c.03-.2.05-.41.05-.63Zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51A8.796 8.796 0 0 0 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71ZM4.27 3 3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06a8.99 8.99 0 0 0 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3ZM12 4 9.91 6.09 12 8.18V4Z" />
+    </svg>
+  )
+}