From aedaa2d78712ab1a890e2dece4cd8ee91ffd1916 Mon Sep 17 00:00:00 2001
From: harshjeet <harshjeetkumar0@gmail.com>
Date: Wed, 22 Jul 2026 08:24:02 +0530
Subject: [PATCH 1/3] feat: add ReadAloud component with Puter AI and Web
 Speech API support

---
 .../.vitepress/theme/components/ReadAloud.vue | 685 ++++++++++++++++++
 docs/.vitepress/theme/index.ts                |  32 +-
 package-lock.json                             | 167 ++++-
 package.json                                  |   9 +-
 4 files changed, 876 insertions(+), 17 deletions(-)
 create mode 100644 docs/.vitepress/theme/components/ReadAloud.vue

diff --git a/docs/.vitepress/theme/components/ReadAloud.vue b/docs/.vitepress/theme/components/ReadAloud.vue
new file mode 100644
index 0000000..f5bc86a
--- /dev/null
+++ b/docs/.vitepress/theme/components/ReadAloud.vue
@@ -0,0 +1,685 @@
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, watch } from 'vue'
+import { useRoute } from 'vitepress'
+
+const route = useRoute()
+
+const isSupported = ref(true)
+const isPlaying = ref(false)
+const isPaused = ref(false)
+const isLoadingModel = ref(false)
+const loadingProgress = ref('')
+const currentRate = ref(1.0)
+const rates = [0.8, 1.0, 1.25, 1.5, 2.0]
+
+// Engine selection
+const ttsMode = ref<'puter' | 'browser'>('puter')
+
+// Puter OpenAI voices
+const puterVoices = [
+  { id: 'nova', name: 'Nova (Female - Natural)', provider: 'openai' },
+  { id: 'alloy', name: 'Alloy (Neutral - Clear)', provider: 'openai' },
+  { id: 'echo', name: 'Echo (Male - Warm)', provider: 'openai' },
+  { id: 'fable', name: 'Fable (Expressive - Story)', provider: 'openai' },
+  { id: 'onyx', name: 'Onyx (Male - Deep)', provider: 'openai' },
+  { id: 'shimmer', name: 'Shimmer (Female - Soft)', provider: 'openai' },
+]
+const selectedPuterVoice = ref('nova')
+
+// Browser voices
+const browserVoices = ref<SpeechSynthesisVoice[]>([])
+const selectedBrowserVoiceIndex = ref(0)
+
+const chunks = ref<string[]>([])
+const currentChunkIndex = ref(0)
+let currentAudio: HTMLAudioElement | null = null
+let currentUtterance: SpeechSynthesisUtterance | null = null
+
+// Audio cache and background prefetch maps
+const audioCache = new Map<string, HTMLAudioElement>()
+const prefetchMap = new Map<string, Promise<HTMLAudioElement | null>>()
+
+const clearAudioCache = () => {
+  audioCache.forEach(audio => {
+    audio.pause()
+    audio.src = ''
+  })
+  audioCache.clear()
+  prefetchMap.clear()
+}
+
+const stopSpeech = () => {
+  isPlaying.value = false
+  isPaused.value = false
+  isLoadingModel.value = false
+  loadingProgress.value = ''
+  currentChunkIndex.value = 0
+  chunks.value = []
+  
+  if (currentAudio) {
+    currentAudio.pause()
+    currentAudio = null
+  }
+
+  if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+    window.speechSynthesis.cancel()
+  }
+  currentUtterance = null
+}
+
+const getArticleText = (): string => {
+  if (typeof document === 'undefined') return ''
+  const docElement = document.querySelector('.vp-doc')
+  if (!docElement) return ''
+
+  const clone = docElement.cloneNode(true) as HTMLElement
+  
+  // Remove non-text UI elements
+  clone.querySelectorAll('.line-numbers-wrapper, .copy, .header-anchor, script, style, .read-aloud-container, nav, footer, .VPNav, .VPFooter, button, img, svg, .vp-code, pre, code').forEach(el => el.remove())
+  
+  let text = clone.innerText || clone.textContent || ''
+  
+  // Normalize text for natural speech pacing
+  text = text
+    .replace(/#{1,6}\s+/g, '. ')
+    .replace(/^[\s]*[-*+]\s+/gm, '. ')
+    .replace(/\n+/g, '. ')
+    .replace(/\s+/g, ' ')
+    .replace(/\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi, match => match.replace(/\./g, ''))
+    .replace(/([.!?])\s*([A-Z])/g, '$1 $2')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .trim()
+    
+  return text
+}
+
+const splitIntoChunks = (text: string): string[] => {
+  const rawSentences = text.match(/[^.!?\n]+[.!?\n]+/g) || [text]
+  const result: string[] = []
+  let current = ''
+
+  for (const sentence of rawSentences) {
+    const trimmed = sentence.trim()
+    if (!trimmed) continue
+    if ((current + ' ' + trimmed).length > 250) {
+      if (current) result.push(current.trim())
+      current = trimmed
+    } else {
+      current = current ? current + ' ' + trimmed : trimmed
+    }
+  }
+  if (current.trim()) result.push(current.trim())
+  return result.length > 0 ? result : [text]
+}
+
+const loadBrowserVoices = () => {
+  if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+    const voices = window.speechSynthesis.getVoices()
+    if (!voices || voices.length === 0) return
+    
+    const scoreVoice = (v: SpeechSynthesisVoice) => {
+      let score = 0
+      const name = v.name.toLowerCase()
+      if (name.includes('google') && name.includes('us english')) score += 1000
+      if (name.includes('microsoft') && (name.includes('jenny') || name.includes('guy') || name.includes('aria'))) score += 1000
+      if (name.includes('samantha') || name.includes('alex') || name.includes('daniel')) score += 900
+      if (name.includes('google') || name.includes('microsoft') || name.includes('natural')) score += 500
+      if (v.lang === 'en-US') score += 100
+      else if (v.lang.startsWith('en')) score += 50
+      if (v.default) score += 200
+      return score
+    }
+    
+    const sortedVoices = [...voices].sort((a, b) => scoreVoice(b) - scoreVoice(a))
+    const englishVoices = sortedVoices.filter(v => v.lang.startsWith('en'))
+    browserVoices.value = englishVoices.length > 0 ? englishVoices : sortedVoices
+  }
+}
+
+// Prefetch audio chunk in background and store in cache
+const fetchChunkAudio = (chunkIndex: number): Promise<HTMLAudioElement | null> => {
+  if (chunkIndex < 0 || chunkIndex >= chunks.value.length) {
+    return Promise.resolve(null)
+  }
+
+  const cacheKey = `${selectedPuterVoice.value}:${chunkIndex}:${chunks.value[chunkIndex]}`
+
+  if (audioCache.has(cacheKey)) {
+    return Promise.resolve(audioCache.get(cacheKey)!)
+  }
+
+  if (prefetchMap.has(cacheKey)) {
+    return prefetchMap.get(cacheKey)!
+  }
+
+  const promise = (async () => {
+    try {
+      const puterModule = await import('@heyputer/puter.js')
+      const puter = puterModule.default || puterModule.puter || puterModule
+
+      const audio = await puter.ai.txt2speech(chunks.value[chunkIndex], {
+        provider: 'openai',
+        model: 'tts-1',
+        voice: selectedPuterVoice.value,
+      })
+
+      audioCache.set(cacheKey, audio)
+      prefetchMap.delete(cacheKey)
+      return audio
+    } catch (err) {
+      console.warn(`Failed to prefetch Puter AI chunk ${chunkIndex}:`, err)
+      prefetchMap.delete(cacheKey)
+      return null
+    }
+  })()
+
+  prefetchMap.set(cacheKey, promise)
+  return promise
+}
+
+const speakCurrentPuterChunk = async () => {
+  if (currentChunkIndex.value >= chunks.value.length) {
+    isPlaying.value = false
+    isPaused.value = false
+    isLoadingModel.value = false
+    loadingProgress.value = ''
+    currentChunkIndex.value = 0
+    return
+  }
+
+  const idx = currentChunkIndex.value
+  const cacheKey = `${selectedPuterVoice.value}:${idx}:${chunks.value[idx]}`
+
+  // Show loading indicator only if chunk is not yet cached
+  if (!audioCache.has(cacheKey)) {
+    isLoadingModel.value = true
+    loadingProgress.value = `Loading AI audio (${idx + 1}/${chunks.value.length})...`
+  }
+
+  const audio = await fetchChunkAudio(idx)
+
+  if (!audio || !isPlaying.value) {
+    isLoadingModel.value = false
+    loadingProgress.value = ''
+    if (!audio) {
+      // Fallback to browser if Puter API fails
+      ttsMode.value = 'browser'
+      speakCurrentBrowserChunk()
+    }
+    return
+  }
+
+  isLoadingModel.value = false
+  loadingProgress.value = ''
+
+  if (currentAudio && currentAudio !== audio) {
+    currentAudio.pause()
+  }
+
+  currentAudio = audio
+  currentAudio.currentTime = 0
+  currentAudio.playbackRate = currentRate.value
+
+  // Trigger background pre-fetch for the NEXT 2 chunks so playback never waits!
+  fetchChunkAudio(idx + 1)
+  fetchChunkAudio(idx + 2)
+
+  audio.onended = () => {
+    if (!isPlaying.value || isPaused.value) return
+    currentChunkIndex.value++
+    if (currentChunkIndex.value < chunks.value.length) {
+      speakCurrentPuterChunk()
+    } else {
+      isPlaying.value = false
+      isPaused.value = false
+      currentChunkIndex.value = 0
+    }
+  }
+
+  audio.onerror = (e: any) => {
+    console.warn('Puter audio chunk error, skipping to next:', e)
+    currentChunkIndex.value++
+    if (isPlaying.value && !isPaused.value && currentChunkIndex.value < chunks.value.length) {
+      speakCurrentPuterChunk()
+    } else {
+      isPlaying.value = false
+      isPaused.value = false
+    }
+  }
+
+  await audio.play().catch(() => {})
+}
+
+const speakCurrentBrowserChunk = () => {
+  if (typeof window === 'undefined' || !('speechSynthesis' in window)) return
+  if (currentChunkIndex.value >= chunks.value.length) {
+    isPlaying.value = false
+    isPaused.value = false
+    currentChunkIndex.value = 0
+    return
+  }
+
+  window.speechSynthesis.cancel()
+
+  const text = chunks.value[currentChunkIndex.value]
+  const utterance = new SpeechSynthesisUtterance(text)
+  const voice = browserVoices.value[selectedBrowserVoiceIndex.value]
+  
+  if (voice) {
+    utterance.voice = voice
+    utterance.lang = voice.lang
+  }
+  
+  utterance.rate = currentRate.value
+  utterance.pitch = 1.0
+  utterance.volume = 1.0
+  
+  utterance.onstart = () => {
+    isPlaying.value = true
+    isPaused.value = false
+  }
+  
+  utterance.onend = () => {
+    if (!isPlaying.value || isPaused.value) return
+    currentChunkIndex.value++
+    if (currentChunkIndex.value < chunks.value.length) {
+      speakCurrentBrowserChunk()
+    } else {
+      isPlaying.value = false
+      isPaused.value = false
+      currentChunkIndex.value = 0
+    }
+  }
+  
+  utterance.onerror = (event) => {
+    if (event.error === 'canceled' || event.error === 'interrupted') return
+    console.error('Speech synthesis error:', event.error)
+    currentChunkIndex.value++
+    if (isPlaying.value && !isPaused.value && currentChunkIndex.value < chunks.value.length) {
+      speakCurrentBrowserChunk()
+    } else {
+      isPlaying.value = false
+      isPaused.value = false
+    }
+  }
+
+  currentUtterance = utterance
+  window.speechSynthesis.speak(utterance)
+}
+
+const togglePlayPause = async () => {
+  if (isPlaying.value && !isPaused.value) {
+    // Pause
+    isPaused.value = true
+    if (ttsMode.value === 'browser') {
+      if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+        window.speechSynthesis.cancel()
+      }
+    } else {
+      if (currentAudio) {
+        currentAudio.pause()
+      }
+    }
+    return
+  }
+
+  if (isPaused.value) {
+    // Resume
+    isPaused.value = false
+    isPlaying.value = true
+    if (ttsMode.value === 'browser') {
+      speakCurrentBrowserChunk()
+    } else {
+      if (currentAudio && currentAudio.paused) {
+        currentAudio.play().catch(() => {
+          speakCurrentPuterChunk()
+        })
+      } else {
+        speakCurrentPuterChunk()
+      }
+    }
+    return
+  }
+
+  // Start new speech
+  stopSpeech()
+  const fullText = getArticleText()
+  if (!fullText) return
+
+  chunks.value = splitIntoChunks(fullText)
+  currentChunkIndex.value = 0
+  isPlaying.value = true
+  isPaused.value = false
+
+  if (ttsMode.value === 'puter') {
+    // Start pre-fetching first 2 chunks immediately
+    fetchChunkAudio(0)
+    fetchChunkAudio(1)
+    await speakCurrentPuterChunk()
+  } else {
+    speakCurrentBrowserChunk()
+  }
+}
+
+const setRate = (rate: number) => {
+  currentRate.value = rate
+  if (ttsMode.value === 'puter') {
+    if (currentAudio) {
+      currentAudio.playbackRate = rate
+    }
+  } else {
+    if (isPlaying.value && !isPaused.value) {
+      speakCurrentBrowserChunk()
+    }
+  }
+}
+
+const onEngineChange = () => {
+  if (isPlaying.value || isPaused.value) {
+    stopSpeech()
+  }
+}
+
+const onVoiceChange = () => {
+  clearAudioCache()
+  if (isPlaying.value || isPaused.value) {
+    stopSpeech()
+    setTimeout(() => togglePlayPause(), 50)
+  }
+}
+
+onMounted(() => {
+  if (typeof window !== 'undefined') {
+    if (!('speechSynthesis' in window)) {
+      isSupported.value = false
+    } else {
+      loadBrowserVoices()
+      window.speechSynthesis.onvoiceschanged = loadBrowserVoices
+    }
+  }
+})
+
+watch(() => route.path, () => {
+  stopSpeech()
+  clearAudioCache()
+})
+
+onUnmounted(() => {
+  stopSpeech()
+  clearAudioCache()
+})
+</script>
+
+<template>
+  <div v-if="isSupported" class="read-aloud-container">
+    <div class="read-aloud-bar">
+      <div class="read-aloud-left">
+        <button 
+          class="action-btn main-btn" 
+          :class="{ active: isPlaying && !isPaused, loading: isLoadingModel }"
+          :disabled="isLoadingModel"
+          @click="togglePlayPause"
+          :title="isPlaying && !isPaused ? 'Pause Reading' : (isPaused ? 'Resume Reading' : 'Listen to article')"
+        >
+          <svg v-if="isLoadingModel" class="spinner" viewBox="0 0 24 24" width="18" height="18">
+            <circle class="path" cx="12" cy="12" r="10" fill="none" stroke-width="3"></circle>
+          </svg>
+          <svg v-else-if="!isPlaying || isPaused" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
+            <path d="M8 5v14l11-7z"/>
+          </svg>
+          <svg v-else xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
+            <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z"/>
+          </svg>
+          <span>{{ isLoadingModel ? 'Loading...' : (isPlaying && !isPaused ? 'Pause' : (isPaused ? 'Resume' : 'Listen')) }}</span>
+        </button>
+
+        <button 
+          v-if="isPlaying || isPaused"
+          class="action-btn stop-btn" 
+          @click="stopSpeech"
+          title="Stop Reading"
+        >
+          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+            <path d="M6 6h12v12H6z"/>
+          </svg>
+        </button>
+
+        <span v-if="isLoadingModel" class="loading-text">{{ loadingProgress }}</span>
+      </div>
+
+      <div class="read-aloud-right">
+        <!-- TTS Engine Selector -->
+        <select 
+          v-model="ttsMode" 
+          @change="onEngineChange"
+          class="mode-select"
+          title="Select TTS Engine"
+        >
+          <option value="puter">Puter AI (Natural OpenAI)</option>
+          <option value="browser">Browser Native (Offline)</option>
+        </select>
+
+        <!-- Voice Selector for Puter AI -->
+        <select 
+          v-if="ttsMode === 'puter'"
+          v-model="selectedPuterVoice" 
+          @change="onVoiceChange"
+          class="voice-select"
+          title="Select Puter AI Voice"
+        >
+          <option 
+            v-for="voice in puterVoices" 
+            :key="voice.id" 
+            :value="voice.id"
+          >
+            {{ voice.name }}
+          </option>
+        </select>
+
+        <!-- Voice Selector for Browser Native -->
+        <select 
+          v-else
+          v-model="selectedBrowserVoiceIndex" 
+          @change="onVoiceChange"
+          class="voice-select"
+          title="Select Browser Voice"
+        >
+          <option 
+            v-for="(voice, index) in browserVoices" 
+            :key="voice.name" 
+            :value="index"
+          >
+            {{ voice.name }} ({{ voice.lang }})
+          </option>
+        </select>
+
+        <!-- Speed control -->
+        <div class="speed-selector">
+          <button 
+            v-for="rate in rates" 
+            :key="rate" 
+            class="rate-pill"
+            :class="{ active: currentRate === rate }"
+            @click="setRate(rate)"
+          >
+            {{ rate }}x
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.read-aloud-container {
+  margin: 1rem 0;
+  padding: 0.75rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+}
+
+.read-aloud-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.read-aloud-left,
+.read-aloud-right {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.loading-text {
+  font-size: 0.8rem;
+  color: var(--vp-c-brand-1);
+  font-weight: 500;
+}
+
+.action-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.4rem 0.8rem;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  font-weight: 600;
+  cursor: pointer;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-1);
+  transition: all 0.2s ease;
+}
+
+.action-btn:hover:not(:disabled) {
+  border-color: var(--vp-c-brand-1);
+  color: var(--vp-c-brand-1);
+}
+
+.action-btn.main-btn {
+  background: var(--vp-c-brand-1);
+  color: #ffffff;
+  border-color: var(--vp-c-brand-1);
+}
+
+.action-btn.main-btn:hover:not(:disabled) {
+  background: var(--vp-c-brand-2);
+  border-color: var(--vp-c-brand-2);
+  color: #ffffff;
+}
+
+.action-btn.main-btn.active {
+  background: #eab308;
+  border-color: #eab308;
+  color: #000000;
+}
+
+.action-btn.stop-btn {
+  padding: 0.4rem 0.5rem;
+  color: var(--vp-c-text-2);
+}
+
+.action-btn.stop-btn:hover {
+  border-color: #ef4444;
+  color: #ef4444;
+}
+
+.mode-select,
+.voice-select {
+  padding: 0.35rem 0.6rem;
+  border-radius: 6px;
+  font-size: 0.8rem;
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+  cursor: pointer;
+  max-width: 220px;
+}
+
+.mode-select:focus,
+.voice-select:focus {
+  outline: none;
+  border-color: var(--vp-c-brand-1);
+}
+
+.speed-selector {
+  display: flex;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  padding: 2px;
+}
+
+.rate-pill {
+  border: none;
+  background: transparent;
+  padding: 0.25rem 0.45rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--vp-c-text-2);
+  border-radius: 4px;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.rate-pill:hover {
+  color: var(--vp-c-text-1);
+}
+
+.rate-pill.active {
+  background: var(--vp-c-brand-1);
+  color: #ffffff;
+  font-weight: 600;
+}
+
+.spinner {
+  animation: rotate 1.5s linear infinite;
+}
+
+.spinner .path {
+  stroke: currentColor;
+  stroke-linecap: round;
+  animation: dash 1.5s ease-in-out infinite;
+}
+
+@keyframes rotate {
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes dash {
+  0% {
+    stroke-dasharray: 1, 150;
+    stroke-dashoffset: 0;
+  }
+  50% {
+    stroke-dasharray: 90, 150;
+    stroke-dashoffset: -35;
+  }
+  100% {
+    stroke-dasharray: 90, 150;
+    stroke-dashoffset: -124;
+  }
+}
+
+@media (max-width: 640px) {
+  .read-aloud-bar {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  .read-aloud-right {
+    justify-content: space-between;
+  }
+  .mode-select,
+  .voice-select {
+    max-width: 100%;
+    flex: 1;
+  }
+}
+</style>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 9533c49..5a7c571 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -3,7 +3,10 @@ import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import { useData } from 'vitepress'
 import { createMermaidRenderer } from 'vitepress-mermaid-renderer'
-import { type App } from 'vue'
+import type { App } from 'vue'
+
+import './style.css'
+
 import ChapterMeta from './components/ChapterMeta.vue'
 import MentalModel from './components/MentalModel.vue'
 import CommonMistake from './components/CommonMistake.vue'
@@ -15,27 +18,31 @@ import ChallengeBlock from './components/ChallengeBlock.vue'
 import Recap from './components/Recap.vue'
 import ProjectResult from './components/ProjectResult.vue'
 import ReadingProgress from './components/ReadingProgress.vue'
-import './style.css'
+import ReadAloud from './components/ReadAloud.vue'
 
 export default {
   extends: DefaultTheme,
-  Layout: () => {
+
+  Layout() {
     const { isDark } = useData()
 
-    const initMermaid = () => {
+    const renderMermaid = () => {
       createMermaidRenderer({
-        theme: 'default',
+        theme: isDark.value ? 'dark' : 'default',
       })
     }
 
-    nextTick(() => initMermaid())
-    watch(
-      () => isDark.value,
-      () => initMermaid(),
-    )
+    nextTick(renderMermaid)
+
+    watch(isDark, () => {
+      nextTick(renderMermaid)
+    })
 
-    return h(DefaultTheme.Layout)
+    return h(DefaultTheme.Layout, null, {
+      'doc-before': () => h(ReadAloud),
+    })
   },
+
   enhanceApp({ app }: { app: App }) {
     app.component('ChapterMeta', ChapterMeta)
     app.component('MentalModel', MentalModel)
@@ -48,5 +55,6 @@ export default {
     app.component('Recap', Recap)
     app.component('ProjectResult', ProjectResult)
     app.component('ReadingProgress', ReadingProgress)
+    app.component('ReadAloud', ReadAloud)
   },
-} satisfies Theme
+} satisfies Theme
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index e98aea6..a792c08 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,7 @@
       "name": "the_quickshell_book",
       "version": "1.0.0",
       "dependencies": {
+        "@heyputer/puter.js": "^2.5.4",
         "vitepress": "^1.6.3"
       },
       "devDependencies": {
@@ -20,7 +21,7 @@
         "vitepress-mermaid-renderer": "^1.1.27"
       },
       "engines": {
-        "node": ">=24.0.0"
+        "node": ">=22.0.0"
       }
     },
     "node_modules/@algolia/abtesting": {
@@ -827,6 +828,22 @@
         "node": ">=18"
       }
     },
+    "node_modules/@heyputer/kv.js": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/@heyputer/kv.js/-/kv.js-0.2.1.tgz",
+      "integrity": "sha512-YhVtzz7ZA/HmuaDvzZZhhUyQWBvp3/TXeY4jULssTdLJwT+tEM4BTYHXttORX+V5auvrYinjj8dNFQnby5T82w==",
+      "license": "MIT"
+    },
+    "node_modules/@heyputer/puter.js": {
+      "version": "2.5.4",
+      "resolved": "https://registry.npmjs.org/@heyputer/puter.js/-/puter.js-2.5.4.tgz",
+      "integrity": "sha512-gZNbTB2k+CLL3zG/RHwpQlcj35+rwQyEn1YebwC09aiMlCT9L3Wr9uU0I18fk/tnA3EFWXWC6Zf2yyse2aJ6oQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@heyputer/kv.js": "^0.2.1",
+        "open": "^10.2.0"
+      }
+    },
     "node_modules/@iconify-json/simple-icons": {
       "version": "1.2.91",
       "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.91.tgz",
@@ -2028,6 +2045,21 @@
         "node": ">=8"
       }
     },
