@djangocfg/ui-tools 2.1.310 → 2.1.313

package/src/tools/AudioPlayer/PlayerShell.tsx

@@ -0,0 +1,122 @@
+'use client';
+
+// Inner shell that runs inside <PlayerProvider>. Owns variant selection,
+// keyboard shortcuts and MediaSession wiring; renders the picked layout.
+
+import { useCallback, useEffect, useImperativeHandle, useState } from 'react';
+import { TooltipProvider } from '@djangocfg/ui-core/components';
+import { useIsPhone } from '@djangocfg/ui-core/hooks';
+import { usePlayerAudio, usePlayerControls, usePlayerMeta } from './context/selectors';
+import { useElementWidth } from './hooks/useResizeObserver';
+import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts';
+import { useMediaSession } from './hooks/useMediaSession';
+import { CompactLayout, DefaultLayout } from './parts/Layout';
+import type { PlayerHandle, PlayerProps, PlayerVariant } from './types';
+
+const COMPACT_BREAKPOINT = 480;
+
+type Props = Pick<
+  PlayerProps,
+  | 'className'
+  | 'variant'
+  | 'waveform'
+  | 'reactiveCover'
+  | 'onPrev'
+  | 'onNext'
+  | 'enableKeyboardShortcuts'
+  | 'ariaLabel'
+  | 'seekStartsPlayback'
+> & {
+  handleRef?: React.Ref<PlayerHandle>;
+};
+
+export function PlayerShell({
+  className = '',
+  variant = 'auto',
+  waveform,
+  reactiveCover = false,
+  onPrev,
+  onNext,
+  enableKeyboardShortcuts = true,
+  ariaLabel,
+  seekStartsPlayback = true,
+  handleRef,
+}: Props) {
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const audio = usePlayerAudio();
+  const controls = usePlayerControls();
+  const meta = usePlayerMeta();
+  const width = useElementWidth(container);
+  const isPhone = useIsPhone();
+
+  // `auto` resolves to the layout best for the available space:
+  // - on a phone viewport we always use compact (regardless of container);
+  // - otherwise compact only when the container itself is narrower than
+  //   COMPACT_BREAKPOINT.
+  const resolvedVariant: PlayerVariant =
+    variant === 'auto'
+      ? isPhone || (width > 0 && width < COMPACT_BREAKPOINT)
+        ? 'compact'
+        : 'default'
+      : variant;
+
+  useMediaSession(audio, meta, controls, onPrev, onNext);
+  const hotkeys = useKeyboardShortcuts({
+    audio,
+    controls,
+    enabled: enableKeyboardShortcuts,
+  });
+
+  // Compose the container state-ref with the hotkey scoping ref. Both want
+  // to see the same DOM node — one for layout/keyboard-focus management, the
+  // other for react-hotkeys-hook's scoped listener.
+  const setRootRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      setContainer(node);
+      hotkeys.ref(node);
+    },
+    [hotkeys],
+  );
+
+  useImperativeHandle(
+    handleRef,
+    (): PlayerHandle => ({
+      audio,
+      play: () => controls.play(),
+      pause: () => controls.pause(),
+      seek: (s: number) => controls.seek(s),
+      getCurrentTime: () => audio.currentTime,
+      getDuration: () => (Number.isFinite(audio.duration) ? audio.duration : 0),
+    }),
+    [audio, controls],
+  );
+
+  // Keyboard shortcuts work only when the container can take focus.
+  useEffect(() => {
+    if (!container || container.hasAttribute('tabindex')) return;
+    container.setAttribute('tabindex', '0');
+  }, [container]);
+
+  return (
+    <TooltipProvider delayDuration={400}>
+      <div
+        ref={setRootRef}
+        role="group"
+        aria-label={ariaLabel ?? 'Audio player'}
+        className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
+      >
+        {resolvedVariant === 'compact' ? (
+          <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
+        ) : (
+          <DefaultLayout
+            waveform={waveform}
+            reactiveCover={reactiveCover}
+            onPrev={onPrev}
+            onNext={onNext}
+            seekStartsPlayback={seekStartsPlayback}
+          />
+        )}
+      </div>
+    </TooltipProvider>
+  );
+}

