2026-06-23 08:32:18 +00:00
7 changed files with 129 additions and 12 deletions
@@ -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`)

@@ -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);
@@ -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();
+});
@@ -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
@@ -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;
@@ -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);
+  });
+});
@@ -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