From 8073971fca526d8c5f9fd75d21e4609a9a160875 Mon Sep 17 00:00:00 2001 From: Ilia Denisov Date: Mon, 15 Jun 2026 17:39:35 +0200 Subject: [PATCH] docs: bake Telegram invite & launch refinements into ARCHITECTURE/UI_DESIGN - UI_DESIGN: mobile immersive fullscreen on launch (desktop keeps full-size); the close confirmation is now mobile-only; friend-code share-via-Telegram deep-link (per-bot, by service language), the friendly self-redeem note, and the outdated-link lobby notice. - ARCHITECTURE: the service language rides the Session wire so the client builds the per-bot invite link; the friend code is shared as a startapp deep-link with graceful spent/expired handling. --- docs/ARCHITECTURE.md | 10 ++++++++-- docs/UI_DESIGN.md | 18 ++++++++++++++---- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0e80f7d..2cb450f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -151,7 +151,9 @@ arrive from a platform rather than completing a mandatory registration). login — last-login-wins) and routes the user's out-of-app push back through the right bot (§10) — **except a game event, which routes by the game's own language** (its variant → en/ru), so a game's notification always comes from the game's bot rather than the - recipient's latest login bot. The service language is distinct from `preferred_language` (the + recipient's latest login bot. It also rides the **Session wire** to the client, which uses it + to build the friend-invite **share link** (and its caption) for the **same bot** the player + is in. The service language is distinct from `preferred_language` (the interface language) and from a game's variant language. Non-Telegram logins (web / email / guest) carry the gateway's default set (`GATEWAY_DEFAULT_SUPPORTED_LANGUAGES`, all variants by default). - The client holds `session_id` in memory for the app session (browser/OS @@ -425,7 +427,11 @@ English game the Latin pool. - **Friends**: two add paths over one `friendships` table. A **one-time code** the to-be-added player issues (a `friend_codes` row: 6-digit numeric, SHA-256-hashed, **12 h** TTL, one live code per issuer, single-use, redeem - rate-limited) is redeemed by the other player to become friends immediately. + rate-limited) is redeemed by the other player to become friends immediately. It is shared as + a Telegram `startapp` deep-link to the issuer's own bot (by service language, with a matching + caption), redeemed by the recipient's Mini App on launch; a **spent or expired** code is not + surfaced as an error there but lands the visitor in the lobby with a gentle pointer to the + right bot, since the shared link outlives the single-use code. Alternatively a **request → accept** is sent to someone you **share a game with** (active or finished); the recipient may accept, ignore (the pending row lazily expires after **30 days** and may be re-sent), or **decline** — a decline is diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index fec6d72..a5dca0a 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -67,8 +67,12 @@ Login uses `Screen`. theme switcher is hidden; the nav bar takes Telegram's background and `setHeaderColor` / `setBackgroundColor` / `setBottomBarColor` paint Telegram's own chrome to match; the native header **BackButton** drives back-navigation (the app's chevron is hidden in - Telegram); **HapticFeedback** fires on tile placement / commit / error; **closing - confirmation** is enabled while a game is open; **vertical swipes** (swipe-to-minimise) + Telegram); **HapticFeedback** fires on tile placement / commit / error; on **mobile** + clients the app enters **immersive fullscreen** on launch (`requestFullscreen`, Bot API + 8.0+) like Telegram's own Mini Apps, while desktop keeps the bot's full-size window; + **closing confirmation** is enabled while a game is open **on mobile only** (on desktop + closing is deliberate and the "changes may not be saved" dialog is just noise — move drafts + auto-save); **vertical swipes** (swipe-to-minimise) are disabled so they don't fight tile drag or the board scroll; and a live stream dropped by a background suspend reconnects silently on return — the connection banner is suppressed while hidden and for a short grace after resume (visibilitychange + @@ -242,8 +246,14 @@ IV 🏅; active games show Your move 🟢 / Opponent's move ⏳; invitations use every field is valid. Interface language stays in **Settings** (it writes through to the account for durable users). - **Friend code**: the issued code sits next to a 📋 copy control; tapping the code or - the icon copies it. Flex text inputs carry `min-width:0` so they shrink instead of - overflowing in Safari. + the icon copies it. **Share via Telegram** wraps the code in a `t.me//?startapp=` + deep-link and opens Telegram's native share-to-chat sheet (Web Share / clipboard fallback + outside Telegram); the link and its caption are for the **same bot the player signed in + through** (its service language). Redeeming your **own** invite shows a friendly note, not an + error; opening an **outdated** invite link (a used or expired single-use code) lands in the + lobby with a calm modal pointing at the right bot (`@`), not a red error on the + Friends tab. Flex text inputs carry `min-width:0` so they shrink instead of overflowing in + Safari. - **History / GCG**: the in-game slide-down history lays each move out in a per-seat grid (the word(s) and the move score, no running total); *Export GCG* (the 📤 in the history header) shares or downloads the `.gcg` file and appears only once the game is finished.