+    "node_modules/bundle-name": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bundle-name/-/bundle-name-4.1.0.tgz",
+      "integrity": "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "run-applescript": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/ccount": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz",
@@ -2657,6 +2689,46 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/default-browser": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/default-browser/-/default-browser-5.5.0.tgz",
+      "integrity": "sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==",
+      "license": "MIT",
+      "dependencies": {
+        "bundle-name": "^4.1.0",
+        "default-browser-id": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser-id": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/default-browser-id/-/default-browser-id-5.0.1.tgz",
+      "integrity": "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/define-lazy-prop": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-3.0.0.tgz",
+      "integrity": "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/delaunator": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.1.0.tgz",
@@ -2988,6 +3060,21 @@
         "node": ">=12"
       }
     },
+    "node_modules/is-docker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz",
+      "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==",
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/is-extendable": {
       "version": "0.1.1",
       "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
@@ -3021,6 +3108,24 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-inside-container": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
+      "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==",
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^3.0.0"
+      },
+      "bin": {
+        "is-inside-container": "cli.js"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/is-number": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
@@ -3043,6 +3148,21 @@
         "url": "https://github.com/sponsors/mesqueeb"
       }
     },
+    "node_modules/is-wsl": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.1.tgz",
+      "integrity": "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-inside-container": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/js-yaml": {
       "version": "3.15.0",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz",
