@dudgy/podcast-widget 0.1.1 → 0.3.0

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/README.md CHANGED
@@ -37,7 +37,7 @@ const mini = new MiniPlayer({
37
37
  const full = new FullPlayer({
38
38
  container: document.getElementById('full-player')!,
39
39
  controller,
40
- controls: { playPause: true, skipForward: true, skipBackward: true, volume: true, speed: true, progress: true, playlist: true },
40
+ controls: { playPause: true, skipForward: true, skipBackward: true, volume: true, speed: true, progress: true, playlist: true, download: true },
41
41
  });
42
42
 
43
43
  // 3. Wire them together
@@ -61,7 +61,7 @@ podcast-widget/
61
61
  │ │ ├── player-state.ts # localStorage for player state + speed preference
62
62
  │ │ └── episode-provider.ts # FetchEpisodeProvider with caching + retry
63
63
  │ ├── ui/
64
- │ │ ├── utils.ts # formatTime, escapeHtml, getEpisodeImage
64
+ │ │ ├── utils.ts # Formatting, artwork fallback, seek tooltip
65
65
  │ │ ├── html-templates.ts # SVG icons, playlist rendering, speed options
66
66
  │ │ ├── player-controller.ts # Orchestrator: engine + storage + provider → events
67
67
  │ │ ├── mini-player.ts # Mini mode with configurable controls + inline playlist
@@ -73,6 +73,8 @@ podcast-widget/
73
73
  │ ├── styles/
74
74
  │ │ └── podcast-player.css # Plain CSS with custom property theming (pw- prefix)
75
75
  │ └── index.ts # Main barrel export
76
+ ├── tests/ # Unit tests (Vitest + jsdom)
77
+ ├── e2e/ # Browser tests (Playwright, Chrome + WebKit)
76
78
  ├── package.json # Dual ESM/CJS, subpath exports
77
79
  ├── tsconfig.json # Client-side TS config
78
80
  ├── tsconfig.server.json # Server-side (podcast-index) config
@@ -97,6 +99,7 @@ interface ControlsConfig {
97
99
  progress?: boolean;
98
100
  playlist?: boolean; // Inline dropdown playlist (mini) or full playlist (full)
99
101
  expand?: boolean; // Button to emit 'expand' event
102
+ download?: boolean; // Download button for current episode
100
103
  }
101
104
  ```
102
105
 
@@ -123,7 +126,7 @@ mini.destroy(); // Cleanup when done
123
126
 
124
127
  ### FullPlayer
125
128
 
126
- Modal overlay with hero section (blurred artwork background), controls, and scrollable playlist. Defaults: all controls enabled.
129
+ Modal overlay with hero section (blurred artwork background), controls, and scrollable playlist. Defaults: all controls enabled. Each playlist item includes a download button.
127
130
 
128
131
  ```typescript
129
132
  const full = new FullPlayer({
@@ -193,13 +196,15 @@ controller.playEpisode(2); // Load and play
193
196
  controller.setSpeed(1.5);
194
197
  controller.setVolume(0.8);
195
198
 
196
- controller.on('episode-change', ({ episode, index }) => {});
199
+ controller.on('episode-change', ({ episode, index }) => {}); // index is -1 if not in the list
197
200
  controller.on('episodes-loaded', ({ episodes }) => {});
198
201
  controller.on('episode-display', ({ imageUrl, title, show }) => {});
199
202
 
200
203
  controller.destroy();
201
204
  ```
202
205
 
206
+ **Restoring on page load.** `loadEpisodes()` restores the episode the listener last had loaded (paused, at its saved position). The episode is saved as a snapshot and matched by `id`, so episode IDs must be stable across fetches — use the feed's `guid` where possible rather than list position or a URL that may change. If the saved episode is still in the list, the fresh copy is used; if it has dropped out (e.g. its feed published something newer), it's restored from the snapshot with `getCurrentIndex() === -1`. With nothing saved, the first episode is cued. Saved resume positions are kept for listed episodes and the current one; others are cleaned up.
207
+
203
208
  ### EpisodeProvider
204
209
 
205
210
  Interface for loading episodes. The package ships `FetchEpisodeProvider` which fetches from a URL with caching and retry.
@@ -303,9 +308,30 @@ const headers = createPodcastIndexHeaders(apiKey, apiSecret);
303
308
  npm run build # Build
304
309
  npm run dev # Build + watch
305
310
  npm run typecheck # Type check
306
- npm test # Run tests
311
+ npm test # Unit tests (Vitest + jsdom)
312
+ npm run test:e2e # Build, then browser tests in Chrome and WebKit
313
+ ```
314
+
315
+ ### Browser tests
316
+
317
+ `e2e/` drives the built package in real browsers through a fixture page
318
+ (`e2e/fixture.html`). Requests are intercepted and answered from code — the page,
319
+ `dist/`, a test-controlled episode list, generated silent audio and test images — so
320
+ there's no server, network access or API keys, and results are repeatable.
321
+
322
+ They cover restoring the listener's episode and position, skip buttons, artwork
323
+ fallback, the seek tooltip, layout, and exact-match screenshots of the players
324
+ (`e2e/player.spec.ts-snapshots/`). After an intended visual change, regenerate the
325
+ screenshots and look at them before committing:
326
+
327
+ ```bash
328
+ npm run test:e2e -- --update-snapshots=all
307
329
  ```
308
330
 
331
+ Requirements: Google Chrome installed (the `chrome` project uses the system
332
+ browser), and Playwright's WebKit (`npx playwright install webkit`) with its system
333
+ libraries (`npx playwright install-deps webkit`, needs sudo).
334
+
309
335
  ### Testing in a Consumer Before Publishing
310
336
 
311
337
  ```bash