package/src/tools/AudioPlayer/README.md

@@ -1,243 +1,178 @@
-# AudioPlayer
+# AudioPlayer (v6)
 
-Audio player with native HTML5 streaming and audio-reactive visualizations.
+WebView-safe React audio player. One component, two layouts, waveform-as-progress.
+Tuned for 60 fps inside WKWebView (Wails / Electron) and Tauri WebView2.
 
-## Features
+Architecture, ADRs and the visual direction live at
+`packages/ui-tools/@dev/@refactoring6-audioplayer/`.
 
-- Native HTML5 audio playback (no crackling, native streaming support)
-- Web Audio API for real-time frequency analysis
-- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
-- Frequency visualization waveform
-- Full playback controls
-
-## Quick Start
+## Quick start
 
 ```tsx
-import { HybridSimplePlayer, HybridCompactPlayer } from '@djangocfg/ui-nextjs';
-
-// Simple usage
-<HybridSimplePlayer src="https://example.com/audio.mp3" />
-
-// Compact single-row player (for lists, sidebars)
-<HybridCompactPlayer src="https://example.com/audio.mp3" title="Rain & Thunder" />
-
-// With metadata and reactive cover
-<HybridSimplePlayer
-  src={audioUrl}
-  title="Track Title"
-  artist="Artist Name"
-  coverArt="/path/to/cover.jpg"
-  reactiveCover
-  variant="spotlight"
-/>
+import { LazyAudioPlayer } from '@djangocfg/ui-tools';
 
-// Full customization
-<HybridSimplePlayer
-  src={audioUrl}
-  title="Track Title"
-  coverArt={coverUrl}
-  showWaveform
-  waveformMode="frequency"  // 'frequency' | 'static'
-  showLoop
-  reactiveCover
-  variant="spotlight"       // 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none'
-  intensity="medium"        // 'subtle' | 'medium' | 'strong'
-  colorScheme="primary"     // 'primary' | 'vibrant' | 'cool' | 'warm'
-  layout="horizontal"       // 'vertical' | 'horizontal'
+<LazyAudioPlayer
+  src="/audio/track.mp3"
+  title="Track"
+  artist="Artist"
+  cover="/cover.jpg"
 />
 ```
 
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | required | Audio URL |
-| `title` | `string` | - | Track title |
-| `artist` | `string` | - | Artist name |
-| `coverArt` | `string \| ReactNode` | - | Cover image URL or custom element |
-| `coverSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Cover art size |
-| `showWaveform` | `boolean` | `true` | Show frequency visualization |
-| `waveformMode` | `'frequency' \| 'static'` | `'frequency'` | Visualization mode |
-| `waveformHeight` | `number` | `64` | Waveform height in pixels |
-| `showTimer` | `boolean` | `true` | Show time display |
-| `showVolume` | `boolean` | `true` | Show volume control |
-| `showLoop` | `boolean` | `true` | Show loop button |
-| `reactiveCover` | `boolean` | `true` | Enable reactive effects |
-| `variant` | `VisualizationVariant` | `'spotlight'` | Effect variant |
-| `intensity` | `EffectIntensity` | `'medium'` | Effect intensity |
-| `colorScheme` | `EffectColorScheme` | `'primary'` | Effect colors |
-| `autoPlay` | `boolean` | `false` | Auto-play on load |
-| `loop` | `boolean` | `false` | Loop playback |
-| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
-
-## Advanced Usage
-
-### HybridAudioProvider + HybridAudioPlayer
-
-For custom layouts:
+For non-lazy use (e.g. above-the-fold):
 
 ```tsx
