webs-sdk 0.19.64 → 0.19.65

package/docs/FOR_YOU_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,1413 @@
+# ForYou — Guía de implementación del SDK
+
+> **Versión SDK:** 0.18.83+  
+> **Componente principal:** `ForYouPage`
+
+---
+
+## Índice
+
+1. [Concepto](#concepto)
+2. [Sistema anterior vs. sistema nuevo](#sistema-anterior-vs-sistema-nuevo)
+3. [Instalación](#instalación)
+4. [Uso básico — ForYouPage](#uso-básico--foryoupage)
+5. [Internacionalización (locale)](#internacionalización-locale)
+6. [Navegación](#navegación)
+7. [Endpoints — modos de llamada a API](#endpoints--modos-de-llamada-a-api)
+8. [Referencia de props: ForYouPage](#referencia-de-props-foryoupage)
+9. [Referencia de props: ForYouFeatureConfig](#referencia-de-props-foryoufeatureconfig)
+10. [Referencia de props: ForYouCardVisual](#referencia-de-props-foryoucardvisual)
+11. [Referencia de props: ForYouPageTheme](#referencia-de-props-foryoupagetheme)
+12. [forYouFetch — helper de API](#foryoufetch--helper-de-api)
+13. [Features disponibles](#features-disponibles)
+14. [Uso de hooks fuera de ForYouPage](#uso-de-hooks-fuera-de-foryoupage)
+15. [Ejemplo completo Winsports](#ejemplo-completo-winsports)
+16. [Descargas y CORS — Proxy de medios](#descargas-y-cors--proxy-de-medios)
+17. [Feature: CreativeFaceSwap — ejemplos + endpoints](#feature-creativefaceswap--ejemplos--endpoints)
+18. [Migración desde el sistema anterior](#migración-desde-el-sistema-anterior)
+
+---
+
+## Concepto
+
+`ForYouPage` es el único componente que necesitas importar para montar la sección completa de ForYou (Fanzone / Para Ti) en cualquier portal.
+
+**Antes (sistema antiguo):** importabas componente a componente y construías la página en el proyecto.  
+**Ahora (sistema nuevo):** un único import, toda la lógica configurada vía props.
+
+Ambos sistemas son **100% compatibles y coexistentes**. Puedes usar el sistema anterior en paralelo al nuevo sin conflicto.
+
+---
+
+## Sistema anterior vs. sistema nuevo
+
+```tsx
+// ─── SISTEMA ANTERIOR ─────────────────────────────────────────────────────────
+// Una feature = un import + su propia página con navegación manual
+
+import { Wallpapers, Quiz, Ringtone } from 'webs-sdk'
+
+function ForYouPage() {
+  const [active, setActive] = useState<string | null>(null)
+  // ...construir navegación, botones de volver, breadcrumbs, etc.
+}
+
+// ─── SISTEMA NUEVO ────────────────────────────────────────────────────────────
+// Un único import, toda la página configurada vía props
+
+import { ForYouPage } from 'webs-sdk'
+
+function MyForYouPage() {
+  return (
+    <ForYouPage
+      locale="es"
+      features={{
+        wallpapers: { card: { desktopImage: '/img/wallpapers.jpg' } },
+        quiz:       { card: { desktopImage: '/img/quiz.jpg' } },
+        ringtone:   { card: { desktopImage: '/img/ringtone.jpg' } },
+      }}
+    />
+  )
+}
+```
+
+---
+
+## Instalación
+
+```bash
+npm install webs-sdk
+# o
+yarn add webs-sdk
+```
+
+---
+
+## Uso básico — ForYouPage
+
+```tsx
+import { ForYouPage } from 'webs-sdk'
+
+export default function ForYouSection() {
+  return (
+    <ForYouPage
+      locale="es"
+      features={{
+        ringtone: {
+          card: {
+            desktopImage: '/images/ringtone-desktop.jpg',
+            mobileImage: '/images/ringtone-mobile.jpg',
+            ctaColor: '#FF5500',
+            backgroundColor: '#F9F9F9',
+          },
+          config: { tags: 'ringtone' },
+        },
+        wallpapers: {
+          card: {
+            desktopImage: '/images/wallpapers-desktop.jpg',
+            imageOnRight: false,
+            ctaColor: '#E10600',
+          },
+          config: { tags: 'wallpaper' },
+        },
+        quiz: {
+          card: {
+            desktopImage: '/images/quiz-desktop.jpg',
+            ctaColor: '#0066CC',
+          },
+          config: { tags: 'quiz' },
+        },
+      }}
+    />
+  )
+}
+```
+
+**¿Qué hace esto?**
+- Muestra un **hub** con las cards de cada feature.
+- Al pulsar una card, navega internamente a la vista del componente.
+- Botón "Volver" con icono SVG para regresar al hub.
+- Scroll automático al tope al entrar/salir.
+- URL actualizada con `?feature=<key>` para deep-linking.
+
+---
+
+## Internacionalización (locale)
+
+El SDK incluye traducciones para **8 idiomas**:
+
+| Código | Idioma | RTL |
+|--------|--------|-----|
+| `en`   | English (default) | No |
+| `es`   | Español | No |
+| `fr`   | Français | No |
+| `pl`   | Polski | No |
+| `nl`   | Nederlands | No |
+| `tr`   | Türkçe | No |
+| `ro`   | Română | No |
+| `ar`   | العربية | **Sí** |
+
+```tsx
+// Solo pasar el locale — el SDK usa sus propias traducciones
+<ForYouPage locale="es" features={...} />
+
+// Override puntual — solo los textos que necesites cambiar
+<ForYouPage
+  locale="es"
+  translations={{
+    backButtonText: '← Atrás',
+    cards: {
+      ringtone: { title: 'Mis Tonos', ctaText: 'Ver más' },
+    },
+  }}
+  features={...}
+/>
+```
+
+**Árabe (RTL):** al pasar `locale="ar"`, el SDK añade automáticamente `dir="rtl"` al contenedor raíz.
+
+### Lógica de merge
+
+```
+SDK defaults 'en' → SDK defaults [locale] → translations (proyecto)
+```
+
+Los textos del proyecto **siempre tienen prioridad** sobre los del SDK.
+
+---
+
+## Navegación
+
+`ForYouPage` gestiona toda la navegación internamente:
+
+- **`?feature=<key>` en la URL** — se actualiza con `window.history.pushState` al entrar/salir. Permite deep-linking directo (p.ej.: `/fanzone?feature=quiz` abre el quiz directamente).
+- **Botón "Atrás" del navegador** — listener `popstate` que vuelve al hub o a la feature anterior.
+- **Scroll automático** — `containerRef.scrollIntoView()` al cambiar de vista.
+- **`initialFeature` prop** — para arrancar directamente en una feature desde el código.
+- **`hideBreadcrumb` en Wallpapers** — cuando Wallpapers se renderiza dentro de ForYouPage, su breadcrumb interno se oculta automáticamente (el hub ya proporciona navegación).
+
+```tsx
+// Abrir directamente en quiz (p.ej. desde un banner externo)
+<ForYouPage initialFeature="quiz" features={...} />
+
+// O leer el query param manualmente y pasarlo
+const feature = new URLSearchParams(location.search).get('feature')
+<ForYouPage initialFeature={feature as keyof ForYouFeatures} features={...} />
+```
+
+---
+
+## Endpoints — modos de llamada a API
+
+### Modo 1: URL directa (sistema anterior — compatible)
+
+```ts
+config: {
+  apiUrl: '/api/get_contents_by_tags',
+  tags: 'quiz',
+  locale: 'es',
+}
+```
+
+### Modo 2: apiBaseUrl (SDK construye la URL)
+
+```ts
+config: {
+  apiBaseUrl: 'https://api.winsports.co',
+  tags: ['quizws', 'quiz'],
+  locale: 'es',
+}
+```
+
+El SDK mapea el preset `getGlobalContentsByTags` → `/api/get_contents_by_tags`.
+
+### Modo 3: Multi-preset (múltiples llamadas en paralelo)
+
+```ts
+config: {
+  apiBaseUrl: 'https://api.winsports.co',
+  locale: 'es',
+  contents: [
+    {
+      preset: 'getGlobalContentsByIDs',
+      includeIds: [103433, 103420, 103396, 103371],
+    },
+    {
+      preset: 'getGlobalContentsByTags',
+      tags: ['quizws'],
+    },
+  ],
+}
+```
+
+**Presets disponibles:**
+
+| Preset | Endpoint |
+|--------|----------|
+| `getGlobalContentsByTags` | `/api/get_contents_by_tags` |
+| `getGlobalContentsByIDs` | `/api/get_contents_by_tags` (con `include_ids`) |
+| `getContentsByCategory` | `/api/get_global_api_contents_by_category` |
+| `getCollectionByTags` | `/api/get_global_api_collections_by_tags` |
+| `getContentPreset` | `/api/content-preset` |
+
+Los resultados de múltiples llamadas se fusionan y **deduplicados por `id`**.
+
+---
+
+## Referencia de props: ForYouPage
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `features` | `ForYouFeatures` | **requerido** | Features a mostrar. Cada key con `card` aparece en el hub. |
+| `order` | `Array<keyof ForYouFeatures>` | Orden del objeto | Orden de renderizado de las cards en el hub. |
+| `hubBanner` | `ForYouHubBanner` | - | Banner hero opcional encima de las cards. |
+| `locale` | `ForYouLocale` | `'en'` | Idioma del SDK. |
+| `translations` | `ForYouPageTranslations` | SDK defaults | Override de textos sobre el locale. |
+| `pageTheme` | `ForYouPageTheme` | - | Tema visual de la página. |
+| `initialFeature` | `keyof ForYouFeatures` | - | Feature que se abre al montar. |
+
+---
+
+## Referencia de props: WallpapersFeatureOverride — tabs
+
+El feature `wallpapers` soporta un selector de pestañas opcionales para filtrar contenido por categoría (como en Winsports). Se activa añadiendo `tabs` a la configuración del feature.
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `tabs` | `WallpapersTab[]` | Array de pestañas. Si se define, aparece el selector encima del componente. |
+| `tabsTheme` | `object` | Personalización visual del selector de tabs (ver tabla abajo). |
+
+### WallpapersTab
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `label` | `string` | Texto visible en la pestaña. |
+| `tag` | `string` | Tag de API para filtrar los wallpapers de esta categoría. |
+
+### tabsTheme
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `activeColor` | `string` | `'#001B5E'` | Fondo de la tab activa. |
+| `activeTextColor` | `string` | `'#FFFFFF'` | Texto de la tab activa. |
+| `inactiveColor` | `string` | `'transparent'` | Fondo de la tab inactiva. |
+| `inactiveTextColor` | `string` | `'#001B5E'` | Texto de la tab inactiva. |
+| `borderColor` | `string` | `'#E5E7EB'` | Color del borde inferior del selector. |
+
+### Ejemplo con tabs (estilo Winsports)
+
+```tsx
+<ForYouPage
+  locale="es"
+  features={{
+    wallpapers: {
+      card: {
+        desktopImage: 'https://cdn.winsports.co/fanzone/wallpapers-card.jpg',
+        ctaColor: '#E6001E',
+      },
+      config: {
+        apiUrl: '/api/get_contents_by_tags',
+        locale: 'es',
+        website_id: '42',
+        heroBannerImage: 'https://cdn.winsports.co/fanzone/wallpapers-banner.jpg',
+      },
+      tabs: [
+        { label: 'Fútbol',    tag: 'wallpaper-futbol'    },
+        { label: 'Ciclismo',  tag: 'wallpaper-ciclismo'  },
+        { label: 'Béisbol',   tag: 'wallpaper-beisbol'   },
+        { label: 'Todos',     tag: 'wallpaper-winsports' },
+      ],
+      tabsTheme: {
+        activeColor:       '#E6001E',
+        activeTextColor:   '#FFFFFF',
+        inactiveTextColor: '#333333',
+        borderColor:       '#E5E7EB',
+      },
+    },
+  }}
+/>
+```
+
+### Sin tabs (por defecto)
+
+Si no se define `tabs`, el componente muestra todos los wallpapers del tag configurado en `config.tags`:
+
+```tsx
+wallpapers: {
+  card: { desktopImage: '/img/wallpapers.jpg' },
+  config: { apiUrl: '/api/get_contents_by_tags', tags: 'wallpaper' },
+}
+```
+
+---
+
+## Referencia de props: ForYouHubBanner
+
+Banner hero configurable que aparece sobre las cards en la vista hub. Completamente opcional.
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `desktopImage` | `string` | **requerido** | Imagen de fondo desktop. |
+| `mobileImage` | `string` | = desktopImage | Imagen de fondo mobile. |
+| `imageAlt` | `string` | `''` | Alt text de la imagen. |
+| `title` | `string` | - | Título principal sobre la imagen. |
+| `subtitle` | `string` | - | Subtítulo / descripción. |
+| `backgroundColor` | `string` | `'transparent'` | Color de fondo (visible si no hay imagen). |
+| `titleColor` | `string` | `'#FFFFFF'` | Color del título. |
+| `subtitleColor` | `string` | `'#FFFFFF'` | Color del subtítulo. |
+| `minHeight` | `string` | `'500px'` | Altura mínima del banner. |
+| `padding` | `string` | `'40px 24px'` | Padding interno del texto. |
+| `highlights` | `ForYouHubBannerHighlight[]` | - | Barra de highlights (iconos + texto) debajo del banner. |
+| `highlightsBackgroundColor` | `string` | `'#FFFFFF'` | Fondo de la barra de highlights. |
+| `highlightsTextColor` | `string` | `'#111827'` | Color del texto de highlights. |
+| `highlightsIconColor` | `string` | = highlightsTextColor | Color del icono SVG de highlights. |
+
+### ForYouHubBannerHighlight
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `icon` | `string` | Raw SVG string (`<svg>...`) o URL de imagen. |
+| `text` | `string` | Texto del highlight. |
+
+### Ejemplo con banner completo (estilo Winsports)
+
+```tsx
+<ForYouPage
+  locale="es"
+  hubBanner={{
+    desktopImage: 'https://cdn.winsports.co/fanzone/hub-banner-desktop.jpg',
+    mobileImage:  'https://cdn.winsports.co/fanzone/hub-banner-mobile.jpg',
+    title: '¡Bienvenido a Para Ti!',
+    subtitle: 'El espacio de WinSports para personalizar tu móvil con el contenido deportivo más original.',
+    backgroundColor: '#1A1063',
+    titleColor: '#FFFFFF',
+    subtitleColor: '#FFFFFF',
+    minHeight: '520px',
+    highlights: [
+      {
+        icon: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"/></svg>',
+        text: 'Elige el mejor contenido para cada momento',
+      },
+      {
+        icon: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z"/></svg>',
+        text: 'Despierta la creatividad que tienes dentro',
+      },
+      {
+        icon: '/icons/share.svg',
+        text: 'Guarda y comparte tus creaciones',
+      },
+    ],
+    highlightsBackgroundColor: '#FFFFFF',
+    highlightsTextColor: '#1A1063',
+  }}
+  features={WINSPORTS_FEATURES}
+/>
+```
+
+### Sin banner (por defecto)
+
+Si no se pasa `hubBanner`, el hub muestra directamente las cards:
+
+```tsx
+<ForYouPage locale="es" features={features} />
+```
+
+---
+
+## Referencia de props: ForYouFeatureConfig
+
+Compartido por todas las features que hacen llamada a API:
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `apiUrl` | `string` | URL directa del endpoint (sistema anterior). |
+| `apiBaseUrl` | `string` | Base URL. El SDK construye la URL según el preset. |
+| `tags` | `string \| string[]` | Tags para la petición. |
+| `contents` | `ForYouContentPreset[]` | Multi-preset: varias llamadas en paralelo. |
+| `locale` | `string` | Locale para esta feature (override del global). |
+| `website_id` | `string` | Website ID para la petición. |
+| `initialCount` | `number` | Items visibles al inicio. |
+| `loadMoreCount` | `number` | Items adicionales por "load more". |
+
+---
+
+## Referencia de props: ForYouCardVisual
+
+Configuración visual de la card del hub (textos en `translations.cards.*`):
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `desktopImage` | `string` | **requerido** | Imagen desktop. |
+| `mobileImage` | `string` | = desktopImage | Imagen mobile. |
+| `imageAlt` | `string` | `''` | Alt text. |
+| `imageOnRight` | `boolean` | `true` | Imagen a la derecha o izquierda. |
+| `titleColor` | `string` | `'#001B5E'` | Color del título. |
+| `descriptionColor` | `string` | `'#001B5E'` | Color de la descripción. |
+| `ctaColor` | `string` | `'#FF5500'` | Color del botón. |
+| `ctaHoverColor` | `string` | `'#ff1600'` | Color hover del botón. |
+| `backgroundColor` | `string` | `'#F9F9F9'` | Color de fondo. |
+| `paddingClass` | `string` | `'py-12 md:py-16 lg:py-20'` | Padding vertical (Tailwind). |
+
+---
+
+## Referencia de props: ForYouPageTheme
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `backgroundColor` | `string` | `'transparent'` | Fondo de la página. |
+| `sectionSpacing` | `string` | `'0'` | Margen entre secciones del hub. |
+| `backButtonStyle` | `React.CSSProperties` | - | Estilos inline del botón volver. |
+| `backButtonClassName` | `string` | - | Clase CSS del botón volver. |
+| `backButtonIconColor` | `string` | `'currentColor'` | Color del icono SVG. |
+| `showBackButtonIcon` | `boolean` | `true` | Mostrar/ocultar icono SVG. |
+
+---
+
+## forYouFetch — helper de API
+
+El helper `forYouFetch` se exporta independientemente para usarlo en proyectos sin `ForYouPage`:
+
+```ts
+import { forYouFetch } from 'webs-sdk'
+
+// Modo simple
+const items = await forYouFetch({
+  apiUrl: '/api/get_contents_by_tags',
+  tags: 'quiz',
+  locale: 'es',
+})
+
+// Modo multi-preset
+const items = await forYouFetch({
+  apiBaseUrl: 'https://api.winsports.co',
+  locale: 'es',
+  website_id: '42',
+  contents: [
+    { preset: 'getGlobalContentsByIDs', includeIds: [103433, 103420] },
+    { preset: 'getGlobalContentsByTags', tags: ['quizws'] },
+  ],
+})
+```
+
+---
+
+## Features disponibles
+
+| Key | Componente | Tags por defecto |
+|-----|-----------|-----------------|
+| `ringtone` | `Ringtone` | `ringtone` |
+| `wallpapers` | `Wallpapers` | `wallpaper` |
+| `wallpapersName` | `WallpapersName` | `wallpaper_name` |
+| `memeGenerator` | `MemeGenerator` | `meme` |
+| `quiz` | `Quiz` | `quiz` |
+| `stickers` | `Stickers` | `stickers` |
+| `avatarAI` | `AvatarAI` | (no aplica) |
+| `creativeFaceSwap` | `CreativeFaceSwap` | (no aplica) |
+| `arFilters` | `ARFilters` | (no aplica) |
+
+---
+
+## Uso de hooks fuera de ForYouPage
+
+Los hooks también se exportan independientemente para casos donde se necesita lógica sin UI:
+
+```ts
+import { useQuiz, useWallpapers, useRingtone, useStickers } from 'webs-sdk'
+
+// Con multi-preset
+const { quizItems, handleOpenQuiz } = useQuiz({
+  config: {
+    apiBaseUrl: 'https://api.winsports.co',
+    locale: 'es',
+    contents: [
+      { preset: 'getGlobalContentsByIDs', includeIds: [103433, 103420] },
+      { preset: 'getGlobalContentsByTags', tags: ['quizws'] },
+    ],
+  },
+})
+```
+
+---
+
+## Ejemplo completo Winsports
+
+```tsx
+import { ForYouPage } from 'webs-sdk'
+import type { ForYouFeatures, ForYouLocale } from 'webs-sdk'
+
+const WINSPORTS_FEATURES: ForYouFeatures = {
+  quiz: {
+    card: {
+      desktopImage: 'https://cdn.winsports.co/fanzone/quiz-desktop.png',
+      mobileImage:  'https://cdn.winsports.co/fanzone/quiz-mobile.png',
+      imageOnRight: true,
+      ctaColor:     '#E6001E',
+      backgroundColor: '#F5F5F5',
+    },
+    config: {
+      apiBaseUrl: 'https://api.winsports.co',
+      locale: 'es',
+      website_id: '42',
+      contents: [
+        { preset: 'getGlobalContentsByIDs', includeIds: [103433, 103420, 103396, 103371] },
+        { preset: 'getGlobalContentsByTags', tags: ['quizws'] },
+      ],
+    },
+    onQuizStart: (quiz) => console.log('Quiz started:', quiz.title),
+    onQuizComplete: (score, total) => console.log(`Score: ${score}/${total}`),
+  },
+
+  ringtone: {
+    card: {
+      desktopImage: 'https://cdn.winsports.co/fanzone/ringtone-desktop.png',
+      imageOnRight: false,
+      ctaColor:     '#E6001E',
+      backgroundColor: '#FFFFFF',
+    },
+    config: {
+      apiBaseUrl: 'https://api.winsports.co',
+      tags: ['ringtone', 'ringtone-winsports'],
+      locale: 'es',
+      website_id: '42',
+    },
+  },
+
+  wallpapers: {
+    card: {
+      desktopImage: 'https://cdn.winsports.co/fanzone/wallpapers-desktop.png',
+      ctaColor: '#E6001E',
+      backgroundColor: '#F5F5F5',
+    },
+    config: {
+      apiBaseUrl: 'https://api.winsports.co',
+      tags: 'wallpaper-winsports',
+      locale: 'es',
+      website_id: '42',
+    },
+    onDownloadSuccess: (w) => console.log('Downloaded:', w.title),
+  },
+
+  stickers: {
+    card: {
+      desktopImage: 'https://cdn.winsports.co/fanzone/stickers-desktop.png',
+      imageOnRight: false,
+      ctaColor: '#E6001E',
+      backgroundColor: '#FFFFFF',
+    },
+    config: {
+      apiBaseUrl: 'https://api.winsports.co',
+      tags: ['stickers', 'stickers-winsports'],
+      locale: 'es',
+      website_id: '42',
+    },
+  },
+}
+
+export default function FanzoneForYou() {
+  return (
+    <ForYouPage
+      locale="es"
+      features={WINSPORTS_FEATURES}
+      order={['quiz', 'ringtone', 'wallpapers', 'stickers']}
+      pageTheme={{
+        backgroundColor: '#FFFFFF',
+        sectionSpacing: '0',
+        backButtonIconColor: '#E6001E',
+      }}
+    />
+  )
+}
+```
+
+---
+
+## Descargas y CORS — Proxy de medios
+
+Algunos componentes del SDK (Stickers, MemeGenerator) descargan archivos desde CDNs de terceros.
+Si el CDN no incluye el header `Access-Control-Allow-Origin`, el navegador bloquea la petición y
+el SDK cae en el **fallback** abriendo la URL en una nueva pestaña en lugar de descargar el archivo.
+
+> **Síntoma típico**: al pulsar "Download" en Stickers o "DOWNLOAD" en MemeGenerator, se abre el
+> contenido en una nueva pestaña en lugar de descargarse directamente.
+
+### Solución: proxy de medios en el proyecto
+
+Hay que crear una ruta API en el propio proyecto que haga de intermediario. Como la petición sale
+del servidor (no del navegador), no hay restricciones CORS.
+
+#### Next.js — App Router (`app/api/media-proxy/route.ts`)
+
+```ts
+// app/api/media-proxy/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+
+export async function GET(req: NextRequest) {
+  const url = req.nextUrl.searchParams.get('url')
+  if (!url) return new NextResponse('Missing url param', { status: 400 })
+
+  try {
+    const upstream = await fetch(url)
+    if (!upstream.ok) return new NextResponse('Upstream error', { status: upstream.status })
+
+    const blob = await upstream.blob()
+
+    return new NextResponse(blob, {
+      headers: {
+        'Content-Type': upstream.headers.get('content-type') || 'application/octet-stream',
+        'Content-Disposition': 'attachment',
+        'Cache-Control': 'public, max-age=86400',
+      },
+    })
+  } catch {
+    return new NextResponse('Proxy error', { status: 500 })
+  }
+}
+```
+
+#### Next.js — Pages Router (`pages/api/media-proxy.ts`)
+
+```ts
+// pages/api/media-proxy.ts
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const url = req.query.url as string
+  if (!url) return res.status(400).send('Missing url param')
+
+  try {
+    const upstream = await fetch(url)
+    if (!upstream.ok) return res.status(upstream.status).send('Upstream error')
+
+    const buffer = Buffer.from(await upstream.arrayBuffer())
+    res.setHeader('Content-Type', upstream.headers.get('content-type') || 'application/octet-stream')
+    res.setHeader('Content-Disposition', 'attachment')
+    res.setHeader('Cache-Control', 'public, max-age=86400')
+    res.send(buffer)
+  } catch {
+    res.status(500).send('Proxy error')
+  }
+}
+```
+
+### Configurar el proxy en ForYouPage
+
+Una vez creada la ruta, pásala al `ForYouPage` mediante las props correspondientes:
+
+```tsx
+<ForYouPage
+  locale="es"
+  features={{
+    stickers: {
+      config: { ... },
+      // ← ruta relativa del proxy: sin CORS porque es el mismo origen
+      downloadProxyUrl: '/api/media-proxy?url=',
+    },
+    memeGenerator: {
+      config: { ... },
+      // ← mismo proxy, el SDK lo usa para cargar la imagen en el canvas
+      imageProxyUrl: '/api/media-proxy?url=',
+    },
+  }}
+/>
+```
+
+### Configurar el proxy en componentes standalone
+
+```tsx
+// Stickers standalone
+<Stickers
+  config={stickersConfig}
+  downloadProxyUrl="/api/media-proxy?url="
+/>
+
+// MemeGenerator standalone
+<MemeGenerator
+  config={memeConfig}
+  imageProxyUrl="/api/media-proxy?url="
+/>
+```
+
+### Usar `downloadFile` del SDK directamente
+
+Si necesitas descargar archivos en tu propio código (fuera de los componentes), el SDK exporta
+la función `downloadFile`:
+
+```ts
+import { downloadFile } from 'webs-sdk'
+
+// Con proxy (recomendado para CDNs de terceros):
+await downloadFile(
+  'https://cdn.example.com/sticker.png',
+  'mi-sticker.png',
+  '/api/media-proxy?url='
+)
+
+// Sin proxy (solo si el CDN tiene CORS habilitado):
+await downloadFile('https://cdn.example.com/sticker.png', 'mi-sticker.png')
+```
+
+> `downloadFile` intenta descargar via fetch+blob. Si falla (p.ej. CORS sin proxy), abre
+> la URL en una nueva pestaña como fallback.
+
+---
+
+## Feature: Quiz — tipos de quiz y pantalla de resultado
+
+El componente `Quiz` diferencia automáticamente entre **3 modos** según los datos del backend:
+
+### Modo 1: Quiz por puntos (`personality = false`)
+
+Cada respuesta tiene un valor numérico (`puntos`). Se muestra la puntuación obtenida vs el máximo posible, y el mensaje de resultado correspondiente al rango.
+
+```
+🏆
+"You got 30/80 points"      ← score / dynamicMax (suma de maxPoints por pregunta)
+"Vous avez des notions..."   ← resultMessage del rango matched
+```
+
+### Modo 2: Quiz de personalidad (`personality = true`)
+
+El campo `personality: true` en el `metadata` del item indica que **no se debe mostrar la puntuación numérica**. Solo aparece el mensaje de resultado en grande.
+
+```
+🏆
+"Eres un experto del fútbol"   ← solo resultMessage, sin puntuación
+```
+
+### Modo 3: Quiz legacy (correcto/incorrecto)
+
+Items sin `quiz_configuration` (formato antiguo con `correct_option` / `option_a..d`). Se muestra el número de aciertos sobre el total de preguntas.
+
+```
+🏆
+"3/5"   ← score / totalPreguntas
+```
+
+### Cómo el SDK detecta el modo
+
+El `personality` se extrae automáticamente del `metadata` del item de la lista:
+
+```json
+{
+  "id": 100,
+  "title": "¿Qué entrenador eres?",
+  "contents": "832",
+  "metadata": "{\"personality\": true}"
+}
+```
+
+El SDK acepta tanto `boolean` como `string 'true'`. **No hay que configurar nada en el proyecto** — el SDK detecta el tipo por sí solo.
+
+### Cálculo del total máximo (`dynamicMax`)
+
+El SDK calcula el total máximo real sumando el `maxPoints` de cada pregunta (la opción con más puntos de cada pregunta):
+
+```
+dynamicMax = Σ Math.max(...options[i].points)
+```
+
+Fallbacks si alguna pregunta no tiene `maxPoints`:
+1. `results[last].maxPoints` (tope del último resultado definido en el backend)
+2. `score` del usuario (fallback extremo)
+
+### `scoreLabel` — personalización
+
+El texto del score es configurable vía `texts.scoreLabel`. Usa `{score}` y `{total}` como variables:
+
+```tsx
+quiz: {
+  texts: {
+    scoreLabel: 'Obtuviste {score} de {total} puntos',  // es
+    // o
+    scoreLabel: 'Tu as obtenu {score}/{total} points',  // fr
+  }
+}
+```
+
+Default del SDK: `'You got {score}/{total} points'`
+
+---
+
+## Feature: WallpapersName — modo dual (clásico vs AETemplates)
+
+La feature `wallpapersName` soporta **dos modos** seleccionados automáticamente según las props:
+
+### Modo clásico (sistema anterior)
+
+Usa `WallpapersName` con contenido cargado vía `get_contents_by_tags`. Compatible con el sistema antiguo.
+
+```tsx
+wallpapersName: {
+  card: { desktopImage: '/img/wallpapers-name.jpg' },
+  config: {
+    apiUrl: '/api/get_contents_by_tags',
+    tags: 'wallpaper_name',
+    website_id: '42',
+    locale: 'es',
+  },
+  howItWorksSteps: [
+    { title: 'Elige una plantilla', description: 'Busca la que más te guste' },
+    { title: 'Escribe tu nombre', description: 'Personaliza con tu nombre' },
+    { title: 'Descarga', description: 'Guárdalo en tu móvil' },
+  ],
+}
+```
+
+### Modo nuevo — AETemplates (sistema unificado)
+
+Cuando se proporciona `aeTemplatesConfig`, `ForYouPage` renderiza `WallpapersNamePage`, que integra en una sola pieza:
+1. **Header** con título y descripción
+2. **"How does it work?"** — carousel de pasos con dots de navegación
+3. **AETemplatesSection** — motor de templates de After Effects con tabs, modal de personalización y botón CUSTOMISE
+
+```tsx
+import type { WallpapersNameFeatureOverride } from 'webs-sdk'
+
+const wallpapersNameFeature: WallpapersNameFeatureOverride = {
+  card: {
+    desktopImage: '/img/wallpapers-name-desktop.jpg',
+    ctaColor: '#E6001E',
+  },
+  // Textos del header
+  pageTexts: {
+    title: 'Wallpapers con tu nombre',
+    description: 'Personaliza wallpapers deportivos con tu nombre o el de tu equipo',
+    howItWorksTitle: '¿Cómo funciona?',
+  },
+  // Pasos del carousel "Cómo funciona"
+  howItWorksSteps: [
+    { title: 'Elige una plantilla', image: '/img/step1.jpg' },
+    { title: 'Escribe tu nombre',   image: '/img/step2.jpg' },
+    { title: 'Descarga',            image: '/img/step3.jpg' },
+  ],
+  // ← La presencia de aeTemplatesConfig activa el modo nuevo
+  aeTemplatesConfig: {
+    apiUrl: '/api/get_ae_templates',
+    langId: 27,
+    clientId: 50,
+    tabs: [
+      { id: 'entertainment', label: 'Entertainment', type: 9 },
+      { id: 'sports',        label: 'Sports',        type: 10 },
+    ],
+    customiseApiUrl: '/api/create-custom-content',
+    userId: user.id,
+    wid: website_id,
+    webLang: locale,
+  },
+  aeTemplatesTexts: {
+    customiseButton: 'PERSONALIZAR',
+    downloadButton: 'Descargar',
+    loadingText: 'Cargando plantillas...',
+    noTemplatesText: 'No hay plantillas disponibles',
+  },
+  aeTemplatesTheme: {
+    primaryColor: '#E6001E',
+    buttonTextColor: '#FFFFFF',
+  },
+}
+```
+
+### Props de `WallpapersNameFeatureOverride`
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `card` | `ForYouCardVisual` | Visual de la card en el hub. |
+| `config` | `ForYouFeatureConfig & { wid? }` | Config para el modo clásico. |
+| `howItWorksSteps` | `WallpapersNameHowItWorksStep[]` | Pasos del carousel "¿Cómo funciona?". |
+| `aeTemplatesConfig` | `AETemplatesConfig` | **Activa el modo nuevo.** Config de AETemplates. |
+| `aeTemplatesTexts` | `AETemplatesTexts` | Textos de la sección AETemplates. |
+| `aeTemplatesTheme` | `AETemplatesTheme` | Tema de colores de AETemplates. |
+| `pageTexts` | `WallpapersNamePageTexts` | Textos del header (título, descripción, howItWorksTitle). Solo modo nuevo. |
+| `pageTheme` | `WallpapersNamePageTheme` | Tema del header. Solo modo nuevo. |
+
+> **Regla de selección:** si `aeTemplatesConfig` está definido → `WallpapersNamePage` (modo nuevo); si no → `WallpapersName` clásico.
+
+---
+
+## Feature: AETemplatesSection — fuente dual (get_ae_templates + get_contents_by_tags)
+
+A partir de `v0.18.82`, `AETemplatesSection` puede combinar **dos fuentes de datos** en el mismo selector de tabs.
+
+### Cuándo usarlo
+
+Cuando tienes templates de After Effects en `get_ae_templates` **y** además contenidos clásicos en `get_contents_by_tags` que quieres mostrar como templates personalizables en el mismo interfaz.
+
+### Props nuevas en `AETemplatesConfig`
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `enableDefaultTemplates` | `boolean` | `true` | Activa los tabs de `get_ae_templates` (`apiUrl`). |
+| `enableCustomTemplates` | `boolean` | `false` | Activa los tabs de `get_contents_by_tags` (`customApiUrl`). |
+| `customApiUrl` | `string` | - | URL del endpoint `get_contents_by_tags`. |
+| `customApiTags` | `string[]` | - | Tags para la llamada a `customApiUrl`. |
+| `customTabs` | `AETab[]` | - | Tabs adicionales que llaman a `customApiUrl`. Se añaden después de los tabs default en el selector. |
+
+### Campo `custom_content` en cada item
+
+El botón **Customise** de cada card se habilita o deshabilita según el campo `custom_content` del item:
+
+| Valor del campo | Estado del botón |
+|-----------------|-----------------|
+| `"1"` o `1` | ✅ Activo — abre el modal de personalización |
+| Ausente, `null`, otro valor | 🚫 Deshabilitado (gris, `cursor: not-allowed`) |
+
+Para los items de `get_ae_templates`, el campo viene directamente del endpoint.  
+Para los items de `get_contents_by_tags`, el SDK lo lee del `metadata` del item:
+
+```json
+{
+  "id": 123,
+  "title": "Mi plantilla",
+  "thumbnail": "https://cdn.example.com/preview.jpg",
+  "metadata": "{\"custom_content\": \"1\"}"
+}
+```
+
+### Ejemplo: solo fuente AETemplates (comportamiento anterior)
+
+```tsx
+aeTemplatesConfig: {
+  apiUrl: '/api/get_ae_templates',
+  langId: 27,
+  clientId: 50,
+  tabs: [
+    { id: 'sports',        label: 'Sports',        type: 10 },
+    { id: 'entertainment', label: 'Entertainment', type: 9  },
+  ],
+  // enableDefaultTemplates: true  ← por defecto, no hace falta declararlo
+  customiseApiUrl: '/api/create-custom-content',
+  userId: user.id,
+  wid: '42',
+}
+```
+
+### Ejemplo: solo fuente custom (get_contents_by_tags)
+
+```tsx
+aeTemplatesConfig: {
+  apiUrl: '/api/get_ae_templates',   // requerido aunque no se use
+  langId: 27,
+  clientId: 50,
+  tabs: [],                           // sin tabs default
+  enableDefaultTemplates: false,      // ← desactiva get_ae_templates
+  enableCustomTemplates: true,        // ← activa get_contents_by_tags
+  customApiUrl: '/api/get_contents_by_tags',
+  customApiTags: ['wallpaper_name'],
+  customTabs: [
+    { id: 'mis-plantillas', label: 'Mis Plantillas', type: 0 },
+  ],
+  customiseApiUrl: '/api/create-custom-content',
+  userId: user.id,
+  wid: '42',
+}
+```
+
+### Ejemplo: ambas fuentes activas a la vez
+
+Los tabs de ambas fuentes aparecen en el mismo selector. Al cambiar de tab, el SDK detecta automáticamente cuál endpoint llamar.
+
+```tsx
+aeTemplatesConfig: {
+  // ── Fuente 1: get_ae_templates ────────────────────────────────────────
+  apiUrl: '/api/get_ae_templates',
+  langId: 27,
+  clientId: 50,
+  enableDefaultTemplates: true,
+  tabs: [
+    { id: 'sports',        label: 'Sports',        type: 10 },
+    { id: 'entertainment', label: 'Entertainment', type: 9  },
+    { id: 'abstract',      label: 'Abstract',      type: 11 },
+  ],
+
+  // ── Fuente 2: get_contents_by_tags ───────────────────────────────────
+  enableCustomTemplates: true,
+  customApiUrl: '/api/get_contents_by_tags',
+  customApiTags: ['wallpaper_name'],
+  customTabs: [
+    { id: 'mis-plantillas', label: 'Mis Plantillas', type: 0 },
+  ],
+
+  // ── Config compartida ─────────────────────────────────────────────────
+  customiseApiUrl: '/api/create-custom-content',
+  userId: user.id,
+  wid: '42',
+  webLang: 'es',
+}
+```
+
+El selector de tabs resultante sería:
+
+```
+[Sports] [Entertainment] [Abstract] [Mis Plantillas]
+ ↑ get_ae_templates                  ↑ get_contents_by_tags
+```
+
+### Deduplicación automática
+
+Si un mismo `id` aparece en ambas fuentes (caso raro), el SDK **descarta el duplicado** manteniendo el primero que llegó.
+
+### Comportamiento del scrollbar en el selector de tabs
+
+El selector de tabs tiene scroll horizontal en caso de overflow (muchas tabs en móvil), pero el scrollbar nativo está **oculto visualmente** para todos los navegadores (`scrollbar-width: none` + `::-webkit-scrollbar { display: none }`). El scroll sigue siendo funcional.
+
+---
+
+## Feature: CreativeFaceSwap — ejemplos + endpoints
+
+El componente `CreativeFaceSwap` permite a los usuarios subir una foto, elegir un ejemplo de carrusel y generar una imagen nueva con IA (face swap / creative generation).
+
+### Partes del componente
+
+```
+┌─────────────────────────┬──────────────────────────────────┐
+│  Columna izquierda      │  Columna derecha                 │
+│  ─────────────────      │  ──────────────                  │
+│  · Upload foto          │  · Textarea descripción          │
+│  · Carrusel ejemplos    │  · Botón CREATE                  │
+│                         │  · Área resultado (progreso/img) │
+└─────────────────────────┴──────────────────────────────────┘
+```
+
+### Props de `CreativeFaceSwapFeatureOverride`
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `card` | `ForYouCardVisual` | Visual de la card en el hub. |
+| `config` | `FaceSwapConfig` | Endpoints de generación + credenciales. **Requerido.** |
+| `examples` | `FaceSwapExample[]` | Ejemplos estáticos para el carrusel (prioridad máxima). |
+| `examplesTag` | `string` | Tag para cargar ejemplos vía `get_contents_by_tags` (carga interna del componente). |
+| `contentsConfig` | `ForYouFeatureConfig` | **Nuevo en v0.18.83.** Config de fetch de ejemplos con presets (multi-source). Prioridad sobre `examplesTag`. |
+| `theme` | `Partial<FaceSwapTheme>` | Override del tema de colores. |
+| `texts` | `Partial<FaceSwapTexts>` | Override de textos. |
+| `apiBaseUrl` | `string` | Base URL para el fetch de `examplesTag` (si se usa). |
+| `locale` | `string` | Locale override para esta feature. |
+| `onGenerationComplete` | `(imageUrl: string) => void` | Callback cuando la imagen está lista. |
+| `onError` | `(error: string) => void` | Callback de error. |
+
+### `config` — endpoints de generación (FaceSwapConfig)
+
+Este objeto **no** carga los ejemplos del carrusel. Contiene los endpoints del servicio de generación de imágenes y las credenciales del usuario:
+
+```ts
+config: {
+  userId: USER_ID,       // number — ID del usuario
+  userLogin: USER_LOGIN, // number — login del usuario
+  wid: WEBSITE_ID,       // string — website ID (opcional)
+  apiEndpoints: {
+    generate: '/api/face-swap/generate',   // POST — inicia el job de generación
+    progress: '/api/face-swap/progress',   // POST — polling del % de progreso
+    getImage:  '/api/face-swap/get-image', // POST — obtiene la imagen final
+  },
+}
+```
+
+> ⚠️ Estas rutas deben existir como **rutas API en el proyecto** (no son endpoints del CMS).
+> El SDK llama a estas rutas directamente desde el navegador del usuario.
+
+### `contentsConfig` — carga de ejemplos del carrusel (v0.18.83+)
+
+Permite cargar los ejemplos del carrusel desde la API del CMS usando el sistema de presets:
+
+```tsx
+creativeFaceSwap: {
+  config: {
+    userId: USER_ID,
+    userLogin: USER_LOGIN,
+    wid: WEBSITE_ID,
+    apiEndpoints: {
+      generate: '/api/face-swap/generate',
+      progress: '/api/face-swap/progress',
+      getImage:  '/api/face-swap/get-image',
+    },
+  },
+  // ← carga los ejemplos del carrusel desde el CMS
+  contentsConfig: {
+    apiBaseUrl: 'https://api.example.com',
+    locale: 'en',
+    website_id: WEBSITE_ID,
+    contents: [
+      {
+        preset: 'getGlobalContentsByIDs',
+        includeIds: [104557, 100180, 98423, 97811],
+      },
+    ],
+  },
+}
+```
+
+También puedes combinar con tags:
+
+```ts
+contentsConfig: {
+  apiBaseUrl: 'https://api.example.com',
+  locale: 'en',
+  contents: [
+    { preset: 'getGlobalContentsByIDs', includeIds: [104557, 100180] },
+    { preset: 'getGlobalContentsByTags', tags: ['faceswap-examples'] },
+  ],
+}
+```
+
+O solo con un tag simple:
+
+```ts
+contentsConfig: {
+  apiBaseUrl: 'https://api.example.com',
+  locale: 'en',
+  tags: 'faceswap-examples',
+}
+```
+
+### Prioridad de ejemplos
+
+El SDK aplica este orden (el primero que tenga datos gana):
+
+```
+1. examples[]       → array estático pasado en la prop
+2. contentsConfig   → fetch interno con forYouFetch (v0.18.83+)
+3. examplesTag      → fetch simple interno del componente
+```
+
+### Qué campos necesita cada item del CMS
+
+| Campo del item | Se usa como |
+|----------------|-------------|
+| `thumbnail` | Imagen del ejemplo en el carrusel |
+| `images.img1` | Imagen (fallback si no hay thumbnail) |
+| `imageUrl` | Imagen (segundo fallback) |
+| `title` | Descripción debajo de la imagen |
+| `description` | Descripción (fallback si no hay title) |
+
+> Si el item no tiene ningún campo de imagen, **se descarta** y no aparece en el carrusel.
+
+### Personalización: `FaceSwapTheme`
+
+| Prop | Default | Descripción |
+|------|---------|-------------|
+| `primaryColor` | `'#FF5500'` | Color principal (botones, spinner). |
+| `primaryHoverColor` | `'#ff1600'` | Color hover de botones. |
+| `secondaryColor` | `'#001B5E'` | Color secundario. |
+| `textColor` | `'#001B5E'` | Color del texto. |
+| `backgroundColor` | `'#F9F9F9'` | Fondo del componente. |
+
+### Personalización: `FaceSwapTexts`
+
+| Prop | Default |
+|------|---------|
+| `uploadTitle` | `'Your original photo'` |
+| `uploadButton` | `'UPLOAD IMAGE'` |
+| `changeImageButton` | `'CHANGE IMAGE'` |
+| `examplesTitle` | `'Get inspired by these examples'` |
+| `tryButton` | `'TRY'` |
+| `describeTitle` | `'Describe your desired image'` |
+| `descriptionPlaceholder` | `'Young curly-haired girl...'` |
+| `createButton` | `'CREATE'` |
+| `generatingButton` | `'GENERATING...'` |
+| `resultTitle` | `'Your result'` |
+| `emptyStateText` | `'Your generated image will appear here'` |
+| `startAgainButton` | `'START AGAIN'` |
+| `downloadButton` | `'DOWNLOAD'` |
+| `progressText` | `'Progress'` |
+| `successMessage` | `'Image generated successfully!'` |
+
+### Ejemplo completo
+
+```tsx
+import { ForYouPage } from 'webs-sdk'
+import type { ForYouFeatures } from 'webs-sdk'
+
+const features: ForYouFeatures = {
+  creativeFaceSwap: {
+    card: {
+      desktopImage: '/images/faceswap-desktop.jpg',
+      mobileImage:  '/images/faceswap-mobile.jpg',
+      imageOnRight: true,
+      ctaColor: '#FF5500',
+      backgroundColor: '#F9F9F9',
+    },
+    config: {
+      userId:    USER_ID,
+      userLogin: USER_LOGIN,
+      wid:       WEBSITE_ID,
+      apiEndpoints: {
+        generate: '/api/face-swap/generate',
+        progress: '/api/face-swap/progress',
+        getImage: '/api/face-swap/get-image',
+      },
+    },
+    contentsConfig: {
+      apiBaseUrl: 'https://api.example.com',
+      locale: 'en',
+      website_id: WEBSITE_ID,
+      contents: [
+        { preset: 'getGlobalContentsByIDs', includeIds: [104557, 100180, 98423] },
+      ],
+    },
+    theme: {
+      primaryColor: '#FF5500',
+      textColor: '#001B5E',
+    },
+    texts: {
+      uploadTitle: 'Tu foto',
+      createButton: 'GENERAR',
+      examplesTitle: 'Inspírate en estos ejemplos',
+    },
+    onGenerationComplete: (imageUrl) => console.log('Listo:', imageUrl),
+    onError: (error) => console.error('Error:', error),
+  },
+}
+
+export default function ForYouSection() {
+  return <ForYouPage locale="en" features={features} />
+}
+```
+
+### Respuesta esperada de los endpoints
+
+El SDK espera las siguientes estructuras JSON. Si el servicio tiene un formato diferente, hay que crear una ruta proxy en el proyecto que adapte la respuesta.
+
+**`/generate` → POST**
+```json
+{ "success": true, "data": { "md5": "abc123", "i_jobs": 1 } }
+```
+
+**`/progress` → POST**
+```json
+{ "success": true, "data": { "pct": 45 } }
+```
+
+**`/get-image` → POST**
+```json
+{ "success": true, "data": { "s3_image": "https%3A%2F%2Fcdn.example.com%2Fresult.jpg" } }
+```
+
+> `s3_image` debe estar URL-encoded. El SDK aplica `decodeURIComponent()` internamente.
+
+### Fix en v0.18.83 — error HTML en el endpoint generate
+
+Si el endpoint `/generate` no existe o falla con un 404/500, Next.js devuelve una página HTML en lugar de JSON. Antes de v0.18.83, esto causaba un crash poco descriptivo:
+
+```
+SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
+```
+
+A partir de v0.18.83, el SDK detecta el `Content-Type` de la respuesta antes de parsear. Si no es JSON, muestra un error legible en la UI:
+
+```
+HTTP 404: The generate endpoint returned an unexpected response.
+Check that the API route exists and is correctly configured in this project.
+```
+
+---
+
+## Migración desde el sistema anterior
+
+Si tienes el sistema antiguo funcionando, **no necesitas migrar todavía**. Ambos sistemas coexisten.
+
+Cuando quieras migrar, el patrón es:
+
+```tsx
+// ANTES
+import { Quiz } from 'webs-sdk'
+<Quiz config={{ apiUrl: '/api/get_contents_by_tags', tags: ['quiz'], locale: 'es' }} />
+
+// DESPUÉS (dentro de ForYouPage)
+<ForYouPage
+  locale="es"
+  features={{
+    quiz: {
+      card: { desktopImage: '/img/quiz.jpg' },         // ← para mostrar la card en el hub
+      config: { tags: 'quiz' },                         // ← misma config de antes
+    }
+  }}
+/>
+```
+
+Los componentes individuales (`Quiz`, `Wallpapers`, `Ringtone`, etc.) **siguen funcionando exactamente igual** que antes.
+
+---
+
+## Changelog
+
+### 0.18.83
+- `CreativeFaceSwapFeatureOverride`: nueva prop `contentsConfig?: ForYouFeatureConfig` — permite cargar los ejemplos del carrusel desde el CMS usando el sistema de presets (`getGlobalContentsByIDs`, `getGlobalContentsByTags`, etc.), igual que el resto de features.
+- `ForYouPage` case `creativeFaceSwap`: nuevo sub-componente interno `CreativeFaceSwapWithContents` que ejecuta `forYouFetch(contentsConfig)` al montar, mapea los items a `FaceSwapExample[]` y los pasa como `examples` al componente.
+- Prioridad de ejemplos: `examples[]` estáticos → `contentsConfig` (fetch interno) → `examplesTag` (fetch del componente).
+- `CreativeFaceSwap.tsx` — `handleCreate`: detección de respuesta HTML antes de `response.json()`. Si el endpoint devuelve un 404/500 de Next.js (HTML en lugar de JSON), el SDK lanza un error legible (`"HTTP 404: The generate endpoint returned an unexpected response..."`) en lugar de crashear con `SyntaxError`.
+
+### 0.18.82
+- `AETemplatesConfig`: nuevas props `enableDefaultTemplates`, `enableCustomTemplates`, `customApiUrl`, `customApiTags`, `customTabs` — soporte para fuente dual (`get_ae_templates` + `get_contents_by_tags`) en el mismo selector de tabs.
+- `AETemplateItem`: nuevo campo `custom_content?: string | number` — el botón Customise se activa solo si el item devuelve `"1"` o `1`. En caso contrario aparece deshabilitado.
+- `AETemplatesSection`: selector de tabs dinámico (fusiona tabs default + customTabs), fetch por fuente, `Promise.all` + deduplicación por `id`, fallback automático al primer tab si el activo desaparece.
+- `mapContentToAETemplateItem`: helper interno que normaliza items de `get_contents_by_tags` → `AETemplateItem`, leyendo `custom_content` del `metadata` o del campo raíz.
+- Scrollbar del selector de tabs oculto visualmente (`scrollbar-width: none` + `::-webkit-scrollbar { display: none }`).
+
+### 0.18.80
+- `WallpapersNamePage` (carousel "How does it work?"): eliminados `backgroundColor` (#EAECF0) y `padding` del card de paso — sin fondo, sin contenedor visible.
+- `WallpapersNamePage`: `maxWidth` de la imagen del paso `260px` → `600px` + `width: 100%` — imagen más grande y responsiva.
+
+### 0.18.79
+- `WallpapersNamePage` (carousel "How does it work?"): fondo del card de paso `#FFFDE7` (amarillo) → `#EAECF0` (gris neutro).
+- `WallpapersNamePage`: `maxWidth` de imagen `160px` → `260px`.
+- `WallpapersNamePage`: padding del card `40px 24px` → `48px 32px 36px`.
+- `WallpapersNamePage`: tipografía del título del paso `1.1rem` → `1.25rem`.
+- `WallpapersNamePage`: tipografía de descripción `0.9rem` → `0.95rem` + `maxWidth: 320px`.
+
+### 0.18.78
+- `Quiz`: fix `scoreLabel` — el default `'You got {score}/{total} {type}'` tenía `{type}` que nunca se reemplazaba, apareciendo literalmente en pantalla. Corregido a `'You got {score}/{total} points'`.
+- `Quiz`: eliminado carácter `←` hardcodeado en el botón "Previous". El texto es ahora controlado exclusivamente por `texts.previousButton`.
+
+### 0.18.77
+- `Quiz`: nuevo campo `QuizItem.personality?: boolean` — extraído del `metadata` del item. Acepta `boolean` o `string 'true'`. Identifica quizzes de personalidad.
+- `Quiz`: nuevo campo `QuizQuestion.maxPoints?: number` — máximo de puntos alcanzable por pregunta (`Math.max(...options.map(o => o.points))`).
+- `Quiz`: cálculo de `totalMax` (dynamicMax) corregido — usa `Σ q.maxPoints` para el total real en lugar de un valor fijo del backend.
+- `Quiz`: pantalla de resultado diferenciada en 3 modos: personality (solo mensaje), puntos (score/max + mensaje) y legacy (aciertos/total).
+- `Quiz`: `personality` propagado desde `activeQuiz` al `<QuizModal>`.
+- `Quiz`: optional chaining en `options[optionIdx]?.points ?? 0` para evitar crashes con índices inválidos.
+
+### 0.18.76
+- `WallpapersName`: nuevo componente `WallpapersNamePage` — integra header, carousel "¿Cómo funciona?" y `AETemplatesSection` en una sola pieza.
+- `ForYouPage` case `wallpapersName`: modo dual — si `aeTemplatesConfig` está presente renderiza `WallpapersNamePage` (modo nuevo); si no, usa `WallpapersName` clásico.
+- Nuevas props en `WallpapersNameFeatureOverride`: `aeTemplatesConfig`, `aeTemplatesTexts`, `aeTemplatesTheme`, `pageTexts`, `pageTheme`.
+- Nuevos tipos exportados: `WallpapersNamePageTexts`, `WallpapersNamePageTheme`, `WallpapersNamePageProps`.
+
+### 0.18.75
+- `ForYouPage` case `wallpapersName`: normalización `website_id` → `wid` (campo específico de `WallpapersNameConfig`). Fix para "No wallpapers available" al usar `ForYouPage` con la feature `wallpapersName`.
+- Auditoría completa de normalizaciones: el resto de cases (`ringtone`, `wallpapers`, `memeGenerator`, `quiz`, `stickers`, `arFilters`) ya normalizaban correctamente.
+
+### 0.18.74
+- Nuevo util exportado: `downloadFile` — función de descarga con soporte de proxy CORS. Extrae la lógica inline de `Stickers.tsx` a `src/utils/downloadFile.ts` y la exporta desde `webs-sdk`.
+- `Stickers.tsx`: usa `downloadFile` del util en lugar de definición inline.
+- Documentación: nueva sección **"Descargas y CORS — Proxy de medios"** en la guía de implementación con código del endpoint proxy (Next.js App Router y Pages Router) y configuración de `downloadProxyUrl` / `imageProxyUrl`.
+
+### 0.18.72
+- `ForYouPage`: scroll al top usa `window.scrollTo({ top: 0 })` en lugar de `scrollIntoView` (scroll ahora va al top de la ventana, no solo al componente)
+- `ForYouPage` case `ringtone`: normaliza correctamente `tags` → `ringtoneTag` (string) que espera `Ringtone.tsx`
+- `ForYouPage` case `quiz`: `apiUrl` siempre tiene valor (construido con `buildPresetUrl` si se usa `apiBaseUrl`); se pasa `questionsApiUrl` correctamente a `Quiz.tsx`
+- `ForYouPage` case `memeGenerator`: `apiUrl` siempre tiene valor; normaliza `tags` → `memeTag` (string) que espera `MemeGenerator.tsx`
+- `ForYouPage` case `wallpapers`: nuevo prop `tabs?: WallpapersTab[]` — selector de pestañas por categoría encima del componente Wallpapers
+- `ForYouPage` case `wallpapers`: nuevo prop `tabsTheme` — personalización visual del selector de tabs
+- `ForYouPage` case `wallpapers`: `heroBannerImage` y `fallbackImage` se pasan correctamente al config de `Wallpapers.tsx`
+- Nuevo tipo exportado: `WallpapersTab`
+
+### 0.18.70
+- `ForYouPage`: nuevo prop `hubBanner` (`ForYouHubBanner`) — banner hero opcional encima de las cards en el hub
+- `ForYouHubBanner`: soporta imagen desktop + mobile, título, subtítulo, color de fondo, altura y padding configurables
+- `ForYouHubBannerHighlight`: barra de highlights con icono (SVG raw o URL imagen) + texto debajo del banner
+- Nuevos tipos exportados: `ForYouHubBanner`, `ForYouHubBannerHighlight`
+
+### 0.18.69
+- `ForYouPage`: nuevo prop `locale` con 8 idiomas (en, es, fr, pl, nl, tr, ro, ar)
+- `ForYouPage`: traducciones integradas en el SDK (`getForYouTranslations`)
+- `ForYouPage`: RTL automático para árabe (`dir="rtl"`)
+- `ForYouPage`: navegación con `window.history.pushState` + `?feature=<key>` en URL
+- `ForYouPage`: listener `popstate` para botón "Atrás" del navegador
+- `ForYouPage`: scroll automático al tope al entrar/salir de features
+- `ForYouPage`: botón volver con icono SVG configurable
+- `ForYouPage`: nuevo `ForYouFeatureConfig.apiBaseUrl` — el SDK construye las URLs
+- `ForYouPage`: nuevo `ForYouFeatureConfig.contents[]` — multi-preset en paralelo
+- `Wallpapers`: nuevo prop `hideBreadcrumb` — oculta el breadcrumb interno
+- Todos los hooks: migrados a `forYouFetch` con soporte `contents[]` y `apiBaseUrl`
+- Nuevo: `forYouFetch` helper exportado independientemente
+- Nuevo: `getForYouTranslations`, `isRTL`, `FOR_YOU_I18N`, `FOR_YOU_LOCALES`
+- Nuevo: tipos `ForYouLocale`, `ForYouContentPreset`, `ForYouFetchOptions` y variantes