From ae5090b851f2b74742da5af137fdaf51174ae720 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 23 Jun 2026 09:59:24 +0200
Subject: [PATCH] fix(ui): load telegram-web-app.js dynamically with a timeout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 docs/UI_DESIGN.md           |  5 +++-
 ui/e2e/fixtures.ts          | 10 +++----
 ui/e2e/telegram.spec.ts     | 12 ++++++++
 ui/index.html               |  8 ++++--
 ui/src/lib/app.svelte.ts    | 17 +++++++++++
 ui/src/lib/telegram.test.ts | 33 ++++++++++++++++++++++
 ui/src/lib/telegram.ts      | 56 +++++++++++++++++++++++++++++++++++--
 7 files changed, 129 insertions(+), 12 deletions(-)

diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md
index ace40bd..298f2d2 100644
--- a/docs/UI_DESIGN.md
+++ b/docs/UI_DESIGN.md
@@ -11,7 +11,10 @@ launch by `Telegram.WebApp.initData` — the SDK's `themeParams` override the to
 runtime; on that path without sign-in data (no `initData` — outside Telegram, or a Mini App
 launch that delivered none, as seen on some Android clients) the app renders a compact,
 shareable launch-diagnostic screen (`screens/TelegramLaunchError.svelte`) rather than
-redirecting to the site root.
+redirecting to the site root. `telegram-web-app.js` is loaded **dynamically with a timeout**,
+only on a Telegram entry — not a render-blocking `<script>` in the shared `index.html` shell —
+so a network that blocks `telegram.org` cannot hang the page; `/app/` (web) and the native build
+never load it.
 
 ## Layout shell (`components/Screen.svelte`)
 
diff --git a/ui/e2e/fixtures.ts b/ui/e2e/fixtures.ts
index 40f9068..3a49222 100644
--- a/ui/e2e/fixtures.ts
+++ b/ui/e2e/fixtures.ts
@@ -1,13 +1,13 @@
 import { test as base } from '@playwright/test';
 
 // All e2e specs run hermetically against the mock transport. Neutralise the real
