====================
Development Journal
====================

July 2, 2025
============

Token Estimator Implementation
-------------------------------

Built `token_estimator.js` - a simplified BPE-based token counter for translation ETA estimation. 

**Not compatible with tiktoken** - this is estimation-only, ~85% accuracy. Good enough for progress bars, not for exact tokenization.

**NVIDIA 4090 Performance Metrics:**
- Prompt processing: 3,144 tokens/sec
- Generation: 121 tokens/sec  
- Translation estimates: 1K tokens ≈ 11 seconds

The estimator uses real production metrics from our Hermes machine to provide realistic translation timing.

July 3, 2025
============

Complete Translation Infrastructure Overhaul
--------------------------------------------

**Modular Language System Implementation**

Restructured the entire translation system to use individual language files instead of one monolithic object. Each of the 19 supported languages now has its own dedicated JS file in `/src/languages/`.

**Language Coverage:**
- 🇺🇸 English (en.js) - 46 translation keys
- 🇨🇳 Chinese Simplified (zh.js) 
- 🇹🇼 Chinese Traditional (zh-tw.js)
- 🇮🇳 Hindi (hi.js)
- 🇪🇸 Spanish (es.js) 
- 🇫🇷 French (fr.js)
- 🇸🇦 Arabic (ar.js)
- 🇧🇩 Bengali (bn.js)
- 🇷🇺 Russian (ru.js)
- 🇧🇷 Portuguese (pt.js)
- 🇵🇰 Urdu (ur.js)
- 🇮🇩 Indonesian (id.js)
- 🇩🇪 German (de.js)
- 🇯🇵 Japanese (ja.js)
- 🇰🇪 Swahili (sw.js)
- 🇮🇳 Marathi (mr.js)
- 🇮🇳 Telugu (te.js)
- 🇹🇷 Turkish (tr.js)
- 🇰🇷 Korean (ko.js)

**Dynamic UI Refresh System**

Implemented `refreshUILanguage()` function that updates all UI text without requiring browser refresh:

- **Declarative translations**: Elements with `data-i18n` attributes automatically update
- **Parameter support**: `data-i18n-params` for dynamic text with variables like `{lang}` and `{error}`
- **Smart element detection**: Handles inputs, buttons, placeholders, and modal titles
- **Event system**: Dispatches `languageChanged` custom events for component integration
- **Backward compatibility**: Maintains `window.refreshUILanguage` for existing code

**Translation Verification System**

Created `verify-translations.js` - a Node.js script that ensures translation consistency:

- **Key extraction**: Parses JS files to extract translation object keys  
- **Completeness verification**: Compares all languages against English reference
- **Missing/extra key detection**: Reports inconsistencies with colored console output
- **Exit codes**: Returns 0 for success, 1 for issues (CI/CD friendly)

**Adding New Languages - Workflow:**

1. **Before adding**: Run verification to ensure current state is clean
   ```bash
   cd /home/fox/git/ai.unturf.com/src/languages
   node verify-translations.js
   ```
   Should show: "🎉 All languages have complete translations!"

2. **Create new language file**: Copy structure from `en.js`
   ```bash
   cp en.js new-lang.js  # Replace 'new-lang' with actual language code
   ```

3. **Translate all values**: Keep the same keys, translate only the string values

4. **Update index.js**: Add import and export for the new language
   ```javascript
   import { newLang } from "./new-lang.js";
   // Add to UI_TRANSLATIONS object
   ```

5. **Verify completeness**: Run script again to check for issues
   ```bash
   node verify-translations.js
   ```
   
6. **Fix any issues**: Script will show missing/extra keys in red
   - Missing keys: Add them with proper translations
   - Extra keys: Remove them or add to English reference if needed

7. **Final verification**: Run until you see the success message again

**File Structure:**
```
src/languages/
├── index.js              # Aggregates all translations
├── en.js                 # English reference (46 keys)
├── [18 other languages]  # Complete translations
└── verify-translations.js # Sanity check script
```

**Benefits:**
- **Maintainability**: Each language isolated in its own file
- **Consistency**: 100% key coverage verified across all 19 languages  
- **Real-time UX**: Language switching without page refresh
- **Developer experience**: Automated verification prevents translation drift
- **Scalability**: Easy to add new languages following the established pattern

This system supports the full user journey from language detection to dynamic interface updates, ensuring a seamless multilingual experience for all Hermes AI users.

July 9, 2025
============

Modal CSS Architecture Overhaul
-------------------------------

**The Problem**

Users reported multiple issues with the UncloseAI modal experience:

1. **Desktop Issue**: PicoCSS-powered sites displayed full-screen modals on large laptop displays instead of centered dialogs
2. **Translation Pages**: Broken CSS in translated pages opened in new windows made them unusable
3. **Mobile Experience**: After initial fixes, mobile devices lost their full-screen modal experience

