# Podcast Player Embed

## Objective

Drop a real episode from your podcast feed onto a page, with artwork and show notes.

An embeddable block that pulls a chosen episode from a podcast feed and renders artwork, notes, and a player.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Let an editor paste a feed address once, then pick an episode from a list rather than pasting an episode URL. The picker is the whole point; a raw URL field puts the work back on the user.
2. Render the audio through the app's existing Audio Player rather than embedding the host's own widget. A third-party iframe means their branding, their tracking, and their outage on your page.
3. Read the feed on the server on a schedule and store what you render. Do not fetch the feed from the visitor's browser on every page view.
4. Show artwork, episode title, publication date, duration, and show notes, and link out to the episode on its original host for people who want their own podcast app.
5. Do not trust the show notes. Feeds carry arbitrary markup written by whoever runs the show; strip scripts, event handlers, and embedded frames, and allow only the small set of tags the notes actually need.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Fetching the feed on every page view will get you rate limited or blocked by the host. Cache the parsed feed with a sensible refresh interval and serve the cached copy while a refresh runs in the background.
- Feeds reorder themselves, republish episodes with new file addresses, and drop old episodes entirely. Match on the episode identifier the feed provides, not on position in the list, and keep showing a stored copy of an episode that has vanished rather than blanking the block.
- Show notes arrive as untrusted markup and are the most likely injection route in this feature. Sanitise on the server before storage as well as on render, so a stored payload cannot leak through a later template change.
- When the feed is unreachable, the block must still render the last known episode with its artwork and a working play link, not an empty box or a raw fetch error.
- Long episodes make seek precision matter. A scrubber a few hundred pixels wide over a three-hour recording needs a fine-seek affordance or keyboard nudge, or listeners cannot land where they meant to.
- Artwork comes from a remote host at unpredictable dimensions. Reserve the space before it loads so the page does not jump, and fall back to a placeholder rather than a broken image.
- A feed address that is not a podcast feed, or that returns a login page, must fail at the point the editor pastes it, with a message saying what was wrong.
- Very large feeds with hundreds of episodes need paging or search in the picker, and a parse limit so one enormous feed cannot exhaust memory.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] An editor pastes a feed once and selects episodes from a list.
- [ ] Feeds are fetched and parsed server-side on a schedule, not per page view.
- [ ] Show notes are sanitised before storage and before render, and scripts and frames never survive.
- [ ] An unreachable feed still renders the last known episode with artwork and playback.
- [ ] Artwork space is reserved so the layout does not shift on load.
- [ ] Playback uses the app's existing audio player, not a third-party embed.
- [ ] An invalid or non-podcast feed address is rejected with a clear message at entry time.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.