@yewdiel21/motion-kit 0.16.0 → 0.17.0

package/src/components/voice-message-bubble/engine.ts

@@ -0,0 +1,68 @@
+import { createScope } from '../../core/scope';
+import type { WaveformPlayerInstance, WaveformPlayerOptions } from '../waveform-player/engine';
+import { createWaveformPlayer } from '../waveform-player/engine';
+
+export type VoiceMessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+export interface VoiceMessageBubbleOptions extends WaveformPlayerOptions {
+  direction?: 'incoming' | 'outgoing';
+  author?: string;
+  timestamp?: string;
+  /** Optional machine-readable timestamp for the time element. */
+  dateTime?: string;
+  status?: VoiceMessageStatus;
+}
+export interface VoiceMessageBubbleInstance extends WaveformPlayerInstance {
+  update(options: Partial<VoiceMessageBubbleOptions>): void;
+}
+
+const statusLabels: Record<VoiceMessageStatus, string> = { sending: 'Enviando', sent: 'Enviado', delivered: 'Entregado', read: 'Leído', failed: 'No enviado' };
+
+/** A message presentation around the real waveform audio player. Never records audio. */
+export function createVoiceMessageBubble(root: HTMLElement | null, options: VoiceMessageBubbleOptions = {}): VoiceMessageBubbleInstance {
+  if (!root) return createWaveformPlayer(null, options);
+  const scope = createScope();
+  let opts = { ...options };
+  const content = document.createElement('div');
+  content.setAttribute('data-mk-voice-message-content', '');
+  const header = document.createElement('div');
+  header.setAttribute('data-mk-voice-message-header', '');
+  const author = document.createElement('span');
+  author.setAttribute('data-mk-voice-message-author', '');
+  const caption = document.createElement('span');
+  caption.setAttribute('data-mk-voice-message-caption', '');
+  caption.textContent = 'Mensaje de voz';
+  header.append(author, caption);
+  const playerRoot = document.createElement('div');
+  playerRoot.className = 'mk-waveform-player';
+  const footer = document.createElement('div');
+  footer.setAttribute('data-mk-voice-message-footer', '');
+  const timestamp = document.createElement('time');
+  const status = document.createElement('span');
+  status.setAttribute('data-mk-voice-message-status', '');
+  footer.append(timestamp, status);
+  content.append(header, playerRoot, footer);
+  root.append(content);
+  scope.add(() => content.remove());
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-direction', 'incoming');
+  const player = createWaveformPlayer(playerRoot);
+  scope.add(() => player.destroy());
+  const update = (next: Partial<VoiceMessageBubbleOptions>) => {
+    if (scope.disposed) return;
+    opts = { ...opts, ...next };
+    author.textContent = opts.author ?? '';
+    author.hidden = !opts.author;
+    timestamp.textContent = opts.timestamp ?? '';
+    timestamp.hidden = !opts.timestamp;
+    if (opts.dateTime) timestamp.dateTime = opts.dateTime;
+    else timestamp.removeAttribute('datetime');
+    status.textContent = opts.status && statusLabels[opts.status] || '';
+    status.hidden = !status.textContent;
+    root.setAttribute('data-mk-direction', opts.direction === 'outgoing' ? 'outgoing' : 'incoming');
+    const { direction: _direction, author: _author, timestamp: _timestamp, dateTime: _dateTime, status: _status, ...audio } = opts;
+    player.update({ ...audio, label: opts.label ?? (opts.author ? `mensaje de voz de ${opts.author}` : 'mensaje de voz') });
+  };
+  update(options);
+  return { play: () => player.play(), pause: () => player.pause(), seek: n => player.seek(n), update,
+    get state() { return player.state; }, get audio() { return player.audio; }, destroy: () => scope.dispose() };
+}

package/src/components/voice-message-bubble/react.tsx