-import {
-  HybridAudioProvider,
-  HybridAudioPlayer,
-  AudioReactiveCover,
-  useHybridAudioContext
-} from '@djangocfg/ui-nextjs';
-
-function MyPlayer({ audioUrl }: { audioUrl: string }) {
-  return (
-    <HybridAudioProvider src={audioUrl}>
-      <AudioReactiveCover variant="spotlight" onClick={handleClick}>
-        <img src={coverUrl} alt="Cover" />
-      </AudioReactiveCover>
-      <HybridAudioPlayer showWaveform showControls />
-      <CustomControls />
-    </HybridAudioProvider>
-  );
-}
-
-function CustomControls() {
-  const { state, controls, audioLevels } = useHybridAudioContext();
-
-  return (
-    <div>
-      <p>Bass level: {(audioLevels.bass * 100).toFixed(0)}%</p>
-      <button onClick={controls.togglePlay}>
-        {state.isPlaying ? 'Pause' : 'Play'}
-      </button>
-    </div>
-  );
-}
+import { Player } from '@djangocfg/ui-tools/tools/AudioPlayer';
+
+<Player src="/audio/track.mp3" />
 ```
 
-## Hooks
+## Why v6
 
-### useHybridAudioContext
+The previous Hybrid* surface (now `AudioPlayer_old/`) used a per-frame
+`AnalyserNode` redraw, multiple effect components and a single Context that
+re-rendered every consumer at 60 Hz. v6 fixes the structural issues:
 
-Full context access:
+- Static peaks decoded **once**, painted **twice** (background + foreground),
+  playhead animated via CSS `clip-path` + a single CSS variable. Zero canvas
+  paints during steady-state playback.
+- Three split contexts (State / Controls / Levels) — controls memoised once,
+  levels exposed as an imperative store; React doesn't re-render on level
+  updates at all.
+- One module-level `AudioContext`, `MediaElementSourceNode` cached in a
+  `WeakMap` per `<audio>` — Safari context-quota safe and StrictMode safe.
 
-```tsx
-const {
-  state,       // { isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping }
-  controls,    // { play, pause, togglePlay, seek, skip, setVolume, toggleMute, toggleLoop }
-  audioLevels, // { bass, mid, high, overall }
-  webAudio,    // { context, analyser, sourceNode }
-  audioRef,    // React ref to HTMLAudioElement
-} = useHybridAudioContext();
-```
+## Props
 
-### Specialized Hooks
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `src` | `string` | required | |
+| `peaks` | `Float32Array` | — | Pre-computed peaks (skips client decode). |
+| `title` / `artist` / `album` / `cover` | `string` | — | Drive `<MediaSession>` too. |
+| `variant` | `'auto' \| 'default' \| 'compact'` | `'auto'` | `auto` → compact on phones / narrow containers. |
+| `waveform.mode` | `'peaks' \| 'live' \| 'bars' \| 'progress' \| 'none'` | `'peaks'` | `progress` is a plain scrubber, no animation. `peaks` falls back to `progress` on decode failure. |
+| `waveform.height` | `number` | 40 (default) / 24 (compact) | |
+| `reactiveCover` | `false \| 'subtle'` | `false` | Compositor-only scale pulse. |
+| `exclusive` | `boolean` | `true` | Pauses sibling players via `activePlayerBus` (cross-tab via `BroadcastChannel`). |
+| `seekStartsPlayback` | `boolean` | `true` | Click on the waveform also starts playback when paused. |
+| `autoplay` / `loop` / `muted` / `initialVolume` / `preload` | — | — | Standard HTML media. |
+| `onPrev` / `onNext` | `() => void` | — | Render skip buttons + `MediaSession` handlers. |
+| `onPlay` / `onPause` / `onEnded` / `onError` | callbacks | — | |
+| `enableKeyboardShortcuts` | `boolean` | `true` | Active only when focus is inside the player. |
+| `ariaLabel` / `className` | `string` | — | |
+
+## Controls
+
+- **Mouse / touch** — click the waveform to seek (and start playback if
+  paused); drag to scrub. Hover shows a time tooltip (desktop only).
+- **Keyboard** — Space/K play-pause, ←/→ seek 5 s, ↑/↓ volume, M mute, L loop.
+- **MediaSession** — wires play / pause / next / prev / seek to OS-level Now
+  Playing controls (works in Wails through WKWebView).
+
+## Mobile
+
+- `variant: 'auto'` resolves to `compact` on phone viewports (< 640 px).
+- Volume popover opens by tap on touch (no hover); hover affordances are
+  hidden via `@media (hover: none)`.
+- iOS Safari: the volume slider is hidden (the OS controls hardware volume
+  there — `audio.volume` is read-only); mute toggle stays.
+- Tap targets ≥ 40 px on coarse pointers.
+
+## Persistent preferences
+
+`volume` and `muted` are stored in `localStorage` (key
+`djangocfg-audioplayer:prefs`) and synced across all uncontrolled players in
+the page and across tabs (`storage` event). Pass `initialVolume` / `muted` to
+opt a specific player out — it then ignores the store and never writes to it.
+
+## Active-player coordination
+
+`exclusive` (default `true`) registers each player with a small in-memory bus.
+Only one player plays at a time per page; `BroadcastChannel` extends the same
+rule across tabs. Hooks for the bus state:
 
 ```tsx
