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

Merged

developer merged 4 commits from development into master 2026-06-23 08:40:10 +00:00

Conversation 1 Commits 4 Files Changed 14

+653 -40

developer commented 2026-06-23 08:36:39 +00:00

Owner

Copy Link

Copy Source

Promote development → master for the v1.4.0 release.

Highlights

• Telegram launch-diagnostic screen. /telegram/ without sign-in data (empty initData) no longer bounces the visitor to the marketing landing. Instead a compact, one-screenshot, privacy-safe diagnostic (screens/TelegramLaunchError.svelte) — SDK load outcome, platform/version, initData state, tgWebAppData-in-URL, field names present/missing, OS/mobile/browser, UA — no secrets, no initData values, no IP — with Share (OS share sheet / clipboard) and Retry.
• Resilient SDK loading. telegram-web-app.js is loaded dynamically with a 10s timeout (pinned ?62), only on a Telegram entry — a network that blocks telegram.org (common where Telegram reaches users over a proxy) no longer hangs the page, and /app/ / native no longer touch telegram.org at all.
• sdk-load outcome (present/loaded/no-webapp/error/timeout) pinpoints a blocked or hanging telegram.org — the prime suspect for the Android "won't open" reports.

Why

Android users were bounced to the landing with no signal, and a blocked telegram.org hung the page. This makes the failure diagnosable on the device: once live, a stuck user taps Share; sdk-load: error|timeout confirms a telegram.org block (next step would be self-hosting the SDK so blocked users get a working app).

Carries #126. Tests: 326 unit + full e2e green; CI green on development (#535). Docs: ARCHITECTURE.md, UI_DESIGN.md.

Promote `development` → `master` for the **v1.4.0** release. ## Highlights - **Telegram launch-diagnostic screen.** `/telegram/` without sign-in data (empty `initData`) no longer bounces the visitor to the marketing landing. Instead a compact, one-screenshot, privacy-safe diagnostic (`screens/TelegramLaunchError.svelte`) — SDK load outcome, platform/version, `initData` state, `tgWebAppData`-in-URL, field names present/missing, OS/mobile/browser, UA — **no secrets, no `initData` values, no IP** — with **Share** (OS share sheet / clipboard) and **Retry**. - **Resilient SDK loading.** `telegram-web-app.js` is loaded dynamically with a 10s timeout (pinned `?62`), only on a Telegram entry — a network that blocks `telegram.org` (common where Telegram reaches users over a proxy) no longer hangs the page, and `/app/` / native no longer touch `telegram.org` at all. - **`sdk-load` outcome** (`present/loaded/no-webapp/error/timeout`) pinpoints a blocked or hanging `telegram.org` — the prime suspect for the Android "won't open" reports. ## Why Android users were bounced to the landing with no signal, and a blocked `telegram.org` hung the page. This makes the failure diagnosable on the device: once live, a stuck user taps **Share**; `sdk-load: error|timeout` confirms a `telegram.org` block (next step would be self-hosting the SDK so blocked users get a working app). Carries #126. Tests: 326 unit + full e2e green; CI green on `development` (#535). Docs: `ARCHITECTURE.md`, `UI_DESIGN.md`.

developer added 4 commits 2026-06-23 08:36:39 +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.

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.

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.

Merge pull request 'feat(ui): diagnostic screen on /telegram/ instead of the landing bounce' (#126) from feature/telegram-launch-diagnostic into development 508dc870ec

owner approved these changes 2026-06-23 08:39:21 +00:00

developer merged commit b6f28a2423 into master 2026-06-23 08:40:10 +00:00

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#127