@@ -0,0 +1,27 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createVoiceMessageBubble, type VoiceMessageBubbleInstance, type VoiceMessageBubbleOptions } from './engine';
+
+export interface VoiceMessageBubbleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPlay' | 'onPause' | 'onEnded' | 'onError' | 'onTimeUpdate' | 'children' | 'dangerouslySetInnerHTML'>, VoiceMessageBubbleOptions {
+  instanceRef?: MutableRefObject<VoiceMessageBubbleInstance | null>;
+}
+export function VoiceMessageBubble({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError, direction, author, timestamp, dateTime, status, instanceRef, className, ...props }: VoiceMessageBubbleProps) {
+  // React must never reconcile descendants owned by the composed player engine.
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<VoiceMessageBubbleInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createVoiceMessageBubble(root.current);
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.update({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError, direction, author, timestamp, dateTime, status });
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef]);
+  return <div {...rootProps} ref={root} className={['mk-voice-message-bubble', className].filter(Boolean).join(' ')} />;
+}

package/src/components/voice-message-bubble/voice-message-bubble.css

@@ -0,0 +1,12 @@
+/* Requires waveform-player.css; the bubble composes its player without duplicating it. */
+.mk-voice-message-bubble, mk-voice-message-bubble { display: block; width: min(100%, 25rem); color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-voice-message-content] { display: grid; gap: .75rem; padding: 1rem 1.125rem .75rem; background: var(--mk-surface-2); border: 1px solid var(--mk-outline-soft); border-radius: 1.5rem 1.5rem 1.5rem .375rem; }
+:is(.mk-voice-message-bubble, mk-voice-message-bubble)[data-mk-direction='outgoing'] { margin-inline-start: auto; }
+:is(.mk-voice-message-bubble, mk-voice-message-bubble)[data-mk-direction='outgoing'] [data-mk-voice-message-content] { background: color-mix(in srgb, var(--mk-accent) 10%, var(--mk-surface-1)); border-radius: 1.5rem 1.5rem .375rem 1.5rem; }
+[data-mk-voice-message-header], [data-mk-voice-message-footer] { display: flex; flex-wrap: wrap; align-items: center; gap: .375rem .75rem; font-size: .6875rem; color: var(--mk-muted); }
+[data-mk-voice-message-author] { font-weight: 600; color: var(--mk-text); }
+[data-mk-voice-message-caption] { margin-inline-start: auto; }
+[data-mk-voice-message-footer] { justify-content: flex-end; }
+[data-mk-voice-message-status] { color: var(--mk-accent); }
+[data-mk-voice-message-content] .mk-waveform-player { --mk-wave-track: color-mix(in srgb, var(--mk-text) 38%, transparent); }
+@media (forced-colors: active) { [data-mk-voice-message-content] { border-color: CanvasText; } }

package/src/components/waveform-player/README.md