-// State only
-const { isPlaying, currentTime, duration } = useHybridAudioState();
-
-// Controls only (no re-render on time updates)
-const { play, pause, togglePlay, seek } = useHybridAudioControls();
-
-// Audio levels for reactive effects
-const { bass, mid, high, overall } = useHybridAudioLevels();
-
-// Web Audio API access
-const { context, analyser, sourceNode } = useHybridWebAudio();
+import {
+  useActivePlayer,        // currently playing id (or null)
+  useLastActivePlayer,    // most recently active id (sticky)
+  useIsActivePlayer,      // boolean for a specific id
+} from '@djangocfg/ui-tools';
 ```
 
-## Components
-
-### AudioReactiveCover
+## Custom layouts (slot composition)
 
-Album art wrapper with audio-reactive effects:
+Drop `<PlayerProvider>` and arrange the parts you want yourself. Every part
+reads from the player context — pass nothing, just compose.
 
 ```tsx
-<AudioReactiveCover
-  variant="spotlight"    // 'glow' | 'orbs' | 'spotlight' | 'mesh'
-  intensity="medium"     // 'subtle' | 'medium' | 'strong'
-  colorScheme="primary"  // 'primary' | 'vibrant' | 'cool' | 'warm'
-  onClick={() => nextVariant()}
->
-  <img src={coverArt} alt="Album cover" />
-</AudioReactiveCover>
+import {
+  PlayerProvider,
+  Cover, Title, Artist, TimeDisplay,
+  PlayButton, VolumeControl, LoopButton,
+  Waveform,
+} from '@djangocfg/ui-tools';
+
+<PlayerProvider src="/track.mp3" title="…" artist="…" cover="/cover.jpg">
+  <div className="grid grid-cols-[96px_1fr_auto] gap-4 rounded-lg border bg-card p-4">
+    <div className="row-span-2"><Cover size={96} /></div>
+    <div className="min-w-0"><Title /><Artist /></div>
+    <TimeDisplay />
+    <div className="col-span-2 space-y-3">
+      <Waveform height={48} />
+      <div className="flex items-center justify-between">
+        <PlayButton />
+        <div className="flex items-center gap-1">
+          <VolumeControl />
+          <LoopButton />
+        </div>
+      </div>
+    </div>
+  </div>
+</PlayerProvider>
 ```
 
-### HybridCompactPlayer
+> **Note:** the slot-composed players use Radix `Tooltip` for control labels.
+> The default `<Player>` ships its own `TooltipProvider`, but slot composition
+> bypasses it — wrap your custom layout in
+> `<TooltipProvider>` (from `@djangocfg/ui-core`) once at the app root, or
+> tooltips will throw `"Tooltip must be used within TooltipProvider"`.
 
-Single-row player — play/pause + waveform + timer. No cover art, no volume slider.
+Re-exported parts: `Cover`, `CoverPlaceholder`, `ReactivePulse`, `Title`,
+`Artist`, `TimeDisplay`, `PlayButton`, `SkipButton`, `VolumeControl`,
+`LoopButton`, `ControlsRow`, `IconButton`, `Waveform`, `PeaksWaveform`,
+`LiveWaveform`, `BarsWaveform`, `ProgressBar`, `WaveformSkeleton`,
+`ErrorState`, `DefaultLayout`, `CompactLayout`.
 
-```tsx
-<HybridCompactPlayer
-  src={audioUrl}
-  title="Track name"     // used as tooltip
-  waveformMode="frequency"  // 'frequency' | 'static'
-  showTimer={true}
-  autoPlay={false}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | required | Audio URL |
-| `title` | `string` | - | Tooltip / aria-label |
-| `waveformMode` | `'frequency' \| 'static'` | `'frequency'` | Visualization mode |
-| `showTimer` | `boolean` | `true` | Show current/total time |
-| `buttonSize` | `'sm' \| 'md'` | `'md'` | Play button size (`sm` = h-6 w-6, `md` = h-8 w-8) |
-| `autoPlay` | `boolean` | `false` | Auto-play on load |
-| `loop` | `boolean` | `false` | Loop playback |
-| `initialVolume` | `number` | `1` | Initial volume 0-1 |
+## Selector hooks
 
