Show a trailer and learn line in the figure carousel

Threads an optional learn line through the figure data and renders
it, next to a trailer play control, in the carousel info overlay.

Author: michael-chipmates

client/src/api/figures.ts

@@ -15,6 +15,7 @@ export interface FigureBase {
 export interface TranslatedFigure {
   name: string;
   about: string;
+  learn?: string; // Golden line: "You will learn to ..."
   id: string;
 }
 
@@ -24,6 +25,7 @@ export interface TranslatedFigure {
 interface FigureTranslation {
   name?: string;
   about?: string;
+  learn?: string;
 }
 
 /**
@@ -83,6 +85,7 @@ export function getHistoricalFigures(language: string = 'en'): TranslatedFigure[
         return {
             name: translation.name || figure.baseNameEn,
             about: translation.about || `Information about ${figure.baseNameEn} is not available.`,
+            learn: translation.learn,
             id: figure.id
         };
     });

client/src/assets/translations/ui-de.json

@@ -547,6 +547,8 @@
     "about": "Über",
     "select": "Wählen",
     "wisdom": "Weisheit",
+    "trailerPlay": "Intro abspielen",
+    "trailerPause": "Pause",
     "echoOf": "Echo von",
     "echoOfName": "Echo von {name}",
     "categories": {

client/src/assets/translations/ui-en.json

@@ -545,6 +545,8 @@
     "about": "About",
     "select": "Select",
     "wisdom": "Wisdom",
+    "trailerPlay": "Play intro",
+    "trailerPause": "Pause",
     "echoOf": "Echo of",
     "echoOfName": "Echo of {name}",
     "categories": {

client/src/components/FigureCarousel.css

@@ -1218,4 +1218,85 @@
     animation:none!important;
     transform: none!important;
   }
+}
+
+/* ============================================================
+   Figure page revision — golden "you will learn" line + trailer
+   play control inside the info-overlay. Additive, existing tokens.
+   ============================================================ */
+
+/* Golden line — the "what you will learn" hook. Always visible. */
+.figure-carousel .figure-learn {
+  margin: 7px auto 0;
+  max-width: 540px;
+  color: var(--secondary-color);
+  font-family: var(--font-content, 'Libre Caslon Text', Georgia, serif);
+  font-size: clamp(0.9375rem, 0.875rem + 0.5vw, 1.25rem);
+  font-weight: 500;
+  line-height: 1.4;
+  text-align: center;
+  text-shadow:
+    0 1px 4px color-mix(in srgb, var(--utility-pure-black) 70%, transparent),
+    0 0 12px color-mix(in srgb, var(--gold-subtle) var(--a-30), transparent);
+}
+
+/* Trailer play control — paired with the golden line, always visible. */
+.figure-carousel .figure-trailer-btn {
+  display: flex;
+  width: fit-content;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  margin: 9px auto 2px;
+  min-height: 44px; /* WCAG touch target */
+  padding: 0 18px;
+  border-radius: 999px;
+  border: 1px solid color-mix(in srgb, var(--gold-subtle) var(--a-40), transparent);
+  background: color-mix(in srgb, var(--gold-subtle) var(--a-15), transparent);
+  color: var(--secondary-color);
+  font-family: var(--ui-font-family);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  transition: background 0.25s ease, border-color 0.25s ease;
+}
+
+.figure-carousel .figure-trailer-btn:hover {
+  background: color-mix(in srgb, var(--gold-subtle) var(--a-30), transparent);
+  border-color: color-mix(in srgb, var(--gold-subtle) var(--a-70), transparent);
+}
+
+.figure-carousel .figure-trailer-btn.is-active {
+  background: color-mix(in srgb, var(--gold-subtle) var(--a-30), transparent);
+  border-color: var(--secondary-color);
+}
+
+.figure-carousel .figure-trailer-btn:focus-visible {
+  outline: 2px solid var(--secondary-color);
+  outline-offset: 2px;
+}
+
+.figure-carousel .figure-trailer-btn svg {
+  flex-shrink: 0;
+}
+
+.figure-carousel .figure-trailer-label {
+  white-space: nowrap;
+}
+
+/* Small mobile (iPhone SE etc.) — keep the overlay compact. */
+@media (max-width: 375px) {
+  .figure-carousel .figure-learn {
+    font-size: 0.9375rem;
+    line-height: 1.35;
+    margin-top: 5px;
+    padding: 0 6px;
+  }
+
+  .figure-carousel .figure-trailer-btn {
+    margin: 7px auto 0;
+    padding: 0 15px;
+  }
 }

client/src/components/FigureCarousel.tsx

@@ -2,13 +2,14 @@ import React, { useState, useEffect, useCallback, FC, MouseEvent, KeyboardEvent
 import { useSwipeable } from 'react-swipeable';
 import { getHistoricalFigures } from '../api/figures';
 import { CategoryTab, ActionButton } from './Button';
-import { BookOpen, Check, Sparkle } from "@phosphor-icons/react";
+import { BookOpen, Check, Sparkle, Play, Pause } from "@phosphor-icons/react";
 import OptimizedImage from './OptimizedImage';
 import { useTranslation } from '../hooks/useTranslation';
 import WisdomMapModal from './WisdomMapModal';
 import type { Figure, Seed } from '../types/global';
 import { useUIStore } from '../stores/uiStore';
 import EchoExplainerHelp, { ECHO_EXPLAINER_HELP_ID } from './EchoExplainerHelp';
+import { useFigureTrailer } from '../hooks/useFigureTrailer';
 import './FigureCarousel.css';
 
 interface FigureCarouselProps {
@@ -49,6 +50,9 @@ const FigureCarousel: FC<FigureCarouselProps> = ({
 }) => {
   const { tString, tNode, language } = useTranslation();
 
+  // Figure page trailer — standalone audio player (play-on-tap, never autoplay)
+  const trailer = useFigureTrailer();
+
   // Echo explainer helper — show once for users who haven't seen it
   const shouldShowHelp = useUIStore((state) => state.shouldShowHelp);
   const [showEchoHelp, setShowEchoHelp] = useState<boolean>(() => shouldShowHelp(ECHO_EXPLAINER_HELP_ID));
@@ -300,6 +304,12 @@ const FigureCarousel: FC<FigureCarouselProps> = ({
     return () => clearTimeout(preloadTimer);
   }, [currentIndex, figures, hasNavigated, preloadedImages]);
 
+  // Stop any trailer when the figure changes or the carousel closes — never
+  // leave audio playing behind a swipe, a category switch, or a close.
+  useEffect(() => {
+    trailer.stop();
+  }, [currentFigure?.id, isOpen, trailer.stop]);
+
   const handleSelect = () => {
     if (onSelectFigure) onSelectFigure(currentFigure);
     else console.error('onSelectFigure is not defined');
@@ -460,6 +470,18 @@ const FigureCarousel: FC<FigureCarouselProps> = ({
     const handleInfoOverlayClick = () => {
       setShowFullInfo(!showFullInfo);
     };
+
+    const trailerStatus = trailer.activeId === currentFigure.id ? trailer.status : 'idle';
+    const trailerEngaged = trailerStatus === 'loading' || trailerStatus === 'playing';
+
+    const handleTrailerClick = (e: MouseEvent<HTMLButtonElement>) => {
+      e.stopPropagation(); // don't toggle the about overlay
+      trailer.toggle(currentFigure.id, language);
+    };
+    // Keep Enter/Space on the trailer button from also toggling the overlay.
+    const handleTrailerKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+      if (e.key === 'Enter' || e.key === ' ') e.stopPropagation();
+    };
 
     return (
       <div className="main-image-section">
@@ -486,15 +508,32 @@ const FigureCarousel: FC<FigureCarouselProps> = ({
             aria-label={tString('carousel.toggleInfo', 'Toggle figure information')}
           >
             <h2>{getDisplayName(currentFigure)}</h2>
+
+            {currentFigure.learn && (
+              <p className="figure-learn">{currentFigure.learn}</p>
+            )}
+
+            <button
+              type="button"
+              className={`figure-trailer-btn ${trailerEngaged ? 'is-active' : ''}`}
+              onClick={handleTrailerClick}
+              onKeyDown={handleTrailerKeyDown}
+            >
+              {trailerEngaged
+                ? <Pause size={16} weight="fill" />
+                : <Play size={16} weight="fill" />}
+              <span className="figure-trailer-label">
+                {trailerEngaged
+                  ? tString('figures.trailerPause', 'Pause')
+                  : tString('figures.trailerPlay', 'Play intro')}
+              </span>
+            </button>
+
             {showFullInfo && currentFigure.about && (
               <div className="figure-about-text">
-                {currentFigure.about.split('\n\n').map((line, index) => {
-                  // Check if this line contains bullet points (tags)
-                  if (line.includes('•')) {
-                    return <div key={index} className="golden-tags no-justify">{line}</div>;
-                  }
-                  return <div key={index}>{line}</div>;
-                })}
+                {currentFigure.about.split('\n\n').map((para, index) => (
+                  <div key={index}>{para}</div>
+                ))}
               </div>
             )}
           </div>

client/src/types/global.ts

@@ -12,6 +12,7 @@ export interface Figure {
   id: string; // e.g., 'plato', 'aurelius'
   name: string; // Display name
   about?: string; // Description
+  learn?: string; // Golden line: "You will learn to ..." (figure page revision)
   image?: string; // Avatar path
   topic?: string; // Main topics/themes
   metadata?: FigureMetadata;