Add React/TypeScript rewrite of tts.bot with full feature parity

- Vite + React + TypeScript SPA replacing static webfront
- Zustand stores for auth, voices, chatters, settings, appearance
- AWS SDK v3 (Polly, Translate, Cognito) replacing monolithic aws-sdk.js
- AudioPlayer class with full queue management (Speak, Skip, Dump, Ban flow)
- useTwitchChat hook wrapping tmi.js
- ChatProcessor port of doChat() pipeline (emote strip, Levenshtein dedup, translation)
- Backend API integration: loadVoice/saveTtsConfig via api.tts.bot
- Chat commands: !setvoice, !setspoken, !voices, !poof, !ttsdump, !ttsban, !tts-pause
- Voice Recognition hook: pause-on-speech, STS, ban hammer, poof regex
- Viewer page (/viewer) for chat viewers to configure their own voice
- SettingsPanel with tabs: general, voices, translation, filters, appearance, websocket, vr, cct
- CCT overlay page (/cct) with postMessage listener
- SPA nginx config with try_files fallback and asset caching
- CLAUDE.md documenting architecture, routes, and dev commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: johnebgood

CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+tts.bot is a Twitch Text-to-Speech bot for streamers. It connects to Twitch chat via TMI.js, synthesizes speech using AWS Polly, and supports real-time translation via AWS Translate. The app runs entirely client-side (no backend).
+
+The **original** static HTML/JS app lives in `webfront/` (served by nginx, kept for reference).
+The **React rewrite** lives in `react-app/` and is the active codebase.
+
+## Development (react-app/)
+
+```bash
+cd react-app
+npm install
+npm run dev        # Vite dev server at localhost:5173
+npm run build      # Produces dist/ — point nginx root here
+npm run typecheck  # tsc -b with no emit
+```
+
+**Nginx**: point the server root at `react-app/dist/`. The `react-app/nginx.conf` file contains the SPA config with `try_files $uri /index.html` fallback. Run `npm run build` and reload nginx after changes.
+
+## Architecture (react-app/src/)
+
+### Auth flow
+1. `/login` — user picks voice/language settings, clicks "Authorize on Twitch"
+2. Twitch redirects to `/callback` with `#access_token=…` in URL hash
+3. `CallbackPage` extracts token → writes to Zustand (persisted in localStorage) → redirects to `/app`
+4. `/app` is protected — redirects to `/login` if no token
+
+### Pages
+| Route | File | Purpose |
+|---|---|---|
+| `/login` | `pages/LoginPage.tsx` | Voice setup + Twitch OAuth |
+| `/callback` | `pages/CallbackPage.tsx` | Extracts OAuth token from URL hash |
+| `/app` | `pages/StreamerDashboard.tsx` | Main TTS dashboard (protected) |
+| `/cct` | `pages/CCTOverlay.tsx` | Closed Captions/Translation standalone popup |
+
+### State (Zustand stores — `store/index.ts`)
+All stores use `zustand/middleware/persist` to localStorage except session stores.
+
+| Store | Persisted | Contents |
+|---|---|---|
+| `useAuthStore` | ✓ | `accessToken`, `twitchUsername` |
+| `useVoiceStore` | ✓ | All voice/language selections |
+| `useChattersStore` | ✓ | Per-user voice configs (`Record<username, ChatterConfig>`) |
+| `useSettingsStore` | ✓ | All checkboxes (`cb*`) and text inputs (`txt*`) |
+| `useAppearanceStore` | ✓ | CCT overlay visual settings |
+| `useConnectionStore` | ✗ | `channel`, `connectionStatus` |
+| `useChatUiStore` | ✗ | `messages[]`, `queueCount`, `isPaused`, `currentSpeakingId` |
+| `useVoicesDataStore` | ✗ | `voices`, `voicesDesc`, `awsInitialized` |
+
+### AudioPlayer (`audio/AudioPlayer.ts`)
+A plain TypeScript class — **not** React state. Created once as a singleton in `hooks/useAudioPlayer.ts` via `useRef`. Key methods: `Speak`, `SpeakNow`, `SpeakNext`, `SpeakCustom`, `SpeakGame2TTS`, `Pause`, `Continue`, `Skip`, `SkipByID`, `Dump`, `DumpByUser`, `PopLastMessage`. Calls `synthesizeSpeech()` from `services/awsService.ts`.
+
+Configure the player after AWS is initialized:
+```ts
+player.configure({ getSystemVoice, getSystemVoiceOption, getVoices, onQueueCount, onSpeakingId });
+```
+
+### TMI.js (`hooks/useTwitchChat.ts`)
+`useTwitchChat` hook owns the Twitch chat connection lifecycle. The connection only starts when `enabled: true`. TMI client is stored in a `useRef` to avoid stale closures in handlers. All event handlers are forwarded through a stable `handlers` ref.
+
+### AWS (`services/awsService.ts`)
+- `initializeAWS()` — Cognito unauthenticated identity → credentials
+- `buildVoiceLookup()` — calls `DescribeVoices`, returns normalized `voices` and `voicesDesc`
+- `synthesizeSpeech()` — calls Polly, returns `Uint8Array`
+- `translateText()` — calls Translate, returns `{ translatedText, sourceLangCode }`
+
+AWS clients are module-level singletons (not React state). `useAWSServices` hook initializes them once.
+
+### Chat pipeline (`services/chatProcessor.ts`)
+`doChat()` is the main async function — ported from the original `doChat()` in `webfront/js/script.js`. It handles:
+- Emote stripping (BTTV, FFZ, Twitch)
+- SSML detection
+- Permission checks (everyone/mod/sub/VIP)
+- AWS Translate
+- Levenshtein dedup (per-user and chat-wide)
+- @username replacement with spoken names
+- Link filtering (TLD regex built in `StreamerDashboard`)
+- Calling `onSpeak` → `AudioPlayer.Speak()`
+
+### WebSocket support
+Two optional WebSocket connections managed in `StreamerDashboard.tsx`:
+- `websocketCustomRef` — custom URL, handles `TTS`, `game2tts`, `GPT-Moderated` topics
+- `websocketProdRef` — AWS WebSocket backend
+
+### CCT cross-window communication
+The original app called `window.cctPopup.processResults()` directly. The React version uses `window.postMessage` with `{ type: 'cct-result', text, isFinal }`. `CCTOverlay` also exposes `window.processResults` for legacy compatibility.
+
+## Key Constants (`constants/index.ts`)
+- `TWITCH_CLIENT_ID` — `dan71ek0pct1u7b8ht5u4h55zlcxvq`
+- `COGNITO_IDENTITY_POOL_ID` — `us-east-1:e9babc40-c043-4729-91be-de6c1d22b919`
+- `AWS_REGION` — `us-east-1`
+
+## Original app (`webfront/`)
+Static HTML/JS, no build step. `webfront/js/script.js` (4,300+ lines) is the reference implementation. Do not modify — it serves as documentation for the React rewrite.

react-app/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

react-app/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

react-app/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

react-app/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en" data-bs-theme="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>tts.bot by Security_Live</title>
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+    />
+    <link
+      rel="stylesheet"
+      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.0/css/all.min.css"
+    />
+  </head>
+  <body class="bg-dark text-white">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

react-app/nginx.conf

@@ -0,0 +1,26 @@
+# Drop this into /etc/nginx/sites-available/tts.bot (or include it from your server block).
+# Adjust `root` to wherever you place the built `dist/` folder.
+
+server {
+    listen 80;
+    server_name tts.bot www.tts.bot local.tts.bot dev.tts.bot uat.tts.bot;
+
+    root /home/security_live/Projects/webroot/tts.bot/react-app/dist;
+    index index.html;
+
+    # SPA fallback — all routes serve index.html
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache hashed assets aggressively
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Don't cache index.html
+    location = /index.html {
+        add_header Cache-Control "no-cache, no-store, must-revalidate";
+    }
+}