@arraypress/waveform-player 1.24.0 → 1.24.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -413,6 +413,13 @@ export declare class WaveformPlayer {
413
413
  * Lets wrappers inherit the complete option surface without drifting.
414
414
  */
415
415
  parseDataAttributes(element: HTMLElement): Partial<WaveformPlayerOptions>;
416
+ /**
417
+ * Detect whether the page around `element` reads as light or dark —
418
+ * explicit theme classes/attributes first, then the backdrop actually
419
+ * visible behind it (every ancestor background composited over the UA
420
+ * canvas). Pass the element the caller is theming; defaults to `<body>`.
421
+ */
422
+ detectColorScheme(element?: Element): 'dark' | 'light';
416
423
  };
417
424
  }
418
425
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.24.0",
3
+ "version": "1.24.2",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
@@ -39,6 +39,7 @@
39
39
  "serve": "npx http-server -p 8000",
40
40
  "test": "vitest run",
41
41
  "test:watch": "vitest",
42
+ "test:visual": "node test/visual/theme-matrix.mjs",
42
43
  "prepublishOnly": "npm run test && npm run build"
43
44
  },
44
45
  "keywords": [
package/src/js/core.js CHANGED
@@ -90,8 +90,10 @@ export class WaveformPlayer {
90
90
  // Merge options: defaults < data attributes < constructor options
91
91
  this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions);
92
92
 
93
- // Apply color preset (auto-detect if not specified)
94
- const preset = getColorPreset(this.options.colorPreset);
93
+ // Apply color preset (auto-detect if not specified). Detection reads
94
+ // the backdrop behind THIS container, so a player dropped into a themed
95
+ // card matches the card rather than the page.
96
+ const preset = getColorPreset(this.options.colorPreset, this.container);
95
97
 
96
98
  // Track auto-theme state so the player can re-detect on a runtime light/
97
99
  // dark switch. Only colours the user LEFT UNSET follow the preset; an
@@ -100,7 +102,7 @@ export class WaveformPlayer {
100
102
  this._presetKeys = [];
101
103
  // Resolved scheme name for the CSS theme class (CSS provides the DOM
102
104
  // chrome colours via --wfp-* variables).
103
- this._scheme = (this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset]) ? this.options.colorPreset : detectColorScheme();
105
+ this._scheme = (this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset]) ? this.options.colorPreset : detectColorScheme(this.container);
104
106
 
105
107
  // Apply preset colors only if individual colors aren't explicitly set