@@ -3347,6 +3467,24 @@
         "regex-recursion": "^6.0.2"
       }
     },
+    "node_modules/open": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/open/-/open-10.2.0.tgz",
+      "integrity": "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==",
+      "license": "MIT",
+      "dependencies": {
+        "default-browser": "^5.2.1",
+        "define-lazy-prop": "^3.0.0",
+        "is-inside-container": "^1.0.0",
+        "wsl-utils": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/package-manager-detector": {
       "version": "1.7.0",
       "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.7.0.tgz",
@@ -3618,6 +3756,18 @@
         "points-on-path": "^0.2.1"
       }
     },
+    "node_modules/run-applescript": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/run-applescript/-/run-applescript-7.1.0.tgz",
+      "integrity": "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/run-parallel": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
@@ -4533,6 +4683,21 @@
         }
       }
     },
+    "node_modules/wsl-utils": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/wsl-utils/-/wsl-utils-0.1.0.tgz",
+      "integrity": "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-wsl": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/zwitch": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",
diff --git a/package.json b/package.json
index 6c97477..2a0b52b 100644
--- a/package.json
+++ b/package.json
@@ -15,15 +15,16 @@
     "validate:links": "tsx scripts/validate-links.ts"
   },
   "dependencies": {
+    "@heyputer/puter.js": "^2.5.4",
     "vitepress": "^1.6.3"
   },
   "devDependencies": {
-    "vitepress-mermaid-renderer": "^1.1.27",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
     "mermaid": "^11.6.0",
+    "playwright": "^1.49.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "playwright": "^1.49.0",
-    "gray-matter": "^4.0.3",
-    "fast-glob": "^3.3.2"
+    "vitepress-mermaid-renderer": "^1.1.27"
   }
 }

