@flamingo-stack/openframe-frontend-core 0.0.387 → 0.0.388-snapshot.20260709030118

package/src/components/features/video-ratio-tabs.tsx

@@ -1,15 +1,14 @@
 "use client";
 
 /**
- * Aspect-ratio tab + grouping primitives for video grids.
+ * Aspect-ratio tab + grouping primitives for video surfaces.
  *
- * Used by `<VideoBitesDisplay>` and by app-level admin editors
- * (VideoBitesEditor, VideoLibraryGrid) so portrait / square / landscape
- * clips render in cohesive groups.
+ * `RatioTabs` + `RATIO_GRID_CLASS` are ADMIN-ONLY now (VideoBitesEditor,
+ * VideoLibraryGrid) — the public grid was replaced by `<VideoBitesStrip>`,
+ * which consumes only `detectAspectRatio` + `RATIO_TO_CSS_ASPECT` from here.
  *
- * Why these live here in the lib (not the hub): `<VideoBitesDisplay>`
- * was moved into the lib for SSoT, and it depends on these primitives.
- * The hub's admin editors re-export from here.
+ * Why these live here in the lib (not the hub): the strip and the hub's
+ * admin editors share the ratio primitives, and the lib is the SSoT.
  */
 
 import {
@@ -29,16 +28,13 @@ export type VizardAspectRatio = '9:16' | '16:9' | '1:1';
 
 /**
  * Extended VideoTeaser with aspect_ratio metadata from Vizard.
- * The lib `VideoTeaser` is the canonical type but doesn't include
- * `aspect_ratio` (stored in JSONB, preserved through spreads).
- * Import this when you need the ratio at compile time.
+ * The base `VideoTeaser` carries every other persisted bite field
+ * (timing/confidence/viral_reason live there); this adds ONLY the
+ * ratio. Import this when you need the ratio at compile time —
+ * it is the canonical type display/aggregation code extends.
  */
 export interface VideoTeaserWithRatio extends VideoTeaser {
   aspect_ratio?: VizardAspectRatio;
-  confidence?: number;
-  viral_reason?: string;
-  start_time_ms?: number;
-  end_time_ms?: number;
 }
 
 /** Ratio category used for grid layout and tab grouping. */
@@ -55,11 +51,11 @@ export const RATIO_GRID_CLASS: Record<RatioCategory, string> = {
   landscape: 'grid grid-cols-1 md:grid-cols-2 gap-4',
 };
 
-/** Grid class for public display (wider grids on detail pages). */
-export const RATIO_DISPLAY_GRID_CLASS: Record<RatioCategory, string> = {
-  portrait: 'grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4',
-  square: 'grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4',
-  landscape: 'grid grid-cols-1 md:grid-cols-2 gap-6',
+/** CSS `aspect-ratio` value per category — sizing for strip cards + placeholders. */
+export const RATIO_TO_CSS_ASPECT: Record<RatioCategory, string> = {
+  portrait: '9 / 16',
+  square: '1 / 1',
+  landscape: '16 / 9',
 };
 
 const RATIO_TAB_CONFIG: { key: RatioCategory; label: string }[] = [

package/src/components/features/video.tsx

@@ -30,9 +30,10 @@
  *   layout="native"   → intrinsic aspect ratio. Bites grid, blog cards.
  */
 
-import React, { useEffect, useMemo, useRef, useState } from 'react';
+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 { fetchPriorityProp } from '../../utils/fetch-priority';
 
 // =============================================================================
@@ -105,6 +106,32 @@ if (typeof window !== 'undefined' && typeof console !== 'undefined') {
   }
 }
 
+// =============================================================================
+// User-activation tracker (module scope) — Chrome's autoplay policy rejects
+// UNMUTED play() until the user has interacted with the page (click/keydown;
+// pointer MOVEMENT does not count). Hover-preview surfaces use this to pick
+// the right first move (sound vs muted) WITHOUT a rejection round-trip, and
+// to unmute a live muted preview the instant the first gesture lands.
+// =============================================================================
+
+let userHasInteracted = false;
+const activationWaiters = new Set<() => void>();
+if (typeof window !== 'undefined') {
+  const w = window as unknown as { __VIDEO_ACTIVATION_TRACKED__?: boolean };
+  if (!w.__VIDEO_ACTIVATION_TRACKED__) {
+    w.__VIDEO_ACTIVATION_TRACKED__ = true;
+    const markActivated = () => {
+      userHasInteracted = true;
+      activationWaiters.forEach(fn => { try { fn(); } catch { /* ignore */ } });
+      activationWaiters.clear();
+      window.removeEventListener('pointerdown', markActivated, true);
+      window.removeEventListener('keydown', markActivated, true);
+    };
+    window.addEventListener('pointerdown', markActivated, true);
+    window.addEventListener('keydown', markActivated, true);
+  }
+}
+
 // =============================================================================
 // URL classifiers (private — `<Video>` is the only consumer)
 // =============================================================================
@@ -208,6 +235,24 @@ 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?: boolean;
+  /** Loop playback — short bite previews. */
+  loop?: boolean;
+  /** Hide all player chrome (MuxPlayer `--controls: none`) — chromeless preview mode. */
+  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. */
+  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. */
+  playWhenHovered?: boolean;
+  /** Hide the bottom control bar, keep only the CENTER play/pause control
+   *  (bite-strip cards per Figma). */
+  centerControlsOnly?: boolean;
 }
 
 interface VideoYouTubeProps extends VideoCommonProps {
@@ -221,6 +266,13 @@ interface VideoAutoProps extends VideoCommonProps {
   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;
+  centerControlsOnly?: boolean;
 }
 
 export type VideoProps = VideoFileProps | VideoYouTubeProps | VideoAutoProps;
@@ -252,6 +304,12 @@ export function Video(props: VideoProps): React.ReactElement | null {
         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}
+        centerControlsOnly={'centerControlsOnly' in props ? props.centerControlsOnly : undefined}
         className={props.className}
       />
     );
@@ -308,7 +366,7 @@ function wrapWithLayout(
       return <div className="absolute inset-0 w-full h-full">{inner}</div>;
     case 'native':
     default:
-      // `native` callers (LazyBite in `<VideoBitesDisplay>`, blog cards) are
+      // `native` callers (blog cards etc.) are
       // expected to provide their own aspect-ratio container so the layout
       // primitive doesn't override portrait/square/landscape bites with 16:9.
       return inner;
@@ -325,6 +383,12 @@ interface FilePlayerProps {
   muted?: boolean;
   srtContent?: string | null;
   captionsUrl?: string | null;
+  autoPlay?: boolean;
+  loop?: boolean;
+  chromeless?: boolean;
+  playOnHover?: boolean;
+  playWhenHovered?: boolean;
+  centerControlsOnly?: boolean;
   className?: string;
 }
 
@@ -334,8 +398,138 @@ function FilePlayer({
   muted,
   srtContent,
   captionsUrl,
+  autoPlay,
+  loop,
+  chromeless,
+  playOnHover,
+  playWhenHovered,
+  centerControlsOnly,
   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)
+  // instead of silently waiting for a click somewhere.
+  const [hoverMutedFallback, setHoverMutedFallback] = useState(false);
+  // playOnHover drives the underlying mux-player element imperatively — the
+  // element exposes native play()/pause()/muted/volume; the chrome stays as
+  // configured. Sound-first: volume 0.5 unmuted, muted fallback when the
+  // browser's autoplay policy rejects unmuted hover playback (hover is not a
+  // user gesture in Chrome's activation model).
+  const hoverPlayerRef = useRef<{
+    play?: () => Promise<void> | void;
+    pause?: () => void;
+    muted?: boolean;
+    volume?: number;
+  } | null>(null);
+  // Tracks whether the pointer is STILL over the player. A fast hover-out
+  // pauses the in-flight play(), which rejects it with AbortError — that must
+  // NOT trigger the muted retry (it would restart playback after the pointer
+  // left, with no visible control to stop it). Only a genuine autoplay-policy
+  // rejection (NotAllowedError) while still hovered retries muted.
+  const hoverActiveRef = useRef(false);
+  // Per-enter generation token: a LATE NotAllowedError from a previous enter
+  // must not fire the muted fallback into a newer (intended-sound) session.
+  const hoverGenerationRef = useRef(0);
+  // This instance's pending activation waiter — pruned on hover-leave,
+  // re-enter, and unmount so pre-activation hovers don't accumulate stale
+  // closures in the module-level set (they'd otherwise setState against
+  // unmounted instances when the first user gesture finally lands).
+  const activationWaiterRef = useRef<(() => void) | null>(null);
+  const clearActivationWaiter = useCallback(() => {
+    if (activationWaiterRef.current) {
+      activationWaiters.delete(activationWaiterRef.current);
+      activationWaiterRef.current = null;
+    }
+  }, []);
+  useEffect(() => clearActivationWaiter, [clearActivationWaiter]);
+  const startHoverPlayback = useCallback(() => {
+    hoverActiveRef.current = true;
+    const generation = ++hoverGenerationRef.current;
+    const el = hoverPlayerRef.current;
+    if (!el) return;
+    try {
+      el.volume = 0.5;
+      if (userHasInteracted) {
+        // Post-activation: unmuted playback is allowed — play with sound.
+        // 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.play?.() as Promise<void> | undefined)?.catch?.((err: unknown) => {
+          const name = (err as { name?: string } | null)?.name;
+          if (
+            name === 'NotAllowedError' &&
+            hoverActiveRef.current &&
+            generation === hoverGenerationRef.current
+          ) {
+            try {
+              el.muted = true;
+              (el.play?.() as Promise<void> | undefined)?.catch?.(() => {});
+              setHoverMutedFallback(true);
+            } catch { /* give up silently */ }
+          }
+        });
+      } else {
+        // Pre-activation: unmuted WOULD be rejected (hover isn't a gesture in
+        // Chrome's activation model) — start muted immediately with no
+        // 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?.(() => {});
+        setHoverMutedFallback(true);
+        clearActivationWaiter();
+        const waiter = () => {
+          activationWaiterRef.current = null;
+          if (hoverActiveRef.current && generation === hoverGenerationRef.current) {
+            try { el.muted = false; el.volume = 0.5; } catch { /* ignore */ }
+            setHoverMutedFallback(false);
+          }
+        };
+        activationWaiterRef.current = waiter;
+        activationWaiters.add(waiter);
+      }
+    } catch { /* ignore */ }
+  }, []);
+  const stopHoverPlayback = useCallback(() => {
+    hoverActiveRef.current = false;
+    setHoverMutedFallback(false);
+    clearActivationWaiter();
+    try { hoverPlayerRef.current?.pause?.(); } catch { /* already torn down */ }
+  }, [clearActivationWaiter]);
+
+  // Explicit unmute affordance: the click IS the user activation the autoplay
+  // policy wants, so unmuting here always succeeds (and the window-level
+  // activation listener flips the module flag for every other player too).
+  const unmuteNow = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation();
+    e.preventDefault();
+    const el = hoverPlayerRef.current;
+    try {
+      if (el) {
+        el.muted = false;
+        el.volume = 0.5;
+        (el.play?.() as Promise<void> | undefined)?.catch?.(() => {});
+      }
+    } catch { /* ignore */ }
+    setHoverMutedFallback(false);
+  }, []);
+
+  // Controlled hover mode (playWhenHovered): the HOST owns hover detection —
+  // e.g. the bite-strip card, where the detail overlay is part of the card and
+  // must NOT pause playback when the pointer moves onto it.
+  const hoverControlled = typeof playWhenHovered === 'boolean';
+  useEffect(() => {
+    if (!hoverControlled) return;
+    if (playWhenHovered) startHoverPlayback();
+    else stopHoverPlayback();
+  }, [hoverControlled, playWhenHovered, startHoverPlayback, stopHoverPlayback]);
+
+  const handleHoverEnter = playOnHover && !hoverControlled ? startHoverPlayback : undefined;
+  const handleHoverLeave = playOnHover && !hoverControlled ? stopHoverPlayback : undefined;
   // 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`