**Root Cause Analysis**

Three interconnected issues created these problems:

1. **Inconsistent CSS Loading**: Different modal files used different detection methods and URL patterns
2. **PicoCSS Overrides**: The framework's aggressive dialog styling required careful specificity management
3. **Breakpoint Mismatch**: Mobile detection used 480px while many tablets needed full-screen at 768px

**Solution: Complete CSS Architecture Refactoring**

**Step 1: Dedicated CSS Files**

Created two purpose-built stylesheets to replace all inline styles:

- ``uncloseai-modal-builtin.css`` - Clean styles for standard blog sites
- ``uncloseai-modal-pico.css`` - Override styles with ``!important`` for PicoCSS sites

**Step 2: Unified CSS Loading Pattern**

Standardized all modal components to use the same detection and loading logic:

```javascript
// Detect if PicoCSS is actually present on the page
const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null;

// Load appropriate CSS based on actual PicoCSS presence
const cssFile = hasPicoCSS ? 'uncloseai-modal-pico.css' : 'uncloseai-modal-builtin.css';

// Use absolute URLs for cross-domain compatibility
link.href = `https://uncloseai.com/src/${cssFile}`;
```

**Step 3: PicoCSS Override Strategy**

```css
/* Override PicoCSS dialog defaults with high specificity */
dialog#uncloseai-embedded-modal[data-theme] {
  position: fixed !important;
  top: 50% !important;
  left: 50% !important;
  transform: translate(-50%, -50%) !important;
  width: 70vw !important;
  max-width: 800px !important;
}