-For lazy-loading (preferred in Next.js apps):
+For custom toolbars — read state without re-implementing the controls UI:
 
 ```tsx
-import { LazyHybridCompactPlayer } from '@djangocfg/ui-tools';
-
-<LazyHybridCompactPlayer src={url} title="Track" autoPlay />
+import {
+  usePlayerState,        // discriminated union: idle | loading | playing | paused | …
+  usePlayerControls,     // play / pause / toggle / seek / setVolume / …
+  usePlayerLevels,       // imperative store; for live-mode canvases
+  usePlayerMeta,         // src / title / artist / cover
+  usePlayerPaused,       // boolean shortcut
+  usePlayerDuration,     // number shortcut
+  usePlayerPreferences,  // { volume, muted } from the persistent store
+} from '@djangocfg/ui-tools';
 ```
 
-### HybridWaveform
+These work inside `<Player>`'s tree; if you need your own JSX around the
+state, mount `<PlayerProvider>` directly (also exported).
 
-Real-time frequency visualization:
+## Stories
 
-```tsx
-<HybridWaveform
-  mode="frequency"  // 'frequency' | 'static'
-  height={64}
-  barWidth={3}
-  barGap={2}
-/>
-```
+Storybook-style stories live in `AudioPlayer.story.tsx`:
 
-## Effect Variants
+- `Default`, `WithCover`, `Compact`, `CustomLayout`, `Bars`, `Live`,
+  `NoWaveform`, `ReactiveCover`, `ErrorState`, `Exclusive`, `Interactive`,
+  `Showcase` (one-page demo of every prop / mode / hook).
 
-| Variant | Description |
-|---------|-------------|
-| `spotlight` | Rotating conic gradient with bass pulse |
-| `glow` | Multi-layered radial glows from edges |
-| `orbs` | Floating orbs that react to frequencies |
-| `mesh` | Large gradient blobs with movement |
-| `none` | Effects disabled |
+Run `pnpm playground` from `packages/ui-tools/`.
 