@@ -349,8 +543,11 @@ function FilePlayer({
     );
   }
 
-  return (
+  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"
@@ -365,6 +562,8 @@ 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}
+      loop={loop}
       className={className}
       // Fill the wrapping aspect-ratio container instead of MuxPlayer's
       // intrinsic size. Without this, MuxPlayer renders at its default
@@ -373,7 +572,25 @@ function FilePlayer({
       // flickers and grows" CLS we're killing. With `aspect-video` on
       // the centered wrapper and `width/height: 100%` here, the box is
       // 16:9 from first paint and stays put.
-      style={{ width: '100%', height: '100%' }}
+      // `--controls: none` is media-chrome's kill switch for ALL player
+      // chrome — the chromeless preview mode. `--bottom-controls: none`
+      // hides only the bottom bar (center play/pause stays) — the
+      // bite-strip card look per Figma. Merged (never replacing) into the
+      // sizing style; custom properties need the CSSProperties cast.
+      style={{
+        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 ? (
         <track
@@ -386,6 +603,50 @@ function FilePlayer({
       ) : null}
     </MuxPlayer>
   );
+
+  // Center unmute control — shown while hover playback runs muted because the
+  // autoplay policy blocked sound. Best-practice pattern (Mux / FB / IG):
+  // muted autoplay + an explicit unmute affordance, never forced sound.
+  // 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 ? (
+    <button
+      type="button"
+      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"
+    >
+      <VolumeXmarkIcon size={56} />
+    </button>
+  ) : null;
+
+  // MuxPlayerProps has no pointer-event props — the hover-play handlers live
+  // on a full-size wrapper instead (only in UNCONTROLLED playOnHover mode;
+  // controlled playWhenHovered hosts own their hover detection). Either
+  // hover-capable mode gets a relative wrapper so the unmute badge can dock.
+  if (playOnHover && !hoverControlled) {
+    return (
+      <div
+        className="relative w-full h-full"
+        onPointerEnter={handleHoverEnter}
+        onPointerLeave={handleHoverLeave}
+      >
+        {player}
+        {unmuteBadge}
+      </div>
+    );
+  }
+  if (hoverControlled) {
+    return (
+      <div className="relative w-full h-full">
+        {player}
+        {unmuteBadge}
+      </div>
+    );
+  }
+  return player;
 }
 
 // -----------------------------------------------------------------------------

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -26,7 +26,8 @@ import { useRouter } from '../../embed-shims'
 import { PageShell } from '../layout/article-detail-layout'
 import { DetailPageSkeleton } from '../shared/detail-page-skeleton'
 import { EntityVideoSection } from '../features/entity-video-section'
-import { VideoBitesDisplay } from '../features/video-bites-display'
+import { VideoBitesStrip } from '../features/video-bites-strip'
+import { toStripProfile } from '../features/video-bites-shared'
 import { useVideoWarmup } from '../features/use-video-warmup'
 import { getCaptionsUrl } from '../features/captions-url'
 import { RichMarkdownRenderer } from '../ui/rich-markdown-renderer'
@@ -208,14 +209,14 @@ export function OnboardingGuideDetailView({
           </div>
         )}
 
-        {/* Video Bites */}
-        {guide.video_bites && guide.video_bites.length > 0 && (
-          <VideoBitesDisplay
-            bites={guide.video_bites as VideoTeaser[]}
-            filterPublished={true}
-            showTitle={false}
-          />
-        )}
+        {/* Video Bites — unified strip; renders nothing when no published bites. */}
+        <VideoBitesStrip
+          bites={(guide.video_bites as VideoTeaser[] | null) ?? []}
+          filterPublished={true}
+          showTitle={false}
+          profile={toStripProfile(guide.author)}
+          href={`/onboarding-guides/${guide.slug}`}
+        />
 
         {/* End-of-article author byline (avatar + linked name + bio) — the
             author DESCRIPTION block every article-shaped detail page renders.

package/src/components/shared/product-release/release-detail-page.tsx

@@ -25,6 +25,11 @@ import { DetailPageSkeleton } from '../detail-page-skeleton';
 import type { ChangelogEntry } from '../../../types/product-release';
 import type { TagAssoc } from '../../../types/blog';
 import type { VideoTeaser } from '../../../types/video-processing';
+import {
+  DEFAULT_VIDEO_BITES_TITLE,
+  toStripProfile,
+  type VideoBiteStripProfile,
+} from '../../features/video-bites-shared';
 
 // Types for injectable components
 export interface MarkdownRendererProps {
@@ -59,12 +64,6 @@ export interface DeliverySectionProps {
   isLoading: boolean;
 }
 
-export interface VideoSectionProps {
-  bites: VideoTeaser[];
-  title?: string;
-  filterPublished?: boolean;
-}
-
 // Type for the useRelease hook result
 export interface UseReleaseResult {
   data: unknown;
@@ -83,6 +82,10 @@ export interface VideoDisplaySectionProps {
   videoBites?: VideoTeaser[];
   bitesTitle?: string;
   filterPublishedBites?: boolean;
+  /** Profile shown in the bites strip's hover overlay (kit sources it from release.author). */
+  bitesProfile?: VideoBiteStripProfile | null;
+  /** Overlay-footer navigation target (the release the bites originated from). */
+  bitesHref?: string;
   srtContent?: string | null;
   captionsUrl?: string | null;
 }
@@ -96,7 +99,6 @@ export interface ReleaseDetailPageProps {
   MarkdownRenderer?: ComponentType<MarkdownRendererProps>;
   RoadmapSection?: ComponentType<RoadmapSectionProps>;
   DeliverySection?: ComponentType<DeliverySectionProps>;
-  VideoSection?: ComponentType<VideoSectionProps>;
   /** Injectable video display section with tabs for full/highlight video + summary + bites */
   VideoDisplaySection?: ComponentType<VideoDisplaySectionProps>;
   // API endpoints for fetching linked tasks
@@ -134,7 +136,6 @@ export function ReleaseDetailPage({
   MarkdownRenderer = DefaultMarkdownRenderer,
   RoadmapSection,
   DeliverySection,
-  VideoSection,
   VideoDisplaySection,
   roadmapApiEndpoint = '/api/roadmap',
   deliveryApiEndpoint = '/api/delivery',
@@ -335,8 +336,10 @@ export function ReleaseDetailPage({
             highlightVideoThumbnail={highlightVideoThumbnail}
             title={releaseTitle}
             videoBites={videoBites}
-            bitesTitle="Video Clips"
+            bitesTitle={DEFAULT_VIDEO_BITES_TITLE}
             filterPublishedBites={true}
+            bitesProfile={toStripProfile(author)}
+            bitesHref={typeof release.slug === 'string' ? `/releases/${release.slug}` : undefined}
             srtContent={release?.srt_content as string | null | undefined}
             captionsUrl={release?.captionsUrl as string | undefined}
           />
@@ -434,15 +437,6 @@ export function ReleaseDetailPage({
           MarkdownRenderer={MarkdownRenderer}
         />
 
-        {/* Video Bites Section - Only when VideoDisplaySection is not handling it */}
-        {!VideoDisplaySection && VideoSection && videoBites && videoBites.length > 0 && (
-          <VideoSection
-            bites={videoBites}
-            title="Video Clips"
-            filterPublished={true}
-          />
-        )}
-
         {/* Related Roadmap Items */}
         {RoadmapSection && (roadmapLoading || roadmapTasks.length > 0) && (
           <div className="space-y-4 w-full">

package/src/components/square-avatar.tsx

@@ -13,6 +13,8 @@ interface SquareAvatarProps {
   size?: number;
   /** If true, avatar takes full width with square aspect ratio */
   fullWidth?: boolean;
+  /** Corner treatment. `'square'` = rounded-lg (default, historical look); `'round'` = fully circular. */
+  shape?: 'square' | 'round';
   className?: string;
 }
 
@@ -20,7 +22,7 @@ interface SquareAvatarProps {
  * Square avatar with rounded edges used across cards / dashboards.
  * Automatically shows image (via proxied URL) or initials fallback.
  */
-export function SquareAvatar({ src, fallbackName = '', size = 56, fullWidth = false, className }: SquareAvatarProps) {
+export function SquareAvatar({ src, fallbackName = '', size = 56, fullWidth = false, shape = 'square', className }: SquareAvatarProps) {
   const initials = React.useMemo(() => {
     if (!fallbackName) return '';
     return fallbackName
@@ -36,7 +38,8 @@ export function SquareAvatar({ src, fallbackName = '', size = 56, fullWidth = fa
   return (
     <div
       className={cn(
-        'rounded-lg border border-ods-border flex items-center justify-center overflow-hidden bg-ods-bg-secondary',
+        'border border-ods-border flex items-center justify-center overflow-hidden bg-ods-bg-secondary',
+        shape === 'round' ? 'rounded-full' : 'rounded-lg',
         fullWidth ? 'w-full aspect-square' : 'flex-shrink-0',
         className,
       )}

package/src/components/user-display.tsx

@@ -11,6 +11,10 @@ interface UserDisplayProps {
   subtitle?: string | null;
   /** Avatar size in px (defaults 32) */
   size?: number;
+  /** Avatar corner treatment, forwarded to SquareAvatar. Default 'square'. */
+  shape?: 'square' | 'round';
+  /** Compact typography (14px/20px rows — video-bite overlay density). */
+  compact?: boolean;
   className?: string;
 }
 
@@ -18,16 +22,22 @@ interface UserDisplayProps {
  * Reusable horizontal avatar + name (+ optional subtitle) row that follows
  * the visual pattern used in CommentCard headers.
  */
-export function UserDisplay({ name, avatarUrl, subtitle, size = 32, className }: UserDisplayProps) {
+export function UserDisplay({ name, avatarUrl, subtitle, size = 32, shape = 'square', compact = false, className }: UserDisplayProps) {
   return (
     <div className={cn('flex items-center gap-2 min-w-0', className)}>
-      <SquareAvatar src={avatarUrl ?? undefined} fallbackName={name} size={size} />
+      <SquareAvatar src={avatarUrl ?? undefined} fallbackName={name} size={size} shape={shape} />
       <div className="min-w-0 flex-1">
-        <p className="font-['DM_Sans'] text-lg leading-[22px] text-ods-text-primary truncate">
+        <p className={cn(
+          "font-['DM_Sans'] text-ods-text-primary truncate",
+          compact ? 'text-xs leading-4 font-medium' : 'text-lg leading-[22px]',
+        )}>
           {name}
         </p>
         {subtitle && (
-          <span className="font-['DM_Sans'] text-md leading-[16px] text-ods-text-secondary truncate">
+          <span className={cn(
+            "font-['DM_Sans'] text-ods-text-secondary truncate block",
+            compact ? 'text-xs leading-4 font-medium' : 'text-md leading-[16px]',
+          )}>
             {subtitle}
           </span>
         )}