106
108
  for (const [key, value] of Object.entries(preset)) {
@@ -1989,8 +1991,8 @@ export class WaveformPlayer {
1989
1991
  */
1990
1992
  refreshTheme() {
1991
1993
  if (!this._autoTheme) return;
1992
- this._scheme = detectColorScheme();
1993
- const preset = getColorPreset(this.options.colorPreset);
1994
+ this._scheme = detectColorScheme(this.container);
1995
+ const preset = getColorPreset(this.options.colorPreset, this.container);
1994
1996
  for (const key of (this._presetKeys || [])) {
1995
1997
  if (key in preset) this.options[key] = preset[key];
1996
1998
  }
package/src/js/index.js CHANGED
@@ -13,14 +13,19 @@
13
13
  // Import the main class
14
14
  import {WaveformPlayer} from './core.js';
15
15
  import {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes} from './utils.js';
16
+ import {detectColorScheme} from './themes.js';
16
17
 
17
18
  // Expose a small set of pure helpers as a single source of truth so consumers
18
19
  // (e.g. @arraypress/waveform-bar, @arraypress/waveform-playlist) can reuse them
19
20
  // instead of shipping divergent copies. `parseDataAttributes` lets wrappers read
20
21
  // the player's full `data-*` option surface off a host element without
21
- // re-implementing (and drifting from) the contract. Attached to the class so
22
- // it's reachable from the IIFE global too.
23
- WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes};
22
+ // re-implementing (and drifting from) the contract. `detectColorScheme` is here
23
+ // for the same reason: the bar used to carry its own copy of the heuristic and
24
+ // the two drifted (both shipped the transparent-background bug of #21, fixed
25
+ // independently). Attached to the class so it's reachable from the IIFE global
26
+ // too — which is how the bar reaches it, since it depends on this package as a
27
+ // runtime peer rather than importing the module.
28
+ WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes, detectColorScheme};
24
29
 
25
30
  /**
26
31
  * Whether we're running in a browser (vs. SSR / Node), where `window` and
package/src/js/themes.js CHANGED
@@ -3,7 +3,14 @@
3
3
  * @description Color presets and default options for WaveformPlayer
4
4
  */
5
5
 
6
- import {perceivedBrightness, DEFAULT_SAMPLES} from './utils.js';
6
+ import {parseColor, perceivedBrightness, DEFAULT_SAMPLES} from './utils.js';
7
+
8
+ /**
9
+ * Brightness (0–255) above which a backdrop counts as light.
10
+ * @type {number}
11
+ * @private
12
+ */
13
+ const LIGHT_THRESHOLD = 128;
7
14
 
8
15
  /**
9
16
  * Does `<html>` or `<body>` explicitly signal the given colour scheme via a
@@ -28,6 +35,88 @@ function hasThemeHint(scheme) {
28
35
  );
29
36
  }
30
37
 
38
+ /**
39
+ * Collect what the page paints behind `el`.
40
+ *
41
+ * Walks `el` and its ancestors up to `<html>`, alpha-compositing each element's
42
+ * background *colour* front-to-back. Walking the chain (rather than reading
43
+ * `<body>` alone) is what makes real layouts work: plenty of pages paint their
44
+ * background on a wrapper `<div>` or on `<html>` instead of `<body>`, and a
45
+ * player sitting inside a dark card on an otherwise light page should theme to
46
+ * the card.
47
+ *
48
+ * Compositing rather than taking the first colour found means translucent
49
+ * layers — an `rgba(0, 0, 0, 0.04)` tint over white, say — score as what the eye
50
+ * sees instead of as their own colour. Brightness is linear in R/G/B, so
51
+ * blending per-layer brightnesses is equivalent to blending the colours.
52
+ *
53
+ * Background *images* and gradients can't be scored from CSS, so a page painted
54
+ * only that way contributes no colour here and is classified by
55
+ * {@link detectCanvasScheme} instead.
56
+ *
57
+ * @param {Element} el - Element to start from (the player's container).
58
+ * @returns {{sum: number, alpha: number}} Premultiplied brightness, and how much
59
+ * of the stack is opaque (0–1).
60
+ * @private
61
+ */
62
+ function collectBackdrop(el) {
63
+ let sum = 0;
64
+ let alpha = 0;
65
+
66
+ for (let node = el; node && node.nodeType === 1 && alpha < 0.995; node = node.parentElement) {
67
+ const c = parseColor(getComputedStyle(node).backgroundColor);
68
+ if (!c || c.a <= 0) continue;
69
+
70
+ // Each layer only shows through however much is still see-through.
71
+ const weight = c.a * (1 - alpha);
72
+ sum += ((c.r * 299 + c.g * 587 + c.b * 114) / 1000) * weight;
73
+ alpha += weight;
74
+ }
75
+
76
+ return {sum, alpha};
77
+ }
78
+
79
+ /**
80
+ * Scheme of the canvas — what is visible wherever the page paints no background
81
+ * colour of its own.
82
+ *
83
+ * Read from the page's *resolved text colour*. `color` initially resolves to the
84
+ * `canvastext` system colour, which browsers flip to white exactly when the
85
+ * document's used colour-scheme is dark, so it reports the palette the page is
86
+ * actually designed for. It is also the only signal that sees the
87
+ * `<meta name="color-scheme" content="light dark">` form — Chrome reports
88
+ * `normal` for the computed `color-scheme` property there, so reading that
89
+ * instead would miss the exact setup in #21.
90
+ *
91
+ * Deliberately NOT `prefers-color-scheme`. That describes the **user**, not the
92
+ * page, and what browsers paint behind an unpainted page under a dark
93
+ * preference turns out to be engine-specific — measured by screenshotting the
94
+ * same page in both engines: Chromium composites a dark `#121212` base
95
+ * background, WebKit keeps it white. Since no scripted signal can tell those
96
+ * apart, we believe the page instead: black text means it was designed light,
97
+ * so it gets the light preset. That is right in WebKit, and in Chromium it only
98
+ * loses on a page whose own text is already unreadable against that same dark
99
+ * base background. The media query survives purely as a last resort for
100
+ * environments with no resolvable text colour.
101
+ *
102
+ * @returns {'dark'|'light'} Scheme of the canvas behind the page.
103
+ * @private
104
+ */
105
+ function detectCanvasScheme() {
106
+ // Light text ⇒ the page is painted for a dark canvas, and vice versa.
107
+ const text = perceivedBrightness(getComputedStyle(document.body).color);
108
+ if (text !== null) return text > LIGHT_THRESHOLD ? 'dark' : 'light';
109
+
110
+ if (window.matchMedia) {
111
+ if (window.matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
112
+ if (window.matchMedia('(prefers-color-scheme: light)').matches) return 'light';
113
+ }
114
+
115
+ // Knowing nothing at all keeps the historic default — most audio players
116
+ // are dark.
117
+ return 'dark';
118
+ }
119
+
31
120
  /**
32
121
  * Detect the appropriate color scheme for the player from the surrounding page.
33
122
  *
@@ -35,46 +124,41 @@ function hasThemeHint(scheme) {
35
124
  * 1. Explicit theme hints on `<html>`/`<body>` — class names
36
125
  * (`dark`, `dark-mode`, `theme-dark`, light equivalents) and data
37
126
  * attributes (`data-theme`, `data-color-scheme`).
38
- * 2. The page's computed `<body>` background colour, classified via
39
- * {@link perceivedBrightness} (>128 = light, <128 = dark; exactly 128
40
- * or unparseable is treated as ambiguous and falls through).
41
- * 3. The OS/browser `prefers-color-scheme` media query.
42
- * 4. Default fallback of `'dark'` (most audio players are dark).
127
+ * 2. The backdrop actually visible behind the player — every background from
128
+ * `el` up through `<html>` ({@link collectBackdrop}), composited over the
129
+ * canvas ({@link detectCanvasScheme}). >128 = light, <128 = dark.
130
+ * 3. The canvas scheme alone, for the knife-edge case where the composite
131
+ * lands exactly on the threshold.
43
132
  *
133
+ * @param {Element} [el] - The player's container, so a player inside a themed
134
+ * card picks up that card. Defaults to `<body>`.
44
135
  * @returns {string} The detected scheme, either `'dark'` or `'light'`.
45
136
  */
46
- export function detectColorScheme() {
137
+ export function detectColorScheme(el) {
47
138
  // 1. Explicit theme class names / data attributes win.
48
139
  if (hasThemeHint('dark')) return 'dark';
49
140
  if (hasThemeHint('light')) return 'light';
50
141
 
51
- // 2. Try to detect website's theme from background color
52
142
  try {
53
- const bodyBg = getComputedStyle(document.body).backgroundColor;
54
- const brightness = perceivedBrightness(bodyBg);
55
-
56
- // Clear determination: bright background = light theme. Exactly 128
57
- // (or unparseable) is ambiguous — fall through to the next method.
58
- if (brightness !== null) {
59
- if (brightness > 128) return 'light';
60
- if (brightness < 128) return 'dark';
61
- }
62
- } catch (e) {
63
- // If background detection fails, continue to next method
64
- }
143
+ // 2. What the player is actually sitting on.
144
+ const start = (el && el.nodeType === 1) ? el : document.body;
145
+ const {sum, alpha} = collectBackdrop(start);
65
146
 
66
- // 3. Check system preference
67
- if (window.matchMedia) {
68
- if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
69
- return 'dark';
70
- }
71
- if (window.matchMedia('(prefers-color-scheme: light)').matches) {
72
- return 'light';
73
- }
74
- }
147
+ // Whatever transparency is left over after the page's own layers shows
148
+ // the canvas through.
149
+ const canvas = detectCanvasScheme();
150
+ const brightness = sum + (canvas === 'dark' ? 0 : 255) * (1 - alpha);
75
151
 
76
- // 4. Default fallback (most audio players are dark)
77
- return 'dark';
152
+ if (brightness > LIGHT_THRESHOLD) return 'light';
153
+ if (brightness < LIGHT_THRESHOLD) return 'dark';
154
+
155
+ // 3. Dead-centre grey tells us nothing; go with the canvas.
156
+ return canvas;
157
+ } catch (e) {
158
+ // No usable computed styles (SSR shim, detached document) — most audio
159
+ // players are dark, so that stays the fallback.
160
+ return 'dark';
161
+ }
78
162
  }
79
163
 
80
164
  /**
@@ -110,17 +194,19 @@ export const COLOR_PRESETS = {
110
194
  *
111
195
  * @param {string|null} presetName - Preset name (`'dark'` or `'light'`), or
112
196
  * null/invalid to trigger auto-detection.
197
+ * @param {Element} [el] - Container passed through to {@link detectColorScheme}
198
+ * so detection reads the backdrop behind this player, not just `<body>`.
113
199
  * @returns {Object<string, string>} The matching colour token map from
114
200
  * {@link COLOR_PRESETS}.
115
201
  */
116
- export function getColorPreset(presetName) {
202
+ export function getColorPreset(presetName, el) {
117
203
  // If explicitly set to a valid preset, use it
118
204
  if (presetName && COLOR_PRESETS[presetName]) {
119
205
  return COLOR_PRESETS[presetName];
120
206
  }
121
207
 
122
208
  // Auto-detect if not specified or invalid
123
- const detected = detectColorScheme();
209
+ const detected = detectColorScheme(el);
124
210
  return COLOR_PRESETS[detected];
125
211
  }
126
212
 
package/src/js/utils.js CHANGED
@@ -283,17 +283,22 @@ export function formatSeekValueText(template, ...args) {
283
283
  * Format a duration as a clock string.
284
284
  *
285
285
  * Renders `M:SS` for durations under an hour and `H:MM:SS` for longer ones,
286
- * zero-padding the minutes and seconds. Falsy, `NaN`, or negative inputs are
287
- * treated as zero and return `'0:00'`.
286
+ * zero-padding the minutes and seconds. Falsy, non-numeric, non-finite, or
287
+ * negative inputs are treated as zero and return `'0:00'`.
288
+ *
289
+ * `Infinity` matters here, and an `isNaN` check does not catch it: a streamed or
290
+ * unseekable source reports `audio.duration === Infinity`, and `Infinity % 3600`
291
+ * is `NaN`, so the old guard rendered a literal `'Infinity:NaN:NaN'` into the UI.
288
292
  * @param {number} seconds - Time in seconds.
289
293
  * @returns {string} Formatted time, e.g. `'3:07'` or `'1:02:09'`.
290
294
  */
291
295
  export function formatTime(seconds) {
292
- if (!seconds || isNaN(seconds) || seconds < 0) return '0:00';
296
+ const total = Number(seconds);
297
+ if (!total || !Number.isFinite(total) || total < 0) return '0:00';
293
298
 
294
- const hrs = Math.floor(seconds / 3600);
295
- const mins = Math.floor((seconds % 3600) / 60);
296
- const secs = Math.floor(seconds % 60);
299
+ const hrs = Math.floor(total / 3600);
300
+ const mins = Math.floor((total % 3600) / 60);
301
+ const secs = Math.floor(total % 60);
297
302
 
298
303
  if (hrs > 0) {
299
304
  return `${hrs}:${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
@@ -352,17 +357,52 @@ export function extractTitleFromUrl(url) {
352
357
  .replace(/\b\w/g, l => l.toUpperCase());
353
358
  }
354
359
 
360
+ /**
361
+ * Parse a CSS `rgb()`/`rgba()` colour into numeric channels.
362
+ *
363
+ * Handles both serializations a browser can hand back from `getComputedStyle`:
364
+ * the legacy comma form (`rgb(34, 34, 34)`, `rgba(34, 34, 34, 0.5)`) and the
365
+ * modern space/slash form (`rgb(34 34 34 / 50%)`). Anything else — the
366
+ * `transparent` keyword, a wide-gamut `color(srgb …)`, an empty string — is
367
+ * reported as `null` so callers treat it as *unknown* rather than as a colour.
368
+ *
369
+ * @param {string} color - CSS colour string.
370
+ * @returns {{r: number, g: number, b: number, a: number}|null} Channels 0–255
371
+ * with alpha 0–1, or `null` when the string isn't an rgb()/rgba() colour.
372
+ */
373
+ export function parseColor(color) {
374
+ if (typeof color !== 'string') return null;
375
+
376
+ const m = color.match(/rgba?\(\s*([\d.]+)\s*[,\s]\s*([\d.]+)\s*[,\s]\s*([\d.]+)\s*(?:[,/]\s*([\d.]+)(%?))?/i);
377
+ if (!m) return null;
378
+
379
+ const r = Number(m[1]), g = Number(m[2]), b = Number(m[3]);
380
+ if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b)) return null;
381
+
382
+ let a = m[4] === undefined ? 1 : Number(m[4]);
383
+ if (!Number.isFinite(a)) return null;
384
+ if (m[5] === '%') a /= 100;
385
+
386
+ return {r, g, b, a: clamp(a, 0, 1)};
387
+ }
388
+
355
389
  /**
356
390
  * Perceived brightness (0–255) of a CSS colour, via the luminance formula.
357
- * Pulls the numeric channels out of an `rgb()`/`rgba()` string.
391
+ *
392
+ * A fully transparent colour returns `null`, not `0`. That distinction matters:
393
+ * `rgba(0, 0, 0, 0)` is the computed background of *every* element the page
394
+ * never paints, so scoring it as pure black made auto-theme detection classify
395
+ * unpainted (i.e. white) pages as dark — see issue #21. Transparent means "this
396
+ * tells you nothing", which is a different answer from "this is black".
397
+ *
358
398
  * @param {string} color - CSS colour string, e.g. `"rgb(34, 34, 34)"`.
359
- * @returns {number|null} Brightness 0–255, or `null` if it can't be parsed.
399
+ * @returns {number|null} Brightness 0–255, or `null` if it can't be parsed or
400
+ * is fully transparent.
360
401
  */
361
402
  export function perceivedBrightness(color) {
362
- const rgb = typeof color === 'string' ? color.match(/\d+/g) : null;
363
- if (!rgb || rgb.length < 3) return null;
364
- const [r, g, b] = rgb.map(Number);
365
- return (r * 299 + g * 587 + b * 114) / 1000;
403
+ const c = parseColor(color);
404
+ if (!c || c.a <= 0) return null;
405
+ return (c.r * 299 + c.g * 587 + c.b * 114) / 1000;
366
406
  }
367
407
 
368
408
  /**