@yewdiel21/motion-kit 0.17.0 → 0.19.0

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

@@ -1,261 +1,344 @@
-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() };
-}
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press, rollDigits } from '../../motion/micro';
+
+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>';
+const level = (n: unknown) => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 0;
+/** Averages (or repeats) the supplied amplitudes into `count` bars; it never invents audio data. */
+const resample = (values: readonly number[], count: number) => count === values.length ? [...values] : Array.from({ length: count }, (_, k) => {
+  const from = Math.floor(k * values.length / count);
+  const slice = values.slice(from, Math.max(from + 1, Math.floor((k + 1) * values.length / count)));
+  return slice.reduce((sum, n) => sum + n, 0) / slice.length;
+});
+
+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 icon = make('span', 'icon', toggle);
+  const body = make('div', 'body', container);
+  const track = make('div', 'track', body);
+  const bars = make('div', 'bars', track);
+  bars.setAttribute('aria-hidden', 'true');
+  const head = make('span', 'head', track); head.setAttribute('aria-hidden', 'true');
+  const preview = make('span', 'preview', track); preview.setAttribute('aria-hidden', 'true'); preview.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');
+  scope.attr(root, 'data-mk-wave-scrubbing', null);
+  let barNodes: HTMLElement[] = [];
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const animation of effects) if (animation.totalProgress() === 1) effects.delete(animation);
+    if (effect) effects.add(effect);
+  };
+  let iconMotion: gsap.core.Tween | null = null;
+  let lastPlaying: boolean | undefined;
+  let lastRate = '';
+  let following = false;
+  const scrubbing = () => root.hasAttribute('data-mk-wave-scrubbing');
+  // Same response as the equalizer: bars crossing the head pop back to height,
+  // except while the head is held, where the value follows the pointer directly.
+  const paintProgress = (seconds: number, animate = true) => {
+    const progress = state.duration ? Math.max(0, Math.min(1, seconds / state.duration)) : 0;
+    track.style.setProperty('--mk-wave-progress', String(progress));
+    barNodes.forEach((bar, i) => {
+      const played = (i + .5) / barNodes.length <= progress;
+      if (bar.hasAttribute('data-mk-played') === played) return;
+      bar.toggleAttribute('data-mk-played', played);
+      if (animate && !scrubbing() && !reduced()) keep(gsap.fromTo(bar, { scaleY: .72 }, { scaleY: 1, duration: .35, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+    });
+  };
+  const followPlayback = () => { if (!scope.disposed && state.status === 'playing') paintProgress(audio.currentTime); };
+  const showPreview = (seconds: number, ratio: number) => {
+    preview.textContent = clock(seconds); preview.style.setProperty('--mk-wave-at', String(Math.max(.04, Math.min(.96, ratio)))); preview.hidden = false;
+  };
+  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';
+    const nextPlaying = playing || requested;
+    if (lastPlaying !== nextPlaying) {
+      icon.innerHTML = nextPlaying ? pauseIcon : playIcon;
+      iconMotion?.kill();
+      if (lastPlaying !== undefined && !reduced()) iconMotion = gsap.fromTo(icon, { scale: .55, opacity: .3, filter: 'blur(5px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: .3, ease: EASE.pop, clearProps: 'transform,opacity,filter' });
+      lastPlaying = nextPlaying;
+    }
+    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;
+    const rateLabel = `${state.playbackRate}×`;
+    if (lastRate !== rateLabel) {
+      if (lastRate) keep(rollDigits(rate, rateLabel, 1, .28));
+      else rate.textContent = rateLabel;
+      lastRate = rateLabel;
+    }
+    rate.setAttribute('aria-label', `Velocidad ${state.playbackRate}×. Cambiar velocidad`);
+    paintProgress(state.currentTime);
+    if (document.activeElement === range) showPreview(state.currentTime, state.duration ? state.currentTime / state.duration : 0);
+    if (playing && !following) { following = true; gsap.ticker.add(followPlayback); }
+    else if (!playing && following) { following = false; gsap.ticker.remove(followPlayback); }
+    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) => {
+    keep(press(target));
+  };
+  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 peakValues = () => {
+    const supplied = Array.isArray(opts.peaks) ? opts.peaks : [];
+    // Empty data is an explicit neutral placeholder, never fabricated audio analysis.
+    return supplied.length ? supplied.slice(0, 256).map(level) : Array<number>(48).fill(0.24);
+  };
+  // Bars keep the equalizer's pitch (pill plus 3px gap ≈ 8px) at any width.
+  const barCount = (values: readonly number[]) => {
+    const width = bars.clientWidth;
+    return width > 0 ? Math.max(12, Math.min(72, Math.floor((width + 3) / 8))) : values.length;
+  };
+  const renderPeaks = () => {
+    const values = peakValues();
+    bars.replaceChildren();
+    barNodes = resample(values, barCount(values)).map(peak => {
+      const bar = make('i', 'bar', bars);
+      bar.style.height = `${8 + peak * 92}%`;
+      return bar;
+    });
+    paintProgress(state.currentTime, false);
+  };
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => {
+    if (!scope.disposed && barCount(peakValues()) !== barNodes.length) renderPeaks();
+  })).observe(bars);
+  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(range, 'pointermove', event => {
+    if (!state.duration || opts.disabled) return;
+    const rect = range.getBoundingClientRect();
+    if (!rect.width) return;
+    // The native thumb spans both insets, as in the equalizer, so its value maps inside them.
+    const inset = parseFloat(getComputedStyle(track).getPropertyValue('--mk-wave-inset')) || 0;
+    const ratio = Math.max(0, Math.min(1, ((event as PointerEvent).clientX - rect.left - inset) / Math.max(1, rect.width - inset * 2)));
+    showPreview(state.duration * ratio, ratio);
+  });
+  scope.on(range, 'pointerleave', () => { if (document.activeElement !== range) preview.hidden = true; });
+  scope.on(range, 'focus', () => { if (state.duration) showPreview(state.currentTime, state.currentTime / state.duration); });
+  scope.on(range, 'blur', () => { preview.hidden = true; });
+  scope.on(range, 'pointerdown', () => {
+    if (range.disabled) return;
+    root.setAttribute('data-mk-wave-scrubbing', ''); keep(press(head));
+  });
+  const release = () => {
+    if (!scrubbing()) return;
+    root.removeAttribute('data-mk-wave-scrubbing');
+    if (!reduced()) keep(gsap.fromTo(head, { scale: 1.12 }, { scale: 1, duration: .4, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+  };
+  scope.on(window, 'pointerup', release);
+  scope.on(window, 'pointercancel', release);
+  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;
+    iconMotion?.kill();
+    for (const effect of effects) effect.kill();
+    gsap.ticker.remove(followPlayback);
+    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() };
+}