Merge pull request 'release: v1.4.0 — Telegram launch diagnostic + dynamic SDK load' (#127) from development into master

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.

docs/ARCHITECTURE.md

@@ -1040,8 +1040,9 @@ a dedicated redeem sub-limit or a longer code is the hardening step if abuse app
 Single public origin, path-routed. The Vite build has two entries: a lightweight
 **landing page** and the game **SPA**. The gateway **embeds** the SPA build
 (`go:embed`, baked in by a node stage in `gateway/Dockerfile`) and serves it at
-`/app/` (web) and `/telegram/` (the Telegram Mini App; outside Telegram that path
+`/app/` (web) and `/telegram/` (the Telegram Mini App; on that path without sign-in data
-redirects to the root — the client-side guard); a stray hit on the gateway's `/`
+— no `initData` — the client renders a compact, shareable launch-diagnostic screen instead
+of redirecting away); a stray hit on the gateway's `/`
 308-redirects to `/app/`. The **landing** ships in its own static container: the
 `landing` target of `gateway/Dockerfile` (caddy:2-alpine + the same Vite build,
 `deploy/landing/Caddyfile`) serves it at `/`, so stray public traffic is absorbed by

docs/UI_DESIGN.md

@@ -8,7 +8,13 @@ emoji glyphs. Tokens are CSS custom properties (`ui/src/app.css`), light/dark vi
 `prefers-color-scheme` or an explicit Settings choice, and **Telegram-themed**:
 on a Telegram Mini App launch — the app is served under `/telegram/` and detects the
 launch by `Telegram.WebApp.initData` — the SDK's `themeParams` override the tokens at
-runtime; opened outside Telegram, the `/telegram/` path redirects to the site root.
+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. `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`)
 

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
+// telegram-web-app.js (the app loads it dynamically — see lib/telegram.ts loadTelegramSDK) so the
-// on telegram.org — it is unreachable from the CI runner, and a render-blocking
+// suite never reaches telegram.org, which is unreachable from the CI runner. Specs that exercise
-// <script> to it would hang every page load. Specs that exercise the Telegram launch
+// the Telegram launch inject their own window.Telegram via addInitScript before navigating, so the
-// inject their own window.Telegram via addInitScript before navigating.
+// 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);

ui/e2e/telegram.spec.ts

@@ -107,11 +107,30 @@ test('inside Telegram, a failed launch shows the retry screen, not the web login
   await expect(page.getByRole('button', { name: /guest/i })).toHaveCount(0);
 });
 