From 31cbe203eabb6fe6e8d232daf4283357c0941aec Mon Sep 17 00:00:00 2001
From: harshjeet <harshjeetkumar0@gmail.com>
Date: Wed, 22 Jul 2026 08:32:04 +0530
Subject: [PATCH 2/3] feat: implement Read Aloud engine with Puter AI and
 browser TTS support via new composables

---
 .../.vitepress/theme/components/ReadAloud.vue | 436 +-----------------
 .../theme/composables/useArticleText.ts       |  52 +++
 .../theme/composables/useBrowserTTS.ts        |  97 ++++
 .../theme/composables/usePuterTTS.ts          | 139 ++++++
 .../theme/composables/useReadAloudEngine.ts   | 226 +++++++++
 5 files changed, 538 insertions(+), 412 deletions(-)
 create mode 100644 docs/.vitepress/theme/composables/useArticleText.ts
 create mode 100644 docs/.vitepress/theme/composables/useBrowserTTS.ts
 create mode 100644 docs/.vitepress/theme/composables/usePuterTTS.ts
 create mode 100644 docs/.vitepress/theme/composables/useReadAloudEngine.ts

diff --git a/docs/.vitepress/theme/components/ReadAloud.vue b/docs/.vitepress/theme/components/ReadAloud.vue
index f5bc86a..d4822d0 100644
--- a/docs/.vitepress/theme/components/ReadAloud.vue
+++ b/docs/.vitepress/theme/components/ReadAloud.vue
@@ -1,414 +1,26 @@
 <script setup lang="ts">
