@arraypress/waveform-bar 1.2.0 → 1.3.0

package/README.md

@@ -47,6 +47,9 @@ Think Spotify's bottom player — but lightweight, zero-config, and works on any
 <!-- WaveformBar -->
 <link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-bar@latest/dist/waveform-bar.css">
 <script src="https://unpkg.com/@arraypress/waveform-bar@latest/dist/waveform-bar.js"></script>
+
+<!-- Optional: Page icons (play/pause overlays, hearts, carts, etc.) -->
+<link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-bar@latest/dist/waveform-bar-icons.css">
 ```
 
 ### NPM
@@ -75,6 +78,33 @@ npm install @arraypress/waveform-player @arraypress/waveform-bar
 Click the button → the bar slides up from the bottom → music plays. Add more buttons anywhere on the page and they all
 share the same player bar.
 
+## Inline WaveformPlayer integration (v1.3+)
+
+When `@arraypress/waveform-player` 1.6+ instances are mounted on the same page with `audioMode: 'external'`, WaveformBar discovers them automatically and treats them as **synchronized visual surfaces**:
+
+- Click the inline player's play button → playback happens in the bar
+- The bar's audio progress mirrors into the inline canvas in real time (scrubber moves, play/pause icon flips)
+- When the bar switches tracks, the previously-active inline player resets to paused
+
+No configuration on the bar side — the discovery scan runs on init + MutationObserver tick, listening for `waveformplayer:request-play|pause|seek` events at the document level. Any inline player whose URL matches the bar's current track gets `setPlayingState(...)` and `setProgress(...)` calls pumped to it.
+
+```html
+<!-- The same element doubles as a bar trigger (data-wb-play) AND an
+     inline visual surface (data-waveform-player + audio-mode). Single
+     audio source (the bar), multiple visual surfaces (bar + every
+     matching inline player). -->
+<div data-waveform-player
+     data-audio-mode="external"
+     data-url="song.mp3"
+     data-waveform-style="bars"
+
+     data-wb-play
+     data-wb-url="song.mp3"
+     data-wb-title="..."></div>
+```
+
+This is the SoundCloud / Bandcamp pattern — the persistent bar owns playback, but every place a track surfaces on the page gets its own playable, progress-aware visualization.
+
 ## Data Attributes
 
 ### Play Trigger (`data-wb-play`)
@@ -130,21 +160,62 @@ Add to any element to queue a track without immediately playing it.
 </button>
 ```
 
-### Pre-Generated Waveform Data
+### Pre-Generated Waveforms
 
