codymaster 4.1.0

package/skills/cm-readit/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: cm-readit
+description: Turn any website into an audio-enabled experience. Covers TTS reading mode (SpeechSynthesis API), pre-recorded MP3 audio player, and Voice CRO trigger system. Zero dependencies, works on any static or dynamic site. Use when adding read-aloud, audio player, or voice-based conversion features.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# CM ReadIt — Web Audio Experience Skill
+
+> **Philosophy:** Reading is passive. Listening is intimate. Voice builds trust faster than any headline.
+> **Core Principle:** Zero dependencies. Progressive enhancement. Respect user's device and preferences.
+
+---
+
+## 🎯 Selective Reading Rule (MANDATORY)
+
+| File | Status | When to Read |
+|------|--------|--------------|
+| [tts-engine.md](tts-engine.md) | 🔴 **REQUIRED** | Adding TTS / read-aloud to any page |
+| [audio-player.md](audio-player.md) | ⚪ Optional | Pre-recorded MP3 playback |
+| [voice-cro.md](voice-cro.md) | ⚪ Optional | Trigger-based voice sales / CRO |
+| [ui-patterns.md](ui-patterns.md) | ⚪ Optional | Player bar & bottom sheet design |
+
+> 🔴 **tts-engine.md = ALWAYS READ when implementing TTS. Others = only if relevant.**
+
+---
+
+## Quick Decision Tree
+
+```
+"I need audio on my website"
+│
+├─ Read article content aloud (text-to-speech)
+│  └─ Use: TTS Engine → tts-engine.md
+│     ├─ Blog / article pages → Content Reader pattern
+│     ├─ Documentation → Section Reader pattern
+│     └─ E-commerce → Product Description Reader pattern
+│
+├─ Play pre-recorded audio files (MP3/WAV)
+│  └─ Use: Audio Player → audio-player.md
+│     ├─ Podcasts / interviews → Playlist pattern
+│     ├─ Sales pitch / welcome → Triggered playback
+│     └─ Background ambient → Loop pattern
+│
+├─ Voice-based conversion optimization (CRO)
+│  └─ Use: Voice CRO → voice-cro.md
+│     ├─ Landing pages → Trigger-based bottom sheet
+│     ├─ Service pages → Per-page audio scripts
+│     └─ Course pages → Social proof audio
+│
+└─ Combination (TTS + CRO)
+   └─ Read tts-engine.md + voice-cro.md
+      └─ Ensure no conflict (TTS reader vs CRO player)
+```
+
+---
+
+## 🧠 Core Principles (Internalize These)
+
+### 1. The 3 Audio Engines
+
+| Engine | API | Source | Best For |
+|--------|-----|--------|----------|
+| **TTS Reader** | `SpeechSynthesis` | Page text content | Blogs, articles, docs |
+| **Audio Player** | `HTMLAudioElement` | Pre-recorded MP3 | Sales, podcasts, guides |
+| **Voice CRO** | `Audio` + triggers | MP3 + behavior detection | Landing pages, sales |
+
+### 2. Progressive Enhancement
+
+```
+Feature detection → Graceful degradation → Never break the page
+
+if (!('speechSynthesis' in window)) return;  // TTS
+if (!window.Audio) return;                    // Audio
+```
+
+**Rule:** Audio features are ENHANCEMENTS. The page must function 100% without them.
+
+### 3. Content Extraction Principle
+
+```
+Clone → Strip → Clean → Split → Speak
+
+DON'T read the raw DOM.
+DO clone, remove noise, extract clean text.
+```
+
+**Strip list (always remove before speaking):**
+- CTAs, promotions, ads
+- Navigation, footer, sidebar
+- Images, videos, iframes, SVGs
+- Scripts, styles, hidden elements
+- Tags, badges, metadata
+
+### 4. The Chunking Problem
+
+Browsers have a **hard limit** on utterance length (~3000-5000 chars depending on browser/OS). Long text must be split into chunks.
+
+```
+Split Strategy:
+├─ Split on sentence boundaries (. ! ? \n)
+├─ Max chunk: 2500 chars (safe across all browsers)
+├─ Preserve sentence integrity (never split mid-sentence)
+└─ Chain chunks via onend callback
+```
+
+### 5. Voice Selection Priority
+
+```
+Language voices:
+1. Local service voice (faster, works offline)
+2. Network voice (higher quality, needs internet)
+3. Any voice matching language prefix
+4. null (browser default)
+```
+
+### 6. Chrome Keep-Alive Bug
+
+> ⚠️ **CRITICAL:** Chrome silently stops SpeechSynthesis after ~15 seconds of continuous speech. This is the #1 gotcha.
+
+```javascript
+// Workaround: pause/resume every 10s
+setInterval(() => {
+    if (synth.speaking && !synth.paused) {
+        synth.pause();
+        synth.resume();
+    }
+}, 10000);
+```
+
+### 7. synth.cancel() Triggers onerror
+
+> ⚠️ **GOTCHA:** Calling `synth.cancel()` fires the `onerror` event on any active utterance with error type `'canceled'` or `'interrupted'`.
+
+**Solution:** Use a guard flag or check error type:
+```javascript
+u.onerror = function(e) {
+    if (e.error === 'canceled' || e.error === 'interrupted') return;
+    stopReading();
+};
+```
+
+---
+
+## 🏗️ Architecture Pattern
+
+### Minimal TTS Reader (Copy-Paste Starting Point)
+
+```
+┌─────────────────────────────────────────┐
+│                  IIFE                    │
+│                                          │
+│  ┌─ Feature Detection ─┐                │
+│  │  speechSynthesis?    │                │
+│  └──────────┬───────────┘                │
+│             ▼                            │
+│  ┌─ Content Extraction ─┐               │
+│  │  Clone → Strip → Clean│              │
+│  └──────────┬────────────┘               │
+│             ▼                            │
+│  ┌─ Chunking Engine ────┐               │
+│  │  Split on sentences   │              │
+│  │  Max 2500 chars       │              │
+│  └──────────┬────────────┘               │
+│             ▼                            │
+│  ┌─ Utterance Builder ──┐               │
+│  │  Set voice/rate/pitch │              │
+│  │  Chain via onend      │              │
+│  └──────────┬────────────┘               │
+│             ▼                            │
+│  ┌─ Player UI ──────────┐               │
+│  │  Bar: play/pause/stop │              │
+│  │  Progress indicator   │              │
+│  │  Trigger button       │              │
+│  └──────────┬────────────┘               │
+│             ▼                            │
+│  ┌─ Keep-Alive Timer ───┐               │
+│  │  pause/resume @ 10s  │               │
+│  └───────────────────────┘               │
+└──────────────────────────────────────────┘
+```
+
+### Lifecycle
+
+```
+Init → Detect → Inject Trigger Button
+         │
+   User clicks ▶
+         │
+   Extract Text → Chunk → Build Utterances
+         │
+   synth.speak(chunk[0])
+         │
+   chunk[0].onend → speak(chunk[1]) → ... → speak(chunk[N])
+         │                                        │
+   Keep-Alive Timer running                   chunk[N].onend
+         │                                        │
+   User clicks ⏸ → synth.pause()             stopReading()
+   User clicks ▶ → synth.resume()            cleanup UI
+   User clicks ✕ → synth.cancel()
+```
+
+---
+
+## 📐 Implementation Checklist
+
+### For TTS Reader
+- [ ] Feature detection (`speechSynthesis` in window)
+- [ ] Content container identified (ID or selector)
+- [ ] Strip list defined (what to remove before reading)
+- [ ] Chunk size set (default 2500)
+- [ ] Voice selection logic (language-specific)
+- [ ] Player bar UI (play/pause/close + progress)
+- [ ] Trigger button injected (topbar or floating)
+- [ ] Chrome keep-alive timer (10s interval)
+- [ ] `onerror` guard (handle cancel/interrupted)
+- [ ] `beforeunload` cleanup
+- [ ] `prefers-reduced-motion` respect
+- [ ] Mobile safe-area padding
+
+### For Audio Player
+- [ ] Audio files hosted and accessible
+- [ ] Preload strategy (`none` → load on demand)
+- [ ] Play/pause toggle with state management
+- [ ] Progress bar with `currentTime/duration`
+- [ ] Error handling (network, format, autoplay policy)
+- [ ] Session state (dismissed = don't show again)
+
+### For Voice CRO
+- [ ] Per-page config object (delay, scroll threshold, audio URLs)
+- [ ] Trigger conditions (time + scroll AND/OR interaction)
+- [ ] Bottom sheet UI (icon, text, CTA, dismiss)
+- [ ] Player bar UI (toggle, progress, CTA button)
+- [ ] Session dismissal tracking
+- [ ] Stats tracking (shown/listened/dismissed)
+- [ ] No conflict with TTS Reader
+
+---
+
+## ⚠️ Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---------|---------|-----|
+| Chrome stops after 15s | Audio cuts mid-sentence | Keep-alive timer (pause/resume) |
+| `synth.cancel()` fires onerror | Settings sheet closes immediately | Guard flag or check error type |
+| Voices not loaded | No voice available | Listen for `voiceschanged` event |
+| Chunk too large | Utterance fails silently | Max 2500 chars per chunk |
+| Reading CTA text | TTS reads "Book Now" button text | Strip non-content elements |
+| Autoplay blocked | Audio won't start on mobile | Require user interaction first |
+| Multiple audio conflicts | TTS + CRO play simultaneously | Mutual exclusion check |
+| No cleanup on nav | Audio keeps playing | `beforeunload` → `synth.cancel()` |
+
+---
+
+## 🌐 Multi-Language Support
+
+```
+Voice selection by language:
+├─ Vietnamese: v.lang === 'vi-VN' || v.lang.startsWith('vi')
+├─ English: v.lang === 'en-US' || v.lang.startsWith('en')
+├─ Japanese: v.lang === 'ja-JP' || v.lang.startsWith('ja')
+├─ Korean: v.lang === 'ko-KR' || v.lang.startsWith('ko')
+└─ Any: Pass language code as config parameter
+```
+
+Set `utterance.lang` to match the content language for correct pronunciation.
+
+---
+
+## 📚 Reference Files
+
+| File | Content |
+|------|---------|
+| [tts-engine.md](tts-engine.md) | Complete SpeechSynthesis API reference, chunking strategies, voice selection |
+| [audio-player.md](audio-player.md) | HTMLAudioElement patterns, preload strategies, error handling |
+| [voice-cro.md](voice-cro.md) | Trigger system, bottom sheet patterns, CRO analytics |
+| [ui-patterns.md](ui-patterns.md) | Player bar CSS, bottom sheet CSS, animations, responsive design |
+
+---
+
+## 🔗 Reference Implementations
+
+| File | Description |
+|------|-------------|
+| [examples/blog-reader.js](examples/blog-reader.js) | Complete TTS reader — Substack-style, 350 LOC |
+| [examples/voice-cro.js](examples/voice-cro.js) | Complete Voice CRO trigger system — 390 LOC |
+
+---
+
+> **Remember:** Voice is the most personal interface. A well-placed audio feature can increase engagement 3-5x. But unwanted audio is the fastest way to lose a user. **Always require user initiation. Never autoplay.**

package/skills/cm-readit/audio-player.md

@@ -0,0 +1,206 @@
+# Audio Player — Pre-Recorded MP3 Patterns
+
+> For when you have pre-recorded audio files (sales pitch, podcast, guide) instead of generating speech from text.
+
+---
+
+## API Quick Reference
+
+```javascript
+const audio = new Audio('/path/to/file.mp3');
+
+// Core methods
+audio.play()               // Returns Promise (may reject: autoplay policy)
+audio.pause()
+audio.load()               // Reload source
+
+// Properties
+audio.src                  // Source URL
+audio.currentTime          // Current position (seconds)
+audio.duration             // Total duration (NaN until loaded)
+audio.paused               // boolean
+audio.ended                // boolean
+audio.volume               // 0.0 — 1.0
+audio.playbackRate         // 0.25 — 4.0
+audio.preload              // 'none' | 'metadata' | 'auto'
+
+// Events
+audio.onplay = fn;
+audio.onpause = fn;
+audio.onended = fn;
+audio.onerror = fn;
+audio.ontimeupdate = fn;   // Fires during playback (~4x/second)
+audio.onloadedmetadata = fn; // duration now available
+audio.oncanplay = fn;      // Enough data to start playing
+```
+
+---
+
+## Patterns
+
+### Simple Play/Pause Toggle
+
+```javascript
+let audio = null;
+let isPlaying = false;
+
+function play(src) {
+    if (!audio) audio = new Audio(src);
+    
+    const promise = audio.play();
+    if (promise) {
+        promise
+            .then(() => { isPlaying = true; updateUI(); })
+            .catch(() => { isPlaying = false; updateUI(); });
+    }
+}
+
+function togglePause() {
+    if (!audio) return;
+    if (audio.paused) {
+        audio.play();
+        isPlaying = true;
+    } else {
+        audio.pause();
+        isPlaying = false;
+    }
+    updateUI();
+}
+
+function stop() {
+    if (audio) {
+        audio.pause();
+        audio.currentTime = 0;
+        audio = null;
+    }
+    isPlaying = false;
+    updateUI();
+}
+```
+
+### Progress Tracking
+
+```javascript
+function startProgressTracking(audioEl, barEl) {
+    const update = () => {
+        if (!audioEl || !barEl) return;
+        if (audioEl.duration) {
+            barEl.style.width = (audioEl.currentTime / audioEl.duration * 100) + '%';
+        }
+        if (!audioEl.paused && !audioEl.ended) {
+            requestAnimationFrame(update);
+        }
+    };
+    
+    audioEl.addEventListener('play', () => requestAnimationFrame(update));
+    requestAnimationFrame(update);
+}
+```
+
+### 2-Part Audio Flow (Intro → Full)
+
+```javascript
+function playIntro(cfg) {
+    playingPart = 1;
+    showPlayer();
+    
+    playAudio(cfg.audio[0], () => {
+        // Intro done → offer full version
+        showNextButton();
+        updateLabel('Bạn muốn nghe thêm?');
+    });
+}
+
+function playFull(cfg) {
+    playingPart = 2;
+    hideNextButton();
+    
+    playAudio(cfg.audio[1], () => {
+        // Full done → show CTA
+        updateLabel('Cảm ơn bạn đã lắng nghe!');
+        showCTA();
+    });
+}
+```
+
+---
+
+## Preload Strategies
+
+| Strategy | Value | When to Use |
+|----------|-------|------------|
+| `none` | Don't preload | Default. Save bandwidth. Load on demand. |
+| `metadata` | Load duration/size | When showing duration in UI |
+| `auto` | Preload full file | Small files (<500KB) that will definitely play |
+
+**Recommendation:** Always default to `'none'`. Only preload when user has indicated intent to listen.
+
+---
+
+## Autoplay Policy
+
+> ⚠️ All modern browsers block autoplay of audio without user interaction.
+
+**Rule:** NEVER try to autoplay. Always require a user gesture (click/tap) before first `audio.play()`.
+
+```javascript
+// ❌ WRONG: This will be blocked
+window.onload = () => new Audio('/intro.mp3').play();
+
+// ✅ CORRECT: User initiates
+button.addEventListener('click', () => {
+    new Audio('/intro.mp3').play();
+});
+```
+
+---
+
+## Error Handling
+
+```javascript
+audio.addEventListener('error', (e) => {
+    switch (audio.error?.code) {
+        case MediaError.MEDIA_ERR_ABORTED:
+            // User aborted — ignore
+            break;
+        case MediaError.MEDIA_ERR_NETWORK:
+            // Network error — show retry
+            showRetryButton();
+            break;
+        case MediaError.MEDIA_ERR_DECODE:
+            // Decode error — file corrupted
+            showError('File audio bị lỗi');
+            break;
+        case MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED:
+            // Format not supported
+            showError('Trình duyệt không hỗ trợ');
+            break;
+    }
+});
+```
+
+---
+
+## Format Support
+
+| Format | Chrome | Safari | Firefox | Edge |
+|--------|--------|--------|---------|------|
+| MP3 | ✅ | ✅ | ✅ | ✅ |
+| AAC | ✅ | ✅ | ✅ | ✅ |
+| OGG | ✅ | ❌ | ✅ | ✅ |
+| WAV | ✅ | ✅ | ✅ | ✅ |
+| WebM | ✅ | ❌ | ✅ | ✅ |
+
+**Recommendation:** Use **MP3** for maximum compatibility. 128kbps is sufficient for voice.
+
+---
+
+## File Size Guidelines
+
+| Content Type | Duration | Recommended Bitrate | Approx. Size |
+|-------------|----------|-------------------|--------------|
+| Voice only | 30s | 64 kbps | ~240 KB |
+| Voice + ambient | 60s | 128 kbps | ~960 KB |
+| High quality | 2 min | 192 kbps | ~2.8 MB |
+
+**Rule of thumb:** Keep audio files under **1 MB** for mobile users. Split long content into intro + full.