@@ -0,0 +1,30 @@
+# Waveform Player
+
+Reproductor real de `HTMLAudioElement` con onda de barras redondeadas, botón reproducir/pausar, posición nativa accesible, tiempo actual/duración y velocidad opcional. No inicia solo ni solicita el micrófono.
+
+```tsx
+import { WaveformPlayer } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css/components/waveform-player';
+
+<WaveformPlayer src="/audio/mensaje.wav" peaks={[.2, .5, .9, .4]} label="mensaje de Ana" />
+```
+
+```html
+<mk-waveform-player src="/audio/mensaje.wav" peaks="[0.2,0.5,0.9,0.4]" label="mensaje de Ana"></mk-waveform-player>
+<script type="module">
+  import { defineWaveformPlayer } from '@yewdiel21/motion-kit/elements';
+  defineWaveformPlayer();
+</script>
+```
+
+Los picos son amplitudes normalizadas **suministradas por la aplicación**, por ejemplo desde el servidor o un proceso previo. El componente no descarga ni analiza el archivo para calcularlos. Acota amplitudes a 0…1 y muestra las primeras 256 barras; sin picos muestra barras neutras iguales. El progreso y la duración sí proceden del audio real. Usa un archivo o una URL compatible con el navegador.
+
+`createWaveformPlayer(root, options)` devuelve `play(): Promise<boolean>`, `pause()`, `seek(seconds)`, `update(partialOptions)`, `state`, `audio` y `destroy()`. `play` resuelve `false` cuando falla, se cancela o falta una fuente; los rechazos del navegador se capturan y se muestran en el estado. `seek` se acota a la duración; antes de metadatos o con duración infinita no hace nada. `audio` es el elemento real y pasa a `null` tras destruir. `state` es una copia: `{ status, currentTime, duration, playbackRate, error }`. El estado puede ser `idle`, `loading`, `ready`, `playing`, `paused`, `ended` o `error`; el siguiente play tras finalizar vuelve al inicio.
+
+Opciones: `src`, `peaks`, `label` (nombre accesible), `disabled`, `playbackRates` (por defecto `[1, 1.5, 2]`, `false` oculta el control; tasas válidas 0.25…4), `onStateChange`, `onTimeUpdate`, `onPlay`, `onPause`, `onEnded`, `onError`. Los callbacks reciben una copia del estado. `onStateChange` informa transiciones de estado; `onTimeUpdate` informa reproducción/búsqueda. Eventos DOM burbujeantes: `mk:audio-statechange`, `mk:audio-play`, `mk:audio-pause`, `mk:audio-ended`, `mk:audio-error`, `mk:audio-timeupdate`, con el estado en `detail`.
+
+React admite `instanceRef` y actualiza las opciones/callbacks sin recrear el audio. El custom element expone los mismos métodos, `state`, `audio` y `instance`; los atributos son reactivos (`playback-rates` y `peaks` son JSON). Cambiar solamente picos, etiquetas o callbacks conserva fuente, tiempo y reproducción. Cambiar `src` pausa, cancela solicitudes y reinicia tiempo/duración. `destroy()` detiene el audio, vacía la fuente, retira listeners/animaciones y conserva el DOM ajeno.
+
+El slider nativo conserva teclado (flechas, Home/End), toque y semántica accesible; su nombre incluye `label` y su valor se anuncia como tiempo. Carga, errores y finalización usan un estado discreto; los tiempos no se anuncian continuamente. El pequeño resorte GSAP del botón se omite con movimiento reducido. Tokens locales: `--mk-wave-color`, `--mk-wave-track`; el resto usa los colores, tipografía y superficies del tema.
+
+Tipos: `WaveformPlayerOptions`, `WaveformPlayerInstance`, `WaveformPlayerState`, `WaveformPlayerStatus`, `WaveformPlayerProps`. El componente reproduce contenido provisto por la aplicación: agrega una transcripción cerca del reproductor cuando el audio contenga información hablada.

package/src/components/waveform-player/element.ts

@@ -0,0 +1,21 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createWaveformPlayer, type WaveformPlayerInstance, type WaveformPlayerOptions } from './engine';
+
+export class MkWaveformPlayerElement extends MkElement<WaveformPlayerInstance> {
+  static options: Record<string, OptionType> = { src: 'string', peaks: 'json', label: 'string', disabled: 'boolean', playbackRates: 'json' };
+  protected create(options: Record<string, unknown>) { return createWaveformPlayer(this, options as WaveformPlayerOptions); }
+  play() { return this.instance?.play() ?? Promise.resolve(false); }
+  pause() { this.instance?.pause(); }
+  seek(seconds: number) { this.instance?.seek(seconds); }
+  update(options: Partial<WaveformPlayerOptions>) { this.instance?.update(options); }
+  get state() { return this.instance?.state; }
+  get audio() { return this.instance?.audio ?? null; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    if (!Object.hasOwn(MkWaveformPlayerElement.options, option)) return;
+    // Undefined resets only the removed option; imperative values for other options survive.
+    this.instance.update({ [option]: this.options[option] });
+  }
+}
+export const defineWaveformPlayer = () => defineElement('mk-waveform-player', MkWaveformPlayerElement);

package/src/components/waveform-player/engine.ts

