feat(offline): implicit net-state model, two-tier version gate, unified lobby

Land the offline-model redesign (ANDROID_PLAN.md O1-O7): replace the explicit offline toggle with a single detected net-state machine, unify the lobby, and add a two-tier client-version gate. Contour-safe: both version vars empty => dormant, the wire change is additive, so web/pwa/vk/tg behaviour is unchanged unless the gate is deliberately configured.

O1 net-state reducer (test-first). O2 store + wiring (connection/offline shims; +@capacitor/network). O3 remove the offline toggle + migrate the pref. O4 two-tier gate: hard update_required degrades to an offline Update/Play-offline notice (not terminal); soft GATEWAY_RECOMMENDED_CLIENT_VERSION -> X-Update-Recommended nudge. O5 unified lobby (device-local + greyed-from-cache server games; self-set identity; closes G-step-0). O6 create flows (with-friends online/offline segment + offline dict guard). O7 docs.

Telegram/VK stay online-only (contour review): the offline model is channel-gated via offlineCapable() (native + plain web; false in the mini-apps). offlineMode.active is hard-gated on it, so the whole model (blue chrome, unified/greyed lobby, transport kill switch, device-local vs_ai/hotseat create) stays inert in Telegram/VK regardless of the detected net state (closing a version-lock path that could have flipped them offline); and New Game's with-friends hides the online/offline segment there, leaving the remote invite alone. ARCHITECTURE already declared "Telegram/VK are exempt" - this makes the code match.

Deploy/CI: wire the version gate through the deploy (GATEWAY_MIN_CLIENT_VERSION + GATEWAY_RECOMMENDED_CLIENT_VERSION as plain unprefixed vars via compose + ci.yaml + prod-deploy.yaml + write-prod-env.sh + .env.example) so the gate is live when set (test-contour commit-hash version fails open; empty => dormant). Disable the manual android-build CI workflow for now (rename .disabled). Bump the app bundle budget 127->130 KB for the added always-loaded wiring. Fix the UI Docker stage (gateway/Dockerfile): install --ignore-scripts so the Alpine/musl SPA build no longer tries to native-build sharp (a local android:assets tool, unused in the image); esbuild's binary is an optional dep so Vite still builds.

Tests: gateway go green (two-tier gate over a real HTTP handler); docker build of the landing + gateway targets green locally; compose --no-interpolate confirms the gateway env; two new telegram.spec.ts e2e (offline signal keeps the chrome online + quick-match opponent choice visible => server enqueue; with-friends shows no pass-and-play), RED-verified; svelte-check 0/0, vitest 617, e2e 248 (chromium + webkit), build + bundle-size 127.8/130.

gateway/Dockerfile

@@ -42,10 +42,15 @@ ENV VITE_TELEGRAM_BOT_ID=$VITE_TELEGRAM_BOT_ID \
     VITE_APP_VERSION=$VITE_APP_VERSION \
     VITE_ADS_STUB=$VITE_ADS_STUB
 
-# Install with the lockfile first (the workspace file carries pnpm's build-script
-# approval for esbuild), then build. Committed src/gen/ means no codegen here.
+# Install with the lockfile first, then build. Committed src/gen/ means no codegen here.
+# --ignore-scripts: the Vite build needs no dependency build script — esbuild's platform binary
+# ships as an optional dependency (only its CLI-shim postinstall is skipped, which Vite does not use),
+# and core-js-bundle's prebuilt file is read directly. It notably skips sharp's native build (a
+# `pnpm android:assets` tool via @capacitor/assets, unused here), which would otherwise fail on this
+# Alpine/musl stage with no prebuilt binary and no compiler. The workspace allowBuilds stay for local
+# installs (where android:assets does need sharp built).
 COPY ui/package.json ui/pnpm-lock.yaml ui/pnpm-workspace.yaml ./
