# Project: FreeExile UI Microcopy, Typography Modernization, Multilingual Lexicon & Wiki Streamlining

## Architecture
- **Client WebApp UI & Typography Layer**:
  - `client/webapp/index.html`: Main DOM entry point, Tailwind typography configuration (mapping `wuxia`, `cinzel`, and `sans` to clean sans-serif stacks), header HUD buttons, tooltips, and bottom action cluster.
  - `client/webapp/css/main.css`: Core CSS variables (`--font-wuxia`, `--font-cinzel`) and styling rules stripped of serif declarations, setting letter-spacing, padding, and ergonomic visual contrast.
  - `client/webapp/css/hud_skills.css` & `client/webapp/css/modals.css`: Modular stylesheets enforcing sans-serif readability, compact button padding, and responsive breathing room for iPhone 120 FPS and desktop.
  - `client/webapp/js/ui/template_catalog_*.js`: HTML template fragments for system modals, auth, inventory/vault/forge, world/dungeons/hideout, shop/season/totem, and atlas/quests. All button labels, tabs, and notices trimmed to 1-2 words with zero `A (B)` bilingual formats.
  - `client/webapp/js/engine/world_renderer.js` & `endgame_atlas.js`: Canvas/SVG ground drop and node typography migrated to clean sans-serif font strings.
- **Multilingual Master Lexicon & Localization Engine Layer**:
  - `client/webapp/js/data/i18n_catalog.js`: Master dictionary across all 9 languages (`vi`, `en`, `zh`, `ja`, `ko`, `th`, `de`, `ru`, `es`). Parity synchronized for all 143 keys with compact horizontal row formatting (staying <= 700 lines). Microcopy strictly capped at 1-2 words for UI controls, NPC names, and currency terms.
  - `client/webapp/js/data/i18n.js`: Localization engine ensuring robust lookup, interpolation, and zero raw key fallback leaks.
  - `tests/unit/test_webapp_localization_engine.py`: Unit test suite enforcing key parity across all 9 languages, 1-2 word microcopy rules, zero bilingual `A (B)` substrings, 1-sentence technical spec tooltips, and 100% HTML key coverage.
- **Wiki & Documentation Diátaxis Layer**:
  - `wiki/vi/`, `wiki/en/`, `wiki/zh/`: Encyclopedia articles converted from flowery prose into high-density Diátaxis Reference tables (Characters, Zones, Weapons, Currencies, Monsters). Missing specs (`ECONOMIC_BALANCE...`, `ENDGAME_WORLD_MAP...`, `MAP_PROCGEN_WARFOG...`) translated and synchronized to EN and ZH.
  - `wiki/README.md`: Central multilingual navigation index linking all 14 articles per language.
  - Tooling & link fixes: Add missing YAML frontmatter to `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md`, fix broken consignment vault link in stash specs, fix NPC system link.
