Merge pull request 'fix(offline): cold-boot offline from the persisted session + profile' (#199) from feature/offline-boot into development

docs/ARCHITECTURE.md

@@ -1259,7 +1259,11 @@ eligible installed PWA (standalone web + confirmed email) **background-preloads*
 — on lobby entry and on a variant-preference change — through the same three-tier loader, retried
 with backoff and honouring the session miss-breaker; the move generator, the loader and the preload
 orchestration stay in lazy chunks. A first-lobby preload failure shows a *poor-connection* notice in
-the ad-banner slot. The gateway registers the `.webmanifest` MIME type
+the ad-banner slot. A **cold launch already in offline mode** boots from the persisted session and
+profile (the profile is saved on every online adopt/refresh) — `bootstrap` skips the session
+adoption and profile fetch that would otherwise hang with no network, and lands straight in the
+offline lobby; without a cached profile (an install that was never online) it drops the sticky flag
+and boots online instead. The gateway registers the `.webmanifest` MIME type
 in-process (the distroless image has no `/etc/mime.types`). Hash-named `/assets/*` are served
 `immutable` (a relaunch is a cache hit, not a re-download); the HTML shells are
 `no-cache` so a new deploy is picked up — both containers apply the same caching. An

ui/src/lib/app.svelte.ts

@@ -43,6 +43,9 @@ import { parseStartParam } from './deeplink';
 import {
   clearOnboarding,
   clearSession,
+  clearProfile,
+  loadProfile,
+  saveProfile,
   loadOnboarding,
   loadPrefs,
   loadSession,
@@ -53,6 +56,8 @@ import {
 } from './session';
 import type { CoachSeries } from './coachmark';
 import { connection, reportOffline, reportOnline, resetConnection } from './connection.svelte';
+import { offlineMode } from './offline.svelte';
+import { shouldBootOffline } from './offline';
 import { isConnectionCode } from './retry';
 import { clearGameCache, getCachedGame, setCachedGame } from './gamecache';
 import { advanceCached } from './gamedelta';
@@ -460,6 +465,7 @@ export async function refreshProfile(): Promise<void> {
   if (!app.session) return;
   try {
     app.profile = await gateway.profileGet();
+    void saveProfile($state.snapshot(app.profile)); // keep the offline-boot cache fresh (plain snapshot)
   } catch {
     // Best-effort; the banner just stays as it was until the next fetch.
   }
@@ -517,6 +523,11 @@ async function adoptSession(s: Session): Promise<void> {
   await saveSession(s);
   try {
     app.profile = await gateway.profileGet();
+    // Persist the profile so a later offline cold start can launch from it (its variant
+    // preferences, dictionary versions and display name) without a network fetch. Snapshot to a
+    // plain object first — the reactive $state proxy is not structured-cloneable, so it would fail
+    // the IndexedDB write and fall back to a localStorage entry that loadProfile never reads.
+    void saveProfile($state.snapshot(app.profile));
     // The live interface language follows the device — the explicit local choice (saved in
     // prefs) or the system guess made at bootstrap — and is no longer overridden from the
     // account here: the Telegram bot a user signs in through must not dictate the UI, so a
@@ -790,6 +801,24 @@ export async function bootstrap(): Promise<void> {
   // and skipped in the mock build; see lib/pwa.svelte.
   registerServiceWorker();
 
+  // Deliberate offline mode carried over from a prior session: with no network the session adoption
+  // + profile fetch below would hang the splash, so skip them and launch straight from the cached
+  // session + profile into the offline lobby. Without a cached profile (e.g. storage cleared) fall
+  // through to the normal online flow but KEEP the sticky flag — the mode is the player's choice, and
+  // an online boot re-persists the profile so the next launch goes offline. (A truly offline launch
+  // with no cached profile is unreachable: enabling offline requires a prior online session.)
+  if (offlineMode.active) {
+    const [offlineSession, offlineProfile] = await Promise.all([loadSession(), loadProfile()]);
+    if (shouldBootOffline({ offlineActive: true, hasSession: !!offlineSession, hasProfile: !!offlineProfile })) {
+      gateway.setToken(offlineSession!.token);
+      app.session = offlineSession!;
+      app.profile = offlineProfile!;
+      if (router.route.name === 'login' || router.route.name === 'confirm') navigate('/');
+      app.ready = true;
+      return;
+    }
+  }
+
   const saved = await loadSession();
   // A VK ID web-link callback (?code&device_id&state) rides the URL after the redirect back
   // from VK; capture and clear it here (it needs the restored session to link against).
@@ -1023,6 +1052,7 @@ export async function logout(): Promise<void> {
   app.splashDone = false;
   gateway.setToken(null);
   await clearSession();
+  await clearProfile();
   app.session = null;
   app.profile = null;
   navigate('/login');

ui/src/lib/localgame/serialize.ts

@@ -17,6 +17,9 @@ import type { Variant } from '../model';
 export interface Seat {
   kind: 'human' | 'robot';
   name: string;
+  /** The player's real account id for a human seat, so the client identifies "you" and the correct
+   *  turn exactly as in an online game; absent for the robot (a synthetic id is derived). */
+  accountId?: string;
 }
 
 /** LocalGameRecord is the durable form of one local game — everything needed to reconstruct it. */

ui/src/lib/localgame/source.list.test.ts

@@ -51,6 +51,20 @@ describe('LocalSource.list', () => {
     expect(list.every((g) => g.vsAi && g.status === 'active')).toBe(true);
   });
 
+  it('carries the human seat account id into the GameView so the client identifies "you"', async () => {
+    const src = new LocalSource();
+    await src.create({
+      ...opts('local:me', 3n),
+      seats: [
+        { kind: 'human', name: 'You', accountId: 'acct-42' },
+        { kind: 'robot', name: 'Robot' },
+      ],
+    });
+    const [g] = await src.list();
+    expect(g.seats[0].accountId).toBe('acct-42'); // the human's real id, matched against the session
+    expect(g.seats[1].accountId).not.toBe('acct-42'); // the robot keeps a synthetic id
+  });
+
   it('reconstructs a game persisted by a previous session (not in the source cache)', async () => {
     // Seed the store via one source, then list from a fresh source whose in-memory cache is empty.
     await new LocalSource().create(opts('local:old', 7n));

ui/src/lib/localgame/source.ts

@@ -120,7 +120,7 @@ export class LocalSource implements GameLoopSource {
     const now = nowUnix();
     const record = serializeGame(game, {
       id: opts.id,
-      seats: opts.seats.map((s) => ({ kind: s.kind, name: s.name })),
+      seats: opts.seats.map((s) => ({ kind: s.kind, name: s.name, accountId: s.accountId })),
       createdAtUnix: now,
       updatedAtUnix: now,
       robotLastMoveAtUnix: now,
@@ -341,7 +341,7 @@ export class LocalSource implements GameLoopSource {
     const { game, record } = entry;
     const seats: Seat[] = record.seats.map((s, i) => ({
       seat: i,
-      accountId: `${LOCAL_ID_PREFIX}${s.kind}:${i}`,
+      accountId: s.accountId ?? `${LOCAL_ID_PREFIX}${s.kind}:${i}`,
       displayName: s.name,
       score: game.scoreOf(i),
       hintsUsed: 0,

ui/src/lib/offline.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { loadOfflinePref, saveOfflinePref, offlineReady, missingDicts, offlinePreloadEligible } from './offline';
+import { loadOfflinePref, saveOfflinePref, offlineReady, missingDicts, offlinePreloadEligible, shouldBootOffline } from './offline';
 import type { Variant } from './model';
 
 // A minimal in-memory localStorage for the persistence tests (node has none).
@@ -45,4 +45,11 @@ describe('offline mode helpers', () => {
     expect(offlinePreloadEligible({ ...base, inVK: true })).toBe(false);
     expect(offlinePreloadEligible({ ...base, online: false })).toBe(false);
   });
+
+  it('shouldBootOffline requires the offline flag plus a cached session and profile', () => {
+    expect(shouldBootOffline({ offlineActive: true, hasSession: true, hasProfile: true })).toBe(true);
+    expect(shouldBootOffline({ offlineActive: false, hasSession: true, hasProfile: true })).toBe(false);
+    expect(shouldBootOffline({ offlineActive: true, hasSession: false, hasProfile: true })).toBe(false);
+    expect(shouldBootOffline({ offlineActive: true, hasSession: true, hasProfile: false })).toBe(false);
+  });
 });

ui/src/lib/offline.ts

@@ -58,3 +58,13 @@ export function offlinePreloadEligible(opts: {
 }): boolean {
   return opts.hasEmail && opts.standalone && !opts.inTelegram && !opts.inVK && opts.online;
 }
+
+/**
+ * shouldBootOffline decides whether a cold start skips the network and launches straight into
+ * offline mode: the deliberate offline flag is persisted-on AND a prior online session left a cached
+ * session and profile to start from. Without both (e.g. cleared storage, or a never-online install),
+ * the app must boot online once first — the caller then drops the sticky flag and continues online.
+ */
+export function shouldBootOffline(opts: { offlineActive: boolean; hasSession: boolean; hasProfile: boolean }): boolean {
+  return opts.offlineActive && opts.hasSession && opts.hasProfile;
+}

ui/src/lib/session.ts

@@ -3,7 +3,7 @@
 // re-login), with a localStorage fallback. Losing the store just means re-login —
 // acceptable, and for a guest it simply mints a fresh guest.
 
-import type { Session } from './model';
+import type { Session, Profile } from './model';
 import type { ThemePref } from './theme';
 import type { Locale } from './i18n/catalog';
 import type { BoardLabelMode } from './boardlabels';
@@ -119,6 +119,25 @@ export function clearSession(): Promise<void> {
   return kvDel(SESSION_KEY);
 }
 
+const PROFILE_KEY = 'profile';
+
+/** loadProfile reads the last persisted profile (or null). It backs the offline cold-boot: with no
+ *  network, bootstrap uses it instead of fetching a fresh one. */
+export function loadProfile(): Promise<Profile | null> {
+  return kvGet<Profile>(PROFILE_KEY);
+}
+
+/** saveProfile persists the caller's own profile so a later offline launch can start from it (its
+ *  variant preferences, dictionary versions and display name), best-effort. */
+export function saveProfile(p: Profile): Promise<void> {
+  return kvSet(PROFILE_KEY, p);
+}
+
+/** clearProfile drops the persisted profile (on logout, with the session). */
+export function clearProfile(): Promise<void> {
+  return kvDel(PROFILE_KEY);
+}
+
 export interface Prefs {
   theme: ThemePref;
   locale: Locale;

ui/src/lib/transport.ts

@@ -12,6 +12,7 @@ import { GatewayError, type GatewayClient } from './client';
 import * as codec from './codec';
 import { browserOffset } from './profileValidation';
 import { registerProbe, reportOffline, reportOnline } from './connection.svelte';
+import { offlineMode } from './offline.svelte';
 import { maintenanceRecovered, registerMaintenanceProbe, reportMaintenance } from './maintenance.svelte';
 import { maintenanceRetryMs } from './maintenance';
 import { backoffMs, isConnectionCode, retryable, toGatewayError } from './retry';
@@ -19,6 +20,13 @@ import { backoffMs, isConnectionCode, retryable, toGatewayError } from './retry'
 const MAX_RETRIES = 6;
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
+// The offline kill switch: in deliberate offline mode every network operation is refused before it
+// leaves the device, so offline truly means offline regardless of any UI affordance that slips
+// through. The local (device-only) game path never uses this transport, so it is unaffected.
+function assertOnline(): void {
+  if (offlineMode.active) throw new GatewayError('offline');
+}
+
 export function createTransport(baseUrl: string): GatewayClient {
   const origin = baseUrl || (typeof location !== 'undefined' ? location.origin : '');
   const transport = createConnectTransport({ baseUrl: origin, useBinaryFormat: true });
@@ -32,6 +40,7 @@ export function createTransport(baseUrl: string): GatewayClient {
   // (it must reject when there is no session, so the watcher keeps waiting rather than reporting up).
   const reachabilityProbe = async (): Promise<void> => {
     if (!token) throw new Error('no session');
+    assertOnline();
     await client.execute({ messageType: 'profile.get', payload: codec.empty(), requestId: '' }, { headers: headers() });
   };
   registerProbe(reachabilityProbe);
@@ -43,6 +52,7 @@ export function createTransport(baseUrl: string): GatewayClient {
   // dropped connection or a rate-limit recovers seamlessly) and driving the global Connecting
   // indicator. A successful round-trip marks the gateway reachable; a domain result_code is final.
   async function exec(messageType: string, payload: Uint8Array, signal?: AbortSignal): Promise<Uint8Array> {
+    assertOnline();
     for (let attempt = 0; ; attempt++) {
       let res;
       try {
@@ -82,6 +92,7 @@ export function createTransport(baseUrl: string): GatewayClient {
 
     async fetchDict(variant, version, opts) {
       if (!token) throw new Error('fetchDict: no session');
+      assertOnline();
       // Low priority so the browser schedules the (large) dictionary behind the game's own
       // requests — the move eval, state and live events — on a slow link (EDGE). Ignored
       // where the Priority Hints API is unsupported (iOS WebKit), which is harmless. The
@@ -99,6 +110,7 @@ export function createTransport(baseUrl: string): GatewayClient {
 
     async reportLocalEval(counts) {
       if (!token) throw new Error('reportLocalEval: no session');
+      assertOnline();
       // keepalive so a batch flushed as the app is backgrounded still reaches the edge.
       const res = await fetch(`${origin}/metrics/local-eval`, {
         method: 'POST',
@@ -319,6 +331,8 @@ export function createTransport(baseUrl: string): GatewayClient {
     },
 
     subscribe(onEvent, onError) {
+      // No live stream in offline mode (the kill switch); return an inert unsubscribe.
+      if (offlineMode.active) return () => {};
       const ctrl = new AbortController();
       void (async () => {
         try {

ui/src/screens/About.svelte

@@ -2,6 +2,7 @@
   import { t } from '../lib/i18n/index.svelte';
   import { app } from '../lib/app.svelte';
   import { navigate } from '../lib/router.svelte';
+  import { offlineMode } from '../lib/offline.svelte';
   import { aboutContent } from '../lib/aboutContent';
   import { onExternalLinkClick } from '../lib/links';
 
@@ -35,7 +36,7 @@
   <p class="muted">{t('about.version', { v: version })}</p>
 
   {#if !(app.profile?.isGuest ?? true)}
-    <button class="feedback" onclick={() => navigate('/feedback')}>
+    <button class="feedback" disabled={offlineMode.active} onclick={() => navigate('/feedback')}>
       {t('feedback.title')}{#if app.feedbackReplyUnread}<span class="fbadge">1</span>{/if}
     </button>
   {/if}

ui/src/screens/NewGame.svelte

@@ -74,7 +74,9 @@
           seed: randomSeed(),
           multipleWords: multipleWordsForRequest(v, multipleWords),
           seats: [
-            { kind: 'human', name: app.profile?.displayName ?? 'You' },
+            // The human seat carries the real account id so the game screen and the lobby identify
+            // "you" and the correct turn exactly as for an online game (the robot uses a synthetic id).
+            { kind: 'human', name: app.profile?.displayName ?? 'You', accountId: app.session?.userId },
             { kind: 'robot', name: 'Robot' },
           ],
         });
@@ -110,7 +112,9 @@
   );
 
   onMount(async () => {
-    if (guest) return;
+    // Offline mode offers only the local vs_ai flow (the friends section is hidden), and the network
+    // is off, so skip the friend fetch — it would be refused by the transport and toast an error.
+    if (guest || offlineMode.active) return;
     try {
       friends = await gateway.friendsList();
     } catch (e) {

ui/src/screens/SettingsHub.svelte

@@ -6,6 +6,7 @@
   import Friends from './Friends.svelte';
   import About from './About.svelte';
   import { app } from '../lib/app.svelte';
+  import { offlineMode } from '../lib/offline.svelte';
   import { t, type MessageKey } from '../lib/i18n/index.svelte';
 
   // The Settings hub: a single nav bar + bottom tab bar hosting the Settings / Profile /
@@ -23,6 +24,12 @@
   $effect(() => {
     if (guest && tab === 'friends') tab = 'settings';
   });
+  // Offline mode has no network, so the Profile and Friends surfaces (which read/save over the
+  // network) are disabled — fall back to Settings if the hub is on one (a deep-link or a live flip).
+  // Settings stays reachable: it holds the online/offline toggle.
+  $effect(() => {
+    if (offlineMode.active && (tab === 'profile' || tab === 'friends')) tab = 'settings';
+  });
 
   const titleKey: Record<SettingsTab, MessageKey> = {
     settings: 'settings.title',
@@ -48,11 +55,11 @@
       <button class="tab" class:active={tab === 'settings'} onclick={() => (tab = 'settings')}>
         <span class="face"><span class="sq" aria-hidden="true">⚙️</span><span class="lbl">{t('settings.title')}</span></span>
       </button>
-      <button class="tab" class:active={tab === 'profile'} onclick={() => (tab = 'profile')}>
+      <button class="tab" class:active={tab === 'profile'} disabled={offlineMode.active} onclick={() => (tab = 'profile')}>
         <span class="face"><span class="sq" aria-hidden="true">👤</span><span class="lbl">{t('profile.title')}</span></span>
       </button>
       {#if !guest}
-        <button class="tab" class:active={tab === 'friends'} onclick={() => (tab = 'friends')}>
+        <button class="tab" class:active={tab === 'friends'} disabled={offlineMode.active} onclick={() => (tab = 'friends')}>
           <span class="face"><span class="sq" aria-hidden="true">🤝{#if app.notifications > 0}<span class="badge">{app.notifications}</span>{/if}</span><span class="lbl">{t('friends.title')}</span></span>
         </button>
       {/if}