-Skip client-side audio analysis by providing pre-generated waveform peaks.
-Use [waveform-gen](https://github.com/arraypress/waveform-gen) to generate the data.
+Skip client-side audio analysis by providing pre-generated waveform data. The `data-wb-waveform` attribute accepts three
+formats:
+
+| Format        | Example                  | Description                                      |
+|---------------|--------------------------|--------------------------------------------------|
+| JSON file URL | `waveforms/song.json`    | Fetches peaks from `{ peaks: [...] }` or `[...]` |
+| Inline array  | `[0.2, 0.37, 0.41, ...]` | JSON array string                                |
+| CSV string    | `0.2,0.37,0.41,...`      | Comma-separated values                           |
 
 ```html
+<!-- JSON file — fetched automatically by the player -->
+<div data-wb-play
+     data-url="audio/song.mp3"
+     data-title="My Song"
+     data-wb-waveform="waveforms/song.json">
+</div>
 
+<!-- Inline peaks -->
 <div data-wb-play
-     data-url="song.mp3"
+     data-url="audio/song.mp3"
      data-title="My Song"
-     data-wb-waveform='[0.12,0.45,0.89,0.34,0.67,0.92,0.15,0.78]'>
+     data-wb-waveform="[0.12,0.45,0.89,0.34,0.67]">
 </div>
 ```
 
-The waveform displays instantly on load without downloading and decoding the audio file.
+Generate JSON files with [WaveformGen](https://github.com/arraypress/waveform-gen):
+
+```bash
+npx @arraypress/waveform-gen ./audio/*.mp3 --output ./waveforms/ --bpm
+```
+
+JSON waveform files can also include markers, which are loaded automatically if none are set via data attributes:
+
+```json
+{
+  "peaks": [
+    0.12,
+    0.45,
+    0.89,
+    0.34,
+    ...
+  ],
+  "markers": [
+    {
+      "time": 0,
+      "label": "Intro"
+    },
+    {
+      "time": 30,
+      "label": "Chorus"
+    }
+  ]
+}
+```
 
 ### DJ Mode Markers
 
@@ -166,32 +237,31 @@ and metadata at each marker boundary.
 </div>
 ```
 
-Markers can include: `time` (seconds, required), `label` (required), `title`, `artist`, `artwork`, `bpm`, `key`,
-`color`.
+Markers can include: `time` (seconds, required), `label` (required), `title`, `artist`, `artwork`, `bpm`, `key`,`color`.
 
 The active marker on the waveform gently pulses to indicate the current section.
 
 ### Attribute Reference
 
-| Attribute           | Description                                                |
-|---------------------|------------------------------------------------------------|
-| `data-wb-play`      | Makes element a play trigger (click to play)               |
-| `data-wb-queue`     | Makes element a queue trigger (click to add to queue)      |
-| `data-url`          | Audio file URL (required)                                  |
-| `data-id`           | Unique track identifier (defaults to URL)                  |
-| `data-title`        | Track title                                                |
-| `data-artist`       | Artist or subtitle                                         |
-| `data-artwork`      | Album artwork URL                                          |
-| `data-album`        | Album name (for Media Session API)                         |
-| `data-link`         | URL to navigate when clicking track info in the bar        |
-| `data-duration`     | Display duration string                                    |
-| `data-bpm`          | BPM value — displayed as a tag in the bar                  |
-| `data-key`          | Musical key — displayed as a tag in the bar                |
-| `data-meta`         | JSON object of custom metadata (e.g. `'{"genre":"Trap"}'`) |
-| `data-wb-waveform`  | Pre-generated waveform peaks JSON array                    |
-| `data-wb-markers`   | JSON array of marker objects for DJ mode                   |
-| `data-wb-favorited` | `"true"` to pre-set favorite state (server-side seeding)   |
-| `data-wb-in-cart`   | `"true"` to pre-set cart state (server-side seeding)       |
+| Attribute           | Description                                                               |
+|---------------------|---------------------------------------------------------------------------|
+| `data-wb-play`      | Makes element a play trigger (click to play)                              |
+| `data-wb-queue`     | Makes element a queue trigger (click to add to queue)                     |
+| `data-url`          | Audio file URL (required)                                                 |
+| `data-id`           | Unique track identifier (defaults to URL)                                 |
+| `data-title`        | Track title                                                               |
+| `data-artist`       | Artist or subtitle                                                        |
+| `data-artwork`      | Album artwork URL                                                         |
+| `data-album`        | Album name (for Media Session API)                                        |
+| `data-link`         | URL to navigate when clicking track info in the bar                       |
+| `data-duration`     | Display duration string                                                   |
+| `data-bpm`          | BPM value — displayed as a tag in the bar                                 |
+| `data-key`          | Musical key — displayed as a tag in the bar                               |
+| `data-meta`         | JSON object of custom metadata (e.g. `'{"genre":"Trap"}'`)                |
+| `data-wb-waveform`  | Pre-generated waveform peaks: JSON array, CSV string, or `.json` file URL |
+| `data-wb-markers`   | JSON array of marker objects for DJ mode                                  |
+| `data-wb-favorited` | `"true"` to pre-set favorite state (server-side seeding)                  |
+| `data-wb-in-cart`   | `"true"` to pre-set cart state (server-side seeding)                      |
 
 All attributes also accept `data-wb-` prefixed versions (`data-wb-url`, `data-wb-title`, etc.) to avoid conflicts with
 other libraries.
@@ -238,11 +308,11 @@ WaveformBar.init({
     // Server-side actions (REST callbacks)
     actions: {
         favorite: {
-            endpoint: '/api/favorites',     // POST URL
+            endpoint: '/api/favorites',
             method: 'POST'
         },
         cart: {
-            endpoint: '/api/cart',          // POST URL
+            endpoint: '/api/cart',
             method: 'POST'
         }
     },
@@ -270,7 +340,6 @@ WaveformBar.init({
 ### Playback
 
 ```javascript
-// Play a track object
 WaveformBar.play({
     url: 'audio/song.mp3',
     title: 'My Song',
@@ -281,15 +350,12 @@ WaveformBar.play({
     link: '/products/my-song'
 });
 
-// Play by URL shorthand
 WaveformBar.play('audio/song.mp3');
-
-// Playback controls
 WaveformBar.togglePlay();
 WaveformBar.pause();
-WaveformBar.next();                      // Next track (wraps if repeat: 'all')
-WaveformBar.previous();                  // Previous track (restarts if >3s in)
-WaveformBar.skipTo(3);                   // Jump to queue index 3
+WaveformBar.next();
+WaveformBar.previous();
+WaveformBar.skipTo(3);
 ```
 
 ### Repeat
@@ -299,102 +365,57 @@ WaveformBar.cycleRepeat();               // Cycles: off → all → one → off
 WaveformBar.setRepeat('all');            // Set directly: 'off', 'all', 'one'
 ```
 
-- **off** — Stops at end of queue
-- **all** — Loops back to first track after last; prev/next wrap around
-- **one** — Replays the current track indefinitely
-
 ### Markers / DJ Mode
 
 ```javascript
-// Seek to marker by index (0-based) on current track
 WaveformBar.seekToMarker(3);
-
-// Seek to marker by label name on current track
 WaveformBar.seekToMarkerByLabel('Horizon');
 ```
 
-Both methods auto-play if the player is paused. They only work on the currently loaded track's markers — if the track
-with markers isn't loaded, they silently return.
-
 ### Volume
 
 ```javascript
-WaveformBar.setVolume(0.5);              // Set to 50%
-WaveformBar.getVolume();                 // Returns 0.5
+WaveformBar.setVolume(0.5);
+WaveformBar.getVolume();
 WaveformBar.toggleMute();
-WaveformBar.isMutedState();              // true/false
 ```
 
-Volume and mute state persist in localStorage across sessions.
-
 ### Queue
 
 ```javascript
-// Add to end of queue
 WaveformBar.addToQueue({url: 'track.mp3', title: 'Next Up', artist: 'Someone'});
-
-// Remove by index
 WaveformBar.removeFromQueue(2);
-
-// Replay a previously played track (by URL)
-WaveformBar.replay('audio/old-track.mp3');
-
-// Clear upcoming tracks
 WaveformBar.clearQueue();
-
-// Clear play history
-WaveformBar.clearHistory();
 ```
 
-The queue panel shows three sections: **Now Playing** (click to toggle play/pause), **Up Next**, and **Previously Played
-**. Tracks can be removed individually from the queue via the × button on hover.
-
-### Favorites
+### Favorites & Cart
 
 ```javascript
-WaveformBar.toggleFavorite();            // Toggle current track's favorite state
-WaveformBar.isFavorited('beat-001');     // Check by track ID
+WaveformBar.toggleFavorite();
+WaveformBar.isFavorited('beat-001');
+WaveformBar.addToCart();
+WaveformBar.isInCart('beat-001');
 ```
 
-Favorites persist in localStorage. Server-side state can be seeded via `data-wb-favorited="true"` on trigger elements —
-this is authoritative and overrides localStorage on page load.
-
-When a track is favorited/unfavorited, the `.wb-favorited` class is toggled on all matching trigger elements on the
-page.
-
-### Cart
-
-```javascript
-WaveformBar.addToCart();                 // Add current track to cart
-WaveformBar.isInCart('beat-001');        // Check by track ID
-```
-
-Cart state is NOT persisted to localStorage — it's server-authoritative. Seed from your server via
-`data-wb-in-cart="true"`. The `.wb-in-cart` class is toggled on matching trigger elements.
-
-If an `actions.cart.endpoint` is configured, a POST request fires automatically with the track data.
-
 ### State
 
 ```javascript
-WaveformBar.getCurrentTrack();           // { url, title, artist, bpm, key, ... }
-WaveformBar.isCurrentlyPlaying('song.mp3'); // true if this URL is actively playing
-WaveformBar.isCurrentTrack('song.mp3');  // true if current (playing or paused)
-WaveformBar.getQueue();                  // Full queue array
-WaveformBar.getHistory();                // Previously played tracks
-WaveformBar.getPlayer();                 // Underlying WaveformPlayer instance
+WaveformBar.getCurrentTrack();
+WaveformBar.isCurrentlyPlaying('song.mp3');
+WaveformBar.isCurrentTrack('song.mp3');
+WaveformBar.getQueue();
+WaveformBar.getCurrentIndex();
+WaveformBar.getPlayer();
 ```
 
 ### UI
 
 ```javascript
-WaveformBar.show();                      // Show the bar
-WaveformBar.hide();                      // Hide the bar
-WaveformBar.toggleQueuePanel();          // Toggle queue panel visibility
-WaveformBar.toggleVolumePopup();         // Toggle volume popup
-WaveformBar.closeQueuePanel();
-WaveformBar.closeVolumePopup();
-WaveformBar.destroy();                   // Remove bar and clean up
+WaveformBar.show();
+WaveformBar.hide();
+WaveformBar.toggleQueuePanel();
+WaveformBar.toggleVolumePopup();
+WaveformBar.destroy();
 ```
 
 ## DOM Events
@@ -405,10 +426,6 @@ All events bubble from the bar element and are prefixed with `waveformbar:`.
 document.addEventListener('waveformbar:play', (e) => {
     console.log('Playing:', e.detail.track);
 });
-
-document.addEventListener('waveformbar:trackchange', (e) => {
-    console.log('Track changed:', e.detail.track, 'Index:', e.detail.index);
-});
 ```
 
 | Event                      | Detail                     |
@@ -434,16 +451,10 @@ WaveformBar automatically adds CSS classes to trigger elements on the page:
 | `.wb-favorited` | The element's track is favorited                  |
 | `.wb-in-cart`   | The element's track is in the cart                |
 
-These update in real-time as the user interacts with the bar.
-
 ## Helper CSS Classes
 
-Ready-made utility classes for common UI patterns. Add them to your trigger elements.
-
 ### Icon Swap (`wb-icon-swap`)
 
-Swaps play/pause content automatically based on playback state.
-
 ```html
 
 <button data-wb-play data-url="song.mp3" class="wb-icon-swap">
@@ -454,100 +465,74 @@ Swaps play/pause content automatically based on playback state.
 
 ### Equalizer Bars (`wb-eq-bars`)
 
-Animated equalizer bars that activate when the track is playing.
-
 ```html
-
-<tr data-wb-play data-url="song.mp3">
-    <td>
-        <span class="wb-eq-bars">
-            <span></span><span></span><span></span><span></span>
-        </span>
-    </td>
-    <td>Track Title</td>
-</tr>
+<span class="wb-eq-bars"><span></span><span></span><span></span><span></span></span>
 ```
 
 ### Card Highlight (`wb-card-highlight`)
 
-Adds accent border and glow when the element's track is current.
-
-```html
-
-<div data-wb-play data-url="song.mp3"
-     class="wb-card-highlight"
-     style="border: 1px solid transparent; border-radius: 8px;">
-    <h3>Track Title</h3>
-</div>
-```
+Adds accent border when the element's track is current.
 
 ### Accent Text (`wb-accent-current`)
 
 Colors text with the accent color when the parent track is current.
 
-```html
-
-<div data-wb-play data-url="song.mp3">
-    <span class="wb-accent-current">Track Title</span>
-</div>
-```
-
-### Pulse Animation (`wb-pulse-playing`)
-
-Subtle opacity pulse on playing elements.
+### Favorite/Cart Visibility
 
 ```html
-
-<div data-wb-play data-url="song.mp3" class="wb-pulse-playing">
-    <img src="cover.jpg">
-</div>
+<span class="wb-hide-if-fav">♡ Save</span>
+<span class="wb-show-if-fav">❤ Saved</span>
+<span class="wb-hide-if-cart">🛒 Add</span>
+<span class="wb-show-if-cart">✓ In Cart</span>
 ```
 
-### Favorite/Cart Visibility
+## Page Icons
 
-Show or hide content based on favorite/cart state.
+The optional `waveform-bar-icons.css` provides a lightweight SVG icon set for use in your page elements (play/pause
+overlays, hearts, carts, etc.):
 
 ```html
 
-<div data-wb-play data-url="song.mp3" data-id="beat-001">
-    <button>
-        <span class="wb-hide-if-fav">♡ Save</span>
-        <span class="wb-show-if-fav">❤ Saved</span>
-    </button>
-    <button>
-        <span class="wb-hide-if-cart">🛒 Add to Cart</span>
-        <span class="wb-show-if-cart">✓ In Cart</span>
-    </button>
-</div>
-```
+<link rel="stylesheet" href="https://unpkg.com/@arraypress/waveform-bar@latest/dist/waveform-bar-icons.css">
+
+<span class="wbi wbi-play"></span>
+<span class="wbi wbi-pause"></span>
+<span class="wbi wbi-heart"></span>
+<span class="wbi wbi-heart-filled"></span>
+<span class="wbi wbi-cart"></span>
+<span class="wbi wbi-cart-check"></span>
+<span class="wbi wbi-queue"></span>
+<span class="wbi wbi-skip-back"></span>
+<span class="wbi wbi-skip-forward"></span>
+<span class="wbi wbi-volume-high"></span>
+<span class="wbi wbi-volume-low"></span>
+<span class="wbi wbi-volume-mute"></span>
+<span class="wbi wbi-repeat"></span>
+<span class="wbi wbi-repeat-one"></span>
+<span class="wbi wbi-close"></span>
+<span class="wbi wbi-check"></span>
+<span class="wbi wbi-link"></span>
+<span class="wbi wbi-download"></span>
+<span class="wbi wbi-share"></span>
+<span class="wbi wbi-music-note"></span>
+```
+
+Icons inherit `color` from their parent and scale with `font-size`. Size variants: `.wbi-sm`, `.wbi-lg`, `.wbi-xl`,
+`.wbi-2x`, `.wbi-3x`.
+
+These are for your page elements only — the bar itself uses its own internal SVG icons and does not require this file.
 
 ## Persistence
 
-WaveformBar uses two storage mechanisms:
-
-**sessionStorage** (cleared when browser closes):
-
-- Queue contents and order
-- Current track index
-- Playback position
-- Playing state
-
-**localStorage** (persists across sessions):
+**sessionStorage** (cleared when browser closes): queue, current track index, playback position, playing state.
 
-- Volume level
-- Mute state
-- Favorite track IDs
-
-When a user navigates between pages, the bar restores the queue, seeks to the saved position, and optionally resumes
-playback (if `autoResume: true`). Position is saved on every page unload for accuracy.
+**localStorage** (persists across sessions): volume level, mute state, favorite track IDs.
 
 Cart state is intentionally NOT persisted — it seeds from `data-wb-in-cart` attributes on page load, making the server
 the source of truth.
 
 ## Custom Styling
 
-Override CSS custom properties to theme the bar:
-
 ```css
 .waveform-bar,
 .wb-queue-panel {
@@ -555,178 +540,32 @@ Override CSS custom properties to theme the bar:
     --wb-border: rgba(255, 255, 255, 0.1);
     --wb-text: #ffffff;
     --wb-text-muted: rgba(255, 255, 255, 0.5);
-    --wb-accent: #1db954; /* e.g. Spotify green */
+    --wb-accent: #1db954;
     --wb-accent-light: #1ed760;
     --wb-hover: rgba(255, 255, 255, 0.08);
-    --wb-tag-bg: rgba(29, 185, 84, 0.12);
-    --wb-tag-text: #1db954;
     --wb-fav-color: #ef4444;
     --wb-cart-color: #4ade80;
 }
 ```
 
-A `.wb-light` class is available for light backgrounds:
-
-```css
-.waveform-bar.wb-light {
-    --wb-bg: rgba(255, 255, 255, 0.95);
-    --wb-text: #1a1a1a;
-    --wb-text-muted: rgba(0, 0, 0, 0.5);
-}
-```
-
-## Layout
-
-The bar uses a three-zone flex layout:
-
-```
-[Left: controls + track info] — [Centre: waveform + time] — [Right: meta + actions + volume + queue]
-```
-
-- **Left zone** — Prev, Play/Pause, Next, Repeat buttons + artwork + title/artist
-- **Centre zone** — Full-width waveform visualization + elapsed/total time
-- **Right zone** — BPM/key tags, favorite/cart buttons, volume popup, queue toggle
-
-On mobile (≤768px):
-
-- Left + Right share the top row
-- Waveform drops to a full-width second row
-- Meta tags, actions, and time display are hidden
-- Queue panel becomes full-width
-
-On small mobile (≤480px):
-
-- Prev/Next and Repeat buttons are hidden
-- Volume is hidden
-- Only play button, track info, and waveform remain
-
-## Use Cases
-
-### Beat Store
-
-```html
-
-<div class="beat-card wb-card-highlight"
-     data-wb-play
-     data-url="beats/trap-42.mp3"
-     data-id="beat-42"
-     data-title="Trap Beat #42"
-     data-artist="ProducerName"
-     data-bpm="140"
-     data-key="Cm"
-     data-artwork="covers/trap-42.jpg"
-     data-link="/beats/trap-42"
-     data-wb-favorited="true">
-    <img src="covers/trap-42.jpg">
-    <h3 class="wb-accent-current">Trap Beat #42</h3>
-    <p>140 BPM · Cm · $29.99</p>
-    <span class="wb-eq-bars"><span></span><span></span><span></span><span></span></span>
-    <button>
-        <span class="wb-hide-if-fav">♡ Save</span>
-        <span class="wb-show-if-fav">❤ Saved</span>
-    </button>
-</div>
-<button data-wb-queue data-url="beats/trap-42.mp3" data-title="Trap Beat #42">+ Queue</button>
-```
-
-### Sample Library Table
-
-```html
-
-<table>
-    <tr data-wb-play
-        data-url="samples/kick.wav"
-        data-title="808 Kick"
-        data-artist="Drum Kit Vol. 3"
-        data-bpm="128"
-        data-meta='{"format":"WAV"}'>
-        <td><span class="wb-eq-bars"><span></span><span></span><span></span><span></span></span></td>
-        <td class="wb-accent-current">808 Kick</td>
-        <td>128 BPM</td>
-        <td>WAV</td>
-    </tr>
-</table>
-```
-
-### DJ Mix with Clickable Tracklist
-
-```html
-<!-- Mix trigger with markers -->
-<div data-wb-play
-     data-url="mixes/guestmix.mp3"
-     data-title="Guest Mix"
-     data-artist="Various Artists"
-     data-wb-waveform='[0.1,0.3,0.5,...]'
-     data-wb-markers='[
-         {"time":0,"label":"Intro","title":"Opening","artist":"DJ One"},
-         {"time":180,"label":"Drop","title":"Big Tune","artist":"Producer X"},
-         {"time":360,"label":"Chill","title":"Wind Down","artist":"Ambient Co"}
-     ]'>
-    🎧 Play Guest Mix
-</div>
-
-<!-- Clickable tracklist buttons -->
-<button onclick="WaveformBar.seekToMarkerByLabel('Intro')">00:00 — DJ One — Opening</button>
-<button onclick="WaveformBar.seekToMarkerByLabel('Drop')">03:00 — Producer X — Big Tune</button>
-<button onclick="WaveformBar.seekToMarkerByLabel('Chill')">06:00 — Ambient Co — Wind Down</button>
-```
-
-### Podcast
-
-```html
-
-<button data-wb-play
-        data-url="episodes/ep42.mp3"
-        data-title="Ep 42: The Future of AI"
-        data-artist="with Dr. Sarah Chen"
-        data-artwork="ep42-cover.jpg"
-        data-link="/episodes/42"
-        class="wb-icon-swap">
-    <span class="wb-show-play">▶ Listen</span>
-    <span class="wb-show-pause">⏸ Playing</span>
-</button>
-```
-
-## Pre-Generating Waveforms
-
-Use [@arraypress/waveform-gen](https://github.com/arraypress/waveform-gen) to batch-generate waveform data:
-
-```bash
-# Generate JSON files for all audio
-npx @arraypress/waveform-gen ./audio/*.mp3 --output ./waveforms/
-
-# Generate ready-to-paste HTML markup
-npx @arraypress/waveform-gen ./audio/*.mp3 --format html --output ./
-```
-
-Then reference the data in your HTML:
-
-```html
-
-<div data-wb-play
-     data-url="song.mp3"
-     data-title="My Song"
-     data-wb-waveform='[0.12,0.45,0.89,0.34,0.67]'>
-</div>
-```
-
 ## Browser Support
 
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Mobile browsers (iOS Safari, Chrome Android)
+Chrome/Edge 90+, Firefox 88+, Safari 14+, iOS Safari, Chrome Android
 
 ## Dependencies
 
-- [WaveformPlayer](https://github.com/arraypress/waveform-player) ≥1.3.5 — must be loaded before WaveformBar
+- [WaveformPlayer](https://github.com/arraypress/waveform-player) ≥1.5.0 — must be loaded before WaveformBar
 
-## License
+## Ecosystem
 
-MIT © [ArrayPress](https://github.com/arraypress)
+| Package                                                                 | Description                                                       |
+|-------------------------------------------------------------------------|-------------------------------------------------------------------|
+| **[WaveformPlayer](https://github.com/arraypress/waveform-player)**     | Core audio player with waveform visualization                     |
+| **[WaveformBar](https://github.com/arraypress/waveform-bar)**           | Persistent bottom-bar player with queue, favorites, cart, DJ mode |
+| **[WaveformGen](https://github.com/arraypress/waveform-generator)**     | CLI tool to pre-generate waveform JSON from audio files           |
+| **[WaveformPlaylist](https://github.com/arraypress/waveform-playlist)** | Playlist and chapter support addon                                |
+| **[WaveformTracker](https://github.com/arraypress/waveform-tracker)**   | Audio engagement analytics                                        |
 
-## Related
+## License
 
-- [WaveformPlayer](https://github.com/arraypress/waveform-player) — Core audio player with waveform visualization
-- [WaveformPlaylist](https://github.com/arraypress/waveform-playlist) — On-page playlist and chapter navigation
-- [WaveformGen](https://github.com/arraypress/waveform-generator) — CLI tool for batch waveform data generation
+MIT © [ArrayPress](https://github.com/arraypress)