Split player adapters out of hyperaudio-lite.js into separate files

[maboa]

Problem

js/hyperaudio-lite.js currently bundles seven player-related classes in one file (~260 of its ~786 lines):

• BasePlayer (shared base)
• NativePlayer (HTML5 <audio> / <video>)
• SoundCloudPlayer
• VideoJSPlayer
• VimeoPlayer
• YouTubePlayer
• SpotifyPlayer

Every consumer ships all seven, even if they only use the native player. For native-only consumers (the common case), that's a meaningful chunk of code they never run — and it couples unrelated third-party APIs into one file, making the core harder to reason about and harder to evolve.

Proposed direction

Phase 1 — code organisation (this issue). Move each non-native adapter into its own file under js/players/. The core keeps BasePlayer, NativePlayer, the hyperaudioPlayer factory, and the HyperaudioLite class. Adapters self-register on a shared namespace the factory looks up at runtime.

js/
  hyperaudio-lite.js          (core: BasePlayer, NativePlayer, factory, HyperaudioLite)
  players/
    soundcloud.js
    videojs.js
    vimeo.js
    youtube.js
    spotify.js

Consumers using non-native players add one extra <script> tag:

<script src="js/hyperaudio-lite.js"></script>
<script src="js/players/youtube.js"></script>

The constructor stays synchronous (no async ceremony). The core is ~40% smaller for native-only consumers. No build step needed.

This is a small breaking change: every consumer using SC/YT/Vimeo/VideoJS/Spotify needs to add one <script> tag. Documented as a 2.5.0 migration in the changelog and README. All 10 example HTML files updated as part of the change.

Phase 2 — lazy loading (separate issue, after #218). Once the library is distributed as ES modules (#218), the factory can import('./players/youtube.js') on demand based on data-player-type, eliminating the consumer-facing <script> and shrinking initial payload further. We considered doing lazy loading directly without #218, but the loader would need to invent base-path discovery, a global-registration shim, and serial script loading — all of which gets thrown away once ESM lands. Worth waiting.

Why not just lazy-load now without #218?

• Path discovery without ESM is fragile (document.currentScript.src derivation has edge cases; hard-coded relative paths break when consumers rehost).
• Constructor becomes async, which would have to be undone or reshaped once a proper module system is in place.
• The loader is throwaway — every line gets replaced by a one-liner import() after Distribute the library in ESM and CJS forms in addition to the classic script #218.

The phase-1 plain-refactor is durable: even after #218 + #218-driven lazy loading, the adapter files keep the same shape.

Compat

• Native-only consumers: no migration. Core gets smaller.
• External-player consumers: one extra <script> per page. Documented migration.
• API surface unchanged. HyperaudioLite constructor signature unchanged. No tests affected.
• Bump to 2.5.0 to flag the migration.

Related

• #217 — options-object constructor (will give a clean place to hook player-ready callbacks if/when we go async in phase 2)
• #218 — ESM/CJS distribution (precondition for phase 2)