@supernal/tts-widget 1.0.0

package/MIGRATION.md

@@ -0,0 +1,502 @@
+# Migration Guide: v1.2.x → v1.3.0
+
+## What Changed?
+
+Version 1.3.0 introduces a **Smart Loader** that gives you automatic updates via CDN while maintaining backward compatibility with bundled code.
+
+### Key Benefits
+
+✅ **Always up-to-date** - Get bug fixes and features automatically
+✅ **Zero-config** - Works out of the box with sensible defaults
+✅ **Graceful fallback** - CSP/firewall scenarios handled automatically
+✅ **Full control** - Opt into bundled mode or pin versions when needed
+
+---
+
+## Breaking Changes
+
+**None!** 🎉
+
+Existing code continues to work exactly as before. The smart loader is opt-in.
+
+---
+
+## Recommended Migration
+
+### Before (v1.2.x)
+
+```javascript
+import { SupernalTTS } from '@supernal/tts-widget';
+import '@supernal/tts-widget/widget.css';
+
+SupernalTTS.init({
+  apiUrl: 'https://tts.supernal.ai',
+  provider: 'openai',
+  voice: 'alloy'
+});
+```
+
+**Behavior:** Loads bundled widget from `node_modules` (never updates)
+
+### After (v1.3.0) - Option 1: Smart Loader (Recommended)
+
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+import '@supernal/tts-widget/widget.css';
+
+const widget = await WidgetLoader.load(); // CDN @1 with fallback
+widget.init({
+  apiUrl: 'https://tts.supernal.ai',
+  provider: 'openai',
+  voice: 'alloy'
+});
+```
+
+**Behavior:**
+1. Tries to load from `https://unpkg.com/@supernal/tts-widget@1/dist/widget.js`
+2. If CDN fails (CSP/firewall/timeout): Falls back to bundled version
+3. Always gets latest v1.x.x (patches and minors auto-apply)
+
+### After (v1.3.0) - Option 2: Keep Bundled (No Change Required!)
+
+```javascript
+import { SupernalTTS } from '@supernal/tts-widget';
+import '@supernal/tts-widget/widget.css';
+
+SupernalTTS.init({
+  apiUrl: 'https://tts.supernal.ai',
+  provider: 'openai',
+  voice: 'alloy'
+});
+```
+
+**Behavior:** Identical to v1.2.x - always uses bundled widget
+**Note:** Your existing code already uses this pattern - no changes needed!
+
+---
+
+## React Migration
+
+### Before (v1.2.x)
+
+```tsx
+import { TTSInitializer } from '@supernal/tts-widget/react';
+
+function App() {
+  return (
+    <>
+      <TTSInitializer apiUrl="https://tts.supernal.ai" />
+      <YourApp />
+    </>
+  );
+}
+```
+
+### After (v1.3.0) - Default (Smart Loader)
+
+```tsx
+import { TTSInitializer } from '@supernal/tts-widget/react';
+
+function App() {
+  return (
+    <>
+      <TTSInitializer
+        apiUrl="https://tts.supernal.ai"
+        mode="auto"      // NEW: Try CDN, fallback to bundled (default)
+        version="major"  // NEW: Load latest v1.x.x (default)
+      />
+      <YourApp />
+    </>
+  );
+}
+```
+
+### After (v1.3.0) - CSP-Safe Mode
+
+```tsx
+import { TTSInitializer } from '@supernal/tts-widget/react';
+
+function App() {
+  return (
+    <>
+      <TTSInitializer
+        apiUrl="https://tts.supernal.ai"
+        mode="bundled"   // Force local version (no CDN)
+      />
+      <YourApp />
+    </>
+  );
+}
+```
+
+---
+
+## Upgrade Strategies
+
+### Strategy 1: Gradual Adoption (Recommended)
+
+**Timeline:** Upgrade npm package now, migrate code later
+
+```bash
+npm install @supernal/tts-widget@1.3.0
+```
+
+**Keep existing code:**
+```javascript
+import { SupernalTTS } from '@supernal/tts-widget';
+// Old behavior, no changes needed
+```
+
+**Migrate when ready:**
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+const widget = await WidgetLoader.load();
+// New behavior, always up-to-date
+```
+
+---
+
+### Strategy 2: Immediate Auto-Update
+
+**For:** Users who want latest features automatically
+
+```bash
+npm install @supernal/tts-widget@1.3.0
+```
+
+**Update all imports:**
+```diff
+- import { SupernalTTS } from '@supernal/tts-widget';
++ import { WidgetLoader } from '@supernal/tts-widget/loader';
+
++ const widget = await WidgetLoader.load();
+- SupernalTTS.init({ ... });
++ widget.init({ ... });
+```
+
+**Benefits:**
+- Get bug fixes without npm updates
+- New features arrive automatically
+- Fallback ensures it works everywhere
+
+---
+
+### Strategy 3: Version Pinning
+
+**For:** Production apps that need stability
+
+```bash
+npm install @supernal/tts-widget@1.3.0
+```
+
+**Pin to current version:**
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+
+const widget = await WidgetLoader.load({
+  version: '1.3.0'  // Lock to exact version
+});
+
+widget.init({ ... });
+```
+
+**When to upgrade:**
+- Test new versions in staging
+- Pin to tested version in production
+- Update pin after verification
+
+---
+
+## Configuration Options
+
+### Version Strategies
+
+```javascript
+// Major version pinning (default, recommended)
+WidgetLoader.load({ version: 'major' })
+// → Loads latest v1.x.x from unpkg.com/@supernal/tts-widget@1/
+
+// Always latest (risky, not recommended)
+WidgetLoader.load({ version: 'latest' })
+// → Loads absolute latest, even v2.0.0 breaking changes
+
+// Specific version (stability)
+WidgetLoader.load({ version: '1.3.0' })
+// → Locks to exactly v1.3.0, never updates
+```
+
+### Loading Modes
+
+```javascript
+// Auto mode (default) - Try CDN, fallback to bundled
+WidgetLoader.load({ mode: 'auto' })
+
+// CDN only - Error if CDN unavailable
+WidgetLoader.load({ mode: 'cdn' })
+
+// Bundled only - Never use CDN (CSP-safe)
+WidgetLoader.load({ mode: 'bundled' })
+```
+
+### Advanced Options
+
+```javascript
+WidgetLoader.load({
+  mode: 'auto',
+  version: 'major',
+  timeout: 5000,  // CDN timeout in ms (default: 3000)
+  cdnUrl: 'https://cdn.example.com/widget',  // Custom CDN
+
+  onCdnSuccess: () => {
+    console.log('Loaded from CDN');
+  },
+
+  onCdnFail: (error) => {
+    console.warn('CDN failed, using bundled:', error);
+  }
+})
+```
+
+---
+
+## Common Use Cases
+
+### Use Case 1: Public Blog (Auto-Update)
+
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+import '@supernal/tts-widget/widget.css';
+
+const widget = await WidgetLoader.load();
+widget.init({
+  apiUrl: 'https://tts.supernal.ai',
+  voice: 'alloy'
+});
+```
+
+**Why:** Get latest features and bug fixes automatically
+
+---
+
+### Use Case 2: Corporate Intranet (Bundled Only)
+
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+import '@supernal/tts-widget/widget.css';
+
+const widget = await WidgetLoader.load({ mode: 'bundled' });
+widget.init({
+  apiUrl: 'https://tts.internal.company.com',
+  voice: 'alloy'
+});
+```
+
+**Why:** Firewall blocks external CDN, need bundled version
+
+---
+
+### Use Case 3: E-Commerce Site (Pinned Version)
+
+```javascript
+import { WidgetLoader } from '@supernal/tts-widget/loader';
+import '@supernal/tts-widget/widget.css';
+
+const widget = await WidgetLoader.load({ version: '1.3.0' });
+widget.init({
+  apiUrl: 'https://tts.supernal.ai',
+  voice: 'nova'
+});
+```
+
+**Why:** Production stability critical, test updates before deploying
+
+---
+
+### Use Case 4: Next.js App with React
+
+```tsx
+// app/layout.tsx
+import { TTSInitializer } from '@supernal/tts-widget/react';
+import '@supernal/tts-widget/widget.css';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <TTSInitializer
+          apiUrl="https://tts.supernal.ai"
+          mode="auto"
+          version="major"
+        />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+**Why:** React integration with automatic updates and SSR support
+
+---
+
+## Troubleshooting
+
+### Issue 1: "Module not found: WidgetLoader"
+
+**Cause:** Old version installed
+
+**Fix:**
+```bash
+npm install @supernal/tts-widget@1.3.0
+```
+
+---
+
+### Issue 2: Widget loads slowly (3s delay)
+
+**Cause:** CDN timeout before fallback
+
+**Fix:** Either force bundled mode or increase timeout
+```javascript
+// Option A: Force bundled (no CDN delay)
+WidgetLoader.load({ mode: 'bundled' })
+
+// Option B: Increase timeout
+WidgetLoader.load({ timeout: 10000 })
+```
+
+---
+
+### Issue 3: CSP violation error
+
+**Cause:** Content Security Policy blocks unpkg.com
+
+**Fix:** Use bundled mode
+```javascript
+WidgetLoader.load({ mode: 'bundled' })
+```
+
+Or update CSP to allow unpkg:
+```html
+<meta http-equiv="Content-Security-Policy"
+      content="script-src 'self' https://unpkg.com">
+```
+
+---
+
+### Issue 4: TypeScript errors with new imports
+
+**Cause:** TypeScript cache not updated
+
+**Fix:**
+```bash
+# Clear TypeScript cache
+rm -rf node_modules/.cache
+npm install
+
+# Restart TypeScript server in VS Code
+Cmd+Shift+P → "TypeScript: Restart TS Server"
+```
+
+---
+
+## Rollback Plan
+
+If you encounter issues with v1.3.0, you can rollback:
+
+### Option 1: Downgrade to v1.2.1
+
+```bash
+npm install @supernal/tts-widget@1.2.1
+```
+
+### Option 2: Keep v1.3.0 but use bundled mode
+
+```javascript
+import { SupernalTTS } from '@supernal/tts-widget';
+// Identical to v1.2.1 behavior
+```
+
+---
+
+## FAQs
+
+### Q: Do I need to update my code?
+
+**A:** No, existing code works as-is. The smart loader is opt-in.
+
+---
+
+### Q: Will this increase my bundle size?
+
+**A:** Slightly. The loader adds ~2KB, but CDN caching saves bandwidth long-term.
+
+**Bundle sizes:**
+- v1.2.1: 13.3KB (widget) + 4KB (CSS) = **17.3KB**
+- v1.3.0: 2KB (loader) + 13.3KB (bundled fallback) + 4KB (CSS) = **19.3KB**
+- v1.3.0 (CDN hit): 2KB (loader) + 4KB (CSS) = **6KB** (widget cached by browser)
+
+---
+
+### Q: What if unpkg.com goes down?
+
+**A:** Automatic fallback to bundled version ensures your site keeps working.
+
+---
+
+### Q: How do I know if CDN or bundled is loading?
+
+**A:** Check browser console for loader messages:
+```
+[TTS Widget] Attempting CDN load...
+[TTS Widget] CDN load successful
+```
+or
+```
+[TTS Widget] CDN load failed: timeout
+[TTS Widget] Falling back to bundled version
+```
+
+---
+
+### Q: Can I self-host the CDN version?
+
+**A:** Yes, but not recommended. Use bundled mode instead:
+```javascript
+WidgetLoader.load({ mode: 'bundled' })
+```
+
+If you must self-host:
+```javascript
+WidgetLoader.load({
+  cdnUrl: 'https://cdn.yoursite.com/tts-widget',
+  version: '1.3.0'
+})
+```
+
+---
+
+### Q: What happens on major version updates (v2.0.0)?
+
+**A:** Your code continues loading v1.x.x until you explicitly upgrade:
+```javascript
+// Still loads v1.x.x
+WidgetLoader.load({ version: 'major' })
+
+// Opt into v2.0.0
+WidgetLoader.load({ version: '2' })
+```
+
+---
+
+## Need Help?
+
+- **Documentation:** https://tts.supernal.ai/docs
+- **GitHub Issues:** https://github.com/supernalintelligence/supernal-tts/issues
+- **Email:** support@supernal.ai
+
+---
+
+**Last Updated:** 2026-01-21
+**Current Version:** 1.3.0
+**Status:** Stable