-## Architecture
-
-```
-AudioPlayer/
-├── index.ts                       # Public API exports
-├── types/                         # TypeScript types
-├── hooks/
-│   ├── useHybridAudio.ts          # HTML5 audio + Web Audio hook
-│   ├── useHybridAudioAnalysis.ts  # Frequency analysis
-│   └── useVisualization.tsx       # Visualization settings
-├── context/
-│   └── HybridAudioProvider.tsx    # Audio context provider
-├── components/
-│   ├── HybridAudioPlayer.tsx      # Main player component
-│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper (with cover, volume, effects)
-│   ├── HybridCompactPlayer.tsx    # Compact single-row player
-│   ├── HybridWaveform.tsx         # Frequency visualization
-│   └── ReactiveCover/             # Reactive effects
-├── effects/                       # Effect calculations
-└── utils/                         # Utilities
-```
+## Related
 
-Key design:
-- HTML5 `<audio>` for playback (native streaming, no crackling)
-- Web Audio API AnalyserNode for visualization only (not connected to output)
-- Audio graph: `source → destination` + `source → analyser` (passive)
+- Old (reference only): `tools/AudioPlayer_old/`.
+- Architecture: `@dev/@refactoring6-audioplayer/`.

package/src/tools/AudioPlayer/audio/audioContext.ts

@@ -0,0 +1,39 @@
+// Singleton AudioContext for the whole tab.
+// See ADR-004. Never closed during normal operation.
+
+let _ctx: AudioContext | null = null;
+
+type WebkitWindow = typeof window & {
+  webkitAudioContext?: typeof AudioContext;
+};
+
+export function getAudioContext(): AudioContext {
+  if (_ctx) return _ctx;
+  const w = window as WebkitWindow;
+  const Ctor = w.AudioContext ?? w.webkitAudioContext;
+  if (!Ctor) {
+    throw new Error('Web Audio API is not supported in this environment');
+  }
+  _ctx = new Ctor({ latencyHint: 'interactive' });
+  return _ctx;
+}
+
+export async function unlockAudioContext(): Promise<void> {
+  const ctx = getAudioContext();
+  if (ctx.state === 'suspended') {
+    try {
+      await ctx.resume();
+    } catch {
+      // Resume requires a user gesture; caller should retry from one.
+    }
+  }
+}
+
+export function isAudioContextRunning(): boolean {
+  return _ctx?.state === 'running';
+}
+
+// Test-only: drop the singleton between test cases.
+export function _resetAudioContextForTesting(): void {
+  _ctx = null;
+}

package/src/tools/AudioPlayer/audio/decodePeaks.ts