-import { ref, onMounted, onUnmounted, watch } from 'vue'
-import { useRoute } from 'vitepress'
-
-const route = useRoute()
-
-const isSupported = ref(true)
-const isPlaying = ref(false)
-const isPaused = ref(false)
-const isLoadingModel = ref(false)
-const loadingProgress = ref('')
-const currentRate = ref(1.0)
-const rates = [0.8, 1.0, 1.25, 1.5, 2.0]
-
-// Engine selection
-const ttsMode = ref<'puter' | 'browser'>('puter')
-
-// Puter OpenAI voices
-const puterVoices = [
-  { id: 'nova', name: 'Nova (Female - Natural)', provider: 'openai' },
-  { id: 'alloy', name: 'Alloy (Neutral - Clear)', provider: 'openai' },
-  { id: 'echo', name: 'Echo (Male - Warm)', provider: 'openai' },
-  { id: 'fable', name: 'Fable (Expressive - Story)', provider: 'openai' },
-  { id: 'onyx', name: 'Onyx (Male - Deep)', provider: 'openai' },
-  { id: 'shimmer', name: 'Shimmer (Female - Soft)', provider: 'openai' },
-]
-const selectedPuterVoice = ref('nova')
-
-// Browser voices
-const browserVoices = ref<SpeechSynthesisVoice[]>([])
-const selectedBrowserVoiceIndex = ref(0)
-
-const chunks = ref<string[]>([])
-const currentChunkIndex = ref(0)
-let currentAudio: HTMLAudioElement | null = null
-let currentUtterance: SpeechSynthesisUtterance | null = null
-
-// Audio cache and background prefetch maps
-const audioCache = new Map<string, HTMLAudioElement>()
-const prefetchMap = new Map<string, Promise<HTMLAudioElement | null>>()
-
-const clearAudioCache = () => {
-  audioCache.forEach(audio => {
-    audio.pause()
-    audio.src = ''
-  })
-  audioCache.clear()
-  prefetchMap.clear()
-}
-
-const stopSpeech = () => {
-  isPlaying.value = false
-  isPaused.value = false
-  isLoadingModel.value = false
-  loadingProgress.value = ''
-  currentChunkIndex.value = 0
-  chunks.value = []
-  
-  if (currentAudio) {
-    currentAudio.pause()
-    currentAudio = null
-  }
-
-  if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
-    window.speechSynthesis.cancel()
-  }
-  currentUtterance = null
-}
-
-const getArticleText = (): string => {
-  if (typeof document === 'undefined') return ''
-  const docElement = document.querySelector('.vp-doc')
-  if (!docElement) return ''
-
-  const clone = docElement.cloneNode(true) as HTMLElement
-  
-  // Remove non-text UI elements
-  clone.querySelectorAll('.line-numbers-wrapper, .copy, .header-anchor, script, style, .read-aloud-container, nav, footer, .VPNav, .VPFooter, button, img, svg, .vp-code, pre, code').forEach(el => el.remove())
-  
-  let text = clone.innerText || clone.textContent || ''
-  
-  // Normalize text for natural speech pacing
-  text = text
-    .replace(/#{1,6}\s+/g, '. ')
-    .replace(/^[\s]*[-*+]\s+/gm, '. ')
-    .replace(/\n+/g, '. ')
-    .replace(/\s+/g, ' ')
-    .replace(/\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi, match => match.replace(/\./g, ''))
-    .replace(/([.!?])\s*([A-Z])/g, '$1 $2')
-    .replace(/`([^`]+)`/g, '$1')
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-    .trim()
-    
-  return text
-}
-
-const splitIntoChunks = (text: string): string[] => {
-  const rawSentences = text.match(/[^.!?\n]+[.!?\n]+/g) || [text]
-  const result: string[] = []
-  let current = ''
-
-  for (const sentence of rawSentences) {
-    const trimmed = sentence.trim()
-    if (!trimmed) continue
-    if ((current + ' ' + trimmed).length > 250) {
-      if (current) result.push(current.trim())
-      current = trimmed
-    } else {
-      current = current ? current + ' ' + trimmed : trimmed
-    }
-  }
-  if (current.trim()) result.push(current.trim())
-  return result.length > 0 ? result : [text]
-}
-
-const loadBrowserVoices = () => {
-  if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
-    const voices = window.speechSynthesis.getVoices()
-    if (!voices || voices.length === 0) return
-    
-    const scoreVoice = (v: SpeechSynthesisVoice) => {
-      let score = 0
-      const name = v.name.toLowerCase()
-      if (name.includes('google') && name.includes('us english')) score += 1000
-      if (name.includes('microsoft') && (name.includes('jenny') || name.includes('guy') || name.includes('aria'))) score += 1000
-      if (name.includes('samantha') || name.includes('alex') || name.includes('daniel')) score += 900
-      if (name.includes('google') || name.includes('microsoft') || name.includes('natural')) score += 500
-      if (v.lang === 'en-US') score += 100
-      else if (v.lang.startsWith('en')) score += 50
-      if (v.default) score += 200
-      return score
-    }
-    
-    const sortedVoices = [...voices].sort((a, b) => scoreVoice(b) - scoreVoice(a))
-    const englishVoices = sortedVoices.filter(v => v.lang.startsWith('en'))
-    browserVoices.value = englishVoices.length > 0 ? englishVoices : sortedVoices
-  }
-}
-
-// Prefetch audio chunk in background and store in cache
-const fetchChunkAudio = (chunkIndex: number): Promise<HTMLAudioElement | null> => {
-  if (chunkIndex < 0 || chunkIndex >= chunks.value.length) {
-    return Promise.resolve(null)
-  }
-
-  const cacheKey = `${selectedPuterVoice.value}:${chunkIndex}:${chunks.value[chunkIndex]}`
-
-  if (audioCache.has(cacheKey)) {
-    return Promise.resolve(audioCache.get(cacheKey)!)
-  }
-
-  if (prefetchMap.has(cacheKey)) {
-    return prefetchMap.get(cacheKey)!
-  }
-
-  const promise = (async () => {
-    try {
-      const puterModule = await import('@heyputer/puter.js')
-      const puter = puterModule.default || puterModule.puter || puterModule
-
-      const audio = await puter.ai.txt2speech(chunks.value[chunkIndex], {
-        provider: 'openai',
-        model: 'tts-1',
-        voice: selectedPuterVoice.value,
-      })
-
-      audioCache.set(cacheKey, audio)
-      prefetchMap.delete(cacheKey)
-      return audio
-    } catch (err) {
-      console.warn(`Failed to prefetch Puter AI chunk ${chunkIndex}:`, err)
-      prefetchMap.delete(cacheKey)
-      return null
-    }
-  })()
-
-  prefetchMap.set(cacheKey, promise)
-  return promise
-}
-
-const speakCurrentPuterChunk = async () => {
-  if (currentChunkIndex.value >= chunks.value.length) {
-    isPlaying.value = false
-    isPaused.value = false
-    isLoadingModel.value = false
-    loadingProgress.value = ''
-    currentChunkIndex.value = 0
-    return
-  }
-
-  const idx = currentChunkIndex.value
-  const cacheKey = `${selectedPuterVoice.value}:${idx}:${chunks.value[idx]}`
-
-  // Show loading indicator only if chunk is not yet cached
-  if (!audioCache.has(cacheKey)) {
-    isLoadingModel.value = true
-    loadingProgress.value = `Loading AI audio (${idx + 1}/${chunks.value.length})...`
-  }
-
-  const audio = await fetchChunkAudio(idx)
-
-  if (!audio || !isPlaying.value) {
-    isLoadingModel.value = false
-    loadingProgress.value = ''
-    if (!audio) {
-      // Fallback to browser if Puter API fails
-      ttsMode.value = 'browser'
-      speakCurrentBrowserChunk()
-    }
-    return
-  }
-
-  isLoadingModel.value = false
-  loadingProgress.value = ''
-
-  if (currentAudio && currentAudio !== audio) {
-    currentAudio.pause()
-  }
-
-  currentAudio = audio
-  currentAudio.currentTime = 0
-  currentAudio.playbackRate = currentRate.value
-
-  // Trigger background pre-fetch for the NEXT 2 chunks so playback never waits!
-  fetchChunkAudio(idx + 1)
-  fetchChunkAudio(idx + 2)
-
-  audio.onended = () => {
-    if (!isPlaying.value || isPaused.value) return
-    currentChunkIndex.value++
-    if (currentChunkIndex.value < chunks.value.length) {
-      speakCurrentPuterChunk()
-    } else {
-      isPlaying.value = false
-      isPaused.value = false
-      currentChunkIndex.value = 0
-    }
-  }
-
-  audio.onerror = (e: any) => {
-    console.warn('Puter audio chunk error, skipping to next:', e)
-    currentChunkIndex.value++
-    if (isPlaying.value && !isPaused.value && currentChunkIndex.value < chunks.value.length) {
-      speakCurrentPuterChunk()
-    } else {
-      isPlaying.value = false
-      isPaused.value = false
-    }
-  }
-
-  await audio.play().catch(() => {})
-}
-
-const speakCurrentBrowserChunk = () => {
-  if (typeof window === 'undefined' || !('speechSynthesis' in window)) return
-  if (currentChunkIndex.value >= chunks.value.length) {
-    isPlaying.value = false
-    isPaused.value = false
-    currentChunkIndex.value = 0
-    return
-  }
-
-  window.speechSynthesis.cancel()
-
-  const text = chunks.value[currentChunkIndex.value]
-  const utterance = new SpeechSynthesisUtterance(text)
-  const voice = browserVoices.value[selectedBrowserVoiceIndex.value]
-  
-  if (voice) {
-    utterance.voice = voice
-    utterance.lang = voice.lang
-  }
-  
-  utterance.rate = currentRate.value
-  utterance.pitch = 1.0
-  utterance.volume = 1.0
-  
-  utterance.onstart = () => {
-    isPlaying.value = true
-    isPaused.value = false
-  }
-  
-  utterance.onend = () => {
-    if (!isPlaying.value || isPaused.value) return
-    currentChunkIndex.value++
-    if (currentChunkIndex.value < chunks.value.length) {
-      speakCurrentBrowserChunk()
-    } else {
-      isPlaying.value = false
-      isPaused.value = false
-      currentChunkIndex.value = 0
-    }
-  }
-  
-  utterance.onerror = (event) => {
-    if (event.error === 'canceled' || event.error === 'interrupted') return
-    console.error('Speech synthesis error:', event.error)
-    currentChunkIndex.value++
-    if (isPlaying.value && !isPaused.value && currentChunkIndex.value < chunks.value.length) {
-      speakCurrentBrowserChunk()
-    } else {
-      isPlaying.value = false
-      isPaused.value = false
-    }
-  }
-
-  currentUtterance = utterance
-  window.speechSynthesis.speak(utterance)
-}
-
-const togglePlayPause = async () => {
-  if (isPlaying.value && !isPaused.value) {
-    // Pause
-    isPaused.value = true
-    if (ttsMode.value === 'browser') {
-      if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
-        window.speechSynthesis.cancel()
-      }
-    } else {
-      if (currentAudio) {
-        currentAudio.pause()
-      }
-    }
-    return
-  }
-
-  if (isPaused.value) {
-    // Resume
-    isPaused.value = false
-    isPlaying.value = true
-    if (ttsMode.value === 'browser') {
-      speakCurrentBrowserChunk()
-    } else {
-      if (currentAudio && currentAudio.paused) {
-        currentAudio.play().catch(() => {
-          speakCurrentPuterChunk()
-        })
-      } else {
-        speakCurrentPuterChunk()
-      }
-    }
-    return
-  }
-
-  // Start new speech
-  stopSpeech()
-  const fullText = getArticleText()
-  if (!fullText) return
-
-  chunks.value = splitIntoChunks(fullText)
-  currentChunkIndex.value = 0
-  isPlaying.value = true
-  isPaused.value = false
-
-  if (ttsMode.value === 'puter') {
-    // Start pre-fetching first 2 chunks immediately
-    fetchChunkAudio(0)
-    fetchChunkAudio(1)
-    await speakCurrentPuterChunk()
-  } else {
-    speakCurrentBrowserChunk()
-  }
-}
-
-const setRate = (rate: number) => {
-  currentRate.value = rate
-  if (ttsMode.value === 'puter') {
-    if (currentAudio) {
-      currentAudio.playbackRate = rate
-    }
-  } else {
-    if (isPlaying.value && !isPaused.value) {
-      speakCurrentBrowserChunk()
-    }
-  }
-}
-
-const onEngineChange = () => {
-  if (isPlaying.value || isPaused.value) {
-    stopSpeech()
-  }
-}
-
-const onVoiceChange = () => {
-  clearAudioCache()
-  if (isPlaying.value || isPaused.value) {
-    stopSpeech()
-    setTimeout(() => togglePlayPause(), 50)
-  }
-}
-
-onMounted(() => {
-  if (typeof window !== 'undefined') {
-    if (!('speechSynthesis' in window)) {
-      isSupported.value = false
-    } else {
-      loadBrowserVoices()
-      window.speechSynthesis.onvoiceschanged = loadBrowserVoices
-    }
-  }
-})
-
-watch(() => route.path, () => {
-  stopSpeech()
-  clearAudioCache()
-})
-
-onUnmounted(() => {
-  stopSpeech()
-  clearAudioCache()
-})
+import { useReadAloudEngine } from '../composables/useReadAloudEngine'
+
+const {
+  isSupported,
+  ttsMode,
+  isPlaying,
+  isPaused,
+  isLoadingModel,
+  loadingProgress,
+  currentRate,
+  rates,
+  puterVoices,
+  selectedPuterVoice,
+  browserVoices,
+  selectedBrowserVoiceIndex,
+  isBrowserSupported,
+  togglePlayPause,
+  stopSpeech,
+  setRate,
+  onEngineChange,
+  onVoiceChange,
+} = useReadAloudEngine()
 </script>
 
 <template>
@@ -457,7 +69,7 @@ onUnmounted(() => {
           title="Select TTS Engine"
         >
           <option value="puter">Puter AI (Natural OpenAI)</option>
-          <option value="browser">Browser Native (Offline)</option>
+          <option v-if="isBrowserSupported" value="browser">Browser Native (Offline)</option>
         </select>
 
         <!-- Voice Selector for Puter AI -->
@@ -479,7 +91,7 @@ onUnmounted(() => {
 
         <!-- Voice Selector for Browser Native -->
         <select 
-          v-else
+          v-else-if="ttsMode === 'browser' && isBrowserSupported"
           v-model="selectedBrowserVoiceIndex" 
           @change="onVoiceChange"
           class="voice-select"
diff --git a/docs/.vitepress/theme/composables/useArticleText.ts b/docs/.vitepress/theme/composables/useArticleText.ts
new file mode 100644
index 0000000..55b55fd
--- /dev/null
+++ b/docs/.vitepress/theme/composables/useArticleText.ts
@@ -0,0 +1,52 @@
+export function useArticleText() {
+  const getArticleText = (): string => {
+    if (typeof document === 'undefined') return ''
+    const docElement = document.querySelector('.vp-doc')
+    if (!docElement) return ''
+
+    const clone = docElement.cloneNode(true) as HTMLElement
+    
+    // Remove non-text UI elements
+    clone.querySelectorAll('.line-numbers-wrapper, .copy, .header-anchor, script, style, .read-aloud-container, nav, footer, .VPNav, .VPFooter, button, img, svg, .vp-code, pre, code').forEach(el => el.remove())
+    
+    let text = clone.innerText || clone.textContent || ''
+    
+    // Normalize text for natural speech pacing
+    text = text
+      .replace(/#{1,6}\s+/g, '. ')
+      .replace(/^[\s]*[-*+]\s+/gm, '. ')
+      .replace(/\n+/g, '. ')
+      .replace(/\s+/g, ' ')
+      .replace(/\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi, match => match.replace(/\./g, ''))
+      .replace(/([.!?])\s*([A-Z])/g, '$1 $2')
+      .replace(/`([^`]+)`/g, '$1')
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+      .trim()
+      
+    return text
+  }
+
+  const splitIntoChunks = (text: string): string[] => {
+    const rawSentences = text.match(/[^.!?\n]+[.!?\n]+/g) || [text]
+    const result: string[] = []
+    let current = ''
+
+    for (const sentence of rawSentences) {
+      const trimmed = sentence.trim()
+      if (!trimmed) continue
+      if ((current + ' ' + trimmed).length > 250) {
+        if (current) result.push(current.trim())
+        current = trimmed
+      } else {
+        current = current ? current + ' ' + trimmed : trimmed
+      }
+    }
+    if (current.trim()) result.push(current.trim())
+    return result.length > 0 ? result : [text]
+  }
+
+  return {
+    getArticleText,
+    splitIntoChunks,
+  }
+}
diff --git a/docs/.vitepress/theme/composables/useBrowserTTS.ts b/docs/.vitepress/theme/composables/useBrowserTTS.ts
new file mode 100644
index 0000000..7983aa5
--- /dev/null
+++ b/docs/.vitepress/theme/composables/useBrowserTTS.ts
@@ -0,0 +1,97 @@
+import { ref, onMounted, onUnmounted } from 'vue'
+
+export function useBrowserTTS() {
+  const isBrowserSupported = ref(false)
+  const browserVoices = ref<SpeechSynthesisVoice[]>([])
+  const selectedBrowserVoiceIndex = ref(0)
+  let currentUtterance: SpeechSynthesisUtterance | null = null
+
+  const loadBrowserVoices = () => {
+    if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+      const voices = window.speechSynthesis.getVoices()
+      if (!voices || voices.length === 0) return
+      
+      const scoreVoice = (v: SpeechSynthesisVoice) => {
+        let score = 0
+        const name = v.name.toLowerCase()
+        if (name.includes('google') && name.includes('us english')) score += 1000
+        if (name.includes('microsoft') && (name.includes('jenny') || name.includes('guy') || name.includes('aria'))) score += 1000
+        if (name.includes('samantha') || name.includes('alex') || name.includes('daniel')) score += 900
+        if (name.includes('google') || name.includes('microsoft') || name.includes('natural')) score += 500
+        if (v.lang === 'en-US') score += 100
+        else if (v.lang.startsWith('en')) score += 50
+        if (v.default) score += 200
+        return score
+      }
+      
+      const sortedVoices = [...voices].sort((a, b) => scoreVoice(b) - scoreVoice(a))
+      const englishVoices = sortedVoices.filter(v => v.lang.startsWith('en'))
+      browserVoices.value = englishVoices.length > 0 ? englishVoices : sortedVoices
+    }
+  }
+
+  onMounted(() => {
+    if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+      isBrowserSupported.value = true
+      loadBrowserVoices()
+      window.speechSynthesis.onvoiceschanged = loadBrowserVoices
+    } else {
+      isBrowserSupported.value = false
+    }
+  })
+
+  onUnmounted(() => {
+    if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+      if (window.speechSynthesis.onvoiceschanged === loadBrowserVoices) {
+        window.speechSynthesis.onvoiceschanged = null
+      }
+      window.speechSynthesis.cancel()
+    }
+    currentUtterance = null
+  })
+
+  const speakBrowserChunk = (
+    text: string,
+    rate: number,
+    onStart: () => void,
+    onEnd: () => void,
+    onError: (err: any) => void
+  ) => {
+    if (typeof window === 'undefined' || !('speechSynthesis' in window)) return
+
+    window.speechSynthesis.cancel()
+
+    const utterance = new SpeechSynthesisUtterance(text)
+    const voice = browserVoices.value[selectedBrowserVoiceIndex.value]
+    if (voice) {
+      utterance.voice = voice
+      utterance.lang = voice.lang
+    }
+
+    utterance.rate = rate
+    utterance.pitch = 1.0
+    utterance.volume = 1.0
+
+    utterance.onstart = () => onStart()
+    utterance.onend = () => onEnd()
+    utterance.onerror = (event) => onError(event)
+
+    currentUtterance = utterance
+    window.speechSynthesis.speak(utterance)
+  }
+
+  const stopBrowserTTS = () => {
+    if (typeof window !== 'undefined' && 'speechSynthesis' in window) {
+      window.speechSynthesis.cancel()
+    }
+    currentUtterance = null
+  }
+
+  return {
+    isBrowserSupported,
+    browserVoices,
+    selectedBrowserVoiceIndex,
+    speakBrowserChunk,
+    stopBrowserTTS,
+  }
+}
diff --git a/docs/.vitepress/theme/composables/usePuterTTS.ts b/docs/.vitepress/theme/composables/usePuterTTS.ts
new file mode 100644
index 0000000..c2aa4fe
--- /dev/null
+++ b/docs/.vitepress/theme/composables/usePuterTTS.ts
@@ -0,0 +1,139 @@
+import { ref } from 'vue'
+
+export interface PuterVoice {
+  id: string
+  name: string
+  provider: string
+}
+
+export function usePuterTTS() {
+  const puterVoices: PuterVoice[] = [
+    { id: 'nova', name: 'Nova (Female - Natural)', provider: 'openai' },
+    { id: 'alloy', name: 'Alloy (Neutral - Clear)', provider: 'openai' },
+    { id: 'echo', name: 'Echo (Male - Warm)', provider: 'openai' },
+    { id: 'fable', name: 'Fable (Expressive - Story)', provider: 'openai' },
+    { id: 'onyx', name: 'Onyx (Male - Deep)', provider: 'openai' },
+    { id: 'shimmer', name: 'Shimmer (Female - Soft)', provider: 'openai' },
+  ]
+  const selectedPuterVoice = ref('nova')
+
+  let currentAudio: HTMLAudioElement | null = null
+
+  // Lightweight Audio Cache & Prefetch Map using key format: `${voice}:${idx}`
+  const audioCache = new Map<string, HTMLAudioElement>()
+  const prefetchMap = new Map<string, Promise<HTMLAudioElement | null>>()
+
+  const clearAudioCache = () => {
+    audioCache.forEach(audio => {
+      audio.pause()
+      audio.src = ''
+    })
+    audioCache.clear()
+    prefetchMap.clear()
+  }
+
+  const fetchPuterChunk = (chunkIndex: number, chunks: string[]): Promise<HTMLAudioElement | null> => {
+    if (chunkIndex < 0 || chunkIndex >= chunks.length) {
+      return Promise.resolve(null)
+    }
+
+    // Optimized memory key: voice:index
+    const cacheKey = `${selectedPuterVoice.value}:${chunkIndex}`
+
+    if (audioCache.has(cacheKey)) {
+      return Promise.resolve(audioCache.get(cacheKey)!)
+    }
+
+    if (prefetchMap.has(cacheKey)) {
+      return prefetchMap.get(cacheKey)!
+    }
+
+    const promise = (async () => {
+      try {
+        const puterModule = await import('@heyputer/puter.js')
+        const puter = puterModule.default || puterModule.puter || puterModule
+
+        const audio = await puter.ai.txt2speech(chunks[chunkIndex], {
+          provider: 'openai',
+          model: 'tts-1',
+          voice: selectedPuterVoice.value,
+        })
+
+        audioCache.set(cacheKey, audio)
+        prefetchMap.delete(cacheKey)
+        return audio
+      } catch (err) {
+        console.warn(`Failed to prefetch Puter AI chunk ${chunkIndex}:`, err)
+        prefetchMap.delete(cacheKey)
+        return null
+      }
+    })()
+
+    prefetchMap.set(cacheKey, promise)
+    return promise
+  }
+
+  const isPuterChunkCached = (chunkIndex: number): boolean => {
+    const cacheKey = `${selectedPuterVoice.value}:${chunkIndex}`
+    return audioCache.has(cacheKey)
+  }
+
+  const stopPuterAudio = () => {
+    if (currentAudio) {
+      currentAudio.pause()
+      currentAudio = null
+    }
+  }
+
+  const playPuterAudio = async (
+    audio: HTMLAudioElement,
+    rate: number,
+    onEnded: () => void,
+    onError: (e: any) => void
+  ) => {
+    if (currentAudio && currentAudio !== audio) {
+      currentAudio.pause()
+    }
+
+    currentAudio = audio
+    currentAudio.currentTime = 0
+    currentAudio.playbackRate = rate
+
+    audio.onended = onEnded
+    audio.onerror = onError
+
+    await audio.play().catch(() => {})
+  }
+
+  const pausePuterAudio = () => {
+    if (currentAudio) {
+      currentAudio.pause()
+    }
+  }
+
+  const resumePuterAudio = () => {
+    if (currentAudio && currentAudio.paused) {
+      return currentAudio.play()
+    }
+    return Promise.resolve()
+  }
+
+  const setPuterRate = (rate: number) => {
+    if (currentAudio) {
+      currentAudio.playbackRate = rate
+    }
+  }
+
+  return {
+    puterVoices,
+    selectedPuterVoice,
+    fetchPuterChunk,
+    isPuterChunkCached,
+    playPuterAudio,
+    pausePuterAudio,
+    resumePuterAudio,
+    stopPuterAudio,
+    setPuterRate,
+    clearAudioCache,
+  }
+}
diff --git a/docs/.vitepress/theme/composables/useReadAloudEngine.ts b/docs/.vitepress/theme/composables/useReadAloudEngine.ts
new file mode 100644
index 0000000..aae61ad
--- /dev/null
+++ b/docs/.vitepress/theme/composables/useReadAloudEngine.ts
@@ -0,0 +1,226 @@
+import { ref, watch, onUnmounted, computed } from 'vue'
+import { useRoute } from 'vitepress'
+import { useArticleText } from './useArticleText'
+import { useBrowserTTS } from './useBrowserTTS'
+import { usePuterTTS } from './usePuterTTS'
+
+export function useReadAloudEngine() {
+  const route = useRoute()
+  const { getArticleText, splitIntoChunks } = useArticleText()
+  const browserTTS = useBrowserTTS()
+  const puterTTS = usePuterTTS()
+
+  const ttsMode = ref<'puter' | 'browser'>('puter')
+  const isPlaying = ref(false)
+  const isPaused = ref(false)
+  const isLoadingModel = ref(false)
+  const loadingProgress = ref('')
+  const currentRate = ref(1.0)
+  const rates = [0.8, 1.0, 1.25, 1.5, 2.0]
+
+  const chunks = ref<string[]>([])
+  const currentChunkIndex = ref(0)
+
+  // Decoupled support check: Puter TTS works keylessly in any browser with internet;
+  // Component is supported if either Puter AI is available or Browser Speech API is available.
+  const isSupported = computed(() => true)
+
+  const stopSpeech = () => {
+    isPlaying.value = false
+    isPaused.value = false
+    isLoadingModel.value = false
+    loadingProgress.value = ''
+    currentChunkIndex.value = 0
+    chunks.value = []
+
+    puterTTS.stopPuterAudio()
+    browserTTS.stopBrowserTTS()
+  }
+
+  const speakNextPuterChunk = async () => {
+    if (currentChunkIndex.value >= chunks.value.length) {
+      stopSpeech()
+      return
+    }
+
+    const idx = currentChunkIndex.value
+
+    if (!puterTTS.isPuterChunkCached(idx)) {
+      isLoadingModel.value = true
+      loadingProgress.value = `Loading AI audio (${idx + 1}/${chunks.value.length})...`
+    }
+
+    const audio = await puterTTS.fetchPuterChunk(idx, chunks.value)
+
+    if (!audio || !isPlaying.value) {
+      isLoadingModel.value = false
+      loadingProgress.value = ''
+      if (!audio) {
+        // Fallback to browser TTS if Puter AI fails
+        if (browserTTS.isBrowserSupported.value) {
+          ttsMode.value = 'browser'
+          speakNextBrowserChunk()
+        } else {
+          stopSpeech()
+        }
+      }
+      return
+    }
+
+    isLoadingModel.value = false
+    loadingProgress.value = ''
+
+    // Pre-fetch next 2 chunks in parallel
+    puterTTS.fetchPuterChunk(idx + 1, chunks.value)
+    puterTTS.fetchPuterChunk(idx + 2, chunks.value)
+
+    await puterTTS.playPuterAudio(
+      audio,
+      currentRate.value,
+      () => {
+        if (!isPlaying.value || isPaused.value) return
+        currentChunkIndex.value++
+        speakNextPuterChunk()
+      },
+      (err) => {
+        console.warn('Puter audio chunk playback error:', err)
+        currentChunkIndex.value++
+        if (isPlaying.value && !isPaused.value) {
+          speakNextPuterChunk()
+        }
+      }
+    )
+  }
+
+  const speakNextBrowserChunk = () => {
+    if (currentChunkIndex.value >= chunks.value.length) {
+      stopSpeech()
+      return
+    }
+
+    const idx = currentChunkIndex.value
+    const text = chunks.value[idx]
+
+    browserTTS.speakBrowserChunk(
+      text,
+      currentRate.value,
+      () => {
+        isPlaying.value = true
+        isPaused.value = false
+      },
+      () => {
+        if (!isPlaying.value || isPaused.value) return
+        currentChunkIndex.value++
+        speakNextBrowserChunk()
+      },
+      (event) => {
+        if (event.error === 'canceled' || event.error === 'interrupted') return
+        currentChunkIndex.value++
+        if (isPlaying.value && !isPaused.value) {
+          speakNextBrowserChunk()
+        }
+      }
+    )
+  }
+
+  const togglePlayPause = async () => {
+    if (isPlaying.value && !isPaused.value) {
+      // Pause
+      isPaused.value = true
+      if (ttsMode.value === 'browser') {
+        browserTTS.stopBrowserTTS()
+      } else {
+        puterTTS.pausePuterAudio()
+      }
+      return
+    }
+
+    if (isPaused.value) {
+      // Resume
+      isPaused.value = false
+      isPlaying.value = true
+      if (ttsMode.value === 'browser') {
+        speakNextBrowserChunk()
+      } else {
+        puterTTS.resumePuterAudio().catch(() => {
+          speakNextPuterChunk()
+        })
+      }
+      return
+    }
+
+    // Start new speech
+    stopSpeech()
+    const fullText = getArticleText()
+    if (!fullText) return
+
+    chunks.value = splitIntoChunks(fullText)
+    currentChunkIndex.value = 0
+    isPlaying.value = true
+    isPaused.value = false
+
+    if (ttsMode.value === 'puter') {
+      puterTTS.fetchPuterChunk(0, chunks.value)
+      puterTTS.fetchPuterChunk(1, chunks.value)
+      await speakNextPuterChunk()
+    } else {
+      speakNextBrowserChunk()
+    }
+  }
+
+  const setRate = (rate: number) => {
+    currentRate.value = rate
+    if (ttsMode.value === 'puter') {
+      puterTTS.setPuterRate(rate)
+    } else {
+      if (isPlaying.value && !isPaused.value) {
+        speakNextBrowserChunk()
+      }
+    }
+  }
+
+  const onEngineChange = () => {
+    if (isPlaying.value || isPaused.value) {
+      stopSpeech()
+    }
+  }
+
+  const onVoiceChange = () => {
+    puterTTS.clearAudioCache()
+    if (isPlaying.value || isPaused.value) {
+      stopSpeech()
+      setTimeout(() => togglePlayPause(), 50)
+    }
+  }
+
+  watch(() => route.path, () => {
+    stopSpeech()
+    puterTTS.clearAudioCache()
+  })
+
+  onUnmounted(() => {
+    stopSpeech()
+    puterTTS.clearAudioCache()
+  })
+
+  return {
+    isSupported,
+    ttsMode,
+    isPlaying,
+    isPaused,
+    isLoadingModel,
+    loadingProgress,
+    currentRate,
+    rates,
+    togglePlayPause,
+    stopSpeech,
+    setRate,
+    onEngineChange,
+    onVoiceChange,
+    puterVoices: puterTTS.puterVoices,
+    selectedPuterVoice: puterTTS.selectedPuterVoice,
+    browserVoices: browserTTS.browserVoices,
+    selectedBrowserVoiceIndex: browserTTS.selectedBrowserVoiceIndex,
+    isBrowserSupported: browserTTS.isBrowserSupported,
+  }
+}

