fix(player): keep playing while you browse, with one player that owns the media

.claude/skills/verify/features/player.md

@@ -38,8 +38,10 @@ Preconditions:
 
 ## Gotchas
 
-- Clicking a finished episode resumes it at its end. That fires `ended` at once, and the queue auto-advances to another episode. Use unplayed episodes or a fresh vault.
+- Playing a finished episode starts it over at 0.
+- Audio keeps playing on the grid and list tabs, in settings, and with the view closed. The one media element is `audio.podnotes-media` (or `video.podnotes-media`) in the main window, not inside the view.
+- After a restart the last episode shows paused at its saved position. Nothing loads or plays until you press play. A sync that lands before then updates the shown episode and position, unless you moved the position.
+- A video plays in the main window only. With the view in a popout, the player shows the artwork and the video keeps playing hidden in the main window.
 - With `Keep a queue of episodes you switch away from` on (the default), switching episodes queues the previous one, and it plays again when the current one ends.
 - The skip buttons have no accessible name. Address them by position inside `.controls-container`.
-- The playback-rate slider renders at 1.5 while the real rate is 1x. Assert on `api.playbackRate` or the rate label, not the slider.
 - Headless Obsidian plays to a null audio sink. Prove playback through `api.currentTime` advancing, not by sound.

docs/src/content/docs/api.md

@@ -73,15 +73,17 @@ Local episodes extend this type with `podcastName: "local file"`, empty `descrip
 
 ## `isPlaying`
 
-Returns the inverse of PodNotes' paused state. It describes the requested player state rather than proof that media playback has started.
+Returns `true` while the current episode plays, or loads to play. It is `false` for a paused, finished, or freshly restored episode.
 
 ## `length`
 
-Returns the player duration in seconds. The value starts at zero before media metadata loads.
+Returns the player duration in seconds. Before the media loads, it is the saved or feed-provided duration, or zero when neither is known.
 
 ## `currentTime`
 
-Gets or sets the player position in seconds. Setting a position clears an active segment's end boundary.
+Gets or sets the player position in seconds. Before the media loads, it is the position playback starts from.
+Setting a position clears an active segment's end boundary. A value that is not a finite, non-negative number is ignored.
+A position at or past the end stops 0.25 seconds before the end and pauses, so the episode does not finish.
 
 ## `volume`
 
@@ -162,11 +164,12 @@ Non-finite writes fall back to **Default Playback Rate**.
 Changing the current rate does not change that saved default.
 
 ## Playback controls
-`start()`, `stop()`, and `togglePlayback()` control the current episode.
-`stop()` pauses without resetting the position.
+`start()`, `stop()`, and `togglePlayback()` control the current episode, also while the PodNotes view is closed.
+`stop()` pauses without resetting the position. `start()` on a finished episode starts it over.
 `skipBackward()` and `skipForward()` use **Skip backward length (s)** and **Skip forward length (s)**.
 Invalid skip lengths fall back to 15 seconds. Backward skips stop at zero.
-With a known duration, forward skips stop up to 0.25 seconds before the end without moving backward.
+With a known duration, a forward skip goes no further than 0.25 seconds before the end and never moves backward.
+Playback continues, so a playing episode finishes and the queue advances.
 
 `increasePlaybackRate()` and `decreasePlaybackRate()` adjust the current playback
 speed in `0.1x` steps. `resetPlaybackRate()` returns playback to the default

docs/src/content/docs/commands.md

@@ -37,7 +37,8 @@ It requires a loaded episode and works while paused. The default skip length is
 ## Skip Forward
 
 `podnotes:skip-forward` seeks forward by **Skip forward length (s)**.
-When duration is known, a forward skip stops up to 0.25 seconds before the end without rewinding an episode already nearer its end.
+When duration is known, a forward skip goes no further than 0.25 seconds before the end and never rewinds an episode already nearer its end.
+Playback continues, so a playing episode finishes and the queue advances.
 It requires a loaded episode and works while paused. The default skip length is 15 seconds.
 
 ## Download Playing Episode

docs/src/content/docs/podcasts.md

@@ -92,9 +92,13 @@ If you would rather manage the queue yourself, turn off **Keep a queue of episod
 You can still add, remove, and reorder episodes in the queue manually from the episode context menu. While the queue is empty in this mode, its tile in the podcast grid and its list in the player are hidden.
 
 ## Player
-The player will automatically load and play the current episode.
+An episode keeps playing while you browse podcasts, change settings, or close the PodNotes view.
+When Obsidian starts, the player shows the last episode paused at its saved position. Nothing plays until you press play.
+If a sync brings newer progress or another episode before then, the player shows that instead.
+A position you already moved that episode to stays.
+A video plays in the main Obsidian window. When the PodNotes view is in a separate window, it shows the episode artwork.
 
-Clicking on the epsiode image will toggle episode playback.
+Clicking on the episode image will toggle episode playback.
 
 The player also features a progress bar, which you can use to seek to a specific time in the episode.
 You can also press the buttons on the player to skip backwards or forwards in the episode.

docs/src/content/docs/timestamps.md

@@ -88,21 +88,24 @@ The handler accepts these query parameters:
 | --- | --- | --- |
 | `url` | Yes | Podcast feed URL, vault media path, or protected private-feed placeholder. |
 | `episodeName` | Yes | Episode title. |
-| `time` | No | Start time parsed as a non-negative finite number of seconds. |
-| `endTime` | No | Segment end parsed as a finite number of seconds greater than `time`. Requires a start time. |
+| `time` | No | Start time in seconds. The whole value must be a non-negative finite number, so `12abc` is refused. |
+| `endTime` | No | Segment end in seconds, greater than `time`. The whole value must be a finite number. Requires a start time. |
 | `end` | No | Accepted alias of `endTime`. |
 | `to` | No | Accepted alias of `endTime`, after `end` in precedence. |
 
 An omitted or empty `time` resumes from saved progress.
 An unplayed or finished episode starts at zero.
+A `time` at or past the episode's end stops 0.25 seconds before the end and pauses.
 `endTime` takes precedence over `end`, which takes precedence over `to`.
 
 Query values are percent-encoded. Current links encode spaces as `%20` and literal plus signs as `%2B`.
 Older links using `+` for spaces are also tried during title and local-path lookup.
 
 Feed targets must use a public HTTP or HTTPS URL. A protected private-feed placeholder resolves only through a saved subscription and its device-local secret.
 Local targets need a registered episode and a media file. See [Sync and devices](/sync/#removal-and-existing-links).
+When the vault path in `url` exists, that file plays, even if a same-named file in another folder took over its registration.
 
+A link plays the loaded episode without a feed lookup only when its `url` names that episode's feed, or its file for a local file.
 Episode lookup first tries the title, ignoring case and surrounding whitespace.
 Its fallback requires a unique match with the same normalized word set, ignoring punctuation, word order, and leading zeros in numeric words.
 Different words or episode numbers can prevent a match. Timestamp links do not guarantee recovery after every feed title change.