@spectrumsense/spectrum-chat-dev/docs/V1_VS_V2_COMPARISON.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Spectrum Chat: v1 vs v2 Comparison

## Quick Decision Guide

**Choose v2 if**:
- ✅ You're starting fresh (new integration)
- ✅ You want simplicity (one-line installation)
- ✅ You don't need custom element
- ✅ You want latest architecture

**Stick with v1 if**:
- ⚠️ You're already using custom element mode extensively
- ⚠️ You need time to migrate
- ⚠️ You have custom integrations that depend on v1 API

## Side-by-Side Comparison

### Installation

| Feature | v1 | v2 |
|---------|----|----|
| **Custom Element** | ✅ `<spectrum-chat site-key="...">` | ❌ Removed |
| **Global Mode** | ✅ `window.SpectrumChatConfig` | ✅ `window.SpectrumChatConfig` |
| **One-Line Install** | ❌ Not available | ✅ `data-*` attributes |
| **Setup Steps** | 2-3 lines | 1 line |

### Architecture

| Aspect | v1 | v2 |
|--------|----|----|
| **Lines of Code** | ~2000 | ~480 |
| **Foundation** | Custom UI + DeepChat | DeepChat only |
| **Modes** | 2 (custom element + global) | 1 (global only) |
| **Code Duplication** | High (separate UIs) | None |
| **Maintainability** | Complex | Simple |

### Features

| Feature | v1 | v2 |
|---------|----|----|
| **JWT Security** | ✅ | ✅ |
| **Site-Key Validation** | ✅ | ✅ |
| **Conversation Persistence** | ✅ | ✅ |
| **Citations** | ✅ | ✅ |
| **Mobile Responsive** | ✅ | ✅ Improved |
| **Fixed Positioning** | ✅ | ✅ Better isolation |
| **Custom Styling** | ✅ | ✅ |
| **Public API** | ✅ | ✅ Enhanced |

### Security

| Feature | v1 | v2 |
|---------|----|----|
| **Phase 0 (Site-Key)** | ✅ | ✅ |
| **Phase 1 (JWT)** | ✅ | ✅ |
| **Auto Token Refresh** | ✅ | ✅ |
| **Origin Validation** | ✅ | ✅ |
| **Page URL Hashing** | ✅ | ✅ |
| **Request Nonces** | ✅ | ✅ |

**Verdict**: Security is identical in both versions.

### Performance

| Metric | v1 | v2 | Winner |
|--------|----|----|--------|
| **File Size** | ~80KB | ~40KB | 🏆 v2 |
| **Parse Time** | ~100ms | ~50ms | 🏆 v2 |
| **Memory Usage** | ~5MB | ~3MB | 🏆 v2 |
| **Load Time** | ~200ms | ~150ms | 🏆 v2 |

**Verdict**: v2 is faster and lighter.

### API Comparison

#### Opening/Closing

**v1**:
```javascript
// Custom element
document.querySelector('spectrum-chat').open();

// Global mode  
window.SpectrumChatGlobal.open();
```

**v2**:
```javascript
// Always the same
window.SpectrumChat.open();
```

#### Configuration

**v1 Custom Element**:
```html
<spectrum-chat 
  site-key="xyz" 
  title="Help" 
  primary-color="#007bff">
</spectrum-chat>
```

**v1 Global**:
```javascript
window.SpectrumChatConfig = {
  siteKey: 'xyz',
  title: 'Help',
  primaryColor: '#007bff'
};
```

**v2 One-Line**:
```html
<script src="..." 
        data-site-key="xyz" 
        data-title="Help" 
        data-primary-color="#007bff"></script>
```

**v2 Global** (same as v1):
```javascript
window.SpectrumChatConfig = {
  siteKey: 'xyz',
  title: 'Help',
  primaryColor: '#007bff'
};
```

### Mobile Experience

| Aspect | v1 | v2 |
|--------|----|----|
| **Centering** | Manual | Automatic |
| **Responsive Width** | Fixed | calc(100vw - 20px) |
| **Responsive Height** | Fixed | 70vh |
| **FAB Position** | Fixed corner | Auto-center |
| **Media Queries** | Basic | Enhanced |

**Verdict**: v2 has better mobile UX out of the box.

### Code Examples

#### v1: Custom Element Mode

```html
<!-- Include script -->
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@1.0.0/dist/spectrum-chat.js"></script>

<!-- Add custom element -->
<spectrum-chat 
  api-url="https://api.example.com/api/v1/conversations"
  site-key="pub_customer_xyz"
  title="Help Center"
  primary-color="#007bff"
  width="400px"
  height="600px"
  citations="true">
</spectrum-chat>

<!-- Control via JS -->
<script>
  const chat = document.querySelector('spectrum-chat');
  chat.open();
</script>
```

