@arraypress/waveform-player-astro 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to `@arraypress/waveform-player-astro` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- Types are now sourced directly from the core
+  `@arraypress/waveform-player` package — a single source of truth. The
+  shared option types (`WaveformStyle`, `ColorPreset`, `AudioMode`,
+  `AudioPreload`, `ButtonAlign`, `WaveformMarker`, `WaveformPeaks`) are
+  re-exported from the core, and `WaveformPlayerProps` now `extends` the
+  core's `WaveformPlayerOptions` instead of re-declaring every option, so
+  the two packages can no longer drift. Every previously-exported type name
+  is preserved.
+- Bumped the `@arraypress/waveform-player` peer (and dev) dependency to
+  `^1.8.0`, which ships the hand-authored `index.d.ts` these types adopt.
+
+### Added
+
+- `accessibleSeek`, `seekLabel`, `barRadius`, and the gradient-array forms
+  of `waveformColor` / `progressColor` are now exposed on
+  `WaveformPlayerProps` (inherited from the core option surface), filling
+  gaps where the previous hand-maintained copy had missed or drifted.
+
 ## [0.1.2] — 2026-06-27
 
 ### Changed

package/README.md

@@ -13,13 +13,18 @@ import wfpJsUrl from '@arraypress/waveform-player/dist/waveform-player.min.js?ur
 <script src={wfpJsUrl} is:inline></script>
 
 <WaveformPlayer
-  url="/audio/track.mp3"
+  src="/audio/track.mp3"
   title="My Track"
   waveformStyle="bars"
   showBPM
 />
 ```
 
+> **Naming note.** `src` is shorthand for `url`. The visual style is `waveformStyle`
+> — **not** `style`, which (as in any Astro component) is the host element's inline
+> CSS. So `style={...}` styles the container; `waveformStyle="bars"` picks the
+> waveform look.
+
 ## Installation
 
 ```bash