@@ -0,0 +1,261 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export type WaveformPlayerStatus = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'ended' | 'error';
+export interface WaveformPlayerState {
+  status: WaveformPlayerStatus;
+  currentTime: number;
+  /** 0 until finite metadata is available. Live streams cannot be sought. */
+  duration: number;
+  playbackRate: number;
+  error: string | null;
+}
+export interface WaveformPlayerOptions {
+  src?: string;
+  /** Normalized amplitudes (0…1), supplied by your application, not audio analysis. */
+  peaks?: readonly number[];
+  label?: string;
+  disabled?: boolean;
+  /** Defaults to [1, 1.5, 2]. false hides the rate button. */
+  playbackRates?: readonly number[] | false;
+  /** Status transitions (time changes have their own callback). */
+  onStateChange?: (state: WaveformPlayerState) => void;
+  onTimeUpdate?: (state: WaveformPlayerState) => void;
+  onPlay?: (state: WaveformPlayerState) => void;
+  onPause?: (state: WaveformPlayerState) => void;
+  onEnded?: (state: WaveformPlayerState) => void;
+  onError?: (state: WaveformPlayerState) => void;
+}
+export interface WaveformPlayerInstance extends Instance {
+  /** Resolves false when unavailable, cancelled, or rejected. Never rejects for media errors. */
+  play(): Promise<boolean>;
+  pause(): void;
+  /** Seconds, clamped to the finite duration; ignored until metadata is available. */
+  seek(seconds: number): void;
+  /** Updates presentation/callbacks in place. A different src pauses and resets playback. */
+  update(options: Partial<WaveformPlayerOptions>): void;
+  readonly state: WaveformPlayerState;
+  readonly audio: HTMLAudioElement | null;
+}
+
+const initialState = (): WaveformPlayerState => ({ status: 'idle', currentTime: 0, duration: 0, playbackRate: 1, error: null });
+const finite = (n: number) => Number.isFinite(n) && n >= 0;
+const clock = (n: number) => `${Math.floor(n / 60)}:${String(Math.floor(n % 60)).padStart(2, '0')}`;
+const playIcon = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m9 6 9 6-9 6Z"/></svg>';
+const pauseIcon = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 6v12M16 6v12"/></svg>';
+
+export function createWaveformPlayer(root: HTMLElement | null, options: WaveformPlayerOptions = {}): WaveformPlayerInstance {
+  if (!root) return inert({ play: async () => false, pause() {}, seek() {}, update() {}, state: initialState(), audio: null });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let state = initialState();
+  let source = '';
+  let request = 0;
+  let requested = false;
+  let pending: Promise<boolean> | null = null;
+  const make = <K extends keyof HTMLElementTagNameMap>(tag: K, part: string, parent: HTMLElement = root) => {
+    const el = document.createElement(tag);
+    el.setAttribute(`data-mk-wave-${part}`, '');
+    parent.append(el);
+    return el;
+  };
+  // A single owned container preserves authored siblings and makes destroy reversible.
+  const container = make('div', 'content');
+  scope.add(() => container.remove());
+  const audio = make('audio', 'audio', container);
+  audio.preload = 'metadata';
+  audio.hidden = true;
+  const toggle = make('button', 'toggle', container);
+  toggle.type = 'button';
+  const body = make('div', 'body', container);
+  const track = make('div', 'track', body);
+  const bars = make('div', 'bars', track);
+  bars.setAttribute('aria-hidden', 'true');
+  const range = make('input', 'seek', track);
+  range.type = 'range';
+  range.min = '0';
+  range.max = '0';
+  range.step = '0.1';
+  const footer = make('div', 'footer', body);
+  const time = make('span', 'time', footer);
+  const rate = make('button', 'rate', footer);
+  rate.type = 'button';
+  const message = make('span', 'message', container);
+  message.setAttribute('role', 'status');
+  message.setAttribute('aria-live', 'polite');
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-wave-state', 'idle');
+  let barNodes: HTMLElement[] = [];
+  let effect: gsap.core.Tween | undefined;
+  const snapshot = () => ({ ...state });
+  const rates = () => {
+    const values = opts.playbackRates === false ? [] : (opts.playbackRates ?? [1, 1.5, 2]);
+    return Array.isArray(values) ? [...new Set(values.filter(n => typeof n === 'number' && Number.isFinite(n) && n >= 0.25 && n <= 4))] : [];
+  };
+  const paint = () => {
+    const playing = state.status === 'playing';
+    toggle.innerHTML = playing || requested ? pauseIcon : playIcon;
+    toggle.setAttribute('aria-label', `${playing || requested ? 'Pausar' : 'Reproducir'} ${opts.label ?? 'audio'}`);
+    toggle.disabled = !!opts.disabled || !source;
+    range.disabled = !!opts.disabled || !state.duration;
+    range.max = String(state.duration);
+    range.value = String(state.currentTime);
+    range.setAttribute('aria-label', `Posición de ${opts.label ?? 'audio'}`);
+    range.setAttribute('aria-valuetext', `${clock(state.currentTime)} de ${clock(state.duration)}`);
+    time.textContent = `${clock(state.currentTime)} / ${clock(state.duration)}`;
+    rate.hidden = rates().length < 2;
+    rate.disabled = !!opts.disabled;
+    rate.textContent = `${state.playbackRate}×`;
+    rate.setAttribute('aria-label', `Velocidad ${state.playbackRate}×. Cambiar velocidad`);
+    const progress = state.duration ? state.currentTime / state.duration : 0;
+    barNodes.forEach((bar, i) => bar.toggleAttribute('data-mk-played', (i + 0.5) / barNodes.length <= progress));
+    root.setAttribute('data-mk-wave-state', state.status);
+    message.textContent = state.error ?? (state.status === 'loading' ? 'Cargando audio…' : state.status === 'ended' ? 'Audio finalizado' : '');
+  };
+  const emit = (patch: Partial<WaveformPlayerState>, event?: 'play' | 'pause' | 'ended' | 'error' | 'timeupdate') => {
+    if (scope.disposed) return;
+    const previous = state.status;
+    state = { ...state, ...patch };
+    paint();
+    const next = snapshot();
+    if (event === 'timeupdate') opts.onTimeUpdate?.(next);
+    if (previous !== state.status) opts.onStateChange?.(snapshot());
+    if (event === 'play') opts.onPlay?.(snapshot());
+    if (event === 'pause') opts.onPause?.(snapshot());
+    if (event === 'ended') opts.onEnded?.(snapshot());
+    if (event === 'error') opts.onError?.(snapshot());
+    if (previous !== state.status) root.dispatchEvent(new CustomEvent('mk:audio-statechange', { bubbles: true, detail: snapshot() }));
+    if (event) root.dispatchEvent(new CustomEvent(`mk:audio-${event}`, { bubbles: true, detail: snapshot() }));
+  };
+  const bounce = (target: HTMLElement) => {
+    if (reduced()) return;
+    effect?.progress(1);
+    effect?.kill();
+    effect = gsap.fromTo(target, { scale: 0.88 }, { scale: 1, duration: 0.4, ease: EASE.swatch, clearProps: 'transform' });
+  };
+  const fail = (message: string) => { requested = false; emit({ status: 'error', error: message }, 'error'); };
+  const pause = () => {
+    if (scope.disposed) return;
+    request++;
+    requested = false;
+    pending = null;
+    audio.pause();
+    if (state.status !== 'idle' && state.status !== 'error' && state.status !== 'ended' && state.status !== 'paused') emit({ status: 'paused' }, 'pause');
+    else paint();
+  };
+  const seek = (seconds: number) => {
+    if (scope.disposed || !state.duration || !Number.isFinite(seconds)) return;
+    const next = Math.max(0, Math.min(state.duration, seconds));
+    try { audio.currentTime = next; }
+    catch { return; }
+    emit({ currentTime: next, ...(state.status === 'ended' && next < state.duration ? { status: 'paused' as const } : {}) }, 'timeupdate');
+  };
+  const play = (): Promise<boolean> => {
+    if (scope.disposed || opts.disabled || !source) return Promise.resolve(false);
+    if (pending) return pending;
+    if (state.status === 'playing') return Promise.resolve(true);
+    if (state.status === 'ended') seek(0);
+    const token = ++request;
+    requested = true;
+    emit({ status: 'loading', error: null });
+    // Promise.resolve also supports older media implementations that return void.
+    let started: Promise<void>;
+    try { started = Promise.resolve(audio.play()); }
+    catch (error) { started = Promise.reject(error); }
+    const result = started.then(() => {
+      if (scope.disposed || token !== request) return false;
+      requested = false;
+      if (audio.paused) { emit({ status: 'paused' }); return false; }
+      if (state.status !== 'playing') emit({ status: 'playing', error: null }, 'play');
+      return true;
+    }).catch((error: unknown) => {
+      if (!scope.disposed && token === request) {
+        requested = false;
+        if (error instanceof Error && error.name === 'AbortError') emit({ status: 'paused' });
+        else fail('No se pudo reproducir el audio. Vuelve a intentarlo.');
+      }
+      return false;
+    }).finally(() => { if (token === request) pending = null; });
+    pending = result;
+    return result;
+  };
+  const renderPeaks = () => {
+    const supplied = Array.isArray(opts.peaks) ? opts.peaks : [];
+    // Empty data is an explicit neutral placeholder, never fabricated audio analysis.
+    const values = supplied.length ? supplied : Array<number>(48).fill(0.24);
+    bars.replaceChildren();
+    barNodes = values.slice(0, 256).map(value => {
+      const bar = make('i', 'bar', bars);
+      const peak = typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+      bar.style.height = `${8 + peak * 92}%`;
+      return bar;
+    });
+  };
+  const update = (next: Partial<WaveformPlayerOptions>) => {
+    if (scope.disposed) return;
+    const previousPeaks = opts.peaks;
+    opts = { ...opts, ...next };
+    const nextSource = typeof opts.src === 'string' ? opts.src : '';
+    if (source !== nextSource) {
+      request++;
+      pending = null;
+      requested = false;
+      audio.pause();
+      source = nextSource;
+      if (source) audio.setAttribute('src', source);
+      else audio.removeAttribute('src');
+      // load() aborts the previous resource and any in-flight play request.
+      audio.load();
+      audio.playbackRate = state.playbackRate;
+      emit({ ...initialState(), playbackRate: state.playbackRate, status: source ? 'loading' : 'idle' });
+    }
+    if (opts.disabled && (requested || state.status === 'playing')) pause();
+    if (previousPeaks !== opts.peaks || !barNodes.length) renderPeaks();
+    paint();
+  };
+  scope.on(toggle, 'click', () => { bounce(toggle); if (requested || state.status === 'playing') pause(); else void play(); });
+  scope.on(range, 'input', () => seek(Number(range.value)));
+  scope.on(rate, 'click', () => {
+    const available = rates();
+    const index = available.indexOf(state.playbackRate);
+    const next = available[(index + 1) % available.length];
+    if (next === undefined) return;
+    audio.playbackRate = next;
+    emit({ playbackRate: next });
+    bounce(rate);
+  });
+  const metadata = () => {
+    const duration = finite(audio.duration) ? audio.duration : 0;
+    emit({ duration, currentTime: duration ? Math.min(duration, Math.max(0, audio.currentTime || 0)) : 0,
+      ...(state.status === 'loading' && !requested ? { status: 'ready' as const } : {}) });
+  };
+  scope.on(audio, 'loadedmetadata', metadata);
+  scope.on(audio, 'durationchange', metadata);
+  scope.on(audio, 'timeupdate', () => emit({ currentTime: finite(audio.currentTime) ? audio.currentTime : 0 }, 'timeupdate'));
+  scope.on(audio, 'playing', () => {
+    if (!source || opts.disabled || !requested && state.status !== 'playing') { audio.pause(); return; }
+    requested = false;
+    if (state.status !== 'playing') emit({ status: 'playing', error: null }, 'play');
+  });
+  scope.on(audio, 'pause', () => {
+    if (state.status === 'playing' || requested) { requested = false; emit({ status: 'paused' }, 'pause'); }
+  });
+  scope.on(audio, 'waiting', () => { if (state.status === 'playing') { requested = true; emit({ status: 'loading' }); } });
+  scope.on(audio, 'ended', () => { request++; pending = null; requested = false; emit({ status: 'ended', currentTime: state.duration || state.currentTime }, 'ended'); });
+  scope.on(audio, 'error', () => { request++; pending = null; fail('No se pudo cargar el audio. Comprueba el archivo.'); });
+  scope.on(audio, 'ratechange', () => { if (audio.playbackRate !== state.playbackRate) emit({ playbackRate: audio.playbackRate }); });
+  scope.add(() => {
+    request++;
+    requested = false;
+    pending = null;
+    effect?.kill();
+    audio.pause();
+    audio.removeAttribute('src');
+    audio.load();
+  });
+  update(options);
+  return { play, pause, seek, update, get state() { return snapshot(); }, get audio() { return scope.disposed ? null : audio; }, destroy: () => scope.dispose() };
+}