-// telegram-web-app.js (loaded from the CDN in index.html) so the suite never blocks
-// on telegram.org — it is unreachable from the CI runner, and a render-blocking
-// <script> to it would hang every page load. Specs that exercise the Telegram launch
-// inject their own window.Telegram via addInitScript before navigating.
+// telegram-web-app.js (the app loads it dynamically — see lib/telegram.ts loadTelegramSDK) so the
+// suite never reaches telegram.org, which is unreachable from the CI runner. Specs that exercise
+// the Telegram launch inject their own window.Telegram via addInitScript before navigating, so the
+// dynamic load short-circuits on the already-present SDK.
 export const test = base.extend({
   page: async ({ page }, use) => {
-    await page.route('**/telegram-web-app.js', (route) =>
+    await page.route('**/telegram-web-app.js*', (route) =>
       route.fulfill({ status: 200, contentType: 'application/javascript', body: '' }),
     );
     await use(page);
diff --git a/ui/e2e/telegram.spec.ts b/ui/e2e/telegram.spec.ts
index dcf0b7b..a4a22e6 100644
--- a/ui/e2e/telegram.spec.ts
+++ b/ui/e2e/telegram.spec.ts
@@ -121,3 +121,15 @@ test('outside Telegram, the /telegram/ entry shows the launch diagnostic, not a
   await expect(page).toHaveURL(/\/telegram\//);
   await expect(page.getByRole('button', { name: /guest/i })).toHaveCount(0);
 });
+
+test('a blocked telegram-web-app.js does not hang the diagnostic screen', async ({ page }) => {
+  // Simulate a network where telegram.org is unreachable: the SDK fetch fails. Because the SPA
+  // loads the SDK dynamically with a timeout (not a render-blocking <script>), a failed/blocked
+  // fetch must not strand the page — the diagnostic screen still renders, reporting no SDK. (This
+  // route overrides the fixture's empty-body fulfill; the later registration wins.)
+  await page.route('**/telegram-web-app.js*', (route) => route.abort());
+  await page.goto('/telegram/');
+
+  await expect(page.getByRole('button', { name: 'Share' })).toBeVisible();
+  await expect(page.getByText('sdk: no')).toBeVisible();
+});
diff --git a/ui/index.html b/ui/index.html
index 4b7c3d1..8eac93b 100644
--- a/ui/index.html
+++ b/ui/index.html
@@ -2,9 +2,11 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <!-- Telegram Mini App SDK: defines window.Telegram.WebApp. Harmless outside
-         Telegram (initData is empty), so it loads on every entry. -->
-    <script src="https://telegram.org/js/telegram-web-app.js"></script>
+    <!-- The Telegram Mini App SDK (window.Telegram.WebApp) is deliberately NOT loaded here: a
+         render-blocking <script> to telegram.org hangs the whole page on a network that blocks
+         telegram.org (common where Telegram itself reaches users only over a proxy), stranding even
+         the launch-diagnostic screen. The app loads it dynamically, with a timeout, only on a
+         Telegram entry — see lib/telegram.ts loadTelegramSDK and lib/app.svelte.ts bootstrap. -->
     <!-- user-scalable=no: the board owns zoom; we do not want the browser's pinch
          to fight our two-state zoom. viewport-fit=cover for native (Capacitor). -->
     <meta
diff --git a/ui/src/lib/app.svelte.ts b/ui/src/lib/app.svelte.ts
index bacda45..32a9663 100644
--- a/ui/src/lib/app.svelte.ts
+++ b/ui/src/lib/app.svelte.ts
@@ -15,6 +15,8 @@ import {
   collectTelegramDiag,
   type TelegramDiag,
   onTelegramPath,
+  hasLaunchFragment,
+  loadTelegramSDK,
   telegramColorScheme,
   telegramContentSafeAreaTop,
   telegramSafeAreaTop,
@@ -561,6 +563,12 @@ function applyTelegramChrome(launch: TelegramLaunch): void {
   telegramRequestFullscreen();
 }
 
+/** How long to wait for the dynamically loaded Telegram Mini App SDK before giving up and showing
+ *  the launch-error screen. A network that blocks telegram.org makes the script hang rather than
+ *  fail fast (a connection refusal resolves immediately via the script's error event), so this only
+ *  bounds a true hang; it is generous enough not to misfire on a slow but working network. */
+const TELEGRAM_SDK_TIMEOUT_MS = 10000;
+
 export async function bootstrap(): Promise<void> {
   const prefs = await loadPrefs();
   app.theme = prefs.theme ?? 'auto';
@@ -584,6 +592,13 @@ export async function bootstrap(): Promise<void> {
     window.visualViewport.addEventListener('scroll', syncViewportHeight);
   }
 
+  // Load the Telegram Mini App SDK dynamically, with a timeout, on a Telegram entry — it is no
+  // longer a render-blocking <script> in index.html, so a network that blocks telegram.org (common
+  // where Telegram itself reaches users only over a proxy) cannot hang the page and strand the app
+  // or the diagnostic screen below. Skipped on a plain web / native entry, which never needs it.
+  if (onTelegramPath() || hasLaunchFragment()) {
+    await loadTelegramSDK(TELEGRAM_SDK_TIMEOUT_MS);
+  }
   // Telegram Mini App launch: apply the platform theme, authenticate via initData, and route any
   // deep-link start parameter. On the dedicated /telegram/ entry without sign-in data (no/empty
   // initData — outside Telegram, or a Mini App launch that delivered none, as seen on some Android
@@ -675,6 +690,8 @@ export async function retryTelegramBoot(): Promise<void> {
  * so a reload could discard the very data we are waiting for.
  */
 export async function retryTelegramLaunch(): Promise<void> {
+  // Re-attempt the SDK load — the network may have recovered since the launch-error screen showed.
+  await loadTelegramSDK(TELEGRAM_SDK_TIMEOUT_MS);
   if (!insideTelegram()) {
     app.launchError = collectTelegramDiag();
     return;
diff --git a/ui/src/lib/telegram.test.ts b/ui/src/lib/telegram.test.ts
index d365282..cb71a30 100644
--- a/ui/src/lib/telegram.test.ts
+++ b/ui/src/lib/telegram.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   collectTelegramDiag,
   insideTelegram,
+  loadTelegramSDK,
   routeExternalLinkInTelegram,
   telegramClosingConfirmation,
   telegramLaunch,
@@ -197,3 +198,35 @@ describe('collectTelegramDiag', () => {
     expect(d.fieldsMissing).toEqual(['signature']);
   });
 });
+
+describe('loadTelegramSDK', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('resolves true immediately when the SDK is already present', async () => {
+    vi.stubGlobal('window', { Telegram: { WebApp: { initData: '' } } });
+    vi.stubGlobal('document', { createElement: vi.fn(), head: { appendChild: vi.fn() } });
+    await expect(loadTelegramSDK(10000)).resolves.toBe(true);
+  });
+
+  it('resolves false when the script errors (telegram.org unreachable)', async () => {
+    const script: Record<string, unknown> = {};
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('document', {
+      createElement: () => script,
+      head: { appendChild: () => (script.onerror as () => void)() },
+    });
+    await expect(loadTelegramSDK(10000)).resolves.toBe(false);
+  });
+
+  it('resolves false when the script hangs past the timeout', async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('document', { createElement: () => ({}), head: { appendChild: vi.fn() } });
+    const p = loadTelegramSDK(10000);
+    await vi.advanceTimersByTimeAsync(10000);
+    await expect(p).resolves.toBe(false);
+  });
+});
diff --git a/ui/src/lib/telegram.ts b/ui/src/lib/telegram.ts
index aa67709..be4ca76 100644
--- a/ui/src/lib/telegram.ts
+++ b/ui/src/lib/telegram.ts
@@ -1,6 +1,7 @@
-// Telegram Mini App SDK access. The official telegram-web-app.js (loaded in
-// index.html) exposes window.Telegram.WebApp; this wraps the subset the app uses:
-// launch detection, initData (for auth.telegram), the deep-link start parameter,
+// Telegram Mini App SDK access. The official telegram-web-app.js (loaded dynamically with a
+// timeout by loadTelegramSDK — not a render-blocking <script> in index.html, so a network that
+// blocks telegram.org cannot hang the page) exposes window.Telegram.WebApp; this wraps the subset
+// the app uses: launch detection, initData (for auth.telegram), the deep-link start parameter,
 // theme params, and ready()/expand(). Every helper is safe to call outside Telegram.
 
 import type { TelegramThemeParams } from './theme';
@@ -54,6 +55,47 @@ export function insideTelegram(): boolean {
   return !!w && typeof w.initData === 'string' && w.initData.length > 0;
 }
 
+// The ?NN suffix pins the Bot API SDK version Telegram serves (and busts the cache); keep it at the
+// version the official Mini Apps page currently recommends so newer client features (fullscreen,
+// safe-area insets, vertical-swipe guard, …) are available. Bump it when Telegram bumps theirs.
+const sdkScriptSrc = 'https://telegram.org/js/telegram-web-app.js?62';
+
+/**
+ * loadTelegramSDK injects the official telegram-web-app.js and resolves true once
+ * window.Telegram.WebApp is available, or false if the script errors or does not load within
+ * timeoutMs. It is loaded dynamically — not a render-blocking <script> in index.html — so a network
+ * that blocks telegram.org (common where Telegram itself reaches users only over a proxy) cannot
+ * hang the page and strand the app or the launch-error screen. Resolves true immediately when the
+ * SDK is already present (a cached load, or a future native injection); a fast connection failure
+ * resolves via the error event without waiting out the timeout, so the timeout only bounds a true
+ * hang.
+ */
+export function loadTelegramSDK(timeoutMs: number): Promise<boolean> {
+  if (typeof document === 'undefined') return Promise.resolve(false);
+  if (webApp()) return Promise.resolve(true);
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const finish = (ok: boolean): void => {
+      if (done) return;
+      done = true;
+      resolve(ok);
+    };
+    const timer = setTimeout(() => finish(!!webApp()), timeoutMs);
+    const s = document.createElement('script');
+    s.src = sdkScriptSrc;
+    s.async = true;
+    s.onload = () => {
+      clearTimeout(timer);
+      finish(!!webApp());
+    };
+    s.onerror = () => {
+      clearTimeout(timer);
+      finish(false);
+    };
+    document.head.appendChild(s);
+  });
+}
+
 /**
  * telegramOpenLink opens a t.me link through the Mini App SDK, so Telegram navigates to
  * it natively (e.g. a bot chat) rather than spawning an in-app browser tab. Returns false
@@ -303,6 +345,14 @@ export function onTelegramPath(): boolean {
   return location.pathname.startsWith('/telegram/');
 }
 
+/** hasLaunchFragment reports whether the URL fragment carries Telegram launch params (tgWebApp…),
+ *  the form Telegram appends when opening a Mini App — so the SDK is loaded for a Mini App opened
+ *  at the site root too, not only the /telegram/ path. */
+export function hasLaunchFragment(): boolean {
+  if (typeof location === 'undefined') return false;
+  return location.hash.includes('tgWebApp');
+}
+
 // --- Launch diagnostics (the /telegram/ entry without sign-in data) ---
 
 /** The initData fields a valid Telegram launch is expected to carry; their absence is the signal