@arraypress/waveform-player-astro 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+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).
+
+## [0.1.0] — Unreleased
+
+Initial release.
+
+### Added
+
+- `<WaveformPlayer>` Astro component wrapping every option exposed by
+  `@arraypress/waveform-player` 1.6.x as a typed prop:
+  - Audio source props (`url`, `audioMode`, `preload`)
+  - Waveform visualisation props (`waveformStyle`, `height`, `samples`,
+    `barWidth`, `barSpacing`, `waveform`)
+  - Colour props (`colorPreset`, `waveformColor`, `progressColor`,
+    `buttonColor`, `buttonHoverColor`, `textColor`,
+    `textSecondaryColor`, `backgroundColor`, `borderColor`)
+  - Playback control props (`playbackRate`, `showPlaybackSpeed`,
+    `playbackRates`)
+  - UI toggle props (`showControls`, `showInfo`, `showTime`,
+    `showHoverTime`, `showBPM`, `buttonAlign`)
+  - Marker props (`markers`, `showMarkers`)
+  - Content metadata props (`title`, `subtitle`, `artwork`, `album`)
+  - Behaviour flags (`autoplay`, `singlePlay`, `playOnSeek`,
+    `enableMediaSession`)
+  - Icon props (`playIcon`, `pauseIcon`)
+- Astro-specific `lazy` prop that switches the init attribute to
+  `data-waveform-player-lazy` and ships a single deduplicated
+  `IntersectionObserver` for grids of many previews.
+- Astro-specific `id`, `class`, and `style` pass-throughs.
+- Public TypeScript types: `WaveformPlayerProps`, `WaveformStyle`,
+  `WaveformMarker`, `WaveformPeaks`, `ColorPreset`, `AudioMode`,
+  `AudioPreload`, `ButtonAlign`.
+- Ambient declaration for `window.WaveformPlayer` to type consumer
+  scripts that reach for the global.
+- Vitest suite (29 tests) covering attribute mapping, omission
+  semantics, JSON serialisation for array props, lazy-mount script
+  presence, and pass-through props.
+- Documentation: full prop reference, setup guide, seven usage
+  examples (`examples/basic.astro`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArrayPress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @arraypress/waveform-player-astro
+
+Astro component wrapper around [`@arraypress/waveform-player`](https://github.com/arraypress/waveform-player). Exposes every library option as a typed prop, handles `data-*` attribute serialisation for you, and ships an optional lazy-mount `IntersectionObserver` for grids of many previews.
+
+The core library stays a zero-dependency vanilla-JS package that works anywhere a `<script>` tag does (WordPress, Shopify, raw HTML). This package adds the framework-native ergonomics Astro users expect — without touching the runtime.
+
+```astro
+---
+import WaveformPlayer from '@arraypress/waveform-player-astro';
+import '@arraypress/waveform-player/dist/waveform-player.css';
+import wfpJsUrl from '@arraypress/waveform-player/dist/waveform-player.min.js?url';
+---
+<script src={wfpJsUrl} is:inline></script>
+
+<WaveformPlayer
+  url="/audio/track.mp3"
+  title="My Track"
+  waveformStyle="bars"
+  showBPM
+/>
+```
+
+## Installation
+
+```bash
+npm install @arraypress/waveform-player-astro @arraypress/waveform-player
+```
+
+`@arraypress/waveform-player` is a peer dependency — you bring it explicitly so you control the version.
+
+## Setup
+
+The wrapper does **not** load the core library's JS or CSS for you. This is deliberate: you might want a CDN, a self-hosted asset, or the bundled npm path. Load both once in your root layout:
+
+```astro
+---
+// src/layouts/Layout.astro
+import '@arraypress/waveform-player/dist/waveform-player.css';
+import wfpJsUrl from '@arraypress/waveform-player/dist/waveform-player.min.js?url';
+---
+<html>
+  <head>
+    <script src={wfpJsUrl} is:inline></script>
+  </head>
+  <body><slot /></body>
+</html>
+```
+
+Then `<WaveformPlayer>` works on any page.
+
+## Usage
+
+### Minimal
+
+```astro
+<WaveformPlayer url="/audio/track.mp3" />
+```
+
+### With metadata + a chosen style
+
+```astro
+<WaveformPlayer
+  url="/audio/track.mp3"
+  title="Midnight Dreams"
+  subtitle="The Wavelength"
+  artwork="/img/cover.jpg"
+  waveformStyle="bars"
+  barWidth={3}
+  barSpacing={1}
+  height={80}
+/>
+```
+
+### Pre-computed peaks (recommended for catalogues)
+
+```astro
+<WaveformPlayer
+  url="/audio/track.mp3"
+  waveform="/peaks/track.json"
+/>
+```
+
+Generate the JSON at build time with [`@arraypress/waveform-gen`](https://github.com/arraypress/waveform-gen). Removes a full Web Audio decode from the runtime render path.
+
+### Chapter markers
+
+```astro
+<WaveformPlayer
+  url="/audio/podcast.mp3"
+  markers={[
+    { time: 0,   label: 'Intro' },
+    { time: 60,  label: 'Main topic', color: '#a855f7' },
+    { time: 600, label: 'Q&A' },
+  ]}
+/>
+```
+
+### Lazy mounting (large grids)
+
+Pass `lazy` and the wrapper switches the init attribute to `data-waveform-player-lazy`, then installs a single shared `IntersectionObserver` that promotes each mount when it crosses the viewport (with 200 px of buffer so audio is decoded before the user actually sees the player).
+
+```astro
+{previews.map((p) => (
+  <WaveformPlayer url={p.url} title={p.title} lazy />
+))}
+```
+
+The observer is installed at most once per page (`window.__wfpLazyMountBound` flag), and re-fires on Astro's `astro:page-load` event so cross-page navigations pick up new mounts.
+
+### External audio mode
+
+For setups where one audio element (e.g. [`@arraypress/waveform-bar`](https://github.com/arraypress/waveform-bar)) drives many visual surfaces:
+
+```astro
+<WaveformPlayer
+  url={track.url}
+  audioMode="external"
+  waveformStyle="seekbar"
+  showInfo={false}
+/>
+```
+
+The player dispatches `waveformplayer:request-play | request-pause | request-seek` custom events instead of touching audio itself. Drive the visualisation from your controller via the player instance's `setProgress(currentTime, duration)` and `setPlayingState(playing)` methods.
+
+## Props
+
+Every prop maps 1:1 to an option on the core library. Omitting a prop emits no `data-*` attribute and lets the library apply its own default.
+
+### Audio source
+
+| Prop        | Type                                  | Default      | Description |
+| ----------- | ------------------------------------- | ------------ | ----------- |
+| `url`       | `string` *(required)*                 | —            | Audio file URL. |
+| `audioMode` | `'self' \| 'external'`                | `'self'`     | `'external'` renders waveform only and emits request events. |
+| `preload`   | `'auto' \| 'metadata' \| 'none'`      | `'metadata'` | Browser preload hint. |
+
+### Waveform visualisation
+
+| Prop            | Type                                                          | Default    | Description |
+| --------------- | ------------------------------------------------------------- | ---------- | ----------- |
+| `waveformStyle` | `'bars' \| 'mirror' \| 'line' \| 'blocks' \| 'dots' \| 'seekbar'` | `'mirror'` | Visual style. |
+| `height`        | `number`                                                      | `60`       | Canvas height in pixels. |
+| `samples`       | `number`                                                      | `200`      | Number of waveform peaks to render. |
+| `barWidth`      | `number`                                                      | style-dependent | Width of each bar/block. |
+| `barSpacing`    | `number`                                                      | style-dependent | Gap between bars. |
+| `waveform`      | `number[] \| string`                                          | —          | Pre-computed peaks (array, JSON URL, or inline JSON). |
+
+### Colours
+
+All optional. `colorPreset` controls the auto theme, and any individual colour wins over the preset.
+
+| Prop                  | Type                            | Description |
+| --------------------- | ------------------------------- | ----------- |
+| `colorPreset`         | `'dark' \| 'light' \| null`     | `null` (default) auto-detects. |
+| `waveformColor`       | `string`                        | Unplayed peak colour. |
+| `progressColor`       | `string`                        | Played-through peak colour. |
+| `buttonColor`         | `string`                        | Play-button colour. |
+| `buttonHoverColor`    | `string`                        | Play-button hover colour. |
+| `textColor`           | `string`                        | Primary text colour. |
+| `textSecondaryColor`  | `string`                        | Secondary text colour. |
+| `backgroundColor`     | `string`                        | Reserved. |
+| `borderColor`         | `string`                        | Reserved. |
+
+### Playback controls
+
+| Prop                | Type        | Default                              | Description |
+| ------------------- | ----------- | ------------------------------------ | ----------- |
+| `playbackRate`      | `number`    | `1`                                  | Initial speed. |
+| `showPlaybackSpeed` | `boolean`   | `false`                              | Show the speed menu. |
+| `playbackRates`     | `number[]`  | `[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Speeds offered in the menu. |
+
+### UI toggles
+
+| Prop            | Type                                       | Default  | Description |
+| --------------- | ------------------------------------------ | -------- | ----------- |
+| `showControls`  | `boolean`                                  | `true`   | Show the play/pause button. |
+| `showInfo`      | `boolean`                                  | `true`   | Show the info bar (title, time, etc.). |
+| `showTime`      | `boolean`                                  | `true`   | Show current / total time. |
+| `showHoverTime` | `boolean`                                  | `false`  | Reserved. |
+| `showBPM`       | `boolean`                                  | `false`  | Detect and display BPM. |
+| `buttonAlign`   | `'auto' \| 'top' \| 'center' \| 'bottom'`  | `'auto'` | Play-button vertical alignment. |
+
+### Markers
+
+| Prop          | Type                                                              | Default | Description |
+| ------------- | ----------------------------------------------------------------- | ------- | ----------- |
+| `markers`     | `Array<{ time: number; label: string; color?: string }>`          | —       | Clickable seek-point markers. |
+| `showMarkers` | `boolean`                                                         | `true`  | Render markers (false to hide without losing data). |
+
+### Content metadata
+
+| Prop       | Type     | Description |
+| ---------- | -------- | ----------- |
+| `title`    | `string` | Track title (defaults to a prettified filename). |
+| `subtitle` | `string` | Subtitle / artist. |
+| `artwork`  | `string` | Thumbnail image URL. |
+| `album`    | `string` | Album name (Media Session API). |
+
+### Behaviour
+
+| Prop                 | Type      | Default | Description |
+| -------------------- | --------- | ------- | ----------- |
+| `autoplay`           | `boolean` | `false` | Start as soon as metadata loads. |
+| `singlePlay`         | `boolean` | `true`  | Pause other players on the page when this one starts. |
+| `playOnSeek`         | `boolean` | `true`  | Resume on seek if paused. |
+| `enableMediaSession` | `boolean` | `true`  | Wire up the Media Session API. |
+
+### Icons
+
+| Prop        | Type     | Description |
+| ----------- | -------- | ----------- |
+| `playIcon`  | `string` | Inline HTML / SVG for the play button (injected raw — trust your source). |
+| `pauseIcon` | `string` | Inline HTML / SVG for the pause button. |
+
+### Astro-specific
+
+| Prop    | Type      | Default | Description |
+| ------- | --------- | ------- | ----------- |
+| `lazy`  | `boolean` | `false` | Defer mount until viewport entry. |
+| `id`    | `string`  | —       | Forwarded to the container element. |
+| `class` | `string`  | —       | Appended to the container's classes (`wfp-host` is always present). |
+| `style` | `string`  | —       | Inline style on the container. |
+
+## TypeScript
+
+Importing the types directly:
+
+```ts
+import type {
+  WaveformPlayerProps,
+  WaveformStyle,
+  WaveformMarker,
+  WaveformPeaks,
+  ColorPreset,
+  AudioMode,
+  AudioPreload,
+  ButtonAlign,
+} from '@arraypress/waveform-player-astro';
+```
+
+The package also ships an ambient declaration for `window.WaveformPlayer` so consumers reaching for it from their own scripts get autocomplete.
+
+## Testing
+
+```bash
+npm test          # one-shot
+npm run test:watch
+npm run typecheck
+```
+
+Tests use Astro's official `experimental_AstroContainer` API to render the component to a string and assert on the resulting HTML. No browser required.
+
+## License
+
+MIT © ArrayPress

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@arraypress/waveform-player-astro",
+  "version": "0.1.0",
+  "description": "Astro component wrapper for @arraypress/waveform-player — typed props for every option, lazy-mount support, framework-idiomatic ergonomics.",
+  "type": "module",
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./WaveformPlayer.astro": "./src/WaveformPlayer.astro",
+    "./types": {
+      "types": "./src/types.ts",
+      "default": "./src/types.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "astro",
+    "astro-component",
+    "audio",
+    "player",
+    "waveform",
+    "visualization",
+    "music",
+    "sound",
+    "html5",
+    "web-audio",
+    "media-session",
+    "audio-player",
+    "waveform-visualization",
+    "podcast-player",
+    "audio-visualization",
+    "bpm-detection",
+    "withastro"
+  ],
+  "author": "ArrayPress",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arraypress/waveform-player-astro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/arraypress/waveform-player-astro/issues"
+  },
+  "homepage": "https://waveformplayer.com",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/arraypress"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@arraypress/waveform-player": "^1.6.0",
+    "astro": "^6.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@arraypress/waveform-player": "^1.6.0",
+    "astro": "^6.3.7",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  }
+}

package/src/WaveformPlayer.astro

@@ -0,0 +1,337 @@
+---
+/**
+ * WaveformPlayer.astro
+ * --------------------
+ *
+ * Astro component wrapper around `@arraypress/waveform-player`. Exposes
+ * every library option as a typed prop and emits the equivalent
+ * `data-*` attribute on the mount container. The library's own
+ * auto-initialiser (registered globally when its script loads) picks up
+ * the container and renders the player into it.
+ *
+ * ## Why a wrapper?
+ *
+ * The core library is intentionally framework-agnostic vanilla JS. That
+ * works great everywhere (WordPress, Shopify, plain HTML) but means
+ * Astro users have to hand-stringify every option as a `data-*`
+ * attribute:
+ *
+ * ```astro
+ * <div data-waveform-player
+ *      data-url={url}
+ *      data-waveform-style={style}
+ *      data-bar-width={String(2)}
+ *      data-markers={JSON.stringify(markers)}
+ *      data-show-bpm="true">
+ * </div>
+ * ```
+ *
+ * This wrapper turns that into:
+ *
+ * ```astro
+ * <WaveformPlayer
+ *   url={url}
+ *   waveformStyle={style}
+ *   barWidth={2}
+ *   markers={markers}
+ *   showBPM
+ * />
+ * ```
+ *
+ * Typed props, correct stringification, omission semantics that let the
+ * library's defaults shine through.
+ *
+ * ## Setup
+ *
+ * Load the core library's JS + CSS once in your layout (the wrapper
+ * intentionally does NOT do this for you — you may want a CDN, a
+ * self-hosted asset, or the bundled npm path):
+ *
+ * ```astro
+ * ---
+ * import '@arraypress/waveform-player/dist/waveform-player.css';
+ * import wfpJsUrl from '@arraypress/waveform-player/dist/waveform-player.min.js?url';
+ * ---
+ * <script src={wfpJsUrl} is:inline></script>
+ * ```
+ *
+ * Then drop `<WaveformPlayer>` anywhere.
+ *
+ * ## Lazy mounting
+ *
+ * Passing `lazy` switches the init attribute from `data-waveform-player`
+ * to `data-waveform-player-lazy` and ships a one-time
+ * `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.
+ *
+ * @example Basic
+ *   <WaveformPlayer url="/audio/track.mp3" title="My Track" />
+ *
+ * @example Pre-computed peaks (recommended for catalogues)
+ *   <WaveformPlayer
+ *     url="/audio/track.mp3"
+ *     waveform="/peaks/track.json"
+ *     waveformStyle="bars"
+ *     barWidth={3}
+ *     showBPM
+ *   />
+ *
+ * @example External mode (paired with `@arraypress/waveform-bar`)
+ *   <WaveformPlayer
+ *     url={track.url}
+ *     audioMode="external"
+ *     showInfo={false}
+ *     waveformStyle="seekbar"
+ *   />
+ *
+ * @example Lazy-mount grid item
+ *   <WaveformPlayer url={preview.url} lazy />
+ */
+
+import type { WaveformPlayerProps } from './types';
+
+const {
+	// Audio
+	url,
+	audioMode,
+	preload,
+	// Waveform visualisation
+	waveformStyle,
+	height,
+	samples,
+	barWidth,
+	barSpacing,
+	waveform,
+	// Colours
+	colorPreset,
+	waveformColor,
+	progressColor,
+	buttonColor,
+	buttonHoverColor,
+	textColor,
+	textSecondaryColor,
+	backgroundColor,
+	borderColor,
+	// Playback controls
+	playbackRate,
+	showPlaybackSpeed,
+	playbackRates,
+	// UI toggles
+	showControls,
+	showInfo,
+	showTime,
+	showHoverTime,
+	showBPM,
+	buttonAlign,
+	// Markers
+	markers,
+	showMarkers,
+	// Metadata
+	title,
+	subtitle,
+	artwork,
+	album,
+	// Behaviour
+	autoplay,
+	singlePlay,
+	playOnSeek,
+	enableMediaSession,
+	// Icons
+	playIcon,
+	pauseIcon,
+	// Astro extras
+	lazy = false,
+	id,
+	class: className,
+	style,
+} = Astro.props as WaveformPlayerProps;
+
+/**
+ * Build the data-attribute map programmatically so an omitted prop
+ * never emits an attribute. This is the contract that lets the library
+ * apply its own defaults when a prop is left out, and keeps the
+ * resulting DOM tidy.
+ *
+ * @type {Record<string, string>}
+ */
+const data: Record<string, string> = {};
+
+/**
+ * Helper — set a string attr only when the value is non-null/non-undefined.
+ * Empty strings are preserved (the library treats them as "set but blank").
+ */
+const setStr = (key: string, value: string | undefined | null): void => {
+	if (value === undefined || value === null) return;
+	data[key] = value;
+};
+
+/**
+ * Helper — set a numeric attr only when the value is a finite number.
+ */
+const setNum = (key: string, value: number | undefined | null): void => {
+	if (value === undefined || value === null) return;
+	if (typeof value !== 'number' || !Number.isFinite(value)) return;
+	data[key] = String(value);
+};
+
+/**
+ * Helper — set a boolean attr as the string `'true'` / `'false'`.
+ * Required because the library compares against `=== 'true'`.
+ */
+const setBool = (key: string, value: boolean | undefined | null): void => {
+	if (value === undefined || value === null) return;
+	data[key] = value ? 'true' : 'false';
+};
+
+// ─── Audio source ────────────────────────────────────────────────────────
+setStr('data-url', url);
+setStr('data-audio-mode', audioMode ?? null);
+setStr('data-preload', preload ?? null);
+
+// ─── Waveform visualisation ──────────────────────────────────────────────
+setStr('data-waveform-style', waveformStyle ?? null);
+setNum('data-height', height);
+setNum('data-samples', samples);
+setNum('data-bar-width', barWidth);
+setNum('data-bar-spacing', barSpacing);
+
+// `waveform` accepts an array (JSON-stringify it) or a string (URL/inline
+// JSON — pass through). The library handles both forms.
+if (Array.isArray(waveform)) {
+	data['data-waveform'] = JSON.stringify(waveform);
+} else if (typeof waveform === 'string') {
+	data['data-waveform'] = waveform;
+}
+
+// ─── Colours ─────────────────────────────────────────────────────────────
+// `colorPreset` is `'dark' | 'light' | null` — only emit when non-null.
+if (colorPreset === 'dark' || colorPreset === 'light') {
+	data['data-color-preset'] = colorPreset;
+}
+setStr('data-waveform-color', waveformColor ?? null);
+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);
+setStr('data-text-secondary-color', textSecondaryColor ?? null);
+setStr('data-background-color', backgroundColor ?? null);
+setStr('data-border-color', borderColor ?? null);
+
+// ─── Playback controls ───────────────────────────────────────────────────
+setNum('data-playback-rate', playbackRate);
+setBool('data-show-playback-speed', showPlaybackSpeed);
+if (Array.isArray(playbackRates) && playbackRates.length > 0) {
+	data['data-playback-rates'] = JSON.stringify(playbackRates);
+}
+
+// ─── UI toggles ──────────────────────────────────────────────────────────
+setBool('data-show-controls', showControls);
+setBool('data-show-info', showInfo);
+setBool('data-show-time', showTime);
+setBool('data-show-hover-time', showHoverTime);
+// The library's data-attribute parser reads `data-show-bpm` (lowercased
+// `bpm`), NOT `data-show-b-p-m`. Get this wrong and BPM never displays.
+setBool('data-show-bpm', showBPM);
+setStr('data-button-align', buttonAlign ?? null);
+
+// ─── Markers ─────────────────────────────────────────────────────────────
+if (Array.isArray(markers) && markers.length > 0) {
+	data['data-markers'] = JSON.stringify(markers);
+}
+setBool('data-show-markers', showMarkers);
+
+// ─── Metadata ────────────────────────────────────────────────────────────
+setStr('data-title', title ?? null);
+setStr('data-subtitle', subtitle ?? null);
+setStr('data-artwork', artwork ?? null);
+setStr('data-album', album ?? null);
+
+// ─── Behaviour ───────────────────────────────────────────────────────────
+setBool('data-autoplay', autoplay);
+setBool('data-single-play', singlePlay);
+setBool('data-play-on-seek', playOnSeek);
+setBool('data-enable-media-session', enableMediaSession);
+
+// ─── Icons ───────────────────────────────────────────────────────────────
+// Pass icon markup verbatim. Consumers are responsible for ensuring
+// the HTML they hand us is safe to inject.
+setStr('data-play-icon', playIcon ?? null);
+setStr('data-pause-icon', pauseIcon ?? null);
+
+/**
+ * The init attribute — the library auto-init scans for
+ * `[data-waveform-player]`. For lazy mounting we emit
+ * `[data-waveform-player-lazy]` instead and let our companion script
+ * promote it on viewport entry.
+ */
+const initAttr = lazy ? 'data-waveform-player-lazy' : 'data-waveform-player';
+---
+
+<div
+	{...{ [initAttr]: '' }}
+	{...data}
+	id={id}
+	class:list={['wfp-host', className]}
+	style={style}
+></div>
+
+{lazy && (
+	<script is:inline>
+		/**
+		 * Lazy-mount watcher for `<WaveformPlayer lazy>` instances.
+		 *
+		 * Installs a single `IntersectionObserver` (deduplicated via a
+		 * `window` flag) that promotes `data-waveform-player-lazy` to
+		 * `data-waveform-player` once an element approaches the viewport,
+		 * then triggers `WaveformPlayer.init()` to mount it.
+		 *
+		 * The 200 px `rootMargin` gives the browser headroom to fetch and
+		 * decode the audio so the player is ready by the time the user
+		 * scrolls it into actual view — eliminates the "Unable to load
+		 * audio" stutter you get when 15+ players try to decode at once
+		 * on page load.
+		 *
+		 * Re-runs on Astro `astro:page-load` so cross-page navigations
+		 * pick up newly-rendered lazy mounts.
+		 */
+		(function () {
+			if (window.__wfpLazyMountBound) return;
+			window.__wfpLazyMountBound = true;
+
+			function mountLazy() {
+				if (!window.WaveformPlayer) return;
+				const targets = document.querySelectorAll('[data-waveform-player-lazy]');
+				if (!targets.length) return;
+
+				const io = new IntersectionObserver(
+					(entries) => {
+						entries.forEach((entry) => {
+							if (!entry.isIntersecting) return;
+							const el = entry.target;
+							el.removeAttribute('data-waveform-player-lazy');
+							el.setAttribute('data-waveform-player', '');
+							io.unobserve(el);
+							try {
+								window.WaveformPlayer.init();
+							} catch (err) {
+								console.error('[waveform-player-astro] init failed:', err);
+							}
+						});
+					},
+					{ rootMargin: '200px 0px 200px 0px', threshold: 0.01 }
+				);
+
+				targets.forEach((target) => io.observe(target));
+			}
+
+			document.addEventListener('astro:page-load', mountLazy);
+			if (document.readyState !== 'loading') {
+				mountLazy();
+			} else {
+				document.addEventListener('DOMContentLoaded', mountLazy);
+			}
+		})();
+	</script>
+)}

package/src/astro-shim.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module astro-shim
+ * @description
+ * Ambient declaration for `*.astro` modules so plain `tsc --noEmit`
+ * can typecheck `index.ts` and the test suite without choking on
+ * `.astro` extensions.
+ *
+ * At runtime, Astro's Vite plugin resolves these imports to real
+ * component factories. For type-check-only contexts (like our
+ * `typecheck` npm script) we model them as opaque components that
+ * accept any props.
+ *
+ * In a consumer's Astro project, this shim is harmless — Astro's own
+ * `astro/client` types win because they're loaded via the project's
+ * `tsconfig` extends chain.
+ */
+declare module '*.astro' {
+	const component: (_props: Record<string, unknown>) => unknown;
+	export default component;
+}

package/src/globals.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module globals
+ * @description
+ * Ambient declarations for the globals the core `@arraypress/waveform-player`
+ * library installs on `window` when its IIFE script runs.
+ *
+ * Consumers don't need to import this file — TypeScript picks it up
+ * automatically via the package's exported types. The shim lets you do
+ * things like:
+ *
+ * ```ts
+ * window.WaveformPlayer?.init();
+ * const player = window.WaveformPlayer?.getInstance('my-player-id');
+ * ```
+ *
+ * without TypeScript complaining about `window.WaveformPlayer` being
+ * `any` / undefined.
+ *
+ * The shape is intentionally minimal — just the static surface a typical
+ * consumer touches. The full instance API lives in the core library's
+ * own types (when those ship) or via `// @ts-expect-error` for now.
+ */
+
+/**
+ * Static / global surface of `window.WaveformPlayer`.
+ *
+ * The core library exposes its class constructor directly on `window`;
+ * static helpers like `init()`, `getInstance()`, `getAllInstances()`,
+ * and `destroyAll()` hang off the same object.
+ */
+interface WaveformPlayerGlobal {
+	/**
+	 * Manually scan the document for any `[data-waveform-player]`
+	 * elements and mount players into them. Called automatically on
+	 * `DOMContentLoaded`; call again after dynamically inserting
+	 * markup.
+	 */
+	init(): void;
+
+	/**
+	 * Retrieve a player instance by element id, DOM element, or
+	 * internally-generated player id.
+	 */
+	getInstance(idOrElement: string | HTMLElement): unknown | undefined;
+
+	/** Return every active player instance. */
+	getAllInstances(): unknown[];
+
+	/** Destroy every active player instance on the page. */
+	destroyAll(): void;
+
+	/**
+	 * Pre-compute peaks from an audio URL using the Web Audio API.
+	 * Useful for ad-hoc generation when you don't have a build-time
+	 * pipeline.
+	 */
+	generateWaveformData(url: string, samples?: number): Promise<number[]>;
+
+	/** Allow `new WaveformPlayer(...)` from user code. */
+	new (container: string | HTMLElement, options?: Record<string, unknown>): unknown;
+}
+
+declare global {
+	interface Window {
+		/**
+		 * Installed by `@arraypress/waveform-player`'s IIFE script.
+		 * `undefined` until that script loads.
+		 */
+		WaveformPlayer?: WaveformPlayerGlobal;
+
+		/**
+		 * Internal — set by `<WaveformPlayer lazy>`'s inline mount
+		 * script to deduplicate the `IntersectionObserver`. Do not
+		 * rely on this; it is an implementation detail.
+		 *
+		 * @internal
+		 */
+		__wfpLazyMountBound?: boolean;
+	}
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @module @arraypress/waveform-player-astro
+ * @description
+ * Public entry point for the Astro wrapper around
+ * `@arraypress/waveform-player`.
+ *
+ * ## Importing the component
+ *
+ * ```astro
+ * ---
+ * import WaveformPlayer from '@arraypress/waveform-player-astro';
+ * // or, if you prefer the explicit path:
+ * import WaveformPlayer from '@arraypress/waveform-player-astro/WaveformPlayer.astro';
+ * ---
+ * <WaveformPlayer url="/audio/track.mp3" />
+ * ```
+ *
+ * ## Importing the types
+ *
+ * ```ts
+ * import type {
+ *   WaveformPlayerProps,
+ *   WaveformStyle,
+ *   WaveformMarker,
+ * } from '@arraypress/waveform-player-astro';
+ * ```
+ *
+ * @see {@link ./WaveformPlayer.astro} for the component implementation
+ * @see {@link ./types.ts}              for the full prop interface
+ */
+
+import WaveformPlayer from './WaveformPlayer.astro';
+
+export { WaveformPlayer };
+export default WaveformPlayer;
+
+export type {
+	WaveformPlayerProps,
+	WaveformStyle,
+	WaveformMarker,
+	WaveformPeaks,
+	ColorPreset,
+	AudioMode,
+	AudioPreload,
+	ButtonAlign,
+} from './types';

package/src/types.ts

@@ -0,0 +1,442 @@
+/**
+ * @module types
+ * @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.
+ *
+ * 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.
+ *
+ * @see {@link https://github.com/arraypress/waveform-player} — core library
+ */
+
+/**
+ * Visual style of the waveform rendering.
+ *
+ * - `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`.
+ */
+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';
+
+/**
+ * Browser preload hint passed through to the underlying `<audio>` element.
+ *
+ * - `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.
+ *
+ * `auto` picks `bottom` for the `bars` style and `center` for everything
+ * else.
+ */
+export type ButtonAlign = 'auto' | 'top' | 'center' | 'bottom';
+
+/**
+ * A clickable chapter marker rendered on top of the waveform.
+ *
+ * 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.
+ *
+ * - `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)
+ *
+ * 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.
+ */
+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 {
+	// ─────────────────────────────────────────────────────────────────────
+	// 1. Audio source
+	// ─────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Audio file URL. Required for the player 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;
+
+	// ─────────────────────────────────────────────────────────────────────
+	// 10. Astro-specific extras
+	// ─────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Defer initialisation until the player scrolls into view.
+	 *
+	 * When `true`, the component emits `data-waveform-player-lazy` and
+	 * the bundled `IntersectionObserver` script promotes it to
+	 * `data-waveform-player` once it crosses the viewport (with a 200px
+	 * buffer so audio is decoded ahead of time).
+	 *
+	 * Use this on grids of many previews to avoid spawning N concurrent
+	 * `fetch()` + `decodeAudioData` jobs on page load.
+	 *
+	 * @default false
+	 */
+	lazy?: boolean;
+
+	/**
+	 * DOM id forwarded to the player container. Useful for targeting
+	 * the player from external scripts via `WaveformPlayer.getInstance(id)`.
+	 */
+	id?: string;
+
+	/**
+	 * Extra class names appended to the container's `class` attribute.
+	 *
+	 * The base class `wfp-host` is always applied so the package's CSS
+	 * (or your own overrides) can target the wrapper.
+	 */
+	class?: string;
+
+	/**
+	 * Inline style passed through to the container. Useful for setting
+	 * `min-height` to reserve layout space before the waveform draws.
+	 */
+	style?: string;
+}