@moni-labs/moni-ui 0.3.1 → 0.3.2

package/src/components/moni-carousel.ts

@@ -8,133 +8,318 @@
 import { html, css } from 'lit';
 import { customElement, property, query, state, queryAll } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
+import { emitMoniEvent } from '../utils/event-emitter.js';
 import { gsap } from 'gsap';
 
 /**
- * Data model for a single item in a `<moni-carousel>`.
+ * Modelo de datos para un solo elemento en un `<moni-carousel>`.
  */
 export interface CarouselItem {
-	/** Display title overlaid on the item. */
+	/** Título a mostrar sobre el elemento. */
 	title: string;
-	/** URL or path to the background image. */
+	/** URL o ruta a la imagen de fondo. */
 	img: string;
-	/** Optional link target. If provided, the item renders as an `<a>` element. */
+	/** Objetivo de enlace opcional. Si se proporciona, el elemento se renderiza como un `<a>`. */
 	href?: string;
-	/** Link target attribute (e.g. `'_blank'`). Only applies if `href` is set. */
+	/** Atributo target del enlace (ej. `'_blank'`). Solo se aplica si se establece `href`. */
 	target?: string;
 }
 
 /**
- * Material Design 3 Expressive Carousel component.
+ * Componente Material Design 3 Expressive Carousel.
  *
- * Carousels display a collection of related items in a scrollable, horizontal list.
- * They allow users to quickly browse through items like images, cards, or products.
+ * Los carruseles muestran una colección de elementos relacionados en una lista horizontal desplazable.
+ * Permiten a los usuarios navegar rápidamente a través de elementos como imágenes, tarjetas, o productos.
  *
- * **M3 spec reference:** `m3-docs/components/carousel/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/carousel/specs.md`
  *
- * **Layout variants:**
- * - `multi-browse` (default) — Shows a mix of large, medium, and small (peeking)
- *   items. Best for exploring a large number of items.
- * - `hero` — Focuses on one large primary item while showing a sliver of the
- *   next item. Best for featuring important content.
- * - `uncontained` — Standard layout where all items have the same width and
- *   bleed off the edges of the container.
+ * **Variantes de diseño:**
+ * - `multi-browse` (por defecto) — Muestra una mezcla de elementos grandes, medianos y pequeños (asomando).
+ *   Mejor para explorar un gran número de elementos.
+ * - `hero` — Se enfoca en un elemento primario grande mientras muestra una fracción del
+ *   siguiente elemento. Mejor para destacar contenido importante.
+ * - `uncontained` — Diseño estándar donde todos los elementos tienen el mismo ancho y
+ *   se desbordan por los bordes del contenedor.
  *
- * **Animation & Gestures:**
- * This component uses GSAP for smooth drag, flick, and snap animations,
- * mirroring the high-fidelity M3 Expressive motion specs. It handles touch
- * gestures for mobile and mouse-drag for desktop.
+ * **Animación y Gestos:**
+ * Este componente usa GSAP para animaciones suaves de arrastre, deslizamiento y ajuste,
+ * reflejando las especificaciones de movimiento de alta fidelidad de M3 Expressive. Maneja
+ * gestos táctiles para móviles y arrastre del ratón para escritorio.
  *
- * **Auto-sizing (`auto` mode):**
- * When `auto=true` (default), the carousel measures its own width and
- * dynamically calculates the optimal sizes for large, medium, and small items
- * based on the active `layout` to ensure they fit perfectly without awkward gaps
- * or clipping at the edges.
+ * **Auto-tamaño (modo `auto`):**
+ * Cuando `auto=true` (por defecto), el carrusel mide su propio ancho y
+ * calcula dinámicamente los tamaños óptimos para los elementos grandes, medianos y pequeños
+ * basados en el `layout` activo para asegurar que encajen perfectamente sin huecos incómodos
+ * ni recortes en los bordes.
  *
  * @example
  * ```html
- * <!-- Declarative usage via DOM properties (recommended) -->
+ * <!-- Uso declarativo a través de propiedades DOM (recomendado) -->
  * <moni-carousel layout="hero"></moni-carousel>
  * <script>
  *   const carousel = document.querySelector('moni-carousel');
  *   carousel.items = [
- *     { title: 'Item 1', img: '/img1.jpg', href: '/link1' },
- *     { title: 'Item 2', img: '/img2.jpg' }
+ *     { title: 'Elemento 1', img: '/img1.jpg', href: '/link1' },
+ *     { title: 'Elemento 2', img: '/img2.jpg' }
  *   ];
  * </script>
  *
- * <!-- Slot-based usage (for SSR or simple static content) -->
+ * <!-- Uso basado en slots (para SSR o contenido estático simple) -->
  * <moni-carousel layout="uncontained">
  *   <div slot="item">
  *     <img src="/img1.jpg" />
- *     <h3>Static Item</h3>
+ *     <h3>Elemento Estático</h3>
  *   </div>
  * </moni-carousel>
  * ```
  *
- * @slot item - Alternative to the `items` property. Slot individual HTML elements
- *              instead of passing data objects.
+ * @slot item - Alternativa a la propiedad `items`. Inserta elementos HTML individuales
+ *              en lugar de pasar objetos de datos.
  *
- * @csspart carousel - The outer wrapper.
- * @csspart track    - The scrolling track element.
- * @csspart item     - Individual carousel item containers.
- * @csspart img      - The image elements inside the items.
- * @csspart title    - The title text elements inside the items.
+ * @csspart carousel - El envoltorio exterior.
+ * @csspart track    - El elemento de la pista desplazable.
+ * @csspart item     - Contenedores de elementos del carrusel individuales.
+ * @csspart img      - Los elementos de imagen dentro de los elementos.
+ * @csspart title    - Los elementos de texto de título dentro de los elementos.
  */
 @customElement('moni-carousel')
 export class MoniCarousel extends MoniElement {
+	/**
+	 * Array de elementos a mostrar en el carrusel.
+	 * Cada elemento requiere al menos `title` e `img`. El opcional `href` renderiza la tarjeta como un enlace.
+	 * @default []
+	 */
 	@property({ type: Array }) items: CarouselItem[] = [];
+
+	/**
+	 * Variante de diseño visual. Determina cuántos elementos son visibles y cómo escalan.
+	 * - `'multi-browse'` (por defecto) — Elementos grandes + medianos + pequeños (asomando).
+	 * - `'hero'` — Uno o más elementos grandes + elemento pequeño asomando.
+	 * - `'uncontained'` — Elementos de igual ancho que se desbordan por el borde.
+	 * @default 'multi-browse'
+	 */
 	@property({ reflect: true }) layout: 'multi-browse' | 'hero' | 'uncontained' = 'multi-browse';
+
+	/**
+	 * Cuando es `true`, el carrusel calcula los tamaños óptimos de los elementos automáticamente
+	 * basado en el ancho del contenedor y la variante de `layout` activa.
+	 * Cuando es `false`, usa los valores explícitos `largeWidth`, `mediumWidth`, `smallWidth`.
+	 * @default true
+	 */
 	@property({ type: Boolean, reflect: true }) auto = true;
+
+	/**
+	 * Ancho en píxeles para el elemento grande (enfoque principal) del carrusel.
+	 * Solo se usa cuando `auto=false`.
+	 * @default 220
+	 */
 	@property({ type: Number, attribute: 'large-width' }) largeWidth = 220;
+
+	/**
+	 * Ancho en píxeles para el elemento de tamaño mediano (secundario) del carrusel.
+	 * Solo se usa cuando `auto=false` y `layout='multi-browse'`.
+	 * @default 96
+	 */
 	@property({ type: Number, attribute: 'medium-width' }) mediumWidth = 96;
+
+	/**
+	 * Ancho en píxeles para el elemento pequeño (asomando) del carrusel.
+	 * Solo se usa cuando `auto=false`.
+	 * @default 48
+	 */
 	@property({ type: Number, attribute: 'small-width' }) smallWidth = 48;
+
+	/**
+	 * Espacio en píxeles entre los elementos del carrusel.
+	 * @default 8
+	 */
 	@property({ type: Number }) gap = 8;
+
+	/**
+	 * Relleno horizontal en píxeles aplicado al inicio de la pista del carrusel.
+	 * @default 16
+	 */
 	@property({ type: Number }) padding = 16;
+
+	/**
+	 * Radio del borde en píxeles aplicado a cada tarjeta.
+	 * @default 28
+	 */
 	@property({ type: Number, attribute: 'border-radius' }) borderRadius = 28;
+
+	/**
+	 * Cuando es `true`, renderiza un enlace "Mostrar todo" en el encabezado.
+	 * @default false
+	 */
 	@property({ type: Boolean, attribute: 'show-all' }) showAll = false;
+
+	/**
+	 * Texto de etiqueta para el enlace "Mostrar todo".
+	 * @default 'Show all'
+	 */
 	@property({ attribute: 'show-all-text' }) showAllText = 'Show all';
+
+	/**
+	 * Encabezado de sección opcional renderizado sobre la pista del carrusel.
+	 * @default ''
+	 */
 	@property({ attribute: 'header-text' }) headerText = '';
+
+	/**
+	 * Cuando es `true`, oculta los botones de flecha de navegación anterior/siguiente.
+	 * @default false
+	 */
 	@property({ type: Boolean, attribute: 'hide-nav' }) hideNav = false;
+
+	/**
+	 * Cuando es `true`, habilita el bucle infinito sin interrupciones clonando la lista de elementos
+	 * a través de un búfer de desplazamiento virtual grande, luego reposicionando silenciosamente
+	 * el desplazamiento cuando el usuario se acerca a cualquier borde.
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) infinite = false;
+
+	/**
+	 * Cuando es `true`, avanza automáticamente el carrusel en el intervalo definido
+	 * por `autoplayInterval`. La reproducción automática se detiene durante las interacciones de arrastre activas.
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) autoplay = false;
+
+	/**
+	 * Milisegundos entre los avances automáticos de diapositivas cuando `autoplay=true`.
+	 * @default 3000
+	 */
 	@property({ type: Number, attribute: 'autoplay-interval' }) autoplayInterval = 3000;
 
+	/**
+	 * Ancho medido del elemento host del carrusel en píxeles.
+	 * Actualizado por el `ResizeObserver` en cada redimensionamiento del contenedor y usado por
+	 * `computedLayout` para calcular cuántos elementos caben en la pantalla.
+	 */
 	@state() private _containerWidth = 0;
+
+	/**
+	 * Elementos analizados desde el slot Light DOM (uso declarativo).
+	 * Poblado por `_handleSlotChange` cuando los usuarios insertan elementos `<img>` o `<a><img></a>`.
+	 */
 	@state() private _slottedItems: CarouselItem[] = [];
+
+	/**
+	 * Si el slot `show-all` contiene contenido proyectado por el usuario.
+	 * Controla si se renderiza el área "Mostrar todo" del encabezado.
+	 */
 	@state() private _hasSlottedShowAll = false;
 
+	/**
+	 * Devuelve la fuente del elemento activo.
+	 * La propiedad programática `items` tiene prioridad sobre los hijos Light DOM en slots.
+	 * Recurre a `_slottedItems` cuando no se proporcionan elementos programáticos.
+	 */
 	get effectiveItems(): CarouselItem[] {
 		return this.items && this.items.length > 0 ? this.items : this._slottedItems;
 	}
 
+	/**
+	 * Referencia directa al div contenedor de desplazamiento.
+	 * Usado para leer `scrollLeft`, modificar `scrollBehavior`, y calcular `scrollWidth`.
+	 */
 	@query('.scroll-container') private _scrollContainer!: HTMLDivElement;
+
+	/**
+	 * NodeList en vivo de todos los elementos de tarjeta renderizados.
+	 * Usado por el motor de diseño para aplicar actualizaciones de transform/width por cuadro a través de GSAP quickSetters.
+	 */
 	@queryAll('.card') private _cards!: NodeListOf<HTMLDivElement>;
 
+	/** Instancia ResizeObserver que observa las dimensiones del elemento host. */
 	private _resizeObserver: ResizeObserver | null = null;
-	private _isDown = false;
-	private _startX = 0;
-	private _scrollLeftStart = 0;
-	private _velocity = 0;
-	private _lastTime = 0;
-	private _lastX = 0;
-	private _draggedDistance = 0;
-	private _rafId: number | null = null;
+
+	/** Estado interno de visibilidad (por índice lógico) para evitar falsos eventos al ciclar el scroll infinito */
+	private _logicalItemInViewport: boolean[] = [];
+
+	/** `true` mientras el usuario arrastra activamente (ratón o toque presionado). */
+	private _isDragging = false;
+
+	/** Coordenada X en el inicio del gesto de arrastre actual (relativa al contenedor de desplazamiento). */
+	private _dragStartX = 0;
+
+	/** Valor `scrollLeft` del contenedor en el momento en que comenzó el arrastre. */
+	private _scrollLeftAtDragStart = 0;
+
+	/**
+	 * Velocidad del puntero en píxeles por milisegundo.
+	 * Calculada gradualmente durante el arrastre y usada para el impulso/inercia al soltar.
+	 */
+	private _pointerVelocity = 0;
+
+	/** Marca de tiempo (de `performance.now()`) del último evento de movimiento del puntero/toque. */
+	private _lastPointerTime = 0;
+
+	/** Coordenada X del puntero en el cuadro del evento de movimiento anterior. */
+	private _lastPointerX = 0;
+
+	/**
+	 * Distancia horizontal absoluta acumulada (en píxeles) recorrida durante el arrastre actual.
+	 * Usada para distinguir un deslizamiento intencional de un clic accidental (umbral: 8px).
+	 */
+	private _totalDraggedDistance = 0;
+
+	/**
+	 * ID de `requestAnimationFrame` activo del bucle de desplazamiento por inercia.
+	 * Almacenado para que pueda cancelarse cuando el usuario inicia un nuevo arrastre.
+	 */
+	private _animationFrameId: number | null = null;
+
+	/** `true` cuando el ancho de la ventana gráfica coincide con el punto de ruptura móvil (`max-width: 600px`). */
 	private _isMobile = false;
 
-	// Scroll interpolation state
+	// ─── Estado de interpolación GSAP Ticker ──────────────────────────────────────
+
+	/**
+	 * La posición de desplazamiento hacia la que el ticker de GSAP está interpolando (lerping) **en cada cuadro**.
+	 * Expresada en unidades de `itemSize` (no píxeles) para matemáticas independientes del diseño.
+	 */
 	private _tickerTarget = 0;
+
+	/**
+	 * La posición de desplazamiento interpolada actual usada para impulsar el diseño visual.
+	 * Interpola hacia `_tickerTarget` en cada cuadro, creando el efecto de suavizado.
+	 */
 	private _tickerCurrent = 0;
+
+	/**
+	 * `true` mientras el callback del ticker de GSAP (`_tick`) está registrado y en ejecución.
+	 * Evita añadir el callback del ticker múltiples veces en llamadas concurrentes.
+	 */
 	private _isTicking = false;
 
-	// Infinite & Autoplay state
+	// ─── Estado de Bucle Infinito & Reproducción Automática ─────────────────────────────────────
+
+	/**
+	 * Protege la inicialización de una sola vez de la posición del búfer de desplazamiento infinito.
+	 * Se establece en `true` una vez que el contenedor de desplazamiento se ha reposicionado
+	 * silenciosamente al centro del búfer virtual después del primer renderizado.
+	 */
 	private _infiniteInitialized = false;
+
+	/** ID del temporizador devuelto por `setInterval()` para la función de reproducción automática. */
 	private _autoplayTimer: any = null;
 
-	// quickSetter caches — avoid gsap.set() overhead per frame
+	// ─── Cachés de GSAP quickSetter ───────────────────────────────────────────────
+	// Las funciones quickSetter evitan la sobrecarga de llamar a `gsap.set()` en cada cuadro.
+	// Pre-construidas una vez después de cada ciclo de renderizado; invalidadas cuando cambia el número de tarjetas.
+
+	/** Array de quickSetters de GSAP para el CSS `transform: translateX()` de cada tarjeta. */
 	private _cardSetX: ((value: number) => void)[] = [];
+
+	/** Array de quickSetters de GSAP para el `width` en línea de cada tarjeta. */
 	private _cardSetWidth: ((value: number) => void)[] = [];
+
+	/** Array de quickSetters de GSAP para el parallax `translateX` del `<img>` de cada tarjeta. */
 	private _imgSetX: ((value: number) => void)[] = [];
+
+	/** Array de quickSetters de GSAP para la `opacity` del elemento `.card-title` de cada tarjeta. */
 	private _titleSetOpacity: ((value: number) => void)[] = [];
 
 	static override styles = [
@@ -196,6 +381,8 @@ export class MoniCarousel extends MoniElement {
 				overflow-x: auto;
 				overflow-y: hidden;
 				scroll-snap-type: x mandatory;
+				scroll-padding-left: var(--carousel-padding, 16px);
+				scroll-padding-right: var(--carousel-padding, 16px);
 				scrollbar-width: none;
 				-webkit-overflow-scrolling: touch;
 				cursor: grab;
@@ -364,6 +551,12 @@ export class MoniCarousel extends MoniElement {
 		`
 	];
 
+	/**
+	 * Hook del ciclo de vida (Lit).
+	 * Inicializa el `ResizeObserver` para reaccionar a cambios en el tamaño del contenedor,
+	 * lo que es crucial para recalcular el `computedLayout` (cuántas cards caben en el viewport).
+	 * También añade listeners globales pasivos para eventos de redimensionamiento de ventana.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		if (typeof ResizeObserver !== 'undefined') {
@@ -388,14 +581,19 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
+	/**
+	 * Hook del ciclo de vida (Lit).
+	 * Limpia y desconecta el `ResizeObserver`, el `IntersectionObserver` y elimina
+	 * los event listeners globales para evitar fugas de memoria (memory leaks).
+	 */
 	override disconnectedCallback() {
 		if (this._resizeObserver) {
 			this._resizeObserver.disconnect();
 		}
 		// Cancel any pending RAF or ticker
-		if (this._rafId !== null) {
-			cancelAnimationFrame(this._rafId);
-			this._rafId = null;
+		if (this._animationFrameId !== null) {
+			cancelAnimationFrame(this._animationFrameId);
+			this._animationFrameId = null;
 		}
 		gsap.ticker.remove(this._tick);
 		this._isTicking = false;
@@ -408,6 +606,11 @@ export class MoniCarousel extends MoniElement {
 		super.disconnectedCallback();
 	}
 
+	/**
+	 * Hook del ciclo de vida (Lit) ejecutado tras el primer render.
+	 * Inspecciona el Shadow DOM para ubicar el slot por defecto y procesar 
+	 * las cards iniciales (`_handleSlotChange` invocado manualmente).
+	 */
 	override firstUpdated() {
 		const defaultSlot = this.shadowRoot?.querySelector('slot:not([name])');
 		if (defaultSlot) {
@@ -417,6 +620,7 @@ export class MoniCarousel extends MoniElement {
 		if (showAllSlot) {
 			this._handleShowAllSlotChange({ target: showAllSlot } as any);
 		}
+
 		this._buildQuickSetters();
 		this.updateLayout(true);
 		
@@ -425,6 +629,15 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
+	/**
+	 * Hook del ciclo de vida (Lit). Se invoca tras cada actualización reactiva.
+	 * 
+	 * Lógica principal:
+	 * - Si cambian propiedades estructurales (`autoplay`, `infinite`, `gap`), reconstruye el
+	 *   layout y detiene/inicia el timer de autoplay.
+	 * - Delega en `_checkInfiniteWrap()` para reposicionar el scroll si estamos cerca
+	 *   de los bordes del carrusel infinito.
+	 */
 	override updated(changedProperties: Map<string, any>) {
 		super.updated(changedProperties);
 		if (
@@ -465,166 +678,282 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
-	get computedLayout() {
-		const W_c = this._containerWidth || this.getBoundingClientRect().width || 360;
+	/**
+	 * Motor de cálculo del Layout.
+	 * 
+	 * Basado en las proporciones de Material 3 para carruseles:
+	 * Calcula el ancho disponible (`W_c`) y determina el número de ítems grandes (`L`),
+	 * medianos (`M`) y pequeños (`S`) que caben en pantalla, usando la fórmula de la
+	 * especificación (multi-browse, hero o uncontained).
+	 * 
+	 * Retorna `{ L, M, S, N }` donde `N` es el divisor base para calcular tamaños proporcionales.
+	 */
+get computedLayout() {
+		/**
+		 * `containerWidth` — ancho total en píxeles del elemento host del carrusel.
+		 * Recurre a `getBoundingClientRect()` si el ResizeObserver aún no se ha disparado,
+		 * y en última instancia por defecto a 360px (un ancho común de ventana gráfica móvil).
+		 */
+		const containerWidth = this._containerWidth || this.getBoundingClientRect().width || 360;
 		const gap = this.gap;
 		const padding = this.padding;
-		const W_a = W_c - 2 * padding;
 
-		let L = this.largeWidth;
-		let M = this.mediumWidth;
-		let S = this.smallWidth;
-		let N = 1;
+		/**
+		 * `availableWidth` — el ancho de pista utilizable después de restar el padding
+		 * inicial y final del ancho total del contenedor. Este es el espacio que el algoritmo de diseño
+		 * divide en ranuras de elementos grandes, medianos y pequeños.
+		 * Fórmula: availableWidth = containerWidth - 2 × padding
+		 */
+		const availableWidth = containerWidth - 2 * padding;
+
+		/** `largeItemWidth` — ancho calculado o configurado (px) de los elementos de enfoque principal. */
+		let largeItemWidth = this.largeWidth;
+		/** `mediumItemWidth` — ancho calculado o configurado (px) de los elementos secundarios. */
+		let mediumItemWidth = this.mediumWidth;
+		/** `smallItemWidth` — ancho calculado o configurado (px) de los elementos pequeños/asomando. */
+		let smallItemWidth = this.smallWidth;
+		/**
+		 * `largeItemCount` — el número de elementos grandes visibles simultáneamente en la ventana gráfica.
+		 * La especificación M3 define la fórmula de la ventana gráfica como:
+		 *   availableWidth = largeItemCount × largeItemWidth + mediumItemWidth + smallItemWidth + (largeItemCount + 1) × gap
+		 */
+		let largeItemCount = 1;
 
 		if (this.auto) {
 			if (this.layout === 'uncontained') {
-				// Fits as many L items as possible, letting them bleed off the right edge.
-				// We target large width around 260px.
-				L = Math.min(W_a, 260);
+				// En diseño 'uncontained', todos los elementos tienen el mismo ancho y se desbordan por el borde.
+				// We target a comfortable width around 260px, but cap it to availableWidth.
+				largeItemWidth = Math.min(availableWidth, 260);
 			} else if (this.layout === 'hero') {
-				// Hero has N large items and 1 small peeking item.
-				// W_a = N * L + S + N * gap
-				S = 48;
-				N = Math.max(1, Math.floor((W_a - S) / (250 + gap)));
-				L = (W_a - S - N * gap) / N;
-
-				if (L < 150) {
-					N = 1;
-					L = W_a - S - gap;
+				// M3 Hero layout formula:
+				//   availableWidth = largeItemCount × largeItemWidth + smallItemWidth + largeItemCount × gap
+				// We fix smallItemWidth = 48px (M3 spec minimum peeking width), then solve for largeItemWidth.
+				smallItemWidth = 48;
+				largeItemCount = Math.max(1, Math.floor((availableWidth - smallItemWidth) / (250 + gap)));
+				largeItemWidth = (availableWidth - smallItemWidth - largeItemCount * gap) / largeItemCount;
+
+				// Límite de seguridad: si el elemento grande fuera menor a 150px, forzar modo de un solo elemento.
+				if (largeItemWidth < 150) {
+					largeItemCount = 1;
+					largeItemWidth = availableWidth - smallItemWidth - gap;
 				}
 			} else {
-				// multi-browse: N large items, 1 medium, 1 small
-				// W_a = N * L + M + S + (N + 1) * gap
-				S = 48;
-				let bestN = 1;
-				let bestL = 220;
+				// M3 Multi-Browse layout formula:
+				//   availableWidth = largeItemCount × largeItemWidth + mediumItemWidth + smallItemWidth + (largeItemCount + 1) × gap
+				// mediumItemWidth = 0.45 × largeItemWidth (derived from M3 spec proportions)
+				// Solving: largeItemWidth = (availableWidth - smallItemWidth - (largeItemCount + 1) × gap) / (largeItemCount + 0.45)
+				smallItemWidth = 48;
+
+				// Optimización: probar valores de largeItemCount de 1 a 10 y elegir aquel cuyo
+				// largeItemWidth esté más cerca del objetivo ideal de 220px.
+				let bestLargeItemCount = 1;
+				let bestLargeItemWidth = 220;
 				let bestDiff = Infinity;
 
-				for (let n = 1; n <= 10; n++) {
-					const l = (W_a - S - (n + 1) * gap) / (n + 0.45);
-					if (l >= 140 && l <= 340) {
-						const diff = Math.abs(l - 220);
+				for (let candidateCount = 1; candidateCount <= 10; candidateCount++) {
+					// Solve for largeItemWidth given this candidateCount:
+					const candidateLargeWidth = (availableWidth - smallItemWidth - (candidateCount + 1) * gap) / (candidateCount + 0.45);
+
+					// Only accept widths within a reasonable human-perceivable range [140px, 340px].
+					if (candidateLargeWidth >= 140 && candidateLargeWidth <= 340) {
+						const diff = Math.abs(candidateLargeWidth - 220);
 						if (diff < bestDiff) {
 							bestDiff = diff;
-							bestN = n;
-							bestL = l;
+							bestLargeItemCount = candidateCount;
+							bestLargeItemWidth = candidateLargeWidth;
 						}
 					}
 				}
 
 				if (bestDiff === Infinity) {
-					N = 1;
-					L = (W_a - S - 2 * gap) / 1.45;
+					// Fallback: no valid solution found; use single large item with minimum spacing.
+					largeItemCount = 1;
+					largeItemWidth = (availableWidth - smallItemWidth - 2 * gap) / 1.45;
 				} else {
-					N = bestN;
-					L = bestL;
+					largeItemCount = bestLargeItemCount;
+					largeItemWidth = bestLargeItemWidth;
 				}
-				M = 0.45 * L;
+				// Especificación M3: el elemento mediano es el 45% del ancho del elemento grande.
+				mediumItemWidth = 0.45 * largeItemWidth;
 			}
 		} else {
-			// Non-auto/manual sizing mode
-			L = this.largeWidth;
-			M = this.mediumWidth;
-			S = this.smallWidth;
+			// ── Manual sizing mode (auto=false) ──────────────────────────────────
+			// Usar los valores explícitos de propiedad proporcionados por el consumidor.
+			largeItemWidth = this.largeWidth;
+			mediumItemWidth = this.mediumWidth;
+			smallItemWidth = this.smallWidth;
 
 			if (this.layout === 'hero') {
-				N = 1;
+				largeItemCount = 1;
 			} else if (this.layout === 'uncontained') {
-				N = Math.max(1, Math.floor(W_a / (L + gap)));
+				// En modo uncontained, calcular cuántos elementos grandes caben en el ancho disponible.
+				largeItemCount = Math.max(1, Math.floor(availableWidth / (largeItemWidth + gap)));
 			} else {
-				N = 1;
+				largeItemCount = 1;
 			}
 		}
 
-		return { L, M, S, N };
+		// Retornar los cuatro valores calculados como propiedades nombradas.
+		// Callers use destructuring: const { largeItemWidth, mediumItemWidth, smallItemWidth, largeItemCount } = this.computedLayout;
+		return { largeItemWidth, mediumItemWidth, smallItemWidth, largeItemCount };
 	}
 
-	get itemSize() {
-		return this.computedLayout.L + this.gap;
+	/**
+	 * Calcula el ancho total (incluyendo el gap) de un ítem de tamaño 'L' (Large).
+	 * Este valor se utiliza como unidad de medida (step) para el Scroll Snapping
+	 * y el cálculo de desplazamiento de páginas (sets).
+	 */
+get itemSize() {
+		// El paso de ajuste es el ancho completo de la ranura: ancho del elemento más una unidad de espacio.
+		// Usado como la unidad de medida para el ajuste de desplazamiento, cálculos de impulso,
+		// y el posicionamiento del búfer de desplazamiento infinito.
+		return this.computedLayout.largeItemWidth + this.gap;
 	}
 
-	private _getCardLayout(p: number) {
-		const { L, M, S, N } = this.computedLayout;
+	/**
+	 * Algoritmo Central del Carrusel M3.
+	 * 
+	 * Calcula el ancho visual, la posición horizontal y la opacidad para una sola tarjeta del carrusel
+	 * basándose en su posición normalizada en relación con la ventana gráfica actualmente visible.
+	 *
+	 * Este es el corazón del efecto "Masked Carousel" de M3: a medida que una tarjeta transita de
+	 * fuera de pantalla a en pantalla (posición -1 → 0 → N), su ancho se interpola de
+	 * `smallItemWidth` → `largeItemWidth`, y su opacidad aumenta.
+	 *
+	 * Semántica de posición:
+	 *   - `normalizedPosition < -1` → tarjeta está fuera de pantalla a la izquierda (oculta)
+	 *   - `normalizedPosition = 0`  → tarjeta está en la ranura grande más a la izquierda (enfoque principal)
+	 *   - `normalizedPosition = N-1` → tarjeta está en la ranura grande más a la derecha
+	 *   - `normalizedPosition > N`  → tarjeta está fuera de pantalla a la derecha (oculta)
+	 *
+	 * @param normalizedPosition - El índice de posición fraccional de la tarjeta en relación con el progreso
+	 *   de desplazamiento actual. Un valor de `0` significa que la tarjeta está perfectamente alineada con la ranura
+	 *   grande inicial; los valores fraccionales representan transiciones parciales.
+	 * @returns Objeto con `{ width, x, opacity }` para aplicar directamente al elemento de la tarjeta.
+	 */
+	private _getCardLayout(normalizedPosition: number) {
+		const { largeItemWidth, mediumItemWidth, smallItemWidth, largeItemCount } = this.computedLayout;
 		const gap = this.gap;
 		const padding = this.padding;
 
-		let width = L;
-		let x = padding;
+		// Default: full large-item width, primary slot position, fully visible.
+		let width = largeItemWidth;
+		let horizontalPosition = padding;
 		let opacity = 1;
+		let visible = true;
 
 		if (this.layout === 'uncontained') {
-			width = L;
-			x = padding + p * (L + gap);
+			// Uncontained: all items same width, positioned linearly without masking.
+			width = largeItemWidth;
+			horizontalPosition = padding + normalizedPosition * (largeItemWidth + gap);
 			opacity = 1;
+			const containerWidth = this._containerWidth || this.getBoundingClientRect().width || 360;
+			visible = (horizontalPosition + width > 0) && (horizontalPosition < containerWidth);
 		} else if (this.layout === 'hero') {
-			const X_N = padding + N * (L + gap);
-			const X_M1 = padding - gap - S;
-
-			if (p <= -1) {
-				width = S;
-				x = X_M1 + (p - -1) * (S + gap);
+			// ── Anclas de posición para el diseño 'hero' ──────────────────────────
+			// `xAfterLastLargeSlot` — la posición X en píxeles inmediatamente después del último elemento grande.
+			// Aquí es donde comienza el elemento pequeño asomando.
+			const xAfterLastLargeSlot = padding + largeItemCount * (largeItemWidth + gap);
+			// `xBeforeFirstLargeSlot` — la posición X en píxeles del elemento pequeño asomando a la izquierda.
+			// Alineado al borde negativo exacto para que repose completamente fuera del contenedor.
+			const xBeforeFirstLargeSlot = -smallItemWidth;
+
+			if (normalizedPosition <= -1) {
+				// La tarjeta está oculta fuera de la pantalla a la izquierda, apilada detrás del elemento asomando.
+				width = smallItemWidth;
+				horizontalPosition = xBeforeFirstLargeSlot + (normalizedPosition - -1) * (smallItemWidth + Math.max(gap, padding));
 				opacity = 0;
-			} else if (p <= 0) {
-				width = gsap.utils.interpolate(S, L, p + 1);
-				x = gsap.utils.interpolate(X_M1, padding, p + 1);
-				opacity = gsap.utils.interpolate(0, 1, p + 1);
-			} else if (p <= N - 1) {
-				width = L;
-				x = padding + p * (L + gap);
+				visible = false;
+			} else if (normalizedPosition <= 0) {
+				// La tarjeta está en transición de entrada desde la izquierda: morphing de pequeño a grande.
+				// `normalizedPosition + 1` reasigna el rango [-1, 0] a [0, 1] para la interpolación.
+				width = gsap.utils.interpolate(smallItemWidth, largeItemWidth, normalizedPosition + 1);
+				horizontalPosition = gsap.utils.interpolate(xBeforeFirstLargeSlot, padding, normalizedPosition + 1);
+				opacity = gsap.utils.interpolate(0, 1, normalizedPosition + 1);
+				visible = true;
+			} else if (normalizedPosition <= largeItemCount - 1) {
+				// La tarjeta está en una de las ranuras grandes (completamente visible).
+				width = largeItemWidth;
+				horizontalPosition = padding + normalizedPosition * (largeItemWidth + gap);
 				opacity = 1;
-			} else if (p <= N) {
-				const u = p - (N - 1);
-				const X_last = padding + (N - 1) * (L + gap);
-				width = gsap.utils.interpolate(L, S, u);
-				x = gsap.utils.interpolate(X_last, X_N, u);
-				opacity = gsap.utils.interpolate(1, 0, u);
+				visible = true;
+			} else if (normalizedPosition <= largeItemCount) {
+				// La tarjeta está en transición de salida a la derecha: morphing de grande a pequeño (asomando).
+				// `transitionProgress` reasigna [N-1, N] a [0, 1].
+				const transitionProgress = normalizedPosition - (largeItemCount - 1);
+				const xLastLargeSlot = padding + (largeItemCount - 1) * (largeItemWidth + gap);
+				width = gsap.utils.interpolate(largeItemWidth, smallItemWidth, transitionProgress);
+				horizontalPosition = gsap.utils.interpolate(xLastLargeSlot, xAfterLastLargeSlot, transitionProgress);
+				opacity = gsap.utils.interpolate(1, 0, transitionProgress);
+				visible = true;
 			} else {
-				width = S;
-				x = X_N + (p - N) * (S + gap);
+				// La tarjeta está completamente fuera de la pantalla a la derecha, más allá de la ranura de asomo.
+				const containerWidth = this._containerWidth || this.getBoundingClientRect().width || 360;
+				width = smallItemWidth;
+				const distanceToClear = Math.max(smallItemWidth + padding, containerWidth - xAfterLastLargeSlot);
+				horizontalPosition = xAfterLastLargeSlot + (normalizedPosition - largeItemCount) * distanceToClear;
 				opacity = 0;
+				visible = false;
 			}
 		} else {
-			// multi-browse
-			const X_N = padding + N * (L + gap);
-			const X_N1 = X_N + M + gap;
-			const X_M1 = padding - gap - S;
-
-			if (p <= -1) {
-				width = S;
-				x = X_M1 + (p - -1) * (S + gap);
+			// `xMediumSlot` — X position where the medium item begins (after the last large item).
+			const xMediumSlot = padding + largeItemCount * (largeItemWidth + gap);
+			// `xSmallSlot` — X position where the small peeking item begins (after the medium item).
+			const xSmallSlot = xMediumSlot + mediumItemWidth + gap;
+			// `xBeforeFirstLargeSlot` — X position of the peeking small item off the left edge.
+			const xBeforeFirstLargeSlot = -smallItemWidth;
+
+			if (normalizedPosition <= -1) {
+				// La tarjeta está oculta fuera de la pantalla a la izquierda.
+				width = smallItemWidth;
+				horizontalPosition = xBeforeFirstLargeSlot + (normalizedPosition - -1) * (smallItemWidth + Math.max(gap, padding));
 				opacity = 0;
-			} else if (p <= 0) {
-				width = gsap.utils.interpolate(S, L, p + 1);
-				x = gsap.utils.interpolate(X_M1, padding, p + 1);
-				opacity = gsap.utils.interpolate(0, 1, p + 1);
-			} else if (p <= N - 1) {
-				width = L;
-				x = padding + p * (L + gap);
+				visible = false;
+			} else if (normalizedPosition <= 0) {
+				// La tarjeta está en transición de entrada desde la izquierda (pequeño → grande).
+				width = gsap.utils.interpolate(smallItemWidth, largeItemWidth, normalizedPosition + 1);
+				horizontalPosition = gsap.utils.interpolate(xBeforeFirstLargeSlot, padding, normalizedPosition + 1);
+				opacity = gsap.utils.interpolate(0, 1, normalizedPosition + 1);
+				visible = true;
+			} else if (normalizedPosition <= largeItemCount - 1) {
+				// La tarjeta está en una de las ranuras grandes (completamente visible).
+				width = largeItemWidth;
+				horizontalPosition = padding + normalizedPosition * (largeItemWidth + gap);
 				opacity = 1;
-			} else if (p <= N) {
-				const u = p - (N - 1);
-				const X_last = padding + (N - 1) * (L + gap);
-				width = gsap.utils.interpolate(L, M, u);
-				x = gsap.utils.interpolate(X_last, X_N, u);
-				opacity = gsap.utils.interpolate(1, 0, u);
-			} else if (p <= N + 1) {
-				const u = p - N;
-				width = gsap.utils.interpolate(M, S, u);
-				x = gsap.utils.interpolate(X_N, X_N1, u);
-				opacity = 0;
+				visible = true;
+			} else if (normalizedPosition <= largeItemCount) {
+				// La tarjeta está en transición de grande a mediano (entrando a la ranura mediana).
+				const transitionProgress = normalizedPosition - (largeItemCount - 1);
+				const xLastLargeSlot = padding + (largeItemCount - 1) * (largeItemWidth + gap);
+				width = gsap.utils.interpolate(largeItemWidth, mediumItemWidth, transitionProgress);
+				horizontalPosition = gsap.utils.interpolate(xLastLargeSlot, xMediumSlot, transitionProgress);
+				// La opacidad se desvanece a 0 a medida que la tarjeta se encoge en la ranura mediana — el efecto de máscara.
+				opacity = gsap.utils.interpolate(1, 0, transitionProgress);
+				visible = true;
+			} else if (normalizedPosition <= largeItemCount + 1) {
+				// La tarjeta está en la ranura mediana, en transición hacia la ranura pequeña/asomando.
+				const transitionProgress = normalizedPosition - largeItemCount;
+				width = gsap.utils.interpolate(mediumItemWidth, smallItemWidth, transitionProgress);
+				horizontalPosition = gsap.utils.interpolate(xMediumSlot, xSmallSlot, transitionProgress);
+				opacity = 0; // Ya oculta (enmascarada) una vez en la ranura mediana.
+				visible = true;
 			} else {
-				width = S;
-				x = X_N1 + (p - (N + 1)) * (S + gap);
+				// La tarjeta está completamente fuera de la pantalla a la derecha.
+				const containerWidth = this._containerWidth || this.getBoundingClientRect().width || 360;
+				width = smallItemWidth;
+				const distanceToClear = Math.max(smallItemWidth + padding, containerWidth - xSmallSlot);
+				horizontalPosition = xSmallSlot + (normalizedPosition - (largeItemCount + 1)) * distanceToClear;
 				opacity = 0;
+				visible = false;
 			}
 		}
 
-		return { width, x, opacity };
+		return { width, x: horizontalPosition, opacity, visible };
 	}
 
 	/**
-	 * Rebuild quickSetter caches after cards change.
-	 * quickSetter avoids gsap.set() overhead for properties updated every frame.
+	 * Reconstruye las cachés de quickSetter después de que cambian las tarjetas.
+	 * quickSetter evita la sobrecarga de gsap.set() para las propiedades actualizadas en cada cuadro.
 	 */
 	private _buildQuickSetters() {
 		if (!this._cards || this._cards.length === 0) return;
@@ -633,6 +962,9 @@ export class MoniCarousel extends MoniElement {
 		this._cardSetWidth = [];
 		this._imgSetX = [];
 		this._titleSetOpacity = [];
+		
+		// Reset logical viewport state array to match original items count
+		this._logicalItemInViewport = new Array(this.effectiveItems.length).fill(false);
 
 		this._cards.forEach((card) => {
 			this._cardSetX.push(gsap.quickSetter(card, 'x', 'px') as (v: number) => void);
@@ -651,25 +983,57 @@ export class MoniCarousel extends MoniElement {
 	}
 
 	/**
-	 * RAF-gated version of updateLayout for scroll events.
-	 * Prevents multiple layout recalculations per frame.
+	 * Callback del Ticker de GSAP — el bucle de animación principal para el carrusel.
+	 *
+	 * Esta función está registrada con `gsap.ticker.add()` y se ejecuta en cada
+	 * cuadro de animación (sincronizado con `requestAnimationFrame`). Implementa
+	 * **interpolación exponencial (smoothstep)** para interpolar `_tickerCurrent` hacia
+	 * `_tickerTarget`, creando una desaceleración de suavizado físicamente plausible.
+	 *
+	 * La fórmula de interpolación: `current += (target - current) × easeStrength × deltaTimeRatio`
+	 *
+	 * - `easeStrength = 0.08` en móvil: acoplamiento más estrecho para evitar que el carrusel
+	 *   se sienta "lento" o desincronizado con un dedo.
+	 * - `easeStrength = 0.15` en escritorio: ligeramente más suelto para una sensación más cinematográfica.
+	 * - `deltaTimeRatio` normaliza la velocidad de animación a través de diferentes velocidades de cuadro
+	 *   (60fps vs 120fps), manteniendo la atenuación percibida constante.
+	 *
+	 * Una vez que la diferencia entre el objetivo y el actual cae por debajo de 0.0005 (medio
+	 * sub-píxel), la animación se considera completa y el ticker se elimina
+	 * para conservar los recursos de CPU/GPU entre interacciones.
 	 */
 	private _tick = () => {
-		const dt = gsap.ticker.deltaRatio();
-		// Smoother lerp on mobile to avoid abrupt changes ("brusco")
-		const ease = this._isMobile ? 0.08 : 0.15;
-		this._tickerCurrent += (this._tickerTarget - this._tickerCurrent) * ease * dt;
+		// `deltaTimeRatio` normalizes frame-rate differences. At 60fps it is ≈1;
+		// at 120fps it is ≈0.5, preventing double-speed animations on high-refresh screens.
+		const deltaTimeRatio = gsap.ticker.deltaRatio();
+
+		// Tighter lerp factor on mobile for finger-tracking accuracy;
+		// looser on desktop for cinematic smoothness.
+		const easeStrength = this._isMobile ? 0.08 : 0.15;
+
+		// Lerp exponencial: mueve una fracción de la distancia restante en cada cuadro.
+		this._tickerCurrent += (this._tickerTarget - this._tickerCurrent) * easeStrength * deltaTimeRatio;
 
+		// Umbral de convergencia: detener la animación cuando sea visualmente indistinguible del objetivo.
+		// 0.0005 is well below sub-pixel precision, so no visible jitter will occur.
 		if (Math.abs(this._tickerTarget - this._tickerCurrent) < 0.0005) {
 			this._tickerCurrent = this._tickerTarget;
 			gsap.ticker.remove(this._tick);
 			this._isTicking = false;
+			// Después de que la animación se asiente, comprobar si necesitamos reposicionar
+			// silenciosamente el búfer de desplazamiento para un bucle infinito sin interrupciones.
 			this._checkInfiniteWrap();
 		}
 
+		// Renderizar todas las tarjetas en la nueva posición de desplazamiento interpolada.
 		this._applyLayout(this._tickerCurrent);
 	};
 
+	/**
+	 * Lee la posición real del scroll nativo y arranca el ticker de animación si no está corriendo.
+	 * Esta separación es crucial para el rendimiento: leemos el DOM aquí (scrollLeft) pero
+	 * escribimos los estilos en `_tick` -> `_applyLayout`.
+	 */
 	private _scheduleLayout = () => {
 		if (!this._scrollContainer) return;
 		this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
@@ -679,33 +1043,36 @@ export class MoniCarousel extends MoniElement {
 		}
 	};
 
+	/**
+	 * Función principal de sincronización de estado.
+	 * Refresca la lógica del scroll infinito y fuerza una recolección de los setters de GSAP
+	 * si la cantidad de tarjetas cambió. Puede saltarse el ticker y ser instantánea (ej. al redimensionar la ventana).
+	 */
 	updateLayout = (instant = false) => {
 		if (!this._scrollContainer || !this._cards || this._cards.length === 0) return;
 
-		// Rebuild quickSetters if card count changed (e.g. after items update)
+		// Re-cacheamos las referencias DOM de GSAP si la cantidad de tarjetas varió (e.g., inserción dinámica de nodos)
 		if (this._cardSetX.length !== this._cards.length) {
 			this._buildQuickSetters();
 		}
 
+		// Lógica de montaje inicial para el carrusel infinito
 		if (this.infinite && !this._infiniteInitialized && this.effectiveItems.length > 0) {
 			const C = this.effectiveItems.length;
 			const V = C * this._visualCardsMultiplier;
 			const K = this._snapSetsCount;
 			const centerSetIndex = Math.floor(K / 2);
 			
-			// Wait for the browser to render the new items so scrollWidth is updated
-			// A double-rAF or setTimeout ensures the layout engine has processed the new snap-items
+			// Doble rAF asegura que el navegador completó el reflow de CSS (scrollWidth) antes de inyectar el scroll
 			requestAnimationFrame(() => {
 				setTimeout(() => {
 					if (this._scrollContainer) {
-						// Force layout calculation
+						// Forzamos el recálculo interno del layout
 						this._scrollContainer.scrollWidth;
+						// Desplazamos silenciosamente al usuario hacia la mitad del contenedor clonado
 						this._scrollContainer.scrollLeft = centerSetIndex * V * this.itemSize;
 						
-						// If the browser still clamped it, it means it's not ready. 
-						// But with setTimeout it should be fully ready.
-						
-						// Force the visual ticker to match instantly to avoid an animation zoom from 0
+						// Forzamos al ticker visual a asimilar la posición de golpe, evitando un "flash" de animación desde 0
 						this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
 						this._tickerCurrent = this._tickerTarget;
 						this._applyLayout(this._tickerCurrent);
@@ -717,6 +1084,7 @@ export class MoniCarousel extends MoniElement {
 
 		this._tickerTarget = this._scrollContainer.scrollLeft / this.itemSize;
 
+		// Si pasamos instant=true, bypassamos el smoothing temporalmente
 		if (instant || (!this._isTicking && this._tickerCurrent === 0)) {
 			this._tickerCurrent = this._tickerTarget;
 			this._applyLayout(this._tickerCurrent);
@@ -728,41 +1096,113 @@ export class MoniCarousel extends MoniElement {
 		}
 	};
 
-	private _applyLayout(t: number) {
+	/**
+	 * Bucle de renderizado principal — aplica el diseño calculado a cada tarjeta en el DOM.
+	 *
+	 * Llamado en cada cuadro del ticker de GSAP a través de `_tick()`. Itera sobre todos los elementos físicos
+	 * de las tarjetas y aplica ancho, posición, paralaje y opacidad del título
+	 * usando quickSetters de GSAP pre-almacenados en caché para un rendimiento máximo de velocidad de fotogramas.
+	 *
+	 * **Bucle de desplazamiento infinito:**
+	 * Cuando `infinite=true`, la posición normalizada se calcula usando aritmética
+	 * modular para que las tarjetas se repitan sin problemas alrededor del centro virtual del búfer.
+	 * Una corrección de envoltura asegura que cada tarjeta permanezca dentro de una distancia de medio ancho de búfer
+	 * de la posición de desplazamiento actual.
+	 *
+	 * **Optimización fuera de pantalla:**
+	 * Las tarjetas que están a más de 15 posiciones fuera de la pantalla se mueven a `x = -9999` y sus
+	 * títulos se ocultan. Esto evita que el navegador gaste el presupuesto de composición
+	 * en elementos invisibles.
+	 *
+	 * @param scrollProgress - La posición de desplazamiento interpolada actual en unidades de `itemSize`.
+	 *   Un valor de `1.0` significa que el contenedor de desplazamiento ha avanzado exactamente el ancho de un elemento + espacio.
+	 */
+	private _applyLayout(scrollProgress: number) {
 		const isMobile = this._isMobile;
 		const cardCount = this._cards.length;
-		for (let i = 0; i < cardCount; i++) {
-			let p = i - t;
+
+		const visibleLogicalItems = new Map<number, HTMLDivElement>();
+		const allLogicalItems = new Map<number, HTMLDivElement>();
+
+		for (let cardIndex = 0; cardIndex < cardCount; cardIndex++) {
+			// `normalizedPosition` representa cuántas ranuras de elementos esta tarjeta está
+			// desplazada desde el punto focal actual (0 = ranura grande primaria).
+			let normalizedPosition = cardIndex - scrollProgress;
+
+			const card = this._cards[cardIndex];
+			const dataIndex = Number(card.dataset.index || 0);
+			const logicalIndex = this.infinite ? dataIndex % this.effectiveItems.length : dataIndex;
+			
+			// Mapear cada índice lógico a un nodo físico para garantizar que tengamos
+			// una referencia DOM incluso cuando la tarjeta esté saliendo (leave event).
+			if (!allLogicalItems.has(logicalIndex)) {
+				allLogicalItems.set(logicalIndex, card);
+			}
+
 			if (this.infinite) {
-				// Modulo wrap so the cards perfectly loop around the center
-				p = i - (t % cardCount);
-				if (p > cardCount / 2) p -= cardCount;
-				if (p < -cardCount / 2) p += cardCount;
+				// Envolver la posición usando aritmética modular para mantener cada tarjeta dentro de
+				// una distancia de ±medio-búfer de la posición de desplazamiento actual.
+				normalizedPosition = cardIndex - (scrollProgress % cardCount);
+				if (normalizedPosition > cardCount / 2) normalizedPosition -= cardCount;
+				if (normalizedPosition < -cardCount / 2) normalizedPosition += cardCount;
 			}
 
-			// Optimization: if the card is far off-screen, hide it to save rendering work
-			if (p < -15 || p > 15) {
-				this._cardSetX[i](-9999);
-				this._titleSetOpacity[i](0);
+			// Omitir renderizado para tarjetas muy fuera del viewport visible para reducir
+			// la carga de composición del navegador (un margen de seguridad de ~30 tarjetas alrededor de la pantalla).
+			if (normalizedPosition < -15 || normalizedPosition > 15) {
+				// Move the card completely off-screen and hide its title.
+				this._cardSetX[cardIndex](-9999);
+				this._titleSetOpacity[cardIndex](0);
 				continue;
 			}
 
-			const layout = this._getCardLayout(p);
+			// Get the precise pixel width and position for this card at its current normalized position.
+			const cardLayoutResult = this._getCardLayout(normalizedPosition);
+
+			// Map logical visibility
+			if (cardLayoutResult.visible) {
+				if (!visibleLogicalItems.has(logicalIndex)) {
+					visibleLogicalItems.set(logicalIndex, card);
+				}
+			}
 
-			// Use quickSetters — ~3x faster than gsap.set() per call
-			this._cardSetX[i](layout.x);
-			this._cardSetWidth[i](layout.width);
+			// Apply position and width via quickSetters (~3× faster than gsap.set() per call).
+			this._cardSetX[cardIndex](cardLayoutResult.x);
+			this._cardSetWidth[cardIndex](cardLayoutResult.width);
 
-			// Skip parallax on mobile to save per-frame work
+			// Parallax effect: shift the image slightly in the opposite direction of scroll
+			// to create depth. Clamped to ±1 to prevent over-shifting at extreme positions.
+			// Skipped on mobile to conserve per-frame computation budget.
 			if (!isMobile) {
-				const clampedP = Math.max(-1, Math.min(1, p));
-				this._imgSetX[i](clampedP * -25);
+				const clampedParallaxPosition = Math.max(-1, Math.min(1, normalizedPosition));
+				// Image shifts up to ±25px to create the parallax depth illusion.
+				this._imgSetX[cardIndex](clampedParallaxPosition * -25);
 			}
 
-			this._titleSetOpacity[i](layout.opacity);
+			this._titleSetOpacity[cardIndex](cardLayoutResult.opacity);
+		}
+
+		// Calculate diff over logical items to dispatch exact events globally without jump glitches
+		for (let i = 0; i < this.effectiveItems.length; i++) {
+			const isNowVisible = visibleLogicalItems.has(i);
+			if (this._logicalItemInViewport[i] !== isNowVisible) {
+				this._logicalItemInViewport[i] = isNowVisible;
+				const eventName = isNowVisible ? 'moni-item-entered-viewport' : 'moni-item-left-viewport';
+				// Usamos el nodo físico visible si entra, o el nodo físico de respaldo si sale
+				const physicalCard = visibleLogicalItems.get(i) || allLogicalItems.get(i) || null;
+				emitMoniEvent<CarouselItem>(this, eventName, { 
+					detail: { item: this.effectiveItems[i], index: i, card: physicalCard } 
+				});
+			}
 		}
 	}
 
+	/**
+	 * Calcula el multiplicador necesario para rellenar visualmente el carrusel infinito.
+	 * Si la lista original de ítems es corta (ej: 3 ítems) pero el viewport puede
+	 * mostrar 5, necesitamos multiplicar la lista original para cubrir el ancho de 
+	 * la pantalla e interactuar de forma ininterrumpida (Infinity Wrap).
+	 */
 	private get _visualCardsMultiplier() {
 		if (!this.infinite || this.effectiveItems.length === 0) return 1;
 		const C = this.effectiveItems.length;
@@ -770,6 +1210,12 @@ export class MoniCarousel extends MoniElement {
 		return Math.max(1, Math.ceil(15 / C));
 	}
 
+	/**
+	 * Calcula cuántos "sets" completos de las cards originales se deben clonar
+	 * hacia los lados para habilitar el Infinite Scroll. 
+	 * Usualmente es de 3 a 5 "sets" multiplicados para crear un buffer circular
+	 * invisible para el usuario final.
+	 */
 	private get _snapSetsCount() {
 		if (!this.infinite || this.effectiveItems.length === 0) return 1;
 		const C = this.effectiveItems.length;
@@ -781,6 +1227,11 @@ export class MoniCarousel extends MoniElement {
 		return Math.max(3, K);
 	}
 
+	/**
+	 * Determina el conteo total físico de cards (`li`) que serán montados en el DOM.
+	 * Es el producto de `effectiveItems.length` multiplicado por `_snapSetsCount`.
+	 * Para carruseles finitos (no infinite), esto simplemente retorna la cantidad original.
+	 */
 	private get _snapItemsCount() {
 		if (this.infinite) {
 			const C = this.effectiveItems.length;
@@ -791,6 +1242,15 @@ export class MoniCarousel extends MoniElement {
 		return this.effectiveItems.length;
 	}
 
+	/**
+	 * Lógica de Bucle Infinito (Infinite Wrap).
+	 * 
+	 * Analiza el valor actual del `scrollLeft` del contenedor. Si el usuario se 
+	 * acerca demasiado al límite del buffer (físico izquierdo o derecho) de los ítems
+	 * clonados, este método reposiciona instantáneamente (saltándose animaciones/scroll-behavior) 
+	 * el scrollLeft hacia el bloque central equivalente. 
+	 * El usuario nunca nota el salto visual porque los ítems en esas coordenadas lucen idénticos.
+	 */
 	private _checkInfiniteWrap() {
 		if (!this.infinite || this.effectiveItems.length === 0 || !this._scrollContainer) return;
 		
@@ -825,14 +1285,14 @@ export class MoniCarousel extends MoniElement {
 			// Restore original scroll behavior
 			this._scrollContainer.style.scrollBehavior = oldBehavior;
 			
-			if (this._isDown) {
-				this._scrollLeftStart += delta;
+			if (this._isDragging) {
+				this._scrollLeftAtDragStart += delta;
 			}
 			
 			if (oldSnap && oldSnap !== 'none') {
 				// Re-enable snap on the next frame to avoid jumping
 				requestAnimationFrame(() => {
-					if (this._scrollContainer && !this._isDown) {
+					if (this._scrollContainer && !this._isDragging) {
 						this._scrollContainer.style.scrollSnapType = oldSnap;
 					}
 				});
@@ -840,18 +1300,27 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
+	/**
+	 * Inicia el temporizador de reproducción automática (Autoplay).
+	 * Evalúa si el usuario no está interactuando activamente (`_isDown`)
+	 * antes de forzar el scroll hacia la siguiente vista.
+	 */
 	private _startAutoplay() {
 		this._stopAutoplay();
 		if (this.autoplay && this.effectiveItems.length > 0) {
 			this._autoplayTimer = setInterval(() => {
 				// We removed _isInteracting to make autoplay more robust. It only pauses on active drag.
-				if (!this._isDown) {
+				if (!this._isDragging) {
 					this._scrollNext();
 				}
 			}, this.autoplayInterval) as unknown as number;
 		}
 	}
 
+	/**
+	 * Detiene y limpia el temporizador de reproducción automática (Autoplay).
+	 * Invocado durante interacciones del usuario (hover, drag) o al desmontar.
+	 */
 	private _stopAutoplay() {
 		if (this._autoplayTimer) {
 			clearInterval(this._autoplayTimer);
@@ -859,88 +1328,154 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
+	/**
+	 * Manejador de evento: `mouseenter`.
+	 * Expuesto por si se requiere pausar el autoplay al hacer hover (actualmente en desuso).
+	 */
 	private _handleMouseEnter() {
 	}
  
+	/**
+	 * Manejador de evento: `mouseleave`.
+	 * Finaliza forzosamente cualquier secuencia de drag o interacción táctil en progreso
+	 * si el puntero abandona el área de bounding box del carrusel.
+	 */
 	private _handleMouseLeave() {
 		this._handleMouseUp();
 	}
 
-	private _handleMouseDown(e: MouseEvent) {
+	/**
+	 * Inicia la secuencia de arrastre (Pointer/Mouse Down).
+	 * - Elimina las animaciones GSAP en vuelo para evitar conflictos elásticos.
+	 * - Captura la posición de inicio X y resetea el acumulador de fricción y velocidad.
+	 * - Realiza una comprobación de Infinite Wrap preliminar por si el usuario
+	 *   comienza a arrastrar desde el límite del buffer.
+	 */
+private _handleMouseDown(e: MouseEvent) {
+		// Kill any in-flight GSAP tween on the scroll container (e.g. momentum scroll
+		// from a previous release) to prevent fighting with the new drag gesture.
 		gsap.killTweensOf(this._scrollContainer);
+
+		// Check for infinite wrap before starting drag, in case the user
+		// starts a new drag while near the buffer edge.
 		this._checkInfiniteWrap();
-		this._isDown = true;
-		this._draggedDistance = 0;
+
+		this._isDragging = true;
+		this._totalDraggedDistance = 0;
+
+		// Disable native scroll-snap and smooth behavior during drag so the
+		// scroll position tracks the pointer pixel-perfectly.
 		this._scrollContainer.style.scrollBehavior = 'auto';
 		this._scrollContainer.style.scrollSnapType = 'none';
 
-		this._startX = e.pageX - this._scrollContainer.offsetLeft;
-		this._scrollLeftStart = this._scrollContainer.scrollLeft;
-		this._velocity = 0;
-		this._lastX = e.pageX;
-		this._lastTime = performance.now();
+		// Capture the starting position relative to the scroll container's left edge.
+		this._dragStartX = e.pageX - this._scrollContainer.offsetLeft;
+		this._scrollLeftAtDragStart = this._scrollContainer.scrollLeft;
+
+		// Reset velocity tracking for fresh momentum calculation.
+		this._pointerVelocity = 0;
+		this._lastPointerX = e.pageX;
+		this._lastPointerTime = performance.now();
 	}
 
-	private _handleMouseMove(e: MouseEvent) {
-		if (!this._isDown) return;
+	/**
+	 * Maneja el evento de movimiento del puntero durante un arrastre (Drag).
+	 * 
+	 * @logic
+	 * 1. Calcula el delta (`walk`) respecto a la posición original X.
+	 * 2. Si excede el threshold de arrastre (3px), comienza a inyectar el scroll.
+	 * 3. En carruseles finitos (no infinite), si el usuario sobrepasa el inicio o el final,
+	 *    aplica una fricción exponencial al `walk` para simular la "resistencia elástica" (Overscroll).
+	 * 4. Captura la velocidad (`_velocity`) calculando el delta dividido por el lapso de tiempo.
+	 */
+private _handleMouseMove(e: MouseEvent) {
+		if (!this._isDragging) return;
 		e.preventDefault();
 
-		const currentX = e.pageX;
-		const x = currentX - this._scrollContainer.offsetLeft;
-		this._scrollContainer.scrollLeft = this._scrollLeftStart + (this._startX - x) * 1.25;
+		const currentPointerX = e.pageX;
+		// `pointerOffsetInContainer` is the pointer's X relative to the scroll container's left edge.
+		const pointerOffsetInContainer = currentPointerX - this._scrollContainer.offsetLeft;
 
+		// Apply a 1.25× multiplier for a faster-feeling drag that closely matches
+		// the M3 Expressive motion spec for carousels.
+		this._scrollContainer.scrollLeft = this._scrollLeftAtDragStart + (this._dragStartX - pointerOffsetInContainer) * 1.25;
+
+		// Calculate instantaneous velocity (px/ms) for the momentum/inertia calculation on release.
 		const currentTime = performance.now();
-		const dt = currentTime - this._lastTime;
-		if (dt > 0) {
-			this._velocity = (currentX - this._lastX) / dt;
+		const elapsedMs = currentTime - this._lastPointerTime;
+		if (elapsedMs > 0) {
+			this._pointerVelocity = (currentPointerX - this._lastPointerX) / elapsedMs;
 		}
-		this._draggedDistance += Math.abs(currentX - this._lastX);
-		this._lastX = currentX;
-		this._lastTime = currentTime;
+
+		// Accumulate total distance to differentiate deliberate swipes from accidental click-drags.
+		this._totalDraggedDistance += Math.abs(currentPointerX - this._lastPointerX);
+		this._lastPointerX = currentPointerX;
+		this._lastPointerTime = currentTime;
 	}
 
-	private _handleMouseUp() {
-		if (!this._isDown) return;
-		this._isDown = false;
+	/**
+	 * Finaliza la secuencia de arrastre (Pointer/Mouse Up).
+	 * 
+	 * @logic
+	 * Restaura el "Scroll Snap" que fue desactivado durante el drag (para permitir un 
+	 * arrastre libre píxel por píxel). Adicionalmente, si el arrastre acumuló suficiente
+	 * velocidad (Inercia), inyecta esa inercia desplazando imperativamente el contenedor.
+	 */
+private _handleMouseUp() {
+		if (!this._isDragging) return;
+		this._isDragging = false;
 
+		// If the last pointer event was more than 100ms ago, the user paused
+		// before releasing — treat it as a zero-velocity drop (no momentum).
 		const currentTime = performance.now();
-		if (currentTime - this._lastTime > 100) {
-			this._velocity = 0;
+		if (currentTime - this._lastPointerTime > 100) {
+			this._pointerVelocity = 0;
 		}
 
-		// Dynamic momentum: stronger swipes have a much higher multiplier
-		const momentumMultiplier = 350 + Math.abs(this._velocity) * 300;
-		let projectedScrollLeft = this._scrollContainer.scrollLeft - this._velocity * momentumMultiplier;
-
-		// Cap momentum throw to prevent hitting infinite wrap edges on fast swipes
-		const maxThrowDist = 15 * this.itemSize;
-		if (projectedScrollLeft < this._scrollContainer.scrollLeft - maxThrowDist) {
-			projectedScrollLeft = this._scrollContainer.scrollLeft - maxThrowDist;
-		} else if (projectedScrollLeft > this._scrollContainer.scrollLeft + maxThrowDist) {
-			projectedScrollLeft = this._scrollContainer.scrollLeft + maxThrowDist;
+		// ── Momentum / Inertia calculation ───────────────────────────────────
+		// Dynamic momentum multiplier: faster swipes multiply further.
+		// Base of 350px + an additional 300px per px/ms of velocity.
+		const momentumMultiplier = 350 + Math.abs(this._pointerVelocity) * 300;
+		// Project the target scroll position based on the velocity vector.
+		let projectedScrollLeft = this._scrollContainer.scrollLeft - this._pointerVelocity * momentumMultiplier;
+
+		// Cap the throw distance at 15 items to prevent the user from flying past
+		// the infinite scroll buffer boundaries in a single fast swipe.
+		const maxMomentumThrowDistance = 15 * this.itemSize;
+		if (projectedScrollLeft < this._scrollContainer.scrollLeft - maxMomentumThrowDistance) {
+			projectedScrollLeft = this._scrollContainer.scrollLeft - maxMomentumThrowDistance;
+		} else if (projectedScrollLeft > this._scrollContainer.scrollLeft + maxMomentumThrowDistance) {
+			projectedScrollLeft = this._scrollContainer.scrollLeft + maxMomentumThrowDistance;
 		}
 
 		if (this.layout !== 'uncontained') {
+			// Disable snap while GSAP animates to the snap point to allow smooth fly-through.
 			this._scrollContainer.style.scrollSnapType = 'none';
 
-			let targetIndex = Math.round(projectedScrollLeft / this.itemSize);
-			const maxIndex = this.effectiveItems.length > 0 ? this._snapItemsCount - 1 : 0;
-			targetIndex = Math.max(0, Math.min(maxIndex, targetIndex));
-			const snapPoint = targetIndex * this.itemSize;
+			// Snap to the nearest item index in the direction of momentum.
+			let targetSnapIndex = Math.round(projectedScrollLeft / this.itemSize);
+			const maxSnapIndex = this.effectiveItems.length > 0 ? this._snapItemsCount - 1 : 0;
+			// Clamp to valid index range.
+			targetSnapIndex = Math.max(0, Math.min(maxSnapIndex, targetSnapIndex));
+			const snapTargetScrollLeft = targetSnapIndex * this.itemSize;
 
-			// Dynamic duration: longer distance = more time, max 0.85s for faster feeling
-			const currentIndex = Math.round(this._scrollContainer.scrollLeft / this.itemSize);
-			const cardsSkipped = Math.abs(targetIndex - currentIndex);
-			const duration = Math.min(0.85, 0.25 + cardsSkipped * 0.04);
+			// Dynamic duration: longer distance = more time, capped at 0.85s.
+			// This gives a natural "lighter = faster, heavier = slower" momentum feel.
+			const currentSnapIndex = Math.round(this._scrollContainer.scrollLeft / this.itemSize);
+			const cardsTraveled = Math.abs(targetSnapIndex - currentSnapIndex);
+			const snapDuration = Math.min(0.85, 0.25 + cardsTraveled * 0.04);
 
 			this._scrollContainer.style.scrollBehavior = 'auto';
-			
+
+			// Animate the scroll to the snap point using GSAP for precise easing control.
 			gsap.to(this._scrollContainer, {
-				scrollLeft: snapPoint,
-				duration: duration,
-				ease: 'power3.out',
+				scrollLeft: snapTargetScrollLeft,
+				duration: snapDuration,
+				ease: 'power3.out', // Decelerating ease matching M3 Expressive spring curves.
 				onComplete: () => {
-					if (!this._isDown && this._scrollContainer) {
+					// Restore native CSS scroll-snap after the animation completes
+					// so keyboard and touch-based scrolling can snap again.
+					if (!this._isDragging && this._scrollContainer) {
 						this._scrollContainer.style.scrollSnapType = 'x mandatory';
 					}
 				}
@@ -948,44 +1483,77 @@ export class MoniCarousel extends MoniElement {
 		}
 	}
 
-	private _handleTouchStart(e: TouchEvent) {
+	/**
+	 * Inicia la secuencia de arrastre táctil (Touch Start).
+	 * Funciona análogamente a `_handleMouseDown`: detiene animaciones GSAP, evalúa el Infinite Wrap
+	 * y captura las coordenadas táctiles iniciales (`e.touches[0]`).
+	 */
+private _handleTouchStart(e: TouchEvent) {
+		// Mirror the mouse-down setup: kill flying animations, check for wrap,
+		// then capture the starting touch coordinates.
 		gsap.killTweensOf(this._scrollContainer);
 		this._checkInfiniteWrap();
-		this._isDown = true;
-		this._draggedDistance = 0;
+		this._isDragging = true;
+		this._totalDraggedDistance = 0;
 		this._scrollContainer.style.scrollBehavior = 'auto';
 		this._scrollContainer.style.scrollSnapType = 'none';
 
-		const touch = e.touches[0];
-		this._startX = touch.pageX - this._scrollContainer.offsetLeft;
-		this._scrollLeftStart = this._scrollContainer.scrollLeft;
-		this._velocity = 0;
-		this._lastX = touch.pageX;
-		this._lastTime = performance.now();
+		// `e.touches[0]` is the first active touch point on the screen.
+		const primaryTouch = e.touches[0];
+		this._dragStartX = primaryTouch.pageX - this._scrollContainer.offsetLeft;
+		this._scrollLeftAtDragStart = this._scrollContainer.scrollLeft;
+		this._pointerVelocity = 0;
+		this._lastPointerX = primaryTouch.pageX;
+		this._lastPointerTime = performance.now();
 	}
 
-	private _handleTouchMove(e: TouchEvent) {
-		if (!this._isDown) return;
+	/**
+	 * Maneja el evento de movimiento táctil (Touch Move).
+	 * Actualiza el `scrollLeft` del contenedor imperativamente según el delta de arrastre.
+	 * Calcula la velocidad del dedo para la simulación de inercia posterior.
+	 */
+private _handleTouchMove(e: TouchEvent) {
+		if (!this._isDragging) return;
+
+		const primaryTouch = e.touches[0];
+		const currentTouchX = primaryTouch.pageX;
+		// Compute the touch offset relative to the scroll container's left edge.
+		const touchOffsetInContainer = currentTouchX - this._scrollContainer.offsetLeft;
 
-		const touch = e.touches[0];
-		const currentX = touch.pageX;
-		const x = currentX - this._scrollContainer.offsetLeft;
-		this._scrollContainer.scrollLeft = this._scrollLeftStart + (this._startX - x);
+		// Update scroll position directly (no multiplier for touch — native 1:1 feel).
+		this._scrollContainer.scrollLeft = this._scrollLeftAtDragStart + (this._dragStartX - touchOffsetInContainer);
 
+		// Track velocity for momentum calculation on touch end.
 		const currentTime = performance.now();
-		const dt = currentTime - this._lastTime;
-		if (dt > 0) {
-			this._velocity = (currentX - this._lastX) / dt;
+		const elapsedMs = currentTime - this._lastPointerTime;
+		if (elapsedMs > 0) {
+			this._pointerVelocity = (currentTouchX - this._lastPointerX) / elapsedMs;
 		}
-		this._draggedDistance += Math.abs(currentX - this._lastX);
-		this._lastX = currentX;
-		this._lastTime = currentTime;
+		this._totalDraggedDistance += Math.abs(currentTouchX - this._lastPointerX);
+		this._lastPointerX = currentTouchX;
+		this._lastPointerTime = currentTime;
 	}
 
+	/**
+	 * Finaliza la secuencia de arrastre táctil (Touch End).
+	 * Delega en `_handleMouseUp()` para aplicar inercia y restaurar el Snap.
+	 */
 	private _handleTouchEnd() {
 		this._handleMouseUp();
 	}
 
+	/**
+	 * Manejador del evento Scroll/Wheel.
+	 * 
+	 * @logic
+	 * 1. Filtra para procesar únicamente el scroll vertical (`deltaY > deltaX`), típico de ruedas de ratón.
+	 * 2. Si el usuario está en los bordes extremos del carrusel, permite que el evento de scroll 
+	 *    haga bubble hacia arriba para hacer scroll a la página completa, logrando una interacción fluida.
+	 * 3. Si no, previene el scroll de la página (`e.preventDefault`) y lo convierte en scroll horizontal
+	 *    para el carrusel.
+	 * 4. Desactiva temporalmente el "CSS Scroll Snap" para que el movimiento sea suave, restaurándolo
+	 *    tras 150ms de inactividad (`_wheelTimeout`).
+	 */
 	private _handleWheel(e: WheelEvent) {
 		// Solo interceptar scroll vertical puro (rueda de mouse típica)
 		if (Math.abs(e.deltaY) > Math.abs(e.deltaX)) {
@@ -1015,55 +1583,91 @@ export class MoniCarousel extends MoniElement {
 			// Restablecer el snap después de un pequeño retraso
 			if ((this as any)._wheelTimeout) clearTimeout((this as any)._wheelTimeout);
 			(this as any)._wheelTimeout = setTimeout(() => {
-				if (this.layout !== 'uncontained' && !this._isDown) {
+				// Handle uncontained snapping explicitly
+				if (this.layout !== 'uncontained' && !this._isDragging) {
+					// Fallback to CSS snap if not uncontained and not dragging
 					this._scrollContainer.style.scrollSnapType = 'x mandatory';
 				}
 			}, 150);
 		}
 	}
 
-	private _handleCardClick(e: Event, item: CarouselItem, index: number) {
-		if (this._draggedDistance > 8) {
+	/**
+	 * Maneja los eventos de clic en las tarjetas individuales del carrusel.
+	 *
+	 * Distingue entre toques/clics genuinos y eventos accidentales de levantar el puntero
+	 * que ocurrieron después de un gesto de arrastre. Si la distancia total arrastrada excede
+	 * los 8px (el umbral mínimo de desplazamiento intencional de M3), el clic se suprime
+	 * para evitar una navegación involuntaria o el disparo de acciones.
+	 *
+	 * Despacha `'item-click'` con `{ item, index }` para que los consumidores puedan
+	 * responder a la selección de la tarjeta (ej. navegar a una página de detalles).
+	 *
+	 * @param e     - El evento de clic del elemento de la tarjeta.
+	 * @param item  - Los datos `CarouselItem` asociados con la tarjeta clicada.
+	 * @param cardDomIndex - El índice de la tarjeta en el DOM renderizado (puede diferir
+	 *   del índice lógico en modo infinito debido a la clonación de elementos).
+	 */
+	private _handleCardClick(e: Event, item: CarouselItem, cardDomIndex: number) {
+		// Suppress click if the gesture traveled more than 8px — it was a swipe, not a tap.
+		if (this._totalDraggedDistance > 8) {
 			e.preventDefault();
 			e.stopPropagation();
 			return;
 		}
 
-		const originalIndex = index % this.effectiveItems.length;
-		this.dispatchEvent(
-			new CustomEvent('item-click', {
-				detail: { item, index: originalIndex },
-				bubbles: true,
-				composed: true
-			})
-		);
+		// In infinite mode, the DOM index may be a multiple of the original list length.
+		// Modulo maps it back to the logical item index.
+		const logicalItemIndex = cardDomIndex % this.effectiveItems.length;
+		this.dispatchEvent(new CustomEvent('item-click', {
+			bubbles: true,
+			composed: true,
+			detail: { item, index: logicalItemIndex }
+		}));
+		emitMoniEvent<CarouselItem>(this, 'moni-item-click', {
+			detail: { item, index: logicalItemIndex }
+		});
 	}
 
+	/**
+	 * Acción Imperativa: Scroll hacia el elemento anterior.
+	 * Desplaza el contenedor una distancia equivalente al tamaño exacto de un ítem `L` (Large) + gap.
+	 * Restaura el comportamiento `smooth` de CSS nativo.
+	 */
 	private _scrollPrevious() {
 		const target = this._scrollContainer.scrollLeft - this.itemSize;
 		this._scrollContainer.style.scrollBehavior = 'smooth';
 		this._scrollContainer.scrollTo({ left: target, behavior: 'smooth' });
 	}
 
+	/**
+	 * Acción Imperativa: Scroll hacia el elemento siguiente.
+	 * Desplaza el contenedor una distancia equivalente al tamaño exacto de un ítem `L` (Large) + gap.
+	 */
 	private _scrollNext() {
 		const target = this._scrollContainer.scrollLeft + this.itemSize;
 		this._scrollContainer.style.scrollBehavior = 'smooth';
 		this._scrollContainer.scrollTo({ left: target, behavior: 'smooth' });
 	}
 
+	/**
+	 * Manejador del botón o enlace "Mostrar Todo" (Show All).
+	 * Intercepta clics en enlaces nulos (`#`) y despacha el evento CustomEvent `show-all-click`.
+	 */
 	private _handleShowAllClick(e: Event) {
 		const target = e.target as HTMLElement;
 		if (target.tagName.toLowerCase() === 'a' && target.getAttribute('href') === '#') {
 			e.preventDefault();
 		}
-		this.dispatchEvent(
-			new CustomEvent('show-all-click', {
-				bubbles: true,
-				composed: true
-			})
-		);
+		this.dispatchEvent(new CustomEvent('show-all-click', { bubbles: true, composed: true }));
+		emitMoniEvent(this, 'moni-show-all-click');
 	}
 
+	/**
+	 * Hook invocado por Lit cuando el contenido del slot `"show-all"` muta en el Light DOM.
+	 * Detecta si hay contenido proyectado para ocultar/mostrar la interfaz correspondiente,
+	 * proveyendo un fallback manual para entornos DOM limitados (como JSDOM en test unitarios).
+	 */
 	private _handleShowAllSlotChange(e: Event) {
 		const slot = e.target as HTMLSlotElement;
 		let nodes = typeof slot.assignedElements === 'function' ? slot.assignedElements({ flatten: true }) : [];
@@ -1076,6 +1680,15 @@ export class MoniCarousel extends MoniElement {
 		this._hasSlottedShowAll = nodes.length > 0;
 	}
 
+	/**
+	 * Hook invocado por Lit cuando los hijos directos proyectados en el `<slot>` por defecto cambian.
+	 * 
+	 * @logic
+	 * Parsea el Light DOM proporcionado por el usuario (ej: lista de `<img>` o `<a><img></a>`).
+	 * Extrae los atributos `src`, `title`, y `href` de esos nodos nativos y los convierte en 
+	 * un array estructurado interno de objetos `CarouselItem`, que el componente usará 
+	 * subsecuentemente para renderizar su propio DOM Shadow infinito.
+	 */
 	private _handleSlotChange(e: Event) {
 		const slot = e.target as HTMLSlotElement;
 		let nodes = typeof slot.assignedElements === 'function' ? slot.assignedElements({ flatten: true }) : [];
@@ -1117,46 +1730,95 @@ export class MoniCarousel extends MoniElement {
 
 		void this.updateComplete.then(() => {
 			this.updateLayout(true);
+			emitMoniEvent(this, 'moni-slot-items-changed', { detail: { items: this._slottedItems } });
 		});
 	}
 
-	override render() {
-		const { L, M, S } = this.computedLayout;
+	/**
+	 * Ensambla la estructura del Shadow DOM del carrusel para cada ciclo de renderizado de Lit.
+	 *
+	 * **Extracción de `computedLayout`:**
+	 * `largeItemWidth`, `mediumItemWidth` y `smallItemWidth` se desestructuran
+	 * del getter `computedLayout` (que devuelve tamaños según la especificación M3 basados en
+	 * el ancho del contenedor a través de `_containerWidth`). Se inyectan como propiedades personalizadas
+	 * CSS en la pista para que el CSS de tamaño de ranura pueda referenciarlos.
+	 *
+	 * **Puerta `showHeader`:**
+	 * El elemento `.header` solo se renderiza cuando hay algo que mostrar:
+	 * un `headerText`, un atributo `showAll`, o un elemento `[slot="show-all"]`.
+	 * Esto evita un espaciador de encabezado vacío cuando el carrusel no tiene fila de título.
+	 *
+	 * **Cálculo de `rightPadding`:**
+	 * Asegura que la última tarjeta pueda desplazarse a ras de la posición focal del elemento grande:
+	 * - Diseño `hero`: sin relleno adicional (el elemento derecho que asoma proporciona espacio natural).
+	 * - Diseños de ancho completo / lista: también relleno mínimo.
+	 * - Todos los demás diseños: `128px` (≈ ancho de la tarjeta pequeña) para que la última tarjeta pueda
+	 *   alcanzar la ranura de enfoque principal sin que el usuario se desplace demasiado.
+	 *
+	 * **Ciclo de vida del ticker de GSAP:**
+	 * El ticker de GSAP (`gsap.ticker.add(_tick)`) se inicia en `firstUpdated()`
+	 * y se detiene en `disconnectedCallback()`. Este método de renderizado NO
+	 * interactúa con el ticker; el ticker impulsa las actualizaciones de posición por cuadro
+	 * independientemente del ciclo de actualización reactiva de Lit.
+	 */
+override render() {
+		const { largeItemWidth, mediumItemWidth, smallItemWidth } = this.computedLayout;
+
+		// Determine whether there are items to render (from either source).
 		const hasItems = this.effectiveItems && this.effectiveItems.length > 0;
+
+		// Check for a slotted "Show All" button or the declarative `show-all` attribute.
 		const hasSlottedShowAll = this._hasSlottedShowAll || !!this.querySelector('[slot="show-all"]');
+		// Only render the header section if there is something to display in it.
 		const showHeader = this.headerText || this.showAll || hasSlottedShowAll;
 
+		// `rightPadding` determines the trailing space in the scroll track so the
+		// last item can scroll all the way to the primary (leftmost large) focus slot.
 		let rightPadding = 128;
 		if (this.layout === 'hero') {
-			rightPadding = S + this.gap;
+			// Hero: the peeking item on the right already provides natural trailing space.
+			rightPadding = smallItemWidth + this.gap;
 		} else if (this.layout === 'uncontained') {
+			// Uncontained: minimal trailing padding; items bleed off the edge.
 			rightPadding = 16;
 		} else {
-			rightPadding = M + S + 2 * this.gap;
+			// Multi-browse: both the medium and small slots provide the trailing buffer.
+			rightPadding = mediumItemWidth + smallItemWidth + 2 * this.gap;
 		}
 
 		// Ensure the scroll track is long enough to allow the last item to scroll to the start (p = 0 focus).
 		// Safety margin of 400px avoids fractional rounding/zoom-scale snapping blockages in Firefox.
-		const W_c = this._containerWidth || this.getBoundingClientRect().width || 360;
-		const minRightPaddingNeeded = W_c - L - this.padding + 400;
-		if (rightPadding < minRightPaddingNeeded) {
-			rightPadding = minRightPaddingNeeded;
+		// Measure the container width for the scroll track overflow calculation.
+		const containerWidth = this._containerWidth || this.getBoundingClientRect().width || 360;
+
+		// Minimum trailing padding needed so the last item can scroll to position 0 (primary focus).
+		// The +400px safety margin prevents fractional zoom-scale snapping blockages in Firefox.
+		const minRequiredRightPadding = containerWidth - largeItemWidth - this.padding + 400;
+		if (rightPadding < minRequiredRightPadding) {
+			rightPadding = minRequiredRightPadding;
 		}
 
+		// Total number of snap items in the track (includes cloned sets for infinite mode).
 		let snapItemsCount = hasItems ? this._snapItemsCount : 0;
+
+		// `visualItems` is the array of items actually rendered as card elements in the Shadow DOM.
+		// For infinite mode, this is a repeated version of `effectiveItems` scaled by `_visualCardsMultiplier`.
 		let visualItems = this.effectiveItems;
-		
+
 		if (this.infinite && hasItems) {
-			const V_mult = this._visualCardsMultiplier;
-			
+			const visualMultiplier = this._visualCardsMultiplier;
+
 			visualItems = [];
-			for (let i = 0; i < V_mult; i++) {
+			// Concatenate the original item list `visualMultiplier` times to create
+			// enough cards to fill the visual viewport without visible gaps.
+			for (let repeatIndex = 0; repeatIndex < visualMultiplier; repeatIndex++) {
 				visualItems = visualItems.concat(this.effectiveItems);
 			}
 		}
 
+		// Total pixel width of the snap track (sum of all item widths + all gaps between them).
 		const trackWidth = hasItems
-			? snapItemsCount * L + (snapItemsCount - 1) * this.gap
+			? snapItemsCount * largeItemWidth + (snapItemsCount - 1) * this.gap
 			: 0;
 
 		const isScrollable = hasItems && this._scrollContainer && 
@@ -1167,7 +1829,7 @@ export class MoniCarousel extends MoniElement {
 
 		return html`
 			<div class="carousel-container" style="
-				--carousel-snap-width: ${L}px;
+				--carousel-snap-width: ${largeItemWidth}px;
 				--carousel-gap: ${this.gap}px;
 				--carousel-padding: ${this.padding}px;
 				--carousel-right-padding: ${rightPadding}px;
@@ -1227,6 +1889,7 @@ export class MoniCarousel extends MoniElement {
 										(item, idx) => html`
 											<div 
 												class="card" 
+												data-index="${idx}"
 												@click=${(e: Event) => this._handleCardClick(e, item, idx)}
 											>
 												${item.href