- **Requirement-Driven E2E Testing Layer**:
  - `tests/e2e/test_ui_typography_i18n_wiki_streamlining_e2e.py`: Autonomous test suite exercising Tiers 1-4.

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | 1-2 Word Microcopy on HUD & Buttons | All buttons, tabs, navigation controls in `index.html` trimmed to 1-2 words | M1 | ORIGINAL_REQUEST §R1 |
| 2 | Elimination of Bilingual `A (B)` Formats | Purge all `Tiếng Việt (English)` parenthetical dual strings from UI controls | M1 | ORIGINAL_REQUEST §R1 |
| 3 | Modal Template Microcopy Streamlining | Trim all 75+ interactive controls across 6 template catalog files | M1 | ORIGINAL_REQUEST §R1 |
| 4 | Dialogue & Notice Condensation | Condense multi-paragraph notices and NPC dialogue choices into 1 concise sentence | M1 | ORIGINAL_REQUEST §R1 |
| 5 | Modern Sans-Serif Typography Migration | Replace Cinzel/Noto Serif with Be Vietnam Pro/Inter in Tailwind config and CSS | M1 | ORIGINAL_REQUEST §R2 |
| 6 | Canvas & SVG Typography Cleanup | Migrate world renderer drop labels and endgame atlas SVG text to clean sans-serif | M1 | ORIGINAL_REQUEST §R2 |
| 7 | Full 9-Language Key Parity (143 Keys) | Synchronize all 143 keys across VI, EN, ZH, JA, KO, TH, DE, RU, ES | M2 | ORIGINAL_REQUEST §R3 |
| 8 | Missing HUD Keys Restoration | Add 6 missing HUD tooltip keys to catalog (`tooltip_bag_*`, `tooltip_character_*`, etc.) | M2 | explorer_survey_i18n_1 |
| 9 | 1-2 Word Action/NPC/Currency Lexicon | Enforce 1-2 word brevity across all 9 language dictionaries | M2 | ORIGINAL_REQUEST §R3 |
| 10 | Technical Spec Tooltip Condensation | Transform 20 flowery skill/item descriptions into 1-sentence technical specs | M2 | ORIGINAL_REQUEST §R3 |
| 11 | Compact Catalog Formatting (<= 700 Lines)| Structure `i18n_catalog.js` horizontally to strictly respect line hygiene limits | M2 | Code Hygiene Standards |
| 12 | Enhanced Localization Unit Test Suite | Add 5 strict test gates in `test_webapp_localization_engine.py` | M2 | Verification Resources |
| 13 | Diátaxis Reference Conversion for Wiki | Convert flowery prose and prompt blocks into concise reference matrices | M3 | ORIGINAL_REQUEST §R4 |
| 14 | Multilingual Wiki File Synchronization | Create missing EN and ZH specs for Economy, Endgame Map, and Warfog | M3 | explorer_survey_wiki_1 |
| 15 | Central Wiki Navigation Index Update | Update `wiki/README.md` to link all 14 articles across all 3 languages | M3 | explorer_survey_wiki_1 |
| 16 | Documentation Frontmatter & Link Fixes | Add YAML frontmatter to PoE2 doc and fix broken clickable links | M3 | tools/lint audit |
| 17 | Comprehensive Requirement-Driven E2E Suite | Build opaque-box E2E test suite covering Tiers 1-4 | E2E-Track | Dual Track |
| 18 | Final E2E Pass, Adversarial Hardening & Hygiene | 100% E2E test pass, Tier 5 adversarial stress testing, and strict hygiene check | M4 | Project Pattern |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| E2E | E2E Testing Track | Requirement-driven test suite (Tiers 1-4) & `TEST_READY.md` | none | DONE |
| M1 | Minimalist UI Layout & Typography Modernization | HTML, CSS, Template Catalogs, Canvas/SVG typography (R1 & R2) | none | IN_PROGRESS |
| M2 | Multilingual Master Lexicon Optimization | `i18n_catalog.js`, `i18n.js`, `test_webapp_localization_engine.py` (R3) | none | DONE |
| M3 | Wiki & Multilingual Encyclopedia Streamlining | `wiki/vi/`, `wiki/en/`, `wiki/zh/`, `docs/` frontmatter & links (R4) | none | DONE |
| M4 | Final E2E Verification & Adversarial Hardening | Full E2E suite pass, Tier 5 adversarial testing, strict hygiene pass | E2E, M1, M2, M3 | IN_PROGRESS |

## Interface Contracts
### UI & Typography ↔ I18n
- Buttons use `data-i18n="<key>"` or direct text from template catalogs.
- `FreeExileI18n.updateDOM()` binds catalog strings into DOM attributes (`title`, `innerText`, `placeholder`).
- Every key present in `index.html` must exist in `I18N_CATALOG` across all 9 languages.

### I18n Engine ↔ Test Suite
- `test_webapp_localization_engine.py` validates that `Object.keys(I18N_CATALOG.vi)` equals `Object.keys(I18N_CATALOG[lang])` for all 9 languages.
- Microcopy test asserts `len(text.split()) <= 2` for all UI controls, NPC names, and currency terms.
- Zero-bilingual test asserts `'(' not in text and ')' not in text` for all interactive button labels.

## Code Layout
- `client/webapp/index.html`: Main HTML entry point.
- `client/webapp/css/main.css`: Core CSS variables and base typography.
- `client/webapp/css/hud_skills.css`: HUD and skill bar styles.
- `client/webapp/css/modals.css`: Modal styling and button ergonomics.
- `client/webapp/js/ui/template_catalog_*.js`: Modular UI template catalogs.
- `client/webapp/js/data/i18n_catalog.js`: Multilingual dictionary (<= 700 lines).
- `client/webapp/js/data/i18n.js`: Localization engine.
- `wiki/vi/*.md`, `wiki/en/*.md`, `wiki/zh/*.md`: Multilingual wiki articles.
- `tests/unit/test_webapp_localization_engine.py`: Unit test runner.
- `tests/e2e/test_ui_typography_i18n_wiki_streamlining_e2e.py`: Requirement-driven E2E test runner.