feat(notes): add {{episodelink}} template tag to resume an episode from its note (#35) (#193)

* feat(notes): add {{episodelink}} template tag to resume an episode from its note (#35)

Add a no-timestamp obsidian://podnotes deep link so an episode note can link
back to the player and resume from the last played location (or the start if
unplayed). The resume point is resolved at click time, not baked into the note.

- New {{episodelink}} note-template tag (src/utility/buildEpisodeResumeLink.ts)
- URIHandler: a link without time reopens the episode and defers the seek to the
  player's existing saved-progress restore; explicit-time links are unchanged
- Docs + unit tests for the link builder, URI handler, and template tag

* fix(notes): make {{episodelink}} resume robust to finished episodes and stale seeks (#35)

Address adversarial review of #193:
- Finished episodes (saved at time===duration) no longer resume at EOF and
  auto-advance the queue; the no-time path resolves the resume point explicitly
  and restarts a finished episode from the beginning (resolveResumeTime), both
  for non-loaded and already-loaded episodes.
- The no-time path now arms requestedPlaybackTime explicitly instead of relying
  on its absence, so a stale pending seek from an earlier link to the same
  episode can no longer override the resume on metadata load.
- buildEpisodeResumeLink falls back to a downloaded copy's path when an episode
  lacks feedUrl, and drops a redundant cast (isLocalFile already narrows).
- Tests for finished resume (non-loaded + loaded), stale-seek override, and the
  downloaded-without-feedUrl link; docs note finished -> start behavior.

Author: chhoumann

docs/docs/templates.md

@@ -40,6 +40,7 @@ This template will be used to create the note text. You can use the following sy
 	- `{{duration:minutes}}` → total whole minutes (e.g. `62`); `{{duration:seconds}}` → total seconds (e.g. `3723`).
 	- Any other argument is treated as a clock format using the tokens `H`/`HH`, `h`/`hh`, `m`/`mm`, `s`/`ss`, `A`/`a` — e.g. `{{duration:HH:mm:ss}}` → `01:02:03`. (Unlike `{{date}}`, `[literal]` bracket escaping is not supported here.)
 - `{{artwork}}`: The URL of the podcast artwork. If no artwork is found, an empty string will be used.
+- `{{episodelink}}`: A clickable `obsidian://podnotes` link that reopens this episode in the PodNotes player and **resumes from where you left off** (or starts at the beginning if you have never played it, or have already finished it). The resume position is resolved when you click the link — not baked in when the note is created — so the link always jumps to your latest position. Put it in your template to get a "back to the episode" link on every note, e.g. `[▶️ Resume in PodNotes]({{episodelink}})`. The value is the bare URL, so wrap it in your own Markdown link text. It is empty when the episode has no feed URL or local file path to address it by. See [issue #35](https://github.com/chhoumann/PodNotes/issues/35).
 
 ### Linking an episode to its podcast (feed) note
 In an episode note, `{{url}}` and `{{artwork}}` always describe the **episode**. To reference the parent podcast (feed), use these additional tags:

src/TemplateEngine.test.ts

@@ -10,7 +10,7 @@ import {
 } from "./TemplateEngine";
 import type { Episode } from "./types/Episode";
 import type { PodcastFeed } from "./types/PodcastFeed";
-import { plugin } from "./store";
+import { downloadedEpisodes, plugin } from "./store";
 
 // The illegal-character sanitizer is private; exercise it through
 // DownloadPathTemplateEngine, which applies it to {{title}} and {{podcast}}.
@@ -116,6 +116,21 @@ describe("NoteTemplateEngine feed-scoped tags (#163)", () => {
 		);
 	});
 
+	it("emits {{episodelink}} as a no-timestamp obsidian://podnotes link to the episode (#35)", () => {
+		plugin.set({ settings: { feedNote: { path: "" }, savedFeeds: {} } } as never);
+		downloadedEpisodes.set({});
+
+		const rendered = NoteTemplateEngine("{{episodelink}}", demoEpisode);
+		const parsed = new URL(rendered);
+
+		expect(parsed.protocol).toBe("obsidian:");
+		expect(parsed.host).toBe("podnotes");
+		expect(parsed.searchParams.get("episodeName")).toBe("Episode 1");
+		expect(parsed.searchParams.get("url")).toBe("https://example.com/feed.xml");
+		// No baked-in time: the resume point is resolved when the link is clicked.
+		expect(parsed.searchParams.has("time")).toBe(false);
+	});
+
 	it("emits {{podcastlink}} as a path-qualified wikilink to the feed note", () => {
 		plugin.set({
 			settings: {

src/TemplateEngine.ts

@@ -9,6 +9,7 @@ import { formatDate } from "./utility/formatDate";
 import { formatDuration } from "./utility/formatDuration";
 import { formatEpisodeNumber } from "./utility/formatEpisodeNumber";
 import { parseEpisodeNumberFromTitle } from "./utility/parseEpisodeNumber";
+import buildEpisodeResumeLink from "./utility/buildEpisodeResumeLink";
 
 // Each tag is either a literal string or a function taking at most one argument
 // (the raw text after the leading colon, e.g. the format in {{date:YYYY}}). The
@@ -157,6 +158,12 @@ export function NoteTemplateEngine(template: string, episode: Episode) {
 	// A ready-made wikilink to the parent feed's note, pointing at the same file
 	// createFeedNote writes (derived from the feed-note path setting).
 	addTag("podcastlink", getFeedNoteWikilink(episode.podcastName));
+	// A clickable obsidian://podnotes deep link that reopens this episode in the
+	// player and resumes from the last played location (or the start if it has
+	// never been played). The resume point is resolved at click time, not baked
+	// in here, so a single templated link always jumps to where you left off.
+	// Empty when the episode has no feed/file URL to address it by. See issue #35.
+	addTag("episodelink", buildEpisodeResumeLink(episode));
 
 	return replacer(template);
 }

src/URIHandler.test.ts

@@ -12,6 +12,7 @@ import podNotesURIHandler from "./URIHandler";
 import {
 	currentEpisode,
 	currentTime,
+	duration,
 	isPaused,
 	localFiles,
 	playedEpisodes,
@@ -64,6 +65,7 @@ const emptyLocalFiles: Playlist = {
 function resetStores() {
 	currentEpisode.update(() => undefined as unknown as Episode);
 	currentTime.set(0);
+	duration.set(0);
 	isPaused.set(true);
 	playedEpisodes.set({});
 	requestedPlaybackTime.set(null);
@@ -331,6 +333,144 @@ describe("podNotesURIHandler", () => {
 		});
 	});
 
+	test("reopens a non-loaded episode without a timestamp and resumes from the saved location (#35)", async () => {
+		playedEpisodes.setEpisodeTime(testEpisode, 321, 3600, false);
+
+		await podNotesURIHandler(
+			{
+				action: "podnotes",
+				url: testFeedUrl,
+				episodeName: testEpisode.title,
+				// No `time`: the {{episodelink}} template tag omits it.
+			},
+			api as never,
+		);
+
+		expect(mockGetEpisodes).toHaveBeenCalledWith(testFeedUrl);
+		expect(get(currentEpisode)).toMatchObject({ title: testEpisode.title });
+		expect(get(viewState)).toBe(ViewState.Player);
+		// The resume point is resolved from saved progress and armed explicitly, so
+		// the player seeks to 321s — and any stale pending request can't override it.
+		expect(get(requestedPlaybackTime)).toEqual({
+			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,
+			time: 321,
+		});
+	});
+
+	test("a no-timestamp link overrides a stale pending seek for the same episode (#35)", async () => {
+		playedEpisodes.setEpisodeTime(testEpisode, 321, 3600, false);
+		// A previous timestamp link left a pending seek that has not been applied
+		// (metadata still loading). The resume link must win, not the stale 999.
+		requestedPlaybackTime.set({
+			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,
+			time: 999,
+		});
+
+		await podNotesURIHandler(
+			{ action: "podnotes", url: testFeedUrl, episodeName: testEpisode.title },
+			api as never,
+		);
+
+		expect(get(requestedPlaybackTime)).toEqual({
+			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,
+			time: 321,
+		});
+	});
+
+	test("restarts a finished episode from the beginning for a no-timestamp link (#35)", async () => {
+		// A finished episode is stored at its end; resuming there would auto-advance.
+		playedEpisodes.markAsPlayed(testEpisode);
+		playedEpisodes.setEpisodeTime(testEpisode, 3600, 3600, true);
+
+		await podNotesURIHandler(
+			{ action: "podnotes", url: testFeedUrl, episodeName: testEpisode.title },
+			api as never,
+		);
+
+		expect(get(currentEpisode)).toMatchObject({ title: testEpisode.title });
+		expect(get(requestedPlaybackTime)).toEqual({
+			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,
+			time: 0,
+		});
+	});
+
+	test("restarts an already-loaded finished episode from the beginning for a no-timestamp link (#35)", async () => {
+		currentEpisode.set(testEpisode);
+		viewState.set(ViewState.PodcastGrid);
+		duration.set(180);
+		currentTime.set(180); // sitting at the very end
+		isPaused.set(true);
+
+		await podNotesURIHandler(
+			{ action: "podnotes", url: testFeedUrl, episodeName: testEpisode.title },
+			api as never,
+		);
+
+		expect(get(viewState)).toBe(ViewState.Player);
+		expect(get(currentTime)).toBe(0);
+		expect(get(isPaused)).toBe(false);
+		expect(mockGetEpisodes).not.toHaveBeenCalled();
+	});
+
+	test("surfaces the player and resumes the already-loaded episode without seeking when no timestamp is given (#35)", async () => {
+		currentEpisode.set(testEpisode);
+		viewState.set(ViewState.PodcastGrid);
+		currentTime.set(1234);
+		isPaused.set(true);
+
+		await podNotesURIHandler(
+			{
+				action: "podnotes",
+				url: testFeedUrl,
+				episodeName: testEpisode.title,
+			},
+			api as never,
+		);
+
+		expect(get(viewState)).toBe(ViewState.Player);
+		// The live position is already the last played location — left untouched.
+		expect(get(currentTime)).toBe(1234);
+		expect(get(isPaused)).toBe(false);
+		expect(get(requestedPlaybackTime)).toBeNull();
+		expect(mockGetEpisodes).not.toHaveBeenCalled();
+	});
+
+	test("treats an empty timestamp the same as an omitted one (resume, not error) (#35)", async () => {
+		await podNotesURIHandler(
+			{
+				action: "podnotes",
+				url: testFeedUrl,
+				episodeName: testEpisode.title,
+				time: "",
+			},
+			api as never,
+		);
+
+		expect(get(currentEpisode)).toMatchObject({ title: testEpisode.title });
+		expect(get(viewState)).toBe(ViewState.Player);
+		// No saved progress for this episode → resume from the start.
+		expect(get(requestedPlaybackTime)).toEqual({
+			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,
+			time: 0,
+		});
+	});
+
+	test("still rejects a present-but-non-numeric timestamp", async () => {
+		await podNotesURIHandler(
+			{
+				action: "podnotes",
+				url: testFeedUrl,
+				episodeName: testEpisode.title,
+				time: "not-a-number",
+			},
+			api as never,
+		);
+
+		expect(get(currentEpisode)).toBeUndefined();
+		expect(get(viewState)).toBe(ViewState.PodcastGrid);
+		expect(mockGetEpisodes).not.toHaveBeenCalled();
+	});
+
 	test("picks the '+'-variant local file (raw-first) even when its space-twin precedes it", async () => {
 		const makeLocal = (title: string): LocalEpisode => ({
 			title,

src/URIHandler.ts

@@ -5,8 +5,11 @@ import type { IAPI } from "./API/IAPI";
 import FeedParser from "./parser/feedParser";
 import {
 	currentEpisode,
+	currentTime,
+	duration,
 	isPaused,
 	localFiles,
+	playedEpisodes,
 	requestedPlaybackTime,
 	viewState,
 } from "./store";
@@ -44,21 +47,43 @@ function findEpisodeByCandidates(
 	return undefined;
 }
 
+/**
+ * The time a no-timestamp link ({{episodelink}}, issue #35) should resume an
+ * episode at: the last played location, or the start. A FINISHED episode is
+ * stored at its end (time === duration); resuming there would immediately fire
+ * the player's `ended` handler and auto-advance the queue, so we restart it from
+ * the beginning instead — matching the issue's "the beginning if not played".
+ */
+function resolveResumeTime(episode: Episode): number {
+	const played = playedEpisodes.get(episode);
+	if (!played) return 0;
+
+	const isFinished =
+		played.finished || (played.duration > 0 && played.time >= played.duration);
+	return isFinished ? 0 : played.time;
+}
+
 export default async function podNotesURIHandler(
 	{ url, episodeName, time }: ObsidianProtocolData,
 	api: IAPI
 ) {
-	if (!url || !episodeName || time === undefined) {
-		new Notice(
-			"URL, episode name, and timestamp are required to play an episode"
-		);
+	if (!url || !episodeName) {
+		new Notice("URL and episode name are required to play an episode");
 		return;
 	}
 
-	const requestedTime = parseFloat(time);
-	if (!Number.isFinite(requestedTime)) {
-		new Notice("Timestamp must be a valid number");
-		return;
+	// A link may omit the timestamp ({{episodelink}}, issue #35). When it does we
+	// reopen the episode and resume from the last played location (resolved from
+	// saved progress below), or the start if it was never played or already
+	// finished — rather than seeking to a baked-in time.
+	const hasExplicitTime = time !== undefined && time !== "";
+	let requestedTime = 0;
+	if (hasExplicitTime) {
+		requestedTime = parseFloat(time);
+		if (!Number.isFinite(requestedTime)) {
+			new Notice("Timestamp must be a valid number");
+			return;
+		}
 	}
 
 	const nameCandidates = candidateValues(episodeName);
@@ -73,16 +98,32 @@ export default async function podNotesURIHandler(
 	const playerIsVisible = get(viewState) === ViewState.Player;
 
 	if (episodeIsPlaying) {
-		requestedPlaybackTime.set({
-			episodeKey: getEpisodeKey(currentEp),
-			time: requestedTime,
-		});
+		if (hasExplicitTime) {
+			requestedPlaybackTime.set({
+				episodeKey: getEpisodeKey(currentEp),
+				time: requestedTime,
+			});
+			viewState.set(ViewState.Player);
+			api.currentTime = requestedTime;
+			isPaused.set(false);
+			if (playerIsVisible) {
+				requestedPlaybackTime.set(null);
+			}
+
+			return;
+		}
+
+		// No timestamp: the live position already is the last played location, so
+		// surface the player and resume playback without seeking — unless the
+		// episode already finished (live position at its end), in which case
+		// replaying would instantly fire `ended` and auto-advance, so restart it.
 		viewState.set(ViewState.Player);
-		api.currentTime = requestedTime;
-		isPaused.set(false);
-		if (playerIsVisible) {
-			requestedPlaybackTime.set(null);
+		const liveTime = get(currentTime);
+		const liveDuration = get(duration);
+		if (liveDuration > 0 && liveTime >= liveDuration) {
+			api.currentTime = 0;
 		}
+		isPaused.set(false);
 
 		return;
 	}
@@ -121,9 +162,14 @@ export default async function podNotesURIHandler(
 		return;
 	}
 
+	// Always arm requestedPlaybackTime so the resume point is explicit. For a
+	// no-timestamp link (issue #35) we resolve it from saved progress here rather
+	// than relying on the player's restore-on-absence: that makes the seek
+	// deterministic and overrides any stale pending request from an earlier link
+	// to this same episode (which would otherwise win on metadata load).
 	requestedPlaybackTime.set({
 		episodeKey: getEpisodeKey(episode),
-		time: requestedTime,
+		time: hasExplicitTime ? requestedTime : resolveResumeTime(episode),
 	});
 	currentEpisode.set(episode);
 	viewState.set(ViewState.Player);