From 16046cf7b2f807a33b7d8f16d35115c05b1cef81 Mon Sep 17 00:00:00 2001
From: harshjeet <harshjeetkumar0@gmail.com>
Date: Wed, 22 Jul 2026 08:38:50 +0530
Subject: [PATCH 3/3] feat: implement real-time text highlighting and improved
 chunking for read-aloud engine

---
 .../.vitepress/theme/components/ReadAloud.vue |  19 +++
 .../theme/composables/useArticleText.ts       | 110 +++++++++++-------
 .../theme/composables/usePuterTTS.ts          |   6 +-
 .../theme/composables/useReadAloudEngine.ts   |  31 ++---
 4 files changed, 108 insertions(+), 58 deletions(-)

diff --git a/docs/.vitepress/theme/components/ReadAloud.vue b/docs/.vitepress/theme/components/ReadAloud.vue
index d4822d0..7ecdbe0 100644
--- a/docs/.vitepress/theme/components/ReadAloud.vue
+++ b/docs/.vitepress/theme/components/ReadAloud.vue
@@ -294,4 +294,23 @@ const {
     flex: 1;
   }
 }
+</style>
+
+<style>
+/* Global text highlighting styling for currently read DOM element */
+.read-aloud-highlight {
+  background-color: #fef08a !important;
+  color: #0f172a !important;
+  border-radius: 6px;
+  padding: 2px 6px;
+  transition: all 0.3s ease-in-out;
+  box-shadow: 0 0 0 2px #fde047, 0 4px 6px -1px rgba(234, 179, 8, 0.2);
+}
+
+.dark .read-aloud-highlight {
+  background-color: rgba(234, 179, 8, 0.3) !important;
+  color: #fef9c3 !important;
+  border-radius: 6px;
+  box-shadow: 0 0 0 2px rgba(234, 179, 8, 0.5), 0 4px 6px -1px rgba(0, 0, 0, 0.3);
+}
 </style>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/composables/useArticleText.ts b/docs/.vitepress/theme/composables/useArticleText.ts
