feat(ui): diagnostic screen on /telegram/ instead of the landing bounce #126

Merged

developer merged 3 commits from feature/telegram-launch-diagnostic into development 2026-06-23 08:32:18 +00:00

Conversation 1 Commits 3 Files Changed 14

+653 -40

developer commented 2026-06-23 07:38:03 +00:00

Owner

Copy Link

Copy Source

Problem

On /telegram/ a Mini App launch without sign-in data (empty initData) did location.replace('/'), bouncing the visitor to the marketing landing. This destroyed any diagnosability and, on some Android clients that reach the entry with empty initData, looked like the app refusing to open while iOS worked.

Change

Replace the bounce with a compact, privacy-safe launch-error screen (screens/TelegramLaunchError.svelte) showing a one-screenshot diagnostic snapshot captured at the moment of failure:

• SDK / WebApp presence, Telegram platform/version
• initData empty?, tgWebAppData present in the URL fragment?
• initData field names present/missing (never the signed values, never an IP)
• OS / mobile / browser via UA Client Hints + full User-Agent

A Share button delivers the report through the OS share sheet (clipboard copy on desktop), reusing the GCG no-webview-strand guard. Retry re-checks in place to recover a late initData without a reload (which would discard the launch fragment).

This is the instrument to root-cause the Android empty-initData failure (not reproducible in Playwright). Hypotheses A (launch method) and B (redirect-drops-fragment) were excluded; the screen captures the state on the real device.

Tests

• Unit: collectTelegramDiag, shareText/pickTextShare
• e2e: the /telegram/ spec now asserts the diagnostic screen (Share + Retry), not a redirect
• Local: pnpm check clean, 321 unit pass, build clean, 154 e2e pass (4 pre-existing skips)
• Docs: ARCHITECTURE.md + UI_DESIGN.md updated

## Problem On `/telegram/` a Mini App launch without sign-in data (empty `initData`) did `location.replace('/')`, bouncing the visitor to the marketing landing. This destroyed any diagnosability and, on some Android clients that reach the entry with empty `initData`, looked like the app refusing to open while iOS worked. ## Change Replace the bounce with a compact, privacy-safe launch-error screen (`screens/TelegramLaunchError.svelte`) showing a one-screenshot diagnostic snapshot captured **at the moment of failure**: - SDK / WebApp presence, Telegram platform/version - `initData` empty?, `tgWebAppData` present in the URL fragment? - initData field **names** present/missing (never the signed values, never an IP) - OS / mobile / browser via UA Client Hints + full User-Agent A **Share** button delivers the report through the OS share sheet (clipboard copy on desktop), reusing the GCG no-webview-strand guard. **Retry** re-checks in place to recover a late `initData` without a reload (which would discard the launch fragment). This is the instrument to root-cause the Android empty-`initData` failure (not reproducible in Playwright). Hypotheses A (launch method) and B (redirect-drops-fragment) were excluded; the screen captures the state on the real device. ## Tests - Unit: `collectTelegramDiag`, `shareText`/`pickTextShare` - e2e: the `/telegram/` spec now asserts the diagnostic screen (Share + Retry), not a redirect - Local: `pnpm check` clean, **321** unit pass, build clean, **154** e2e pass (4 pre-existing skips) - Docs: `ARCHITECTURE.md` + `UI_DESIGN.md` updated

developer added 1 commit 2026-06-23 07:38:03 +00:00

feat(ui): diagnostic screen on /telegram/ instead of the landing bounce ... 0c5d3808d7

A Mini App launch on /telegram/ without sign-in data (empty initData) used to
location.replace('/') — bouncing the visitor to the marketing landing. That
destroyed all diagnosability and, on some Android clients that reach the entry
with no initData, simply looked like the app refusing to open.

Replace the bounce with a compact, privacy-safe launch-error screen
(screens/TelegramLaunchError.svelte) that renders a one-screenshot diagnostic
snapshot captured at the moment of failure: SDK/WebApp presence, Telegram
platform/version, whether initData is empty, whether the URL fragment carried
tgWebAppData, the initData field NAMES present/missing (never the signed
values, never an IP), and OS/mobile/browser via User-Agent Client Hints plus
the full User-Agent. A Share button delivers it through the OS share sheet
(clipboard copy on desktop, reusing the GCG no-webview-strand guard); Retry
re-checks in place to recover a late initData without a reload (which would
discard the launch fragment).

This is the instrument to root-cause the Android empty-initData failure, which
is not reproducible in Playwright.

Tests: collectTelegramDiag + shareText/pickTextShare unit tests; the /telegram/
e2e now asserts the diagnostic screen, not a redirect. Docs: ARCHITECTURE.md +
UI_DESIGN.md updated.

developer added 1 commit 2026-06-23 07:59:25 +00:00

fix(ui): load telegram-web-app.js dynamically with a timeout ... ae5090b851

The Telegram SDK was a render-blocking <script src="telegram.org/..."> in the
shared index.html shell, so it ran on every entry (/telegram/, /app/, native).
On a network that blocks telegram.org — common where Telegram itself reaches
users only over a proxy — the script hangs forever, stranding the whole page,
including the launch-diagnostic screen meant to surface exactly this failure.
This is the likely root cause of the Android "won't open" reports (all launch
methods fail identically; iOS on a different network works).

Remove the head <script> and load the SDK dynamically (lib/telegram.ts
loadTelegramSDK) with a 10s timeout, only on a Telegram entry (the /telegram/
path or a tgWebApp launch fragment). The SPA — served from our own reachable
origin — boots first and controls the load: on a block/error it falls through
to the diagnostic screen (reporting sdk: no) instead of hanging, and Retry
re-attempts. /app/ and the native build no longer touch telegram.org.

Pin the SDK to the version the official page recommends (?62) for the newer
client features the app already uses (fullscreen, safe areas, swipe guard).

Tests: loadTelegramSDK unit tests (present / error / timeout); an e2e that
aborts the script fetch and asserts the diagnostic still renders.

developer added 1 commit 2026-06-23 08:18:03 +00:00

feat(ui): record the SDK load outcome in the launch diagnostic ... e3899d4755

The diagnostic showed only sdk: yes/no (window.Telegram presence), not why the
SDK was absent. Capture how the dynamic telegram-web-app.js load resolved —
present / loaded / no-webapp / error / timeout — and surface it as
"sdk-load: <outcome>". error/timeout pinpoint a blocked or hanging telegram.org
(the prime suspect for an empty launch); no-webapp a loaded-but-broken script.

loadTelegramSDK records the outcome (telegramSdkOutcome); collectTelegramDiag
carries it into the screen. Unit tests cover each outcome; the blocked-script
e2e now asserts sdk-load: error.

owner approved these changes 2026-06-23 08:31:57 +00:00

developer merged commit 508dc870ec into development 2026-06-23 08:32:18 +00:00

developer deleted branch feature/telegram-launch-diagnostic 2026-06-23 08:32:18 +00:00

developer referenced this pull request 2026-06-23 08:36:39 +00:00

release: v1.4.0 — Telegram launch diagnostic + dynamic SDK load #127

Sign in to join this conversation.

Reviewers

No Reviewers

owner

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

owner (Ilia) developer

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: developer/scrabble-game#126