# Project: Reactive i18n & Chat UI Architecture Overhaul

## Architecture
- **Client Architecture**: Native ES Modules (`client/webapp/js/`), DOM UI (`client/webapp/js/ui/`), Engine (`client/webapp/js/engine/`).
- **i18n Core Subsystem**: `client/webapp/js/data/i18n.js` (`FreeExileI18nEngine`), `client/webapp/js/data/i18n_catalog.js`, `client/webapp/js/data/chat_i18n_catalog.js` (9 languages: `vi`, `en`, `zh`, `ja`, `ko`, `th`, `de`, `ru`, `es`).
- **Reactive Event Bus**: `FreeExileI18n.subscribe(cb)`, `onLocaleChanged(cb)`, `window.dispatchEvent(new CustomEvent('freeexile:localeChanged'))`, template mount synchronization (`freeexile:templateMounted`, `freeexile:templatesMounted`), cross-tab storage event synchronization.
- **Chat UI Controller**: `client/webapp/js/ui/chat_ui.js` subscribing to `freeexile:localeChanged` and `FreeExileI18n.onLocaleChanged`, dynamic atomic re-render of channel tabs, placeholder, status labels, tooltips, cooldown messages, and notices without F5 reload. Soft cap $\le 350$ lines (current: 346 lines).
- **Anti-Regression Verification**:
  - `tools/lint/check_i18n_hygiene.py`: Static linter enforcing zero unlocalized Vietnamese strings, 9-language parity, and zero dangling keys (337 lines).
  - `tests/unit/test_i18n_event_bus.py`: 23 unit test cases verifying observer lifecycle, fallback chaining, and reactive DOM rendering (328 lines).
  - `tests/e2e/test_i18n_reactive_switching_e2e.py`: Playwright automated browser E2E test verifying zero-reload live switching across languages (193 lines).
  - `tests/unit/test_challenger_i18n_reactive_chat.py`: Adversarial switching stress tests (275 lines).
  - `tests/unit/test_challenger_i18n_m1_parity.py`: Catalog parity and parameter interpolation tests (280 lines).
  - `tests/e2e/test_challenger_i18n_m2_stress.py`: Sub-second rapid switching and non-Latin script tests (320 lines).
  - `tests/unit/test_challenger_m2_i18n_stress.py`: High-throughput stress tests (251 lines).
  - `tests/unit/test_challenger_i18n_hygiene_adversarial.py`: Linter adversarial test harness (176 lines).

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | Reactive Language Event Bus | Centralized Pub/Sub Observer pattern in `FreeExileI18n` with DOM `freeexile:localeChanged` event & template hooks | M1 | Survey |
| 2 | 9-Language Chat Catalog Keys | Register 77 localized keys across 9 languages in `chat_i18n_catalog.js` (channels, permissions, placeholder, buttons, tooltips, HMAC) | M1 | Survey |
| 3 | Chat UI Zero-Hardcoded Localization | Complete elimination of hardcoded strings in `chat_ui.js`, `index.html`, and `template_catalog_system.js` | M1 | Survey |
| 4 | Instant Dynamic Chat Re-render | In-place dynamic re-render of channel tabs, active placeholder, cooldown badges, chat log messages, and open tooltips without reload | M1 | Survey |
| 5 | Chat UI Initialization & Persistence | Boot chat with stored locale from `localStorage` or `FreeExileI18n.getLocale()`, guard against duplicate listeners | M1 | Survey |
| 6 | i18n Static Linter | Python static hygiene checker `tools/lint/check_i18n_hygiene.py` detecting Vietnamese hardcoded strings, dictionary parity, dangling references | M2 | Survey |
| 7 | i18n Event Bus Unit Test Suite | Python/Node unit test suite `tests/unit/test_i18n_event_bus.py` with 23 test cases covering event bus mechanics, fallbacks, parity, reactive UI | M2 | Survey |
| 8 | E2E Reactive Switching Verification | Full browser/DOM E2E test `tests/e2e/test_i18n_reactive_switching_e2e.py` validating live zero-reload language switching | M2 | Survey |
| 9 | Engineering Standards Directives | Update AGENTS.md, GEMINI.md, and docs/standards/ENGINEERING_STANDARDS_2026.md with mandatory i18n & reactive UI directives | M3 | Survey |
| 10 | Global Localization Dictionary Sync | Update docs/standards/GLOBAL_LOCALIZATION_DICTIONARY.md with chat, permission, and item tooltip terminology | M3 | Survey |
| 11 | Full Regression & Forensic Integrity Audit | Execute full test suite (>185 tests), hygiene linters, security audit, and Forensic Auditor verification | M4 | Survey |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| 0 | Survey & Architecture Mapping | Deep codebase scan of chat_ui, i18n, and tests | None | DONE |
| 1 | Reactive i18n Bus & Chat UI Overhaul | Event bus + 9-language catalog + chat UI reactive localization (0 hardcoded) | M0 | DONE |
| 2 | Anti-Regression & Linter Suite | Static hygiene checker + 23 unit tests + E2E test | M1 | DONE |
| 3 | Standards Documentation | AGENTS.md, GEMINI.md, ENGINEERING_STANDARDS_2026.md, GLOBAL_LOCALIZATION_DICTIONARY.md | M1, M2 | DONE |
| 4 | Final Verification & Forensic Audit | E2E verification, full test suite pass, Forensic Audit Gate | M1, M2, M3 | DONE |

## Interface Contracts
### `FreeExileI18n` Event Bus ↔ UI Modules (`chat_ui.js`, `settings_modal.js`, etc.)
- `FreeExileI18n.subscribe(callback: (newLocale, prevLocale, dict) => void): () => void`
- `FreeExileI18n.onLocaleChanged(callback: (newLocale) => void): void`
- `window.dispatchEvent(new CustomEvent('freeexile:localeChanged', { detail: { locale, prevLocale, dict } }))`
- `FreeExileI18n.t(key: string, params?: Record<string, any>, fallback?: string): string`
- `FreeExileI18n.setLocale(locale: string): void`
- `FreeExileI18n.getLocale(): string`

### Chat UI ↔ DOM & Event Bus
- `initChatUI(): void`: Bootstraps with stored locale, registers `freeexile:localeChanged` listener, guards against duplicate initialization.
- `updateLanguage(lang: string): void`: Atomic in-place re-render of channel tabs, ticker, input placeholder, send button, cooldown badge, chat log messages, and open item link tooltip.
- `export const CHANNEL_I18N`: Retained as backwards-compatible export populated from `chat_i18n_catalog.js`.

## Code Layout
- `client/webapp/js/data/i18n.js`: Core reactive i18n engine with pub/sub event bus & DOM updates (342 lines).
- `client/webapp/js/data/i18n_catalog.js`: Core 143-key dictionary.
- `client/webapp/js/data/chat_i18n_catalog.js`: 77-key 9-language chat catalog (394 lines).
- `client/webapp/js/ui/chat_ui.js`: Chat interface controller (346 lines).
- `client/webapp/index.html`: Chat dock markup with `data-chat-i18n` attributes (199 lines).
- `tools/lint/check_i18n_hygiene.py`: Static linter enforcing zero unlocalized strings and dictionary parity (337 lines).
- `tests/unit/test_i18n_event_bus.py`: Unit tests for event bus and reactive Chat UI (328 lines).
- `tests/e2e/test_i18n_reactive_switching_e2e.py`: E2E test verifying zero-reload reactive language changes (193 lines).
- `AGENTS.md`, `GEMINI.md`, `docs/standards/ENGINEERING_STANDARDS_2026.md`: Engineering directives.