@@ -0,0 +1,36 @@
+// fetch + OfflineAudioContext + bucketize. See ADR-002 / research 02.
+// Uses a low-sample-rate mono context to keep memory bounded.
+
+import { bucketize } from '../utils/bucketize';
+
+const SAMPLE_RATE = 22_050;
+const DEFAULT_BUCKETS = 1800;
+
+type WebkitWindow = typeof window & {
+  webkitOfflineAudioContext?: typeof OfflineAudioContext;
+};
+
+function getOfflineCtor(): typeof OfflineAudioContext {
+  const w = window as WebkitWindow;
+  const Ctor = w.OfflineAudioContext ?? w.webkitOfflineAudioContext;
+  if (!Ctor) throw new Error('OfflineAudioContext is not supported');
+  return Ctor;
+}
+
+export async function decodePeaks(
+  src: string,
+  buckets: number = DEFAULT_BUCKETS,
+  signal?: AbortSignal,
+): Promise<Float32Array> {
+  const response = await fetch(src, { signal, credentials: 'same-origin' });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch audio for peaks (${response.status})`);
+  }
+  const arr = await response.arrayBuffer();
+  const Ctor = getOfflineCtor();
+  // Length must be ≥ 1; the actual length doesn't matter for decodeAudioData.
+  const ctx = new Ctor(1, 1, SAMPLE_RATE);
+  const audio = await ctx.decodeAudioData(arr);
+  const channel = audio.getChannelData(0);
+  return bucketize(channel, buckets);
+}

package/src/tools/AudioPlayer/audio/index.ts

@@ -0,0 +1,4 @@
+export { getAudioContext, unlockAudioContext, isAudioContextRunning } from './audioContext';
+export { getMediaElementSource, hasMediaElementSource } from './mediaElementSourceCache';
+export { decodePeaks } from './decodePeaks';
+export { getPeaks, setPeaks, getPeaksFromCache, clearPeaksCache } from './peaksCache';

package/src/tools/AudioPlayer/audio/mediaElementSourceCache.ts

@@ -0,0 +1,20 @@
+// Per-element MediaElementSourceNode cache.
+// See ADR-004 §B. WeakMap so entries die with the audio element.
+
+import { getAudioContext } from './audioContext';
+
+const cache = new WeakMap<HTMLAudioElement, MediaElementAudioSourceNode>();
+
+export function getMediaElementSource(el: HTMLAudioElement): MediaElementAudioSourceNode {
+  const hit = cache.get(el);
+  if (hit) return hit;
+  const ctx = getAudioContext();
+  const node = ctx.createMediaElementSource(el);
+  node.connect(ctx.destination);
+  cache.set(el, node);
+  return node;
+}
+
+export function hasMediaElementSource(el: HTMLAudioElement): boolean {
+  return cache.has(el);
+}

package/src/tools/AudioPlayer/audio/peaksCache.ts

@@ -0,0 +1,37 @@
+// Module-level peaks cache. Dedupes in-flight decodes; caches resolved buffers.
+// See ADR-002.
+
+import { decodePeaks } from './decodePeaks';
+
+const cache = new Map<string, Float32Array>();
+const inflight = new Map<string, Promise<Float32Array>>();
+
+export async function getPeaks(src: string, buckets?: number): Promise<Float32Array> {
+  const hit = cache.get(src);
+  if (hit) return hit;
+  const flying = inflight.get(src);
+  if (flying) return flying;
+  const promise = decodePeaks(src, buckets).then((peaks) => {
+    cache.set(src, peaks);
+    return peaks;
+  });
+  inflight.set(src, promise);
+  try {
+    return await promise;
+  } finally {
+    inflight.delete(src);
+  }
+}
+
+export function setPeaks(src: string, peaks: Float32Array): void {
+  cache.set(src, peaks);
+}
+
+export function getPeaksFromCache(src: string): Float32Array | undefined {
+  return cache.get(src);
+}
+
+export function clearPeaksCache(src?: string): void {
+  if (src) cache.delete(src);
+  else cache.clear();
+}

package/src/tools/AudioPlayer/context/AudioRefContext.tsx

@@ -0,0 +1,9 @@
+'use client';
+
+import { createContext } from 'react';
+
+// The persistent <audio> element. Components that need imperative access
+// (TimeDisplay, Waveform playhead, click-to-seek) read this — not the React
+// state — to avoid coupling per-frame work to renders.
+export const AudioRefCtx = createContext<HTMLAudioElement | null>(null);
+AudioRefCtx.displayName = 'AudioPlayerAudioRefCtx';

package/src/tools/AudioPlayer/context/ControlsContext.tsx

@@ -0,0 +1,7 @@
+'use client';
+
+import { createContext } from 'react';
+import type { PlayerControls } from '../types';
+
+export const ControlsCtx = createContext<PlayerControls | null>(null);
+ControlsCtx.displayName = 'AudioPlayerControlsCtx';

package/src/tools/AudioPlayer/context/LevelsContext.tsx

@@ -0,0 +1,7 @@
+'use client';
+
+import { createContext } from 'react';
+import type { LevelsStore } from '../store';
+
+export const LevelsCtx = createContext<LevelsStore | null>(null);
+LevelsCtx.displayName = 'AudioPlayerLevelsCtx';