2026-03-20 | 🔄🔊 TTS Auto-Play — Continuous Reading Across Pages
🧑💻 Author’s Note
- 🎯 Goal: When the TTS player finishes reading a page, automatically navigate to the next page and continue reading
- 🔧 Approach: Pure functional utilities for nav link detection, localStorage-based read tracking, BFS link discovery, and SPA navigation integration
- 🧪 Testing: 60 new tests (unit + property-based), all 178 TTS tests pass
- 📐 Principles: Functional Composition, Domain-Driven Design, Progressive Enhancement
🎭 The Problem: The Podcast That Stops Between Chapters
Imagine listening to a multi-part blog series through the TTS player. You’re walking, cooking, or commuting — hands busy, eyes elsewhere. The player finishes reading one post and… silence. You have to pull out your phone, find the next post in the series, and tap play again.
For a series with 30+ posts, this friction transforms continuous listening into an exercise in screen-tapping. The TTS player should behave like a podcast app — when one episode ends, the next one starts automatically.
🏗️ The Design: Three Candidate Approaches
Plan 1: Monolithic — Everything in tts.inline.ts
Add all auto-play logic directly into the existing TTS inline script. Navigation detection, localStorage tracking, and URL resolution all live alongside the speech synthesis code.
Pros: Single file, simple mental model.
Cons: Untestable (DOM-dependent), bloated file, violates Single Responsibility.
Plan 2: Pure Utilities + Thin DOM Integration
Extract all auto-play logic into a separate pure utility module (tts.autoplay.ts). The DOM-facing code in tts.inline.ts calls these pure functions, keeping the integration layer minimal.
Pros: Fully testable, follows existing pattern (tts.utils.ts is pure, tts.inline.ts is DOM glue), modular.
Cons: One additional file.
Plan 3: Event-Driven Controller
Create a separate auto-play controller that listens for custom TTS completion events. The TTS player dispatches events, and the controller handles all navigation logic independently.
Pros: Maximum decoupling.
Cons: Complex event choreography, harder to reason about ordering, potential race conditions with SPA navigation.
Decision: Plan 2
Plan 2 wins convincingly. It follows the exact pattern already established in the codebase — tts.utils.ts contains pure functions tested in isolation, while tts.inline.ts wires them to the DOM. The auto-play utilities slot naturally into this architecture.
🧩 The Architecture
Pure Utility Module: tts.autoplay.ts
Five core functions, all pure and testable:
extractNavLinks(links) — Given an array of {text, href} link descriptors from the article, identifies series navigation links by their marker emoji (⏭️ for next, ⏮️ for back).
urlToSlug(href) — Normalises any URL (absolute or relative) to a canonical slug for consistent comparison and storage.
isIndexOrHome(slug) — Returns true for index pages and the site root — these are excluded from auto-play candidates since they’re navigation hubs, not content pages.
decodeReadPages(stored) / encodeReadPages(pages) — Round-trip serialisation between localStorage strings and Set<string> for the read-page tracker.
resolveNextUrl(navLinks, articleLinks, readPages) — The core resolution algorithm with a clear priority chain:
- Series ⏭️ link (if not already read)
- Series ⏮️ link (if not already read)
- First article link via BFS (excluding index/home pages and already-read pages)
null— nothing left to play
DOM Integration in tts.inline.ts
The inline script gains four new capabilities:
-
Auto-play toggle — A button that persists its state in
localStorage. When enabled, the icon is fully opaque; when disabled, it’s dimmed. -
Page completion tracking — When TTS reaches the end of a page’s content naturally (not paused by the user), it marks the current page as read.
-
Next-page navigation — After marking, it collects all article links, runs
resolveNextUrl, and navigates viawindow.spaNavigate. -
Auto-start on arrival — A
AUTOPLAY_PENDING_KEYflag in localStorage signals the next page load to start playing immediately.
The stop(reachedEnd) Distinction
The existing stop() function is called from multiple contexts — user pause, seeking, cleanup. The auto-play feature needs to distinguish between “user stopped playback” and “playback naturally reached the end.” A boolean parameter reachedEnd (defaulting to false) cleanly separates these cases without changing any existing call sites.
🔄 The Auto-Play Flow
Page A finishes reading
└─ stop(reachedEnd=true)
├─ Mark page A as read in localStorage
└─ resolveNextUrl()
├─ Has ⏭️ next link? → Navigate to it
├─ Has ⏮️ back link? → Navigate to it
└─ BFS article links → First unread non-index page
└─ Set AUTOPLAY_PENDING_KEY
└─ window.spaNavigate(nextUrl)
└─ SPA loads Page B
└─ "nav" event fires
└─ TTS initialises
└─ Checks AUTOPLAY_PENDING_KEY
└─ speakFrom(0)
🧪 Testing: 60 New Tests
Following the codebase convention of thorough property-based testing:
| Category | Tests | Coverage |
|---|---|---|
| Constants | 3 | Storage keys are distinct, non-empty; markers are single grapheme clusters |
extractNavLinks | 7 | Empty, single marker, both markers, multiple matches, no markers |
urlToSlug | 8 | Slashes, full URLs, hash fragments, root, bare slugs |
isIndexOrHome | 8 | Empty, “index”, nested index, regular articles, false positives |
decodeReadPages | 6 | Null, empty, valid JSON, invalid JSON, non-array, deduplication |
encodeReadPages | 3 | Empty set, set of slugs, round-trip |
resolveNextUrl | 12 | Priority chain, index skipping, home skipping, read tracking, exhaustion |
| Integration | 4 | Full series flow, BFS fallback, round-trip tracking, slug normalisation |
| Property-based | 9 | Slug invariants, index detection, resolution safety, encode/decode round-trips |
Every property-based test runs 50 randomised iterations to catch edge cases that unit tests might miss.
🎨 The UI: Minimal and Familiar
The auto-play toggle is a small button in the TTS controls row, using a standard “skip to end” icon (▶|). When auto-play is off, the icon is dimmed to 40% opacity. When on, it’s fully visible. The state persists across page loads via localStorage.
No modal dialogs, no toast notifications, no complex state machines — just a toggle that does what it says.
💡 Key Design Decisions
localStorage over sessionStorage — Read-page tracking must survive browser restarts. A user who reads 15 posts in a series on Monday shouldn’t re-read them on Tuesday.
Slug normalisation — URLs can appear as full URLs, relative paths, or paths with hash fragments. urlToSlug normalises all of these to a canonical form for reliable set membership checks.
Index page exclusion — Series index pages and the home page are navigation hubs, not content. Including them in BFS would cause the auto-player to read navigation lists aloud — not useful.
BFS depth-1 — True multi-level BFS would require fetching and parsing multiple pages. The depth-1 approach (links on the current page) is practical, fast, and sufficient for the series-based content structure of this site.
reachedEnd parameter — Adding a boolean parameter to stop() is the minimal change that cleanly separates user-initiated stops from natural completion, without restructuring the existing code.