-test('outside Telegram, the /telegram/ entry redirects to the site root', async ({ page }) => {
+test('outside Telegram, the /telegram/ entry shows the launch diagnostic, not a redirect', async ({
+  page,
+}) => {
   await page.goto('/telegram/');
 
-  // The guard sends a non-Telegram visitor back to the root, where the normal
+  // The entry no longer bounces a visitor without Telegram sign-in data to the marketing landing;
-  // (guest / email) login is shown.
+  // it shows a compact diagnostic screen (Share + Retry) that helps pinpoint why initData was
-  await expect(page.getByRole('button', { name: /guest/i })).toBeVisible();
+  // absent — notably the Android empty-initData failure.
-  await expect(page).not.toHaveURL(/\/telegram\//);
+  await expect(page.getByRole('button', { name: 'Share' })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+  // It stays on /telegram/ (no redirect) and never shows the web (guest) login.
+  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();
+  // The diagnostic names the load outcome: a failed fetch reads as sdk-load: error.
+  await expect(page.getByText('sdk-load: error')).toBeVisible();
 });

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
+    <!-- The Telegram Mini App SDK (window.Telegram.WebApp) is deliberately NOT loaded here: a
-         Telegram (initData is empty), so it loads on every entry. -->
+         render-blocking <script> to telegram.org hangs the whole page on a network that blocks
-    <script src="https://telegram.org/js/telegram-web-app.js"></script>
+         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

ui/src/App.svelte

@@ -19,6 +19,7 @@
   import Feedback from './screens/Feedback.svelte';
   import Blocked from './screens/Blocked.svelte';
   import BootError from './screens/BootError.svelte';
+  import TelegramLaunchError from './screens/TelegramLaunchError.svelte';
 
   onMount(() => {
     void bootstrap();
@@ -84,6 +85,11 @@
   {#if !routeIsLobby}
     <div class="splash">{t('common.loading')}</div>
   {/if}
+{:else if app.launchError}
+  <!-- The /telegram/ entry without sign-in data: a compact, shareable diagnostic screen instead
+       of bouncing to the marketing landing (also the probe for the empty-initData failure on
+       some Android clients). -->
+  <TelegramLaunchError />
 {:else if app.bootError}
   <!-- A Mini App launch that failed to authenticate (e.g. the backend was down mid-deploy):
        show the retry screen instead of falling back to the web login. -->
@@ -128,7 +134,7 @@
 <StaleInviteModal />
 <WelcomeRedeemModal />
 
-{#if routeIsLobby && !app.splashDone && !app.blocked && !app.bootError}
+{#if routeIsLobby && !app.splashDone && !app.blocked && !app.bootError && !app.launchError}
   <Splash />
 {/if}
 

ui/src/lib/app.svelte.ts

@@ -12,7 +12,11 @@ import { languageNeedsServerSync } from './language';
 import { applyReduceMotion, applyTelegramTheme, applyTheme, type ThemePref } from './theme';
 import {
   insideTelegram,
+  collectTelegramDiag,
+  type TelegramDiag,
   onTelegramPath,
+  hasLaunchFragment,
+  loadTelegramSDK,
   telegramColorScheme,
   telegramContentSafeAreaTop,
   telegramSafeAreaTop,
@@ -47,6 +51,11 @@ export const app = $state<{
    *  backend was down during a deploy). App.svelte then renders the boot-error retry screen
    *  instead of the web login — a Mini App has no manual sign-in to fall back to. */
   bootError: boolean;
+  /** On the dedicated /telegram/ entry, set to a privacy-safe diagnostic snapshot when a Mini App
+   *  launch carried no sign-in data (empty initData). App.svelte then renders the compact
+   *  launch-error screen (screens/TelegramLaunchError) — a shareable probe for why Telegram
+   *  delivered no initData (seen on some Android clients) — instead of bouncing to the landing. */
+  launchError: TelegramDiag | null;
   /** Whether the lobby's first cold load has settled (success or error). The loading splash
    *  (components/Splash.svelte) watches it to know when to dismiss; set by screens/Lobby. */
   lobbyReady: boolean;
@@ -96,6 +105,7 @@ export const app = $state<{
 }>({
   ready: false,
   bootError: false,
+  launchError: null,
   lobbyReady: false,
   splashDone: false,
   streamAlive: false,
@@ -530,6 +540,35 @@ function syncViewportHeight(): void {
   if (h > 0) document.documentElement.style.setProperty('--vvh', `${h}px`);
 }
 
+/**
+ * applyTelegramChrome applies a Mini App launch's visual integration: Telegram's authoritative
+ * colour scheme and theme, the matching header / background / bottom chrome, the safe-area insets,
+ * the swipe-down guard, and immersive fullscreen on mobile. It is idempotent, so both the initial
+ * bootstrap and a manual launch retry call it.
+ */
+function applyTelegramChrome(launch: TelegramLaunch): void {
+  if (launch.theme) applyTelegramTheme(launch.theme);
+  // Inside Telegram the colour scheme is Telegram's to decide; force it explicitly so the OS
+  // prefers-color-scheme (which leaks into the Telegram Desktop webview) cannot fight it. Falls
+  // back to the stored preference when the SDK omits it.
+  applyTheme(telegramColorScheme() ?? app.theme);
+  // Match Telegram's chrome to the app and stop its swipe-down-to-minimise from fighting tile
+  // drag / board scroll.
+  syncTelegramChrome();
+  syncTelegramSafeArea();
+  telegramDisableVerticalSwipes();
+  // On mobile, go immersive fullscreen like Telegram's own Mini Apps; the fullscreenChanged
+  // listener (registered at bootstrap) then re-syncs the safe-area insets. Desktop keeps the bot's
+  // full-size window. No-op on clients predating Bot API 8.0.
+  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';
@@ -553,33 +592,30 @@ export async function bootstrap(): Promise<void> {
     window.visualViewport.addEventListener('scroll', syncViewportHeight);
   }
 
-  // Telegram Mini App launch: apply the platform theme, authenticate via initData,
+  // Load the Telegram Mini App SDK dynamically, with a timeout, on a Telegram entry — it is no
-  // and route any deep-link start parameter. On the dedicated /telegram/ entry path
+  // longer a render-blocking <script> in index.html, so a network that blocks telegram.org (common
-  // outside Telegram (no initData), refuse to render and send the visitor to the
+  // where Telegram itself reaches users only over a proxy) cannot hang the page and strand the app
-  // site root.
+  // 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
+  // clients), render the compact launch-error screen with a diagnostic snapshot the user can share
+  // with the developer, instead of bouncing the visitor to the marketing landing.
   if (onTelegramPath() && !insideTelegram()) {
-    if (typeof location !== 'undefined') location.replace('/');
+    app.launchError = collectTelegramDiag();
+    app.ready = true;
     return;
   }
   if (insideTelegram()) {
     const launch = telegramLaunch();
-    if (launch.theme) applyTelegramTheme(launch.theme);
+    applyTelegramChrome(launch);
-    // Inside Telegram the colour scheme is Telegram's to decide; force it explicitly
+    // Re-sync the safe-area insets whenever Telegram's chrome changes (registered once per load).
-    // so the OS prefers-color-scheme (which leaks into the Telegram Desktop webview)
-    // cannot fight it. Falls back to the stored preference when the SDK omits it.
-    applyTheme(telegramColorScheme() ?? app.theme);
-    // Match Telegram's chrome to the app and stop its swipe-down-to-minimise from
-    // fighting tile drag / board scroll.
-    syncTelegramChrome();
-    syncTelegramSafeArea();
     telegramOnEvent('contentSafeAreaChanged', syncTelegramSafeArea);
     telegramOnEvent('safeAreaChanged', syncTelegramSafeArea);
     telegramOnEvent('fullscreenChanged', syncTelegramSafeArea);
-    telegramDisableVerticalSwipes();
-    // On mobile, go immersive fullscreen like Telegram's own Mini Apps; the fullscreenChanged
-    // listener above then re-syncs the safe-area insets. Desktop keeps the bot's full-size
-    // window. No-op on clients predating Bot API 8.0.
-    telegramRequestFullscreen();
     await bootTelegram(launch);
     app.ready = true;
     return;
@@ -646,6 +682,28 @@ export async function retryTelegramBoot(): Promise<void> {
   app.ready = true;
 }
 
+/**
+ * retryTelegramLaunch re-attempts a Mini App launch from the launch-error screen's Retry button. If
+ * sign-in data is present now (e.g. it arrived late on a slow client) it clears the error and runs
+ * the normal launch; otherwise it refreshes the diagnostic snapshot so the screen reflects the
+ * current state. It never reloads — telegram-web-app.js consumes the launch fragment on first load,
+ * 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;
+  }
+  app.launchError = null;
+  app.ready = false;
+  const launch = telegramLaunch();
+  applyTelegramChrome(launch);
+  await bootTelegram(launch);
+  app.ready = true;
+}
+
 /**
  * routeStartParam navigates a Telegram deep-link start parameter to its target: a
  * specific game, the friends screen with a friend-code redemption, or the lobby

ui/src/lib/i18n/en.ts

@@ -14,6 +14,11 @@ export const en = {
   'boot.errorTitle': "Couldn't load the game",
   'boot.errorBody': 'Please try again in a moment.',
 
+  'launch.errorTitle': "Can't open in Telegram",
+  'launch.errorBody': 'Screenshot or share this with the developer.',
+  'launch.share': 'Share',
+  'launch.copied': 'Copied',
+
   'common.back': 'Back',
   'common.cancel': 'Cancel',
   'common.ok': 'OK',

ui/src/lib/i18n/ru.ts

@@ -15,6 +15,11 @@ export const ru: Record<MessageKey, string> = {
   'boot.errorTitle': 'Не удалось загрузить игру',
   'boot.errorBody': 'Попробуйте ещё раз или зайдите позже.',
 
+  'launch.errorTitle': 'Не открывается в Telegram',
+  'launch.errorBody': 'Сделайте скриншот или поделитесь с разработчиком.',
+  'launch.share': 'Поделиться',
+  'launch.copied': 'Скопировано',
+
   'common.back': 'Назад',
   'common.cancel': 'Отмена',
   'common.ok': 'ОК',

ui/src/lib/share.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { pickGcgDelivery, shareOrDownloadGcg } from './share';
+import { pickGcgDelivery, pickTextShare, shareOrDownloadGcg, shareText } from './share';
 import type { GcgExport } from './model';
 
 const file = {} as File;
@@ -60,3 +60,42 @@ describe('shareOrDownloadGcg', () => {
     expect(anchor.click).toHaveBeenCalledOnce();
   });
 });
+
+describe('pickTextShare', () => {
+  it('shares when Web Share is available', () => {
+    expect(pickTextShare({ share: async () => {}, canShare: () => true })).toBe('share');
+  });
+
+  it('shares when share exists without canShare (text needs no file capability check)', () => {
+    expect(pickTextShare({ share: async () => {} })).toBe('share');
+  });
+
+  it('copies when there is no Web Share (desktop)', () => {
+    expect(pickTextShare(undefined)).toBe('copy');
+    expect(pickTextShare({} as never)).toBe('copy');
+  });
+});
+
+describe('shareText', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('uses the OS share sheet when available', async () => {
+    const share = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal('navigator', { share, canShare: () => true });
+    expect(await shareText('diag', 'title')).toBe('shared');
+    expect(share).toHaveBeenCalledWith({ title: 'title', text: 'diag' });
+  });
+
+  it('copies to the clipboard when Web Share is absent (desktop)', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal('navigator', { clipboard: { writeText } });
+    expect(await shareText('diag', 'title')).toBe('copied');
+    expect(writeText).toHaveBeenCalledWith('diag');
+  });
+
+  it('reports failure without a fallback when the share is cancelled', async () => {
+    const share = vi.fn().mockRejectedValue(new DOMException('cancelled', 'AbortError'));
+    vi.stubGlobal('navigator', { share, canShare: () => true });
+    expect(await shareText('diag', 'title')).toBe('failed');
+  });
+});

ui/src/lib/share.ts

@@ -51,3 +51,42 @@ function downloadFile(content: string, filename: string): void {
   a.remove();
   URL.revokeObjectURL(url);
 }
+
+type TextShareNav = Pick<Navigator, 'share'> & { canShare?: Navigator['canShare'] };
+
+/**
+ * pickTextShare decides how to deliver a plain-text payload: through the OS share sheet (Web Share,
+ * available on mobile including the Telegram Mini App) or, on a desktop browser without it, a
+ * clipboard copy. Pure, so it is unit-tested with a mock navigator.
+ */
+export function pickTextShare(nav: TextShareNav | undefined): 'share' | 'copy' {
+  if (nav && typeof nav.share === 'function' && (typeof nav.canShare !== 'function' || nav.canShare({ text: 'x' }))) {
+    return 'share';
+  }
+  return 'copy';
+}
+
+/**
+ * shareText delivers text through the OS share sheet where supported, else copies it to the
+ * clipboard. It reports the path taken — 'shared', 'copied', or 'failed' (a cancelled share or an
+ * unavailable clipboard) — so the caller can confirm a silent copy to the user. Like
+ * shareOrDownloadGcg it never strands the webview: a cancelled share simply does nothing.
+ */
+export async function shareText(text: string, title: string): Promise<'shared' | 'copied' | 'failed'> {
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+  if (!nav) return 'failed';
+  if (pickTextShare(nav) === 'share') {
+    try {
+      await nav.share({ title, text });
+      return 'shared';
+    } catch {
+      return 'failed';
+    }
+  }
+  try {
+    await nav.clipboard.writeText(text);
+    return 'copied';
+  } catch {
+    return 'failed';
+  }
+}

ui/src/lib/telegram.test.ts

@@ -1,6 +1,9 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
+  collectTelegramDiag,
   insideTelegram,
+  loadTelegramSDK,
+  telegramSdkOutcome,
   routeExternalLinkInTelegram,
   telegramClosingConfirmation,
   telegramLaunch,
@@ -155,3 +158,106 @@ describe('routeExternalLinkInTelegram', () => {
     expect(routeExternalLinkInTelegram({ href: 'https://x.io', target: '_blank' })).toBe(false);
   });
 });
+
+describe('collectTelegramDiag', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('reports a missing SDK outside Telegram', () => {
+    const d = collectTelegramDiag();
+    expect(d.hasSDK).toBe(false);
+    expect(d.hasWebApp).toBe(false);
+    expect(d.initDataLen).toBe(0);
+    expect(d.fieldsPresent).toEqual([]);
+    expect(d.fieldsMissing).toEqual(['user', 'auth_date', 'hash', 'signature']);
+  });
+
+  it('reads field NAMES (never values) from a non-empty initData', () => {
+    stubWebApp('query_id=abc&user=%7B%7D&auth_date=1&hash=deadbeef');
+    const d = collectTelegramDiag();
+    expect(d.hasSDK).toBe(true);
+    expect(d.hasWebApp).toBe(true);
+    expect(d.initDataLen).toBeGreaterThan(0);
+    expect(d.fieldsPresent).toEqual(['query_id', 'user', 'auth_date', 'hash']);
+    expect(d.fieldsMissing).toEqual(['signature']);
+  });
+
+  it('recovers field names from the URL fragment when the SDK left initData empty', () => {
+    // Telegram passed launch data in the fragment, but WebApp.initData is empty (the Android
+    // failure this screen diagnoses): the names come from the raw fragment instead, and
+    // hashHadTgData flags that the data did arrive in the URL.
+    vi.stubGlobal('window', { Telegram: { WebApp: { initData: '', platform: 'android' } } });
+    vi.stubGlobal('location', {
+      hash: '#tgWebAppData=user%3D%257B%257D%26auth_date%3D1%26hash%3Ddeadbeef&tgWebAppVersion=7.0',
+      pathname: '/telegram/',
+    });
+    const d = collectTelegramDiag();
+    expect(d.hasSDK).toBe(true);
+    expect(d.platform).toBe('android');
+    expect(d.initDataLen).toBe(0);
+    expect(d.hashHadTgData).toBe(true);
+    expect(d.fieldsPresent).toEqual(['user', 'auth_date', 'hash']);
+    expect(d.fieldsMissing).toEqual(['signature']);
+  });
+});
+
+describe('loadTelegramSDK', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('resolves true and records "present" when the SDK is already there', async () => {
+    vi.stubGlobal('window', { Telegram: { WebApp: { initData: '' } } });
+    vi.stubGlobal('document', { createElement: vi.fn(), head: { appendChild: vi.fn() } });
+    await expect(loadTelegramSDK(10000)).resolves.toBe(true);
+    expect(telegramSdkOutcome()).toBe('present');
+  });
+
+  it('records "loaded" when the script defines the WebApp', async () => {
+    const script: Record<string, unknown> = {};
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('document', {
+      createElement: () => script,
+      head: {
+        appendChild: () => {
+          (window as unknown as { Telegram: unknown }).Telegram = { WebApp: { initData: '' } };
+          (script.onload as () => void)();
+        },
+      },
+    });
+    await expect(loadTelegramSDK(10000)).resolves.toBe(true);
+    expect(telegramSdkOutcome()).toBe('loaded');
+  });
+
+  it('records "no-webapp" when the script loads but defines nothing', async () => {
+    const script: Record<string, unknown> = {};
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('document', {
+      createElement: () => script,
+      head: { appendChild: () => (script.onload as () => void)() },
+    });
+    await expect(loadTelegramSDK(10000)).resolves.toBe(false);
+    expect(telegramSdkOutcome()).toBe('no-webapp');
+  });
+
+  it('records "error" when the script fails to load (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);
+    expect(telegramSdkOutcome()).toBe('error');
+  });
+
+  it('records "timeout" when the script neither loads nor fails in time', 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);
+    expect(telegramSdkOutcome()).toBe('timeout');
+  });
+});

ui/src/lib/telegram.ts

@@ -1,6 +1,7 @@
-// Telegram Mini App SDK access. The official telegram-web-app.js (loaded in
+// Telegram Mini App SDK access. The official telegram-web-app.js (loaded dynamically with a
-// index.html) exposes window.Telegram.WebApp; this wraps the subset the app uses:
+// timeout by loadTelegramSDK — not a render-blocking <script> in index.html, so a network that
-// launch detection, initData (for auth.telegram), the deep-link start parameter,
+// 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';
@@ -9,6 +10,7 @@ interface TelegramWebApp {
   initData: string;
   initDataUnsafe?: { start_param?: string };
   platform?: string;
+  version?: string;
   themeParams?: TelegramThemeParams;
   colorScheme?: 'light' | 'dark';
   isFullscreen?: boolean;
@@ -53,6 +55,72 @@ 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';
+
+/**
+ * TelegramSdkOutcome records how the dynamic telegram-web-app.js load resolved, surfaced on the
+ * launch-error screen to tell the failure modes apart — notably 'error' / 'timeout', which mean the
+ * network could not reach telegram.org (the script blocked or hung):
+ *
+ *   not-attempted — loadTelegramSDK was never called (a plain web / native entry)
+ *   present       — window.Telegram.WebApp was already there (a cached load or native injection)
+ *   loaded        — the script loaded and defined window.Telegram.WebApp
+ *   no-webapp     — the script loaded (HTTP 200) but did not define window.Telegram.WebApp
+ *   error         — the script failed to load (telegram.org unreachable / blocked, a fast failure)
+ *   timeout       — the script neither loaded nor failed within the timeout (a blocked, hanging fetch)
+ */
+export type TelegramSdkOutcome = 'not-attempted' | 'present' | 'loaded' | 'no-webapp' | 'error' | 'timeout';
+
+let sdkLoadOutcome: TelegramSdkOutcome = 'not-attempted';
+
+/** telegramSdkOutcome returns how the last loadTelegramSDK attempt resolved (see TelegramSdkOutcome). */
+export function telegramSdkOutcome(): TelegramSdkOutcome {
+  return sdkLoadOutcome;
+}
+
+/**
+ * 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()) {
+    sdkLoadOutcome = 'present';
+    return Promise.resolve(true);
+  }
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const finish = (outcome: TelegramSdkOutcome): void => {
+      if (done) return;
+      done = true;
+      sdkLoadOutcome = outcome;
+      resolve(outcome === 'loaded');
+    };
+    const timer = setTimeout(() => finish(webApp() ? 'loaded' : 'timeout'), timeoutMs);
+    const s = document.createElement('script');
+    s.src = sdkScriptSrc;
+    s.async = true;
+    s.onload = () => {
+      clearTimeout(timer);
+      finish(webApp() ? 'loaded' : 'no-webapp');
+    };
+    s.onerror = () => {
+      clearTimeout(timer);
+      finish('error');
+    };
+    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
@@ -302,6 +370,132 @@ 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
+ *  the launch-error screen reports. Only field names are ever inspected, never their values. */
+const expectedInitDataFields = ['user', 'auth_date', 'hash', 'signature'];
+
+interface uaBrand {
+  brand: string;
+  version: string;
+}
+
+interface uaDataValue {
+  platform?: string;
+  mobile?: boolean;
+  brands?: uaBrand[];
+}
+
+/** uaData returns the User-Agent Client Hints object (Chromium only — notably the Android Telegram
+ *  webview), or undefined where it is unavailable (iOS / Safari / Firefox). */
+function uaData(): uaDataValue | undefined {
+  if (typeof navigator === 'undefined') return undefined;
+  return (navigator as unknown as { userAgentData?: uaDataValue }).userAgentData;
+}
+
+/** launchFragmentData returns the raw tgWebAppData carried in the URL fragment (the form Telegram
+ *  appends on launch), or '' when absent. With no SDK present a non-empty value means Telegram
+ *  delivered the data but telegram-web-app.js never ran to parse it. */
+function launchFragmentData(): string {
+  if (typeof location === 'undefined') return '';
+  const frag = location.hash.replace(/^#/, '');
+  if (!frag) return '';
+  try {
+    return new URLSearchParams(frag).get('tgWebAppData') ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/** initDataFieldNames parses a Telegram initData (or raw fragment data) query string and returns
+ *  only its field NAMES — never the values, since the hash / signature are auth material. */
+function initDataFieldNames(raw: string): string[] {
+  if (!raw) return [];
+  try {
+    return [...new URLSearchParams(raw).keys()];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * TelegramDiag is a privacy-safe snapshot of why a Mini App launch lacked sign-in data, taken at
+ * the moment of failure and rendered on the launch-error screen so a stuck user can share it with
+ * the developer. It carries no secret values — only presence flags, client / OS identification and
+ * the field NAMES of the launch data, never the signed initData itself, and never an IP.
+ */
+export interface TelegramDiag {
+  /** Whether window.Telegram (the telegram-web-app.js script) is present at all. */
+  hasSDK: boolean;
+  /** Whether window.Telegram.WebApp is present. */
+  hasWebApp: boolean;
+  /** How the dynamic telegram-web-app.js load resolved (see TelegramSdkOutcome) — 'error' /
+   *  'timeout' mean telegram.org was unreachable, the prime suspect for an empty launch. */
+  sdkLoad: TelegramSdkOutcome;
+  /** Telegram's own platform string (ios | android | android_x | tdesktop | web | …), or ''. */
+  platform: string;
+  /** The Bot API version the client reports, or ''. */
+  version: string;
+  /** The length of WebApp.initData — 0 is the failure this screen reports. */
+  initDataLen: number;
+  /** Whether the URL fragment still carried tgWebAppData at launch; true with hasSDK false means
+   *  Telegram delivered the data but the SDK script did not load to parse it. */
+  hashHadTgData: boolean;
+  /** The field names present in the launch data (from initData, or the raw fragment when the SDK
+   *  left initData empty); values are never included. */
+  fieldsPresent: string[];
+  /** The expected field names absent from the launch data (a subset of expectedInitDataFields). */
+  fieldsMissing: string[];
+  /** The OS / platform per User-Agent Client Hints (else navigator.platform), e.g. 'Android', ''. */
+  osPlatform: string;
+  /** Whether the client reports itself mobile per Client Hints: 'yes' | 'no' | '' (unknown). */
+  mobile: string;
+  /** The browser brands + major versions per Client Hints (Chromium only), or ''. */
+  browser: string;
+  /** The full User-Agent string — the catch-all that also carries the OS version and webview build. */
+  userAgent: string;
+}
+
+/**
+ * collectTelegramDiag captures a TelegramDiag snapshot of the current launch state. Call it at the
+ * point a /telegram/ launch is found to lack sign-in data, so the snapshot reflects that moment —
+ * sign-in data arriving late would otherwise mask the failure.
+ */
+export function collectTelegramDiag(): TelegramDiag {
+  const w = webApp();
+  const sdk = typeof window !== 'undefined' && !!(window as unknown as { Telegram?: unknown }).Telegram;
+  const initData = w?.initData ?? '';
+  const fragData = initData ? '' : launchFragmentData();
+  const present = initDataFieldNames(initData || fragData);
+  const ua = uaData();
+  const navPlatform =
+    typeof navigator === 'undefined' ? '' : (navigator as unknown as { platform?: string }).platform ?? '';
+  return {
+    hasSDK: sdk,
+    hasWebApp: !!w,
+    sdkLoad: sdkLoadOutcome,
+    platform: w?.platform ?? '',
+    version: w?.version ?? '',
+    initDataLen: initData.length,
+    hashHadTgData: fragData.length > 0,
+    fieldsPresent: present,
+    fieldsMissing: expectedInitDataFields.filter((f) => !present.includes(f)),
+    osPlatform: ua?.platform ?? navPlatform,
+    mobile: ua?.mobile === undefined ? '' : ua.mobile ? 'yes' : 'no',
+    browser: (ua?.brands ?? []).map((b) => `${b.brand} ${b.version}`).join(', '),
+    userAgent: typeof navigator === 'undefined' ? '' : navigator.userAgent,
+  };
+}
+
 // --- Login Widget (web sign-in for account linking) ---
 
 // The Login Widget is the web (non-Mini-App) Telegram sign-in. It is used only to

ui/src/screens/TelegramLaunchError.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+  // Shown on the dedicated /telegram/ entry when a Mini App launch carried no sign-in data (empty
+  // initData) — instead of bouncing the visitor to the marketing landing. It states the problem
+  // plainly and renders a compact, privacy-safe diagnostic snapshot (taken at the moment of
+  // failure, app.launchError) sized to fit one screenshot, with a Share button (the OS share sheet,
+  // or a clipboard copy on desktop) so a stuck user can send it to the developer to pinpoint why
+  // Telegram provided no initData — notably on some Android clients. The snapshot carries only
+  // presence / identification signals and field NAMES, never the signed initData itself, nor an IP.
+  import { app, retryTelegramLaunch } from '../lib/app.svelte';
+  import { shareText } from '../lib/share';
+  import { t } from '../lib/i18n/index.svelte';
+
+  const diag = $derived(app.launchError);
+
+  // One compact "key: value" line per fact; the field labels are fixed diagnostic tokens (not UI
+  // prose), so the developer reads the same report in any locale. Kept terse to fit one screenshot.
+  const report = $derived(
+    diag
+      ? [
+          `sdk-load: ${diag.sdkLoad}`,
+          `sdk: ${diag.hasSDK ? 'yes' : 'no'}   webapp: ${diag.hasWebApp ? 'yes' : 'no'}`,
+          `tg-platform: ${diag.platform || '—'}   tg-version: ${diag.version || '—'}`,
+          `initData: ${diag.initDataLen > 0 ? diag.initDataLen : 'empty'}   tgdata-in-url: ${diag.hashHadTgData ? 'yes' : 'no'}`,
+          `fields: ${diag.fieldsPresent.join(',') || '—'}`,
+          `missing: ${diag.fieldsMissing.join(',') || '—'}`,
+          `os: ${diag.osPlatform || '—'}   mobile: ${diag.mobile || '—'}`,
+          `browser: ${diag.browser || '—'}`,
+          `ua: ${diag.userAgent || '—'}`,
+        ].join('\n')
+      : '',
+  );
+
+  let retrying = $state(false);
+  async function retry(): Promise<void> {
+    if (retrying) return;
+    retrying = true;
+    try {
+      await retryTelegramLaunch();
+    } finally {
+      retrying = false;
+    }
+  }
+
+  let copied = $state(false);
+  let copyTimer: ReturnType<typeof setTimeout> | undefined;
+  async function share(): Promise<void> {
+    const r = await shareText(report, t('launch.errorTitle'));
+    // The OS share sheet is its own feedback; a desktop clipboard copy is silent, so confirm it.
+    if (r === 'copied') {
+      copied = true;
+      clearTimeout(copyTimer);
+      copyTimer = setTimeout(() => (copied = false), 1500);
+    }
+  }
+</script>
+
+{#if diag}
+  <div class="boot">
+    <div class="card">
+      <h1>{t('launch.errorTitle')}</h1>
+      <p class="msg">{t('launch.errorBody')}</p>
+      <pre class="diag">{report}</pre>
+      <div class="actions">
+        <button class="share" onclick={share}>{copied ? t('launch.copied') : t('launch.share')}</button>
+        <button class="retry" onclick={retry} disabled={retrying}>{t('common.retry')}</button>
+      </div>
+    </div>
+  </div>
+{/if}
+
+<style>
+  .boot {
+    height: 100%;
+    display: grid;
+    place-items: center;
+    padding: 16px;
+    background: var(--bg);
+  }
+  .card {
+    max-width: 32rem;
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+    text-align: center;
+    color: var(--text);
+  }
+  h1 {
+    margin: 0;
+    font-size: 1.1rem;
+  }
+  .msg {
+    margin: 0;
+    color: var(--text-muted);
+    font-size: 0.9rem;
+  }
+  .diag {
+    margin: 0;
+    text-align: left;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 11px;
+    line-height: 1.4;
+    color: var(--text);
+    background: var(--bg-elev);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    padding: 8px 10px;
+  }
+  .actions {
+    display: flex;
+    justify-content: center;
+    gap: 0.5rem;
+  }
+  .share,
+  .retry {
+    padding: 8px 16px;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--accent);
+  }
+  .share {
+    background: var(--accent);
+    color: var(--accent-text);
+  }
+  .retry {
+    background: transparent;
+    color: var(--accent);
+  }
+  .retry:disabled {
+    opacity: 0.5;
+  }
+</style>