#### v1: Global Mode

```html
<!-- Configure -->
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://api.example.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz',
    title: 'Help Center',
    primaryColor: '#007bff',
    width: '400px',
    height: '600px',
    enableCitations: true
  };
</script>

<!-- Include script -->
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@1.0.0/dist/spectrum-chat.js"></script>

<!-- Control via JS -->
<script>
  window.SpectrumChatGlobal.open();
</script>
```

#### v2: One-Line Installation

```html
<!-- Single line with data-* attributes -->
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@2.0.0/dist/spectrum-chat.js" 
        data-api-url="https://api.example.com/api/v1/conversations"
        data-site-key="pub_customer_xyz"
        data-title="Help Center"
        data-primary-color="#007bff"
        data-width="400px"
        data-height="600px"
        data-enable-citations="true"></script>

<!-- Control via JS -->
<script>
  window.SpectrumChat.open();
</script>
```

#### v2: Global Config (same as v1)

```html
<!-- Configure -->
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://api.example.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz',
    title: 'Help Center',
    primaryColor: '#007bff',
    width: '400px',
    height: '600px',
    enableCitations: true
  };
</script>

<!-- Include script -->
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@2.0.0/dist/spectrum-chat.js"></script>

<!-- Control via JS -->
<script>
  window.SpectrumChat.open();
</script>
```

### What's Removed in v2?

| Removed Feature | Why | Alternative |
|----------------|-----|-------------|
| Custom Element (`<spectrum-chat>`) | Code duplication | Use one-line installation |
| `window.SpectrumChatGlobal` API | Naming clarity | Use `window.SpectrumChat` |
| Custom HTML/CSS UI | Complexity | DeepChat handles it |
| Shadow DOM | Not needed | Fixed positioning instead |

### Migration Effort

| Current Setup | Migration Difficulty | Time Estimate |
|---------------|---------------------|---------------|
| **v1 Global Mode** | ⭐ Easy | 5 minutes |
| **v1 Custom Element (few pages)** | ⭐⭐ Medium | 15 minutes |
| **v1 Custom Element (many pages)** | ⭐⭐⭐ Higher | 1 hour |

### Migration Steps

#### From v1 Global Mode → v2

**Before (v1)**:
```javascript
window.SpectrumChatGlobal.open();
```

**After (v2)**:
```javascript
window.SpectrumChat.open(); // Just rename the API
```

**Steps**:
1. Update script URL from v1 to v2
2. Replace `SpectrumChatGlobal` with `SpectrumChat` in your code
3. Test - everything else works the same!

#### From v1 Custom Element → v2

**Before (v1)**:
```html
<script src="...v1..."></script>
<spectrum-chat site-key="xyz" title="Help"></spectrum-chat>
```

**After (v2 - Option A: One-Line)**:
```html
<script src="...v2..." data-site-key="xyz" data-title="Help"></script>
```

**After (v2 - Option B: Global)**:
```html
<script>
  window.SpectrumChatConfig = { siteKey: 'xyz', title: 'Help' };
</script>
<script src="...v2..."></script>
```

**Steps**:
1. Remove `<spectrum-chat>` tags from all pages
2. Choose installation method (one-line or global)
3. Update script URL to v2
4. Test on all pages

### Recommendation Matrix

| Your Situation | Recommendation |
|----------------|----------------|
| New integration | 🚀 Use v2 (one-line installation) |
| Existing v1 global mode | 🚀 Upgrade to v2 (5 min effort) |
| Existing v1 custom element, few pages | ⭐ Consider v2 (15 min effort) |
| Existing v1 custom element, many pages | ⏰ Plan migration (schedule time) |
| Production site, can't test thoroughly | ⏸️ Wait until you have test time |
| Need custom element for specific reason | 🤔 Stay on v1 or contact support |

### Support Timeline

| Version | Support Status | Recommendation |
|---------|---------------|----------------|
| **v2.x** | ✅ Active development | Use for new projects |
| **v1.x** | 🟡 Maintenance mode | Migrate when convenient |
| **v0.x** | ❌ Deprecated | Upgrade immediately |

## Summary

### v2 Wins
- ✅ Simpler installation (one-line)
- ✅ Smaller file size (50% reduction)
- ✅ Faster performance
- ✅ Easier to maintain (75% less code)
- ✅ Better mobile experience
- ✅ Cleaner architecture

### v1 Advantages
- ✅ Custom element option (if you need it)
- ✅ Already integrated (no migration needed)

### The Verdict

**For new integrations**: Use v2  
**For existing v1**: Upgrade when convenient  
**Bottom line**: v2 is the future

---

**Questions?** See [V2_CHANGES.md](./V2_CHANGES.md) for detailed documentation.