package/src/components/waveform-player/react.tsx

@@ -0,0 +1,27 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createWaveformPlayer, type WaveformPlayerInstance, type WaveformPlayerOptions } from './engine';
+
+export interface WaveformPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPlay' | 'onPause' | 'onEnded' | 'onError' | 'onTimeUpdate' | 'children' | 'dangerouslySetInnerHTML'>, WaveformPlayerOptions {
+  instanceRef?: MutableRefObject<WaveformPlayerInstance | null>;
+}
+export function WaveformPlayer({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError, instanceRef, className, ...props }: WaveformPlayerProps) {
+  // The engine owns descendants. Also filter runtime JS props that bypass the public type.
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<WaveformPlayerInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createWaveformPlayer(root.current);
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.update({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError });
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef]);
+  return <div {...rootProps} ref={root} className={['mk-waveform-player', className].filter(Boolean).join(' ')} />;
+}

package/src/components/waveform-player/waveform-player.css

@@ -0,0 +1,35 @@
+.mk-waveform-player, mk-waveform-player {
+  --mk-wave-color: var(--mk-accent);
+  --mk-wave-track: color-mix(in srgb, var(--mk-text) 38%, transparent);
+  display: block;
+  width: 100%;
+  min-width: 0;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+[data-mk-wave-content] { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: center; column-gap: .875rem; }
+[data-mk-wave-toggle] { display: grid; place-items: center; width: 3rem; height: 3rem; border: 0; border-radius: 50%; background: var(--mk-wave-color); color: var(--mk-on-accent, var(--mk-bg)); cursor: pointer; }
+[data-mk-wave-toggle] svg { width: 1.4rem; height: 1.4rem; fill: currentColor; stroke: currentColor; stroke-width: 2; stroke-linecap: round; }
+[data-mk-wave-body] { min-width: 0; }
+[data-mk-wave-track] { position: relative; height: 3rem; border-radius: .5rem; }
+[data-mk-wave-bars] { display: flex; align-items: center; gap: 3px; height: 100%; pointer-events: none; overflow: hidden; }
+[data-mk-wave-bar] { display: block; flex: 1 1 0; min-width: 1px; border-radius: 999px; background: var(--mk-wave-track); transition: background-color .16s ease; }
+[data-mk-wave-bar][data-mk-played] { background: var(--mk-wave-color); }
+[data-mk-wave-seek] { position: absolute; inset: 0; width: 100%; height: 100%; margin: 0; opacity: 0; cursor: pointer; }
+[data-mk-wave-track]:has(input:focus-visible) { outline: 2px solid var(--mk-wave-color); outline-offset: 4px; }
+[data-mk-wave-footer] { display: flex; justify-content: space-between; align-items: center; gap: .75rem; min-height: 2rem; }
+[data-mk-wave-time] { color: var(--mk-muted); font-size: .75rem; font-variant-numeric: tabular-nums; }
+[data-mk-wave-rate] { min-width: 44px; min-height: 44px; padding: .25rem .5rem; border: 0; border-radius: 99px; color: var(--mk-text); background: var(--mk-surface-2); font: 600 .75rem var(--mk-font); cursor: pointer; }
+[data-mk-wave-rate][hidden] { display: none; }
+[data-mk-wave-message] { grid-column: 2; color: var(--mk-muted); font-size: .75rem; line-height: 1.5; }
+[data-mk-wave-message]:empty { display: none; }
+[data-mk-wave-toggle]:focus-visible, [data-mk-wave-rate]:focus-visible { outline: 2px solid var(--mk-wave-color); outline-offset: 3px; }
+[data-mk-wave-toggle]:disabled, [data-mk-wave-rate]:disabled { opacity: .5; cursor: default; }
+[data-mk-wave-track]:has(input:disabled) { opacity: .55; }
+[data-mk-wave-state='error'] [data-mk-wave-message] { color: var(--mk-error, var(--mk-text)); }
+@media (prefers-reduced-motion: reduce) { [data-mk-wave-bar] { transition: none; } }
+@media (forced-colors: active) {
+  [data-mk-wave-toggle], [data-mk-wave-rate] { border: 1px solid ButtonText; }
+  [data-mk-wave-bar] { background: GrayText; }
+  [data-mk-wave-bar][data-mk-played] { background: Highlight; }
+}

package/src/components/wheel-picker/README.md

@@ -0,0 +1,33 @@
+# wheel-picker
+
+Selector de rueda con desplazamiento nativo e inercia en táctil, arrastre de ratón, ajuste al centro y navegación por teclado. El valor elegido queda en un input oculto para formularios.
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { WheelPicker } from '@yewdiel21/motion-kit/react';
+
+<WheelPicker label="Duración" name="duration" value={duration} onChange={setDuration}
+  items={[{ value: '15', label: '15 min' }, { value: '25', label: '25 min' }, { value: '45', label: '45 min' }]} />
+```
+
+En React, `defaultValue` inicializa el estado sin controlarlo; `instanceRef` permite llamar al motor. Los cambios de `items` y `value` se aplican sin sustituir el listbox.
+
+```html
+<mk-wheel-picker label="Duración" name="duration" value="25"
+  items='[{"value":"15","label":"15 min"},{"value":"25","label":"25 min"},{"value":"45","label":"45 min"}]'>
+</mk-wheel-picker>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-wheel-picker']);
+</script>
+```
+
+También puedes usar `createWheelPicker(root, options)` en vanilla. El CLI copia las fuentes con `npx @yewdiel21/motion-kit add wheel-picker --react --elements`.
+
+Opciones: `items` (strings o `{value,label,disabled?}`), `value`, `name`, `label`, `disabled`, `visibleItems` (impar de 3 a 9; 5 por defecto), `itemHeight` (44…96 px; 44 por defecto), `onInput(value)` durante el desplazamiento y `onChange(value)` al confirmar. Los valores duplicados se omiten y las etiquetas siempre se tratan como texto.
+
+La instancia expone `setValue(value, notify=false)`, `setItems(items, notify=false)`, `value` y `destroy()`. Eventos: `mk:input` y `mk:change` con `{value,item}`. Las actualizaciones por código son silenciosas por defecto.
+
+Flechas arriba/abajo omiten opciones deshabilitadas; Home/End van a los extremos y PageUp/PageDown saltan varias filas. Escribir busca una etiqueta por prefijo. El listbox tiene un solo foco y `aria-activedescendant`, las opciones exponen selección/estado deshabilitado y los cambios confirmados se anuncian. El reset de formulario recupera el valor inicial o una opción válida si cambió la lista. Sin opciones, el valor enviado es vacío.
+
+El movimiento reducido elimina la inclinación y los desplazamientos programados suaves. Se usan los tokens de superficie, acento, tipografía y forma del kit; `--mk-wheel-row` y `--mk-wheel-rows` reflejan el tamaño configurado. El componente cancela temporizadores y listeners y restaura el contenedor al destruirse.

package/src/components/wheel-picker/element.ts

@@ -0,0 +1,18 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createWheelPicker, type WheelPickerInstance, type WheelPickerEntry } from './engine';
+
+export class MkWheelPickerElement extends MkElement<WheelPickerInstance> {
+  static options: Record<string, OptionType> = { items: 'json', value: 'string', name: 'string', label: 'string', disabled: 'boolean', visibleItems: 'number', itemHeight: 'number' };
+  protected create(options: Record<string, unknown>) { return createWheelPicker(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value' && next !== null) { this.instance.setValue(next); return; }
+    if (name === 'items') { this.instance.setItems((this.options.items as WheelPickerEntry[]) ?? []); if (this.options.value !== undefined) this.instance.setValue(String(this.options.value)); return; }
+    super.attributeChangedCallback(name, previous, next);
+  }
+  get value() { return this.instance?.value ?? ''; }
+  set value(next: string) { this.setAttribute('value', next); }
+  setValue(value: string, notify = false) { this.instance?.setValue(value, notify); }
+  setItems(items: WheelPickerEntry[], notify = false) { this.instance?.setItems(items, notify); }
+}
+export const defineWheelPicker = () => defineElement('mk-wheel-picker', MkWheelPickerElement);