@@ -130,7 +135,8 @@ Every prop maps 1:1 to an option on the core library. Omitting a prop emits no `
 
 | Prop        | Type                                  | Default      | Description |
 | ----------- | ------------------------------------- | ------------ | ----------- |
-| `url`       | `string` *(required)*                 | —            | Audio file URL. |
+| `url`       | `string`                              | —            | Audio file URL. Provide one of `url` or `src`. |
+| `src`       | `string`                              | —            | Shorthand alias for `url` (the core's `data-src`). `url` wins if both are set. |
 | `audioMode` | `'self' \| 'external'`                | `'self'`     | `'external'` renders waveform only and emits request events. |
 | `preload`   | `'auto' \| 'metadata' \| 'none'`      | `'metadata'` | Browser preload hint. |
 
@@ -180,6 +186,14 @@ All optional. `colorPreset` controls the auto theme, and any individual colour w
 | `showBPM`       | `boolean`                                  | `false`  | Detect and display BPM. |
 | `buttonAlign`   | `'auto' \| 'top' \| 'center' \| 'bottom'`  | `'auto'` | Play-button vertical alignment. |
 
+### Accessibility & error UI
+
+| Prop             | Type      | Default               | Description |
+| ---------------- | --------- | --------------------- | ----------- |
+| `accessibleSeek` | `boolean` | `true`                | Render the waveform as an ARIA slider (keyboard-seekable). |
+| `seekLabel`      | `string`  | —                     | Accessible name for the seek slider (falls back to the title). |
+| `errorText`      | `string`  | `'Unable to load audio'` | Message shown when audio fails to load. |
+
 ### Markers
 
 | Prop          | Type                                                              | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/waveform-player-astro",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Astro component wrapper for @arraypress/waveform-player — typed props for every option, lazy-mount support, framework-idiomatic ergonomics.",
   "type": "module",
   "files": [
@@ -62,7 +62,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
-    "@arraypress/waveform-player": "^1.7.2",
+    "@arraypress/waveform-player": "^1.8.0",
     "astro": "^6.0.0 || ^7.0.0"
   },
   "scripts": {
@@ -71,9 +71,9 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@arraypress/waveform-player": "^1.7.2",
-    "astro": "^6.3.7",
+    "@arraypress/waveform-player": "^1.8.0",
+    "astro": "^7.0.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.9"
   }
 }

package/src/WaveformPlayer.astro

@@ -64,7 +64,22 @@
  * `IntersectionObserver` script that promotes lazy mounts when they
  * approach the viewport. The script self-deduplicates via
  * `window.__wfpLazyMountBound` so multiple `<WaveformPlayer lazy>`
- * instances on the same page reuse a single observer.
+ * instances on the same page reuse a single observer. If the core
+ * library's script hasn't loaded yet, the lazy script waits for
+ * `window.WaveformPlayer` via a small bounded retry rather than silently
+ * never mounting.
+ *
+ * ## Astro View Transitions
+ *
+ * The core library auto-initialises on `DOMContentLoaded` only. Under
+ * Astro View Transitions, client-side navigations swap the DOM without
+ * re-firing `DOMContentLoaded`, so a freshly-rendered (non-lazy) player
+ * would never be mounted after navigation. To cover that, non-lazy
+ * instances ship a tiny one-time script that re-runs the core's
+ * (idempotent) `WaveformPlayer.init()` on every `astro:page-load`.
+ * It self-deduplicates via `window.__wfpInitBound`, and the core skips
+ * any container already flagged `data-waveform-initialized`, so the
+ * re-init is safe to call repeatedly.
  *
  * @example Basic
  *   <WaveformPlayer url="/audio/track.mp3" title="My Track" />
@@ -95,6 +110,7 @@ import type { WaveformPlayerProps } from './types';
 const {
 	// Audio
 	url,
+	src,
 	audioMode,
 	preload,
 	// Waveform visualisation
@@ -103,6 +119,7 @@ const {
 	samples,
 	barWidth,
 	barSpacing,
+	barRadius,
 	waveform,
 	// Colours
 	colorPreset,
@@ -125,6 +142,10 @@ const {
 	showHoverTime,
 	showBPM,
 	buttonAlign,
+	// Accessibility + error UI
+	accessibleSeek,
+	seekLabel,
+	errorText,
 	// Markers
 	markers,
 	showMarkers,
@@ -186,7 +207,9 @@ const setBool = (key: string, value: boolean | undefined | null): void => {
 };
 
 // ─── Audio source ────────────────────────────────────────────────────────
-setStr('data-url', url);
+// `src` is the core's shorthand alias for `url`; emit a single canonical
+// `data-url` from whichever was provided (`url` wins if both are set).
+setStr('data-url', url ?? src ?? null);
 setStr('data-audio-mode', audioMode ?? null);
 setStr('data-preload', preload ?? null);
 
@@ -196,6 +219,7 @@ setNum('data-height', height);
 setNum('data-samples', samples);
 setNum('data-bar-width', barWidth);
 setNum('data-bar-spacing', barSpacing);
+setNum('data-bar-radius', barRadius);
 
 // `waveform` accepts an array (JSON-stringify it) or a string (URL/inline
 // JSON — pass through). The library handles both forms.
@@ -210,8 +234,12 @@ if (Array.isArray(waveform)) {
 if (colorPreset === 'dark' || colorPreset === 'light') {
 	data['data-color-preset'] = colorPreset;
 }
-setStr('data-waveform-color', waveformColor ?? null);
-setStr('data-progress-color', progressColor ?? null);
+// Colours accept an array of gradient stops — JSON-encode those so the
+// library's data-attribute parser can rebuild the gradient.
+if (Array.isArray(waveformColor)) data['data-waveform-color'] = JSON.stringify(waveformColor);
+else setStr('data-waveform-color', waveformColor ?? null);
+if (Array.isArray(progressColor)) data['data-progress-color'] = JSON.stringify(progressColor);
+else setStr('data-progress-color', progressColor ?? null);
 setStr('data-button-color', buttonColor ?? null);
 setStr('data-button-hover-color', buttonHoverColor ?? null);
 setStr('data-text-color', textColor ?? null);
@@ -236,6 +264,11 @@ setBool('data-show-hover-time', showHoverTime);
 setBool('data-show-bpm', showBPM);
 setStr('data-button-align', buttonAlign ?? null);
 
+// ─── Accessibility + error UI ────────────────────────────────────────────
+setBool('data-accessible-seek', accessibleSeek);
+setStr('data-seek-label', seekLabel ?? null);
+setStr('data-error-text', errorText ?? null);
+
 // ─── Markers ─────────────────────────────────────────────────────────────
 if (Array.isArray(markers) && markers.length > 0) {
 	data['data-markers'] = JSON.stringify(markers);
@@ -277,7 +310,7 @@ const initAttr = lazy ? 'data-waveform-player-lazy' : 'data-waveform-player';
 	style={style}
 ></div>
 
-{lazy && (
+{lazy ? (
 	<script is:inline>
 		/**
 		 * Lazy-mount watcher for `<WaveformPlayer lazy>` instances.
@@ -295,35 +328,70 @@ const initAttr = lazy ? 'data-waveform-player-lazy' : 'data-waveform-player';
 		 *
 		 * Re-runs on Astro `astro:page-load` so cross-page navigations
 		 * pick up newly-rendered lazy mounts.
+		 *
+		 * If the core library's script hasn't installed `window.WaveformPlayer`
+		 * yet (e.g. on a plain page where this inline script runs before the
+		 * library's `<script>`), we wait for it via a small bounded retry
+		 * instead of returning and never mounting.
 		 */
 		(function () {
 			if (window.__wfpLazyMountBound) return;
 			window.__wfpLazyMountBound = true;
 
-			function mountLazy() {
-				if (!window.WaveformPlayer) return;
-				const targets = document.querySelectorAll('[data-waveform-player-lazy]');
+			var MAX_WAIT_ATTEMPTS = 20; // ~1s total at 50ms between attempts
+
+			function observeLazyMounts() {
+				var targets = document.querySelectorAll('[data-waveform-player-lazy]');
 				if (!targets.length) return;
 
-				const io = new IntersectionObserver(
-					(entries) => {
-						entries.forEach((entry) => {
+				var io = new IntersectionObserver(
+					function (entries) {
+						entries.forEach(function (entry) {
 							if (!entry.isIntersecting) return;
-							const el = entry.target;
+							var el = entry.target;
 							el.removeAttribute('data-waveform-player-lazy');
 							el.setAttribute('data-waveform-player', '');
 							io.unobserve(el);
 							try {
-								window.WaveformPlayer.init();
+								window.WaveformPlayer && window.WaveformPlayer.init();
 							} catch (err) {
-								console.error('[waveform-player-astro] init failed:', err);
+								console.error('[WaveformPlayerAstro] init failed:', err);
 							}
 						});
 					},
 					{ rootMargin: '200px 0px 200px 0px', threshold: 0.01 }
 				);
 
-				targets.forEach((target) => io.observe(target));
+				targets.forEach(function (target) {
+					io.observe(target);
+				});
+			}
+
+			function mountLazy() {
+				// Core already present — wire up the observer immediately.
+				if (window.WaveformPlayer) {
+					observeLazyMounts();
+					return;
+				}
+				// Core script not loaded yet. Poll a bounded number of times
+				// for `window.WaveformPlayer` rather than silently giving up.
+				var attempts = 0;
+				(function waitForCore() {
+					if (window.WaveformPlayer) {
+						observeLazyMounts();
+						return;
+					}
+					if (++attempts > MAX_WAIT_ATTEMPTS) {
+						console.warn(
+							'[WaveformPlayerAstro] window.WaveformPlayer not found after ' +
+								MAX_WAIT_ATTEMPTS +
+								' attempts; lazy players will not mount. Did you load ' +
+								"@arraypress/waveform-player's script?"
+						);
+						return;
+					}
+					setTimeout(waitForCore, 50);
+				})();
 			}
 
 			document.addEventListener('astro:page-load', mountLazy);
@@ -334,4 +402,36 @@ const initAttr = lazy ? 'data-waveform-player-lazy' : 'data-waveform-player';
 			}
 		})();
 	</script>
+) : (
+	<script is:inline>
+		/**
+		 * View Transitions re-init for non-lazy `<WaveformPlayer>` instances.
+		 *
+		 * The core library auto-initialises on `DOMContentLoaded` only.
+		 * Under Astro View Transitions, client-side navigations swap the DOM
+		 * without re-firing `DOMContentLoaded`, so freshly-rendered
+		 * `[data-waveform-player]` containers would never be mounted after a
+		 * navigation. Re-run the core initialiser on every `astro:page-load`.
+		 *
+		 * `WaveformPlayer.init()` is idempotent — it skips any container
+		 * already flagged `data-waveform-initialized` (which the core sets on
+		 * first mount) — so calling it repeatedly only mounts the new ones.
+		 *
+		 * Deduplicated via `window.__wfpInitBound` so multiple non-lazy
+		 * instances bind a single shared `astro:page-load` listener that
+		 * persists across navigations.
+		 */
+		(function () {
+			if (window.__wfpInitBound) return;
+			window.__wfpInitBound = true;
+
+			document.addEventListener('astro:page-load', function () {
+				try {
+					window.WaveformPlayer && window.WaveformPlayer.init();
+				} catch (err) {
+					console.error('[WaveformPlayerAstro] init failed:', err);
+				}
+			});
+		})();
+	</script>
 )}

package/src/globals.d.ts

@@ -76,6 +76,17 @@ declare global {
 		 * @internal
 		 */
 		__wfpLazyMountBound?: boolean;
+
+		/**
+		 * Internal — set by the non-lazy `<WaveformPlayer>`'s inline
+		 * script to deduplicate the `astro:page-load` re-init listener
+		 * that re-runs `WaveformPlayer.init()` after View Transitions
+		 * navigations. Do not rely on this; it is an implementation
+		 * detail.
+		 *
+		 * @internal
+		 */
+		__wfpInitBound?: boolean;
 	}
 }
 

package/src/types.ts

@@ -3,406 +3,110 @@
  * @description
  * Public TypeScript types for `@arraypress/waveform-player-astro`.
  *
- * Every option exposed by the core `@arraypress/waveform-player` library is
- * surfaced here as a typed prop. The prop names match the library option
- * names 1:1 (camelCase) — the Astro component handles the conversion to the
- * library's `data-*` attribute contract (kebab-case) under the hood.
+ * The shared option surface — visual styles, colour presets, audio modes,
+ * markers, peaks, and the full per-option list — is owned by the core
+ * `@arraypress/waveform-player` library, which ships hand-authored type
+ * declarations (`index.d.ts`). This wrapper re-exports those shared types
+ * verbatim (so consumers can keep importing them from this package) and
+ * derives its component prop interface from the core's
+ * {@link WaveformPlayerOptions} rather than re-declaring it. That keeps the
+ * two packages from drifting: any option the core adds (or renames) flows
+ * through here automatically, and there is a single source of truth.
  *
- * Props are intentionally all optional (except `url`, which the library
- * requires to load audio). When a prop is omitted, the wrapper emits no
- * corresponding `data-*` attribute, letting the core library apply its
- * own internal defaults.
+ * The prop names match the library option names 1:1 (camelCase) — the
+ * Astro component handles the conversion to the library's `data-*`
+ * attribute contract (kebab-case) under the hood.
  *
- * @see {@link https://github.com/arraypress/waveform-player} — core library
- */
-
-/**
- * Visual style of the waveform rendering.
+ * Props are intentionally all optional (except `url`, which the wrapper
+ * requires so the player always has audio to load). When a prop is
+ * omitted, the wrapper emits no corresponding `data-*` attribute, letting
+ * the core library apply its own internal defaults.
  *
- * - `bars`    — classic vertical bars from the baseline up
- * - `mirror`  — symmetrical bars mirrored around the centre line
- * - `line`    — connected line graph
- * - `blocks`  — chunky square blocks
- * - `dots`    — dotted plot
- * - `seekbar` — minimal seek bar with no peak detail
- */
-export type WaveformStyle =
-	| 'bars'
-	| 'mirror'
-	| 'line'
-	| 'blocks'
-	| 'dots'
-	| 'seekbar';
-
-/**
- * Forced colour scheme. `null` (the default) auto-detects from the page
- * theme and `prefers-color-scheme`.
+ * @see {@link https://github.com/arraypress/waveform-player} — core library
  */
-export type ColorPreset = 'dark' | 'light' | null;
 
-/**
- * How the player handles audio.
- *
- * - `self`     — (default) the player owns an `<audio>` element and plays
- *   the URL itself. Use this for standalone players.
- * - `external` — the player renders the waveform visualisation only and
- *   dispatches `waveformplayer:request-play|pause|seek` events for an
- *   external controller (e.g. `@arraypress/waveform-bar`) to handle.
- *   Drive the visualisation from the controller by calling
- *   `setProgress()` and `setPlayingState()` on the player instance.
- */
-export type AudioMode = 'self' | 'external';
+import type { WaveformPlayerOptions } from '@arraypress/waveform-player';
 
 /**
- * Browser preload hint passed through to the underlying `<audio>` element.
+ * Shared option types, re-exported from the core library so consumers can
+ * continue to import them from `@arraypress/waveform-player-astro`:
  *
- * - `auto`     — fetch the entire file ahead of time
- * - `metadata` — (default) fetch only enough to determine duration
- * - `none`     — fetch nothing until play is requested
- */
-export type AudioPreload = 'auto' | 'metadata' | 'none';
-
-/**
- * Vertical alignment of the play button relative to the waveform.
+ * ```ts
+ * import type {
+ *   WaveformStyle,
+ *   WaveformMarker,
+ *   WaveformPeaks,
+ * } from '@arraypress/waveform-player-astro';
+ * ```
  *
- * `auto` picks `bottom` for the `bars` style and `center` for everything
- * else.
+ * The core's `index.d.ts` is the single source of truth for their shape —
+ * this wrapper no longer maintains parallel copies that can drift.
  */
-export type ButtonAlign = 'auto' | 'top' | 'center' | 'bottom';
+export type {
+	WaveformStyle,
+	ColorPreset,
+	AudioMode,
+	AudioPreload,
+	ButtonAlign,
+	WaveformMarker,
+	WaveformPeaks,
+} from '@arraypress/waveform-player';
 
 /**
- * A clickable chapter marker rendered on top of the waveform.
+ * Props accepted by the `<WaveformPlayer>` Astro component.
  *
- * Clicking a marker seeks the player to its `time`. Markers also display
- * their `label` as a tooltip on hover.
- */
-export interface WaveformMarker {
-	/** Time in seconds at which the marker appears. */
-	time: number;
-	/** Short label shown as a tooltip. */
-	label: string;
-	/** Optional override colour (CSS colour string). Falls back to the
-	 *  player's progress colour. */
-	color?: string;
-}
-
-/**
- * Pre-computed waveform peaks, OR a string pointer to them.
+ * Inherits every construction option from the core library's
+ * {@link WaveformPlayerOptions} (including `accessibleSeek`, `seekLabel`,
+ * `barRadius`, and the gradient-array forms of `waveformColor` /
+ * `progressColor`) and layers on the Astro-specific extras. Two groups of
+ * core options are deliberately removed:
  *
- * - `number[]`            — inline array of peak amplitudes (0..1)
- * - `string` (.json URL)  — JSON file URL the library will `fetch()`
- * - `string` (JSON array) — inline JSON string the library will parse
- * - `null` / omitted      — the library decodes the audio file with the
- *   Web Audio API at load time (slowest path)
+ *  - `url` — optional on the core options, but **required** here (the
+ *    wrapper exists to render a player, which needs a source). Redeclared
+ *    below as a required `string`.
+ *  - `style` — the core exposes `style` as a shorthand alias for
+ *    {@link WaveformStyle} (`data-style`), but in an Astro component `style`
+ *    is the HTML inline-style attribute. We remove the core's alias and
+ *    redeclare `style` below as the inline-CSS `string`; consumers select
+ *    the visual style via the canonical `waveformStyle` prop instead.
+ *  - the `on*` lifecycle callbacks (`onLoad`, `onPlay`, …) — these are JS
+ *    functions, and a server-rendered Astro component emits static HTML
+ *    plus `data-*` attributes with nothing to attach a runtime callback
+ *    to. Consumers wire lifecycle handling via the DOM
+ *    `waveformplayer:*` events instead.
  *
- * Pre-computing peaks with `@arraypress/waveform-gen` at build time is
- * strongly recommended for any catalogue of more than a handful of
- * tracks; it removes a full Web Audio decode from the render path.
+ * Because the option surface is inherited rather than hand-copied, anything
+ * the core adds in future is exposed here without a manual edit.
  */
-export type WaveformPeaks = number[] | string | null;
-
-/**
- * Props accepted by the `<WaveformPlayer>` Astro component.
- *
- * Grouped to mirror the README sections:
- *   1. Audio source
- *   2. Waveform visualisation
- *   3. Colours
- *   4. Playback controls
- *   5. UI toggles
- *   6. Markers
- *   7. Content metadata
- *   8. Behaviour flags
- *   9. Icons
- *  10. Astro-specific extras
- */
-export interface WaveformPlayerProps {
+export interface WaveformPlayerProps
+	extends Omit<
+		WaveformPlayerOptions,
+		| 'url'
+		| 'style'
+		| 'onLoad'
+		| 'onPlay'
+		| 'onPause'
+		| 'onEnd'
+		| 'onError'
+		| 'onTimeUpdate'
+	> {
 	// ─────────────────────────────────────────────────────────────────────
-	// 1. Audio source
+	// Audio source (Astro-required override)
 	// ─────────────────────────────────────────────────────────────────────
 
 	/**
-	 * Audio file URL. Required for the player to do anything useful.
+	 * Audio file URL. Provide one of `url` or its shorthand alias `src`
+	 * (inherited from the core options) — the player needs a source to do
+	 * anything useful.
 	 *
 	 * Supported formats are whatever the user's browser supports — MP3,
 	 * WAV, OGG, AAC, etc. CORS headers must allow cross-origin loads if
 	 * hosted on a different domain.
 	 */
-	url: string;
-
-	/**
-	 * Whether the player owns its `<audio>` element (`self`) or only
-	 * renders visualisation and emits request events (`external`).
-	 *
-	 * Use `external` together with `@arraypress/waveform-bar` for
-	 * persistent-bar setups where one audio element drives many visual
-	 * surfaces across the page.
-	 *
-	 * @default 'self'
-	 */
-	audioMode?: AudioMode;
-
-	/**
-	 * Browser preload hint for the underlying `<audio>` element.
-	 *
-	 * @default 'metadata'
-	 */
-	preload?: AudioPreload;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 2. Waveform visualisation
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Which waveform render style to use.
-	 *
-	 * @default 'mirror'
-	 */
-	waveformStyle?: WaveformStyle;
-
-	/**
-	 * Canvas height in pixels.
-	 *
-	 * @default 60
-	 */
-	height?: number;
-
-	/**
-	 * Number of peak samples to render across the waveform. Higher values
-	 * give finer detail at the cost of slightly higher CPU and a busier
-	 * visual. 100–300 is the sweet spot for most player widths.
-	 *
-	 * @default 200
-	 */
-	samples?: number;
-
-	/**
-	 * Width of each bar/block in pixels (where applicable). Defaults
-	 * depend on `waveformStyle` (e.g. `2` for `mirror`, `3` for `bars`).
-	 */
-	barWidth?: number;
-
-	/**
-	 * Gap between adjacent bars/blocks in pixels. Defaults depend on
-	 * `waveformStyle`.
-	 */
-	barSpacing?: number;
-
-	/**
-	 * Pre-computed peaks data. See {@link WaveformPeaks}.
-	 *
-	 * - `number[]` is JSON-stringified into the emitted attribute.
-	 * - `string` (URL or inline JSON) is emitted verbatim — the library
-	 *   parses it.
-	 */
-	waveform?: WaveformPeaks;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 3. Colours
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Forced colour preset. `null` auto-detects from the page theme.
-	 *
-	 * Individual `*Color` props always win over the preset, letting you
-	 * keep the auto-detection but tweak one or two colours.
-	 *
-	 * @default null
-	 */
-	colorPreset?: ColorPreset;
-
-	/** Colour of the unplayed waveform peaks (CSS colour string). */
-	waveformColor?: string;
-	/** Colour of the played-through portion of the waveform. */
-	progressColor?: string;
-	/** Border/text colour of the play button. */
-	buttonColor?: string;
-	/** Play button hover colour. */
-	buttonHoverColor?: string;
-	/** Primary text colour (title). */
-	textColor?: string;
-	/** Secondary text colour (subtitle, time). */
-	textSecondaryColor?: string;
-	/** Reserved for future use; currently no visible effect. */
-	backgroundColor?: string;
-	/** Reserved for future use; currently no visible effect. */
-	borderColor?: string;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 4. Playback controls
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Initial playback rate (1 = normal speed; 0.5..2 supported).
-	 *
-	 * @default 1
-	 */
-	playbackRate?: number;
-
-	/**
-	 * Whether to render the playback-speed control menu.
-	 *
-	 * @default false
-	 */
-	showPlaybackSpeed?: boolean;
-
-	/**
-	 * List of speeds to offer in the speed menu.
-	 *
-	 * @default [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
-	 */
-	playbackRates?: number[];
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 5. UI toggles
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Show the play/pause button.
-	 *
-	 * @default true
-	 */
-	showControls?: boolean;
-
-	/**
-	 * Show the info bar (title, subtitle, time, BPM, speed).
-	 *
-	 * @default true
-	 */
-	showInfo?: boolean;
-
-	/**
-	 * Show the current-time / total-time readout.
-	 *
-	 * @default true
-	 */
-	showTime?: boolean;
-
-	/**
-	 * Show a hover-time indicator on the waveform (reserved — not all
-	 * library versions implement this yet).
-	 *
-	 * @default false
-	 */
-	showHoverTime?: boolean;
-
-	/**
-	 * Detect and display the track's BPM in the info bar.
-	 *
-	 * Adds a ~50–200 ms onset-detection pass on first load.
-	 *
-	 * @default false
-	 */
-	showBPM?: boolean;
-
-	/**
-	 * Where to align the play button vertically relative to the waveform.
-	 *
-	 * @default 'auto'
-	 */
-	buttonAlign?: ButtonAlign;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 6. Markers
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Chapter markers to render on the waveform. Each becomes a clickable
-	 * seek point.
-	 *
-	 * Emitted as JSON-stringified `data-markers`. The library parses it.
-	 */
-	markers?: WaveformMarker[];
-
-	/**
-	 * Whether to render markers at all. Useful for hiding markers in
-	 * compact layouts while still passing them in for future use.
-	 *
-	 * @default true
-	 */
-	showMarkers?: boolean;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 7. Content metadata
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Track title shown in the info bar. Falls back to a prettified
-	 * filename extracted from the URL.
-	 */
-	title?: string;
-
-	/**
-	 * Subtitle shown under the title — typically the artist name.
-	 */
-	subtitle?: string;
-
-	/**
-	 * Album / collection cover image URL displayed as a thumbnail.
-	 */
-	artwork?: string;
-
-	/**
-	 * Album name. Passed through to the Media Session API for lockscreen
-	 * and OS-level media displays.
-	 */
-	album?: string;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 8. Behaviour flags
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Start playback as soon as audio metadata loads.
-	 *
-	 * Note that most browsers block autoplay with audible audio unless
-	 * the user has interacted with the page first.
-	 *
-	 * @default false
-	 */
-	autoplay?: boolean;
-
-	/**
-	 * Pause any other `WaveformPlayer` on the page when this one starts.
-	 *
-	 * @default true
-	 */
-	singlePlay?: boolean;
-
-	/**
-	 * Resume playback automatically when the user seeks on a paused
-	 * waveform.
-	 *
-	 * @default true
-	 */
-	playOnSeek?: boolean;
-
-	/**
-	 * Wire up the browser's Media Session API so OS media keys, lock
-	 * screens, and bluetooth controls drive the player.
-	 *
-	 * @default true
-	 */
-	enableMediaSession?: boolean;
-
-	// ─────────────────────────────────────────────────────────────────────
-	// 9. Icons
-	// ─────────────────────────────────────────────────────────────────────
-
-	/**
-	 * Inline HTML/SVG to use for the play button. Anything you pass is
-	 * injected raw — use trusted markup only.
-	 */
-	playIcon?: string;
-
-	/**
-	 * Inline HTML/SVG to use for the pause button. Anything you pass is
-	 * injected raw — use trusted markup only.
-	 */
-	pauseIcon?: string;
+	url?: string;
 
 	// ─────────────────────────────────────────────────────────────────────
-	// 10. Astro-specific extras
+	// Astro-specific extras
 	// ─────────────────────────────────────────────────────────────────────
 
 	/**