index 55b55fd..290b543 100644
--- a/docs/.vitepress/theme/composables/useArticleText.ts
+++ b/docs/.vitepress/theme/composables/useArticleText.ts
@@ -1,52 +1,78 @@
+export interface ChunkItem {
+  text: string
+  element: Element | null
+}
+
 export function useArticleText() {
-  const getArticleText = (): string => {
-    if (typeof document === 'undefined') return ''
+  const getArticleChunks = (): ChunkItem[] => {
+    if (typeof document === 'undefined') return []
     const docElement = document.querySelector('.vp-doc')
-    if (!docElement) return ''
-
-    const clone = docElement.cloneNode(true) as HTMLElement
-    
-    // Remove non-text UI elements
-    clone.querySelectorAll('.line-numbers-wrapper, .copy, .header-anchor, script, style, .read-aloud-container, nav, footer, .VPNav, .VPFooter, button, img, svg, .vp-code, pre, code').forEach(el => el.remove())
-    
-    let text = clone.innerText || clone.textContent || ''
-    
-    // Normalize text for natural speech pacing
-    text = text
-      .replace(/#{1,6}\s+/g, '. ')
-      .replace(/^[\s]*[-*+]\s+/gm, '. ')
-      .replace(/\n+/g, '. ')
-      .replace(/\s+/g, ' ')
-      .replace(/\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi, match => match.replace(/\./g, ''))
-      .replace(/([.!?])\s*([A-Z])/g, '$1 $2')
-      .replace(/`([^`]+)`/g, '$1')
-      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-      .trim()
-      
-    return text
-  }
+    if (!docElement) return []
+
+    const elements = docElement.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, blockquote')
+    const chunks: ChunkItem[] = []
+
+    elements.forEach((el) => {
+      // Exclude UI controls, read-aloud component, pre & code blocks
+      if (el.closest('.read-aloud-container, pre, .vp-code')) return
+
+      const clone = el.cloneNode(true) as HTMLElement
+      clone.querySelectorAll('.line-numbers-wrapper, .copy, .header-anchor, script, style, .read-aloud-container, button, img, svg, code').forEach(child => child.remove())
+
+      let text = clone.innerText || clone.textContent || ''
+      text = text
+        .replace(/\s+/g, ' ')
+        .replace(/\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi, match => match.replace(/\./g, ''))
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+        .trim()
+
+      if (!text) return
+
+      const rawSentences = text.match(/[^.!?\n]+[.!?\n]+/g) || [text]
+      let current = ''
 
-  const splitIntoChunks = (text: string): string[] => {
-    const rawSentences = text.match(/[^.!?\n]+[.!?\n]+/g) || [text]
-    const result: string[] = []
-    let current = ''
-
-    for (const sentence of rawSentences) {
-      const trimmed = sentence.trim()
-      if (!trimmed) continue
-      if ((current + ' ' + trimmed).length > 250) {
-        if (current) result.push(current.trim())
-        current = trimmed
-      } else {
-        current = current ? current + ' ' + trimmed : trimmed
+      for (const sentence of rawSentences) {
+        const trimmed = sentence.trim()
+        if (!trimmed) continue
+        if ((current + ' ' + trimmed).length > 250) {
+          if (current) chunks.push({ text: current.trim(), element: el })
+          current = trimmed
+        } else {
+          current = current ? current + ' ' + trimmed : trimmed
+        }
       }
+      if (current.trim()) {
+        chunks.push({ text: current.trim(), element: el })
+      }
+    })
+
+    return chunks
+  }
+
+  const highlightElement = (el: Element | null) => {
+    if (typeof document === 'undefined') return
+
+    document.querySelectorAll('.read-aloud-highlight').forEach(item => {
+      item.classList.remove('read-aloud-highlight')
+    })
+
+    if (el) {
+      el.classList.add('read-aloud-highlight')
+      el.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
     }
-    if (current.trim()) result.push(current.trim())
-    return result.length > 0 ? result : [text]
+  }
+
+  const clearHighlight = () => {
+    if (typeof document === 'undefined') return
+    document.querySelectorAll('.read-aloud-highlight').forEach(item => {
+      item.classList.remove('read-aloud-highlight')
+    })
   }
 
   return {
-    getArticleText,
-    splitIntoChunks,
+    getArticleChunks,
+    highlightElement,
+    clearHighlight,
   }
 }
diff --git a/docs/.vitepress/theme/composables/usePuterTTS.ts b/docs/.vitepress/theme/composables/usePuterTTS.ts
index c2aa4fe..368bd35 100644
--- a/docs/.vitepress/theme/composables/usePuterTTS.ts
+++ b/docs/.vitepress/theme/composables/usePuterTTS.ts
@@ -1,4 +1,5 @@
 import { ref } from 'vue'
+import type { ChunkItem } from './useArticleText'
 
 export interface PuterVoice {
   id: string
@@ -32,12 +33,11 @@ export function usePuterTTS() {
     prefetchMap.clear()
   }
 
-  const fetchPuterChunk = (chunkIndex: number, chunks: string[]): Promise<HTMLAudioElement | null> => {
+  const fetchPuterChunk = (chunkIndex: number, chunks: ChunkItem[]): Promise<HTMLAudioElement | null> => {
     if (chunkIndex < 0 || chunkIndex >= chunks.length) {
       return Promise.resolve(null)
     }
 
-    // Optimized memory key: voice:index
     const cacheKey = `${selectedPuterVoice.value}:${chunkIndex}`
 
     if (audioCache.has(cacheKey)) {
@@ -53,7 +53,7 @@ export function usePuterTTS() {
         const puterModule = await import('@heyputer/puter.js')
         const puter = puterModule.default || puterModule.puter || puterModule
 
-        const audio = await puter.ai.txt2speech(chunks[chunkIndex], {
+        const audio = await puter.ai.txt2speech(chunks[chunkIndex].text, {
           provider: 'openai',
           model: 'tts-1',
           voice: selectedPuterVoice.value,
diff --git a/docs/.vitepress/theme/composables/useReadAloudEngine.ts b/docs/.vitepress/theme/composables/useReadAloudEngine.ts
index aae61ad..33a8722 100644
--- a/docs/.vitepress/theme/composables/useReadAloudEngine.ts
+++ b/docs/.vitepress/theme/composables/useReadAloudEngine.ts
@@ -1,12 +1,12 @@
 import { ref, watch, onUnmounted, computed } from 'vue'
 import { useRoute } from 'vitepress'
-import { useArticleText } from './useArticleText'
+import { useArticleText, type ChunkItem } from './useArticleText'
 import { useBrowserTTS } from './useBrowserTTS'
 import { usePuterTTS } from './usePuterTTS'
 
 export function useReadAloudEngine() {
   const route = useRoute()
-  const { getArticleText, splitIntoChunks } = useArticleText()
+  const { getArticleChunks, highlightElement, clearHighlight } = useArticleText()
   const browserTTS = useBrowserTTS()
   const puterTTS = usePuterTTS()
 
@@ -18,11 +18,9 @@ export function useReadAloudEngine() {
   const currentRate = ref(1.0)
   const rates = [0.8, 1.0, 1.25, 1.5, 2.0]
 
-  const chunks = ref<string[]>([])
+  const chunks = ref<ChunkItem[]>([])
   const currentChunkIndex = ref(0)
 
-  // Decoupled support check: Puter TTS works keylessly in any browser with internet;
-  // Component is supported if either Puter AI is available or Browser Speech API is available.
   const isSupported = computed(() => true)
 
   const stopSpeech = () => {
@@ -33,6 +31,7 @@ export function useReadAloudEngine() {
     currentChunkIndex.value = 0
     chunks.value = []
 
+    clearHighlight()
     puterTTS.stopPuterAudio()
     browserTTS.stopBrowserTTS()
   }
@@ -44,6 +43,10 @@ export function useReadAloudEngine() {
     }
 
     const idx = currentChunkIndex.value
+    const currentChunk = chunks.value[idx]
+
+    // Highlight active DOM element in yellow
+    highlightElement(currentChunk ? currentChunk.element : null)
 
     if (!puterTTS.isPuterChunkCached(idx)) {
       isLoadingModel.value = true
@@ -56,7 +59,6 @@ export function useReadAloudEngine() {
       isLoadingModel.value = false
       loadingProgress.value = ''
       if (!audio) {
-        // Fallback to browser TTS if Puter AI fails
         if (browserTTS.isBrowserSupported.value) {
           ttsMode.value = 'browser'
           speakNextBrowserChunk()
@@ -99,10 +101,13 @@ export function useReadAloudEngine() {
     }
 
     const idx = currentChunkIndex.value
-    const text = chunks.value[idx]
+    const currentChunk = chunks.value[idx]
+
+    // Highlight active DOM element in yellow
+    highlightElement(currentChunk ? currentChunk.element : null)
 
     browserTTS.speakBrowserChunk(
-      text,
+      currentChunk.text,
       currentRate.value,
       () => {
         isPlaying.value = true
@@ -125,7 +130,7 @@ export function useReadAloudEngine() {
 
   const togglePlayPause = async () => {
     if (isPlaying.value && !isPaused.value) {
-      // Pause
+      // Pause: Keep highlight visible on current element
       isPaused.value = true
       if (ttsMode.value === 'browser') {
         browserTTS.stopBrowserTTS()
@@ -149,12 +154,12 @@ export function useReadAloudEngine() {
       return
     }
 
-    // Start new speech
+    // Start fresh
     stopSpeech()
-    const fullText = getArticleText()
-    if (!fullText) return
+    const articleChunks = getArticleChunks()
+    if (!articleChunks || articleChunks.length === 0) return
 
-    chunks.value = splitIntoChunks(fullText)
+    chunks.value = articleChunks
     currentChunkIndex.value = 0
     isPlaying.value = true
     isPaused.value = false