/* Mobile/tablet full-screen experience */
@media (max-width: 768px) {
  dialog#uncloseai-embedded-modal[data-theme] {
    top: 0 !important;
    left: 0 !important;
    width: 100vw !important;
    height: 100vh !important;
  }
}
```

**Step 4: Translation Page CSS Fix**

- Added ``<base href="${baseUrl}">`` tag to resolve relative URLs in new windows
- Ensured all modal CSS uses absolute URLs for cross-window compatibility
- Maintained original page styling while adding AI functionality

**Technical Implementation**

**Files Modified:**
- ``uncloseai-embed-modal.js`` - Main modal with PicoCSS detection
- ``translate-modal.js`` - Translation modal with absolute URLs
- ``tts-modal.js`` - TTS modal with consistent loading
- ``widget-library.js`` - Widget components with proper CSS
- ``translation.js`` - Base tag injection for new windows
- ``uncloseai-modal-builtin.css`` - Standard site styles
- ``uncloseai-modal-pico.css`` - PicoCSS override styles

**Responsive Breakpoints:**
- **Desktop (>768px)**: Centered modal (70vw × 90vh, max 800px width)
- **Mobile/Tablet (≤768px)**: Full-screen modal (100vw × 100vh)

**Results**

✅ **Desktop Experience**: Properly centered modals on large displays
✅ **Mobile Experience**: Full-screen modals on phones and tablets
✅ **Translation Pages**: Functional CSS in new window contexts
✅ **Code Architecture**: Clean separation between JS logic and CSS styling
✅ **Cross-Site Compatibility**: Consistent behavior across all site types
✅ **Maintainability**: Single source of truth for modal styling

This comprehensive refactoring established a robust CSS architecture that handles all edge cases while providing an optimal user experience across all devices and contexts.

July 11, 2025
=============

Custom API Integration & UI Overhaul
-------------------------------------

**Major Features Implemented:**

Custom API Endpoint Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implemented comprehensive custom OpenAI-compatible API support allowing users to integrate their own AI providers (Groq, OpenAI, Claude, etc.) into the chat system:

- **Centralized Configuration System**: Created ``getAPIConfig()`` in ``config.js`` to manage API settings
- **Universal API Call Patching**: All chat functions now check for custom configuration automatically
- **Dynamic Model Discovery**: System fetches available models from custom endpoints via ``/v1/models``
- **Intelligent Max Tokens**: Automatically detects context limits from model metadata:
  - VLLM: ``max_model_len`` (e.g., 82,000 tokens)
  - OpenAI: ``max_tokens`` (e.g., 8,192 tokens)  
  - Groq: ``context_length`` (e.g., 128,000 tokens)
- **Seamless Fallback**: Falls back to default Hermes endpoints when custom API unavailable

**Settings Panel Complete Redesign**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Restructured the settings interface for better organization and usability:

- **Two-Column Grid Layout**: Left column (Model, Voice, Language), Right column (API Configuration)
- **Quick Actions Header**: Action buttons span both columns at the top for prominence
- **Mobile Responsive**: Automatically stacks to single column on screens ≤768px
- **Label Cleanup**: Removed redundant section headers (``AI Model:``, ``TTS Voice:``, etc.) for cleaner look
- **Grid Override Fixes**: Added ``!important`` declarations to overcome PicoCSS conflicts

**Translation System Improvements**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enhanced the multilingual system with new keys and cleanup:

- **Chat Audio Downloads**: Added ``downloadChatAudio`` key for chat message audio
- **Custom API Description**: Added ``useCustomAPI`` across all 19 languages: "Use a custom openai compatible endpoint."
- **Translation Cleanup**: Removed 5 unused keys (``modelLabel``, ``voiceLabel``, ``languageLabel``, ``quickActions``, ``apiConfigLabel``)
- **Validator Updates**: Enhanced verification scripts to handle translation changes

**Critical Bug Fixes:**

Model Selection System Overhaul
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed fundamental issues with model selection that were causing API mismatches:

**Issue**: Users selected Groq models but system sent requests to Hermes models
**Root Cause**: Modal model dropdown had no HTML ID, causing ``getSelectedModel()`` to fall back to defaults

**Solution**: 
- Added ``id="hermes-model-selection"`` to modal dropdown
- Enhanced debug logging to trace model selection flow
- Fixed model registry to properly store endpoint relationships

**Cache System Enhancement**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed refresh models button not working when custom API settings changed:

**Issue**: Clicking refresh didn't fetch new models after enabling custom API
**Root Cause**: Cache key only considered ``VLLM_ENDPOINTS`` array, not custom API configuration

**Solution**:
- Include custom API settings in cache hash key
- Cache now properly invalidates when toggling custom API
- Test case: Checking/unchecking custom API produces different model lists

**Error Handling & Debugging**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added comprehensive error tracking and debugging tools:

- **API Error Details**: Full HTTP status codes and response bodies logged
- **Model Selection Tracing**: Debug messages show exactly which model is selected and why
- **Configuration Verification**: Clear console indicators for custom vs default API usage
- **Max Tokens Logging**: Shows token limits being used for each request type

**Technical Implementation Details:**

**Files Modified:**
- ``src/config.js`` - Central API configuration with ``getAPIConfig()``
- ``src/models.js`` - Enhanced model selection, caching, and max_tokens support  
- ``src/chat.js`` - Dynamic max_tokens for all chat functions
- ``src/translation.js`` - Custom API support with dynamic token limits
- ``src/ui.js`` - Intro generation API integration
- ``src/uncloseai-embed-modal.js`` - Settings UI redesign and model dropdown ID fix
- ``src/uncloseai-modal-*.css`` - Grid layouts and responsive design improvements
- ``src/languages/*.js`` - Translation updates across all 19 language files

**API Call Patching Strategy:**
All API functions now follow this pattern:
```javascript
const apiConfig = await getAPIConfig();
if (apiConfig.isCustom) {
    // Use custom endpoint, API key, and selected model
    apiUrl = `${apiConfig.endpoint}/chat/completions`;
    headers = { "Authorization": `Bearer ${apiConfig.apiKey}` };
    model = apiConfig.model;
} else {
    // Use default Hermes configuration
    apiUrl = `${getSelectedModelEndpoint()}/chat/completions`;
    headers = { "Authorization": `Bearer ${API_KEY}` };
    model = getSelectedModel();
}
```

**Dynamic Max Tokens Implementation:**
```javascript
const maxTokens = getSelectedModelMaxTokens(); // Reads from model registry
// Translation: Could be 70,000 for VLLM or 8,192 for Groq
// Chat: Adapts to whatever the selected model supports
```

**UI Flow Improvements:**
1. User configures custom API (base URL + API key)
2. Clicks "🔄 Refresh Models" → Fetches models from both Hermes + custom endpoint
3. Selects model from combined dropdown (e.g., ``https://api.groq.com/openai/v1-llama-3.1-8b-instant``)
4. All features (chat, translation) automatically use selected custom model

**Deployment Notes:**
- **Backward Compatible**: Existing users continue using Hermes by default
- **Progressive Enhancement**: Custom API is opt-in with fallback protection
- **Cache Management**: Model cache automatically refreshes when configuration changes
- **Cross-Platform**: Works on both modal interface and blog site integration

**Testing Completed:**
- ✅ Custom API integration with Groq, OpenAI endpoints
- ✅ Model selection working across modal and blog interfaces
- ✅ Dynamic max_tokens based on model capabilities (82k for VLLM, 8k for Groq)
- ✅ Cache invalidation when toggling custom API settings
- ✅ Mobile responsive 2-column grid layout
- ✅ Translation key cleanup across all 19 languages

This release transforms the AI chat system from a single-provider solution into a flexible, multi-provider platform while maintaining the clean user experience and adding significant debugging capabilities for troubleshooting.