-RUN pnpm install --frozen-lockfile
+RUN pnpm install --frozen-lockfile --ignore-scripts
 COPY ui ./
 RUN pnpm build
 

gateway/cmd/gateway/main.go

@@ -221,23 +221,24 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	}
 	registry := transcode.NewRegistry(backend, validator, regOpts...)
 	edge := connectsrv.NewServer(connectsrv.Deps{
-		Registry:         registry,
-		Sessions:         sessions,
-		Backend:          backend,
-		Limiter:          limiter,
-		Tracker:          tracker,
-		Banlist:          banlist,
-		Blocklist:        blocklist,
-		Honeytoken:       cfg.Abuse.Honeytoken,
-		VKAppSecret:      cfg.VKAppSecret,
-		Hub:              hub,
-		RateLimit:        cfg.RateLimit,
-		Heartbeat:        cfg.PushHeartbeatInterval,
-		Logger:           logger,
-		AdminProxy:       adminProxy,
-		Meter:            tel.MeterProvider().Meter("scrabble/gateway/edge"),
-		MaxBodyBytes:     cfg.MaxBodyBytes,
-		MinClientVersion: cfg.MinClientVersion,
+		Registry:                 registry,
+		Sessions:                 sessions,
+		Backend:                  backend,
+		Limiter:                  limiter,
+		Tracker:                  tracker,
+		Banlist:                  banlist,
+		Blocklist:                blocklist,
+		Honeytoken:               cfg.Abuse.Honeytoken,
+		VKAppSecret:              cfg.VKAppSecret,
+		Hub:                      hub,
+		RateLimit:                cfg.RateLimit,
+		Heartbeat:                cfg.PushHeartbeatInterval,
+		Logger:                   logger,
+		AdminProxy:               adminProxy,
+		Meter:                    tel.MeterProvider().Meter("scrabble/gateway/edge"),
+		MaxBodyBytes:             cfg.MaxBodyBytes,
+		MinClientVersion:         cfg.MinClientVersion,
+		RecommendedClientVersion: cfg.RecommendedClientVersion,
 	})
 
 	// Bridge the backend push stream into the fan-out hub (and the out-of-app

gateway/internal/config/config.go

@@ -60,6 +60,11 @@ type Config struct {
 	// "update required" signal before its payload is decoded. Empty leaves the gate dormant
 	// (every client is served) — the default for web-only deployments.
 	MinClientVersion string
+	// RecommendedClientVersion, when non-empty, is the version below which a served client is nudged
+	// to update — a non-blocking "update available" signal (the X-Update-Recommended response header)
+	// on gated responses; the call still succeeds. It must be at least MinClientVersion. Empty leaves
+	// the soft tier off (the default); it does not affect the hard MinClientVersion gate.
+	RecommendedClientVersion string
 	// RateLimit configures the in-memory anti-abuse limiter.
 	RateLimit RateLimitConfig
 	// Abuse configures the temporary IP ban and the honeytoken (prod-only).
@@ -232,15 +237,16 @@ func (c VKIDConfig) Enabled() bool {
 func Load() (Config, error) {
 	var err error
 	c := Config{
-		HTTPAddr:         envOr("GATEWAY_HTTP_ADDR", defaultHTTPAddr),
-		LogLevel:         envOr("GATEWAY_LOG_LEVEL", defaultLogLevel),
-		BackendHTTPURL:   envOr("GATEWAY_BACKEND_HTTP_URL", defaultBackendHTTPURL),
-		BackendGRPCAddr:  envOr("GATEWAY_BACKEND_GRPC_ADDR", defaultBackendGRPCAddr),
-		AdminUser:        os.Getenv("GATEWAY_ADMIN_USER"),
-		AdminPassword:    os.Getenv("GATEWAY_ADMIN_PASSWORD"),
-		ValidatorAddr:    os.Getenv("GATEWAY_VALIDATOR_ADDR"),
-		VKAppSecret:      os.Getenv("GATEWAY_VK_APP_SECRET"),
-		MinClientVersion: os.Getenv("GATEWAY_MIN_CLIENT_VERSION"),
+		HTTPAddr:                 envOr("GATEWAY_HTTP_ADDR", defaultHTTPAddr),
+		LogLevel:                 envOr("GATEWAY_LOG_LEVEL", defaultLogLevel),
+		BackendHTTPURL:           envOr("GATEWAY_BACKEND_HTTP_URL", defaultBackendHTTPURL),
+		BackendGRPCAddr:          envOr("GATEWAY_BACKEND_GRPC_ADDR", defaultBackendGRPCAddr),
+		AdminUser:                os.Getenv("GATEWAY_ADMIN_USER"),
+		AdminPassword:            os.Getenv("GATEWAY_ADMIN_PASSWORD"),
+		ValidatorAddr:            os.Getenv("GATEWAY_VALIDATOR_ADDR"),
+		VKAppSecret:              os.Getenv("GATEWAY_VK_APP_SECRET"),
+		MinClientVersion:         os.Getenv("GATEWAY_MIN_CLIENT_VERSION"),
+		RecommendedClientVersion: os.Getenv("GATEWAY_RECOMMENDED_CLIENT_VERSION"),
 		VKID: VKIDConfig{
 			AppID:        os.Getenv("GATEWAY_VK_ID_APP_ID"),
 			ClientSecret: os.Getenv("GATEWAY_VK_ID_CLIENT_SECRET"),
@@ -344,6 +350,18 @@ func (c Config) validate() error {
 			return fmt.Errorf("config: GATEWAY_MIN_CLIENT_VERSION %q is not a MAJOR.MINOR.PATCH version", c.MinClientVersion)
 		}
 	}
+	if c.RecommendedClientVersion != "" {
+		rec, ok := clientver.Parse(c.RecommendedClientVersion)
+		if !ok {
+			return fmt.Errorf("config: GATEWAY_RECOMMENDED_CLIENT_VERSION %q is not a MAJOR.MINOR.PATCH version", c.RecommendedClientVersion)
+		}
+		// The soft tier must sit at or above the hard minimum: a recommended below the minimum is a
+		// misconfiguration (every client below min is already turned away). An empty/unparseable
+		// minimum imposes no lower bound, so the recommended may stand alone.
+		if min, ok := clientver.Parse(c.MinClientVersion); ok && clientver.Less(rec, min) {
+			return fmt.Errorf("config: GATEWAY_RECOMMENDED_CLIENT_VERSION %q must be >= GATEWAY_MIN_CLIENT_VERSION %q", c.RecommendedClientVersion, c.MinClientVersion)
+		}
+	}
 	if c.Abuse.BanEnabled && (c.Abuse.BanThreshold <= 0 || c.Abuse.BanWindow <= 0 || c.Abuse.BanDuration <= 0) {
 		return fmt.Errorf("config: GATEWAY_ABUSE_BAN_THRESHOLD/_WINDOW/_DURATION must be positive when GATEWAY_ABUSE_BAN_ENABLED")
 	}

gateway/internal/config/config_test.go

@@ -70,6 +70,42 @@ func TestLoadMinClientVersion(t *testing.T) {
 	}
 }
 
+// TestLoadRecommendedClientVersion verifies the soft-tier config: dormant (empty) by default, a
+// parseable version accepted (standing alone with no minimum, or at/above one), an unparseable one
+// rejected, and a recommended below the minimum rejected.
+func TestLoadRecommendedClientVersion(t *testing.T) {
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.RecommendedClientVersion != "" {
+		t.Errorf("RecommendedClientVersion = %q, want empty (soft tier dormant)", c.RecommendedClientVersion)
+	}
+	// Stands alone with no minimum configured.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "v1.20.0")
+	if c, err = Load(); err != nil {
+		t.Fatalf("Load with a valid recommended version (no min): %v", err)
+	}
+	if c.RecommendedClientVersion != "v1.20.0" {
+		t.Errorf("RecommendedClientVersion = %q, want %q", c.RecommendedClientVersion, "v1.20.0")
+	}
+	// At or above the minimum is accepted.
+	t.Setenv("GATEWAY_MIN_CLIENT_VERSION", "v1.16.0")
+	if _, err = Load(); err != nil {
+		t.Fatalf("Load with recommended >= min: %v", err)
+	}
+	// Below the minimum is rejected.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "v1.10.0")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for a recommended version below the minimum, got nil")
+	}
+	// Unparseable is rejected.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "dev")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for an unparseable GATEWAY_RECOMMENDED_CLIENT_VERSION, got nil")
+	}
+}
+
 // TestLoadAbuseDefaults verifies the anti-abuse ban defaults: disabled (prod-only),
 // the agreed thresholds, and no honeytoken.
 func TestLoadAbuseDefaults(t *testing.T) {

gateway/internal/connectsrv/server.go

@@ -51,10 +51,15 @@ const honeypotHeader = "X-Scrabble-Honeypot"
 // the edge can turn away a build too old to speak the current wire contract, before it decodes
 // the payload. resultUpdateRequired is the stable envelope result_code — with the Subscribe
 // counterpart connect.CodeFailedPrecondition — that any build, however old, recognises as
-// "you must update". Both are part of the frozen wire contract (docs/ARCHITECTURE.md §2).
+// "you must update". updateRecommendedHeader is the additive, non-blocking soft-tier signal: set
+// on a served Execute response when the client is at or above the hard minimum but below the
+// recommended version, it nudges an update without failing the call. Headers are the
+// version-tolerant layer, so an old client simply ignores it. All part of the frozen wire
+// contract (docs/ARCHITECTURE.md §2).
 const (
-	clientVersionHeader  = "X-Client-Version"
-	resultUpdateRequired = "update_required"
+	clientVersionHeader     = "X-Client-Version"
+	resultUpdateRequired    = "update_required"
+	updateRecommendedHeader = "X-Update-Recommended"
 )
 
 // Limiter classes, the `class` attribute of gateway_rate_limited_total and the
@@ -104,6 +109,12 @@ type Server struct {
 	minClient clientver.Version
 	gateOn    bool
 
+	// recClient is the version below which a served client is nudged to update (the soft tier);
+	// recOn is false when the soft tier is dormant (GATEWAY_RECOMMENDED_CLIENT_VERSION empty or
+	// unparseable). It is independent of the hard gate.
+	recClient clientver.Version
+	recOn     bool
+
 	publicPolicy ratelimit.Policy
 	userPolicy   ratelimit.Policy
 	emailPolicy  ratelimit.Policy
@@ -148,6 +159,9 @@ type Deps struct {
 	// older X-Client-Version is turned away with "update required". Empty or unparseable leaves
 	// the gate dormant.
 	MinClientVersion string
+	// RecommendedClientVersion is the version below which a served client is nudged to update (the
+	// non-blocking X-Update-Recommended header). Empty or unparseable leaves the soft tier dormant.
+	RecommendedClientVersion string
 }
 
 // NewServer constructs the edge service.
@@ -192,6 +206,18 @@ func NewServer(d Deps) *Server {
 			log.Warn("ignoring unparseable MinClientVersion; client-version gate disabled", zap.String("value", d.MinClientVersion))
 		}
 	}
+	// Parse the recommended (soft-tier) version once, the same way. Config.validate already rejects an
+	// unparseable value or one below the minimum, so the warn branch only guards a direct (test)
+	// construction; an empty value leaves the soft tier dormant.
+	var recClient clientver.Version
+	recOn := false
+	if d.RecommendedClientVersion != "" {
+		if v, ok := clientver.Parse(d.RecommendedClientVersion); ok {
+			recClient, recOn = v, true
+		} else {
+			log.Warn("ignoring unparseable RecommendedClientVersion; update-recommended tier disabled", zap.String("value", d.RecommendedClientVersion))
+		}
+	}
 	return &Server{
 		registry:     d.Registry,
 		sessions:     d.Sessions,
@@ -210,6 +236,8 @@ func NewServer(d Deps) *Server {
 		maxBodyBytes: maxBody,
 		minClient:    minClient,
 		gateOn:       gateOn,
+		recClient:    recClient,
+		recOn:        recOn,
 		publicPolicy: ratelimit.PerMinute(rl.PublicPerMinute, rl.PublicBurst),
 		userPolicy:   ratelimit.PerMinute(rl.UserPerMinute, rl.UserBurst),
 		emailPolicy:  ratelimit.Per(rl.EmailPer10Min, 10*time.Minute, rl.EmailBurst),
@@ -335,15 +363,44 @@ func (s *Server) clientTooOld(header string) bool {
 	return clientver.Less(v, s.minClient)
 }
 
+// clientUpdateRecommended reports whether the X-Client-Version header names a version in the soft
+// band — at or above the hard minimum but below the recommended version — so a served response can
+// carry the non-blocking X-Update-Recommended nudge. It fails open exactly like clientTooOld: a
+// dormant soft tier, or an absent or unparseable header, returns false. A client below the minimum is
+// turned away by the hard gate and is never nudged, so it is excluded here too (a dormant hard gate
+// leaves minClient at the zero version, which no real version is below, so the band is simply
+// "below recommended").
+func (s *Server) clientUpdateRecommended(header string) bool {
+	if !s.recOn {
+		return false
+	}
+	v, ok := clientver.Parse(header)
+	if !ok {
+		return false
+	}
+	return !clientver.Less(v, s.minClient) && clientver.Less(v, s.recClient)
+}
+
 // Execute runs one unary operation. Domain failures are returned in the envelope
 // (result_code != "ok", HTTP 200); only edge failures (rate limit, missing
 // session, unknown type, internal) become Connect errors.
-func (s *Server) Execute(ctx context.Context, req *connect.Request[edgev1.ExecuteRequest]) (*connect.Response[edgev1.ExecuteResponse], error) {
+func (s *Server) Execute(ctx context.Context, req *connect.Request[edgev1.ExecuteRequest]) (resp *connect.Response[edgev1.ExecuteResponse], err error) {
 	start := time.Now()
 	msgType := req.Msg.GetMessageType()
 	result := "internal"
 	defer func() { s.metrics.recordEdge(ctx, msgType, result, start) }()
 
+	// The soft-tier nudge rides a response header on any served response (the call still succeeds), so a
+	// client at or above the hard minimum but below the recommended version is told an update is
+	// available without being interrupted. A too-old client (turned away below) or a missing/garbled
+	// version yields no nudge.
+	recommend := s.clientUpdateRecommended(req.Header().Get(clientVersionHeader))
+	defer func() {
+		if recommend && resp != nil {
+			resp.Header().Set(updateRecommendedHeader, "1")
+		}
+	}()
+
 	// The version gate rides the outermost stable layer (an HTTP header) and is checked before
 	// the payload is decoded, so a too-old client makes zero successful calls but sees the
 	// recognizable update_required envelope rather than a decode crash (docs/ARCHITECTURE.md §2).

gateway/internal/connectsrv/server_test.go

@@ -53,6 +53,33 @@ func newEdgeMin(t *testing.T, minVersion string, backendHandler http.HandlerFunc
 	}
 }
 
+// newEdgeVersions is newEdgeMin with the soft-tier recommended version also armed (empty leaves it off).
+func newEdgeVersions(t *testing.T, minVersion, recommendedVersion string, backendHandler http.HandlerFunc) (edgev1connect.GatewayClient, func()) {
+	t.Helper()
+	backendSrv := httptest.NewServer(backendHandler)
+	backend, err := backendclient.New(backendSrv.URL, "localhost:9090", 2*time.Second)
+	if err != nil {
+		t.Fatalf("backendclient: %v", err)
+	}
+	edge := connectsrv.NewServer(connectsrv.Deps{
+		Registry:                 transcode.NewRegistry(backend, nil),
+		Sessions:                 session.NewCache(backend, time.Minute, 100),
+		Limiter:                  ratelimit.New(),
+		Hub:                      push.NewHub(0),
+		RateLimit:                config.DefaultRateLimit(),
+		Heartbeat:                15 * time.Second,
+		MinClientVersion:         minVersion,
+		RecommendedClientVersion: recommendedVersion,
+	})
+	edgeSrv := httptest.NewServer(edge.HTTPHandler())
+	client := edgev1connect.NewGatewayClient(http.DefaultClient, edgeSrv.URL)
+	return client, func() {
+		edgeSrv.Close()
+		_ = backend.Close()
+		backendSrv.Close()
+	}
+}
+
 func TestExecuteGuestAuthOK(t *testing.T) {
 	client, cleanup := newEdge(t, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
@@ -156,6 +183,54 @@ func TestExecuteVersionGate(t *testing.T) {
 	}
 }
 
+// TestExecuteUpdateRecommended verifies the soft-tier nudge on the unary path: a served client at or
+// above the hard minimum but below the recommended version gets the X-Update-Recommended response
+// header (the call still succeeds); a too-old (hard-gated), up-to-date, absent, or unparseable version
+// and a dormant soft tier get no header.
+func TestExecuteUpdateRecommended(t *testing.T) {
+	backend := func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
+	}
+	tests := []struct {
+		name       string
+		min        string
+		rec        string
+		header     string
+		wantResult string
+		wantHeader bool
+	}{
+		{"soft band is nudged", "v1.16.0", "v1.20.0", "v1.17.0", "ok", true},
+		{"at the minimum is nudged", "v1.16.0", "v1.20.0", "v1.16.0", "ok", true},
+		{"at the recommended is not nudged", "v1.16.0", "v1.20.0", "v1.20.0", "ok", false},
+		{"newer than recommended is not nudged", "v1.16.0", "v1.20.0", "v2.0.0", "ok", false},
+		{"too old is gated, not nudged", "v1.16.0", "v1.20.0", "v1.0.0", "update_required", false},
+		{"absent header, no nudge", "v1.16.0", "v1.20.0", "", "ok", false},
+		{"unparseable header, no nudge", "v1.16.0", "v1.20.0", "dev", "ok", false},
+		{"recommended alone (no min) nudges below it", "", "v1.20.0", "v1.0.0", "ok", true},
+		{"soft tier dormant, no nudge", "v1.16.0", "", "v1.0.0", "update_required", false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client, cleanup := newEdgeVersions(t, tc.min, tc.rec, backend)
+			defer cleanup()
+			req := connect.NewRequest(&edgev1.ExecuteRequest{MessageType: transcode.MsgAuthGuest, RequestId: "rq"})
+			if tc.header != "" {
+				req.Header().Set("X-Client-Version", tc.header)
+			}
+			resp, err := client.Execute(context.Background(), req)
+			if err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			if got := resp.Msg.GetResultCode(); got != tc.wantResult {
+				t.Fatalf("result_code = %q, want %q", got, tc.wantResult)
+			}
+			if got := resp.Header().Get("X-Update-Recommended") == "1"; got != tc.wantHeader {
+				t.Fatalf("X-Update-Recommended present = %v, want %v", got, tc.wantHeader)
+			}
+		})
+	}
+}
+
 // TestSubscribeVersionGate verifies the streaming path: a too-old client is refused with
 // FailedPrecondition, while an equal or absent version is admitted and proceeds to auth (which
 // fails Unauthenticated with no session, proving it passed the version gate).