ui/phase-24: push events, turn-ready toast, single SubscribeEvents consumer

Wires the gateway's signed SubscribeEvents stream end-to-end:

- backend: emit game.turn.ready from lobby.OnRuntimeSnapshot on every
  current_turn advance, addressed to every active membership, push-only
  channel, idempotency key turn-ready:<game_id>:<turn>;
- ui: single EventStream singleton replaces revocation-watcher.ts and
  carries both per-event dispatch and revocation detection; toast
  primitive (store + host) lives in lib/; GameStateStore gains
  pendingTurn/markPendingTurn/advanceToPending and a persisted
  lastViewedTurn so a return after multiple turns surfaces the same
  "view now" affordance as a live push event;
- mandatory event-signature verification through ui/core
  (verifyPayloadHash + verifyEvent), full-jitter exponential backoff
  1s -> 30s on transient failure, signOut("revoked") on
  Unauthenticated or clean end-of-stream;
- catalog and migration accept the new kind; tests cover producer
  (testcontainers + capturing publisher), consumer (Vitest event
  stream, toast, game-state extensions), and a Playwright e2e
  delivering a signed frame to the live UI.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ui/frontend/src/api/events.svelte.ts

@@ -0,0 +1,376 @@
+// `EventStream` is the single SubscribeEvents consumer for the
+// authenticated UI session. It opens one server-streaming RPC against
+// the gateway, verifies every incoming event (payload-hash +
+// Ed25519 signature) through `ui/core`, dispatches verified events to
+// type-keyed handlers, and reconnects with full-jitter exponential
+// backoff on transient failure.
+//
+// Phase 24 introduces this module in place of `revocation-watcher.ts`.
+// The watcher's revocation semantics are absorbed: a clean
+// end-of-stream while the session is authenticated, or an
+// `Unauthenticated` ConnectError, both call `session.signOut("revoked")`.
+// Per-event-type dispatch (turn-ready toasts in this phase; battle and
+// mail toasts in later phases) is registered through `on(eventType,
+// handler)`.
+//
+// The store exposes `connectionStatus` as a Svelte rune so the
+// connection-state indicator in the shell header (see PLAN.md
+// cross-cutting shell) can subscribe without ceremony. The indicator
+// itself is not part of Phase 24, but the rune is wired here so the
+// next phase that adds the dot can read it directly.
+
+import { create } from "@bufbuild/protobuf";
+import { ConnectError } from "@connectrpc/connect";
+import type { Core } from "../platform/core/index";
+import type { DeviceKeypair } from "../platform/store/index";
+import {
+	GatewayEventSchema,
+	SubscribeEventsRequestSchema,
+	type GatewayEvent,
+} from "../proto/galaxy/gateway/v1/edge_gateway_pb";
+import { GATEWAY_BASE_URL } from "../lib/env";
+import { session } from "../lib/session-store.svelte";
+import { createEdgeGatewayClient, type EdgeGatewayClient } from "./connect";
+
+const PROTOCOL_VERSION = "v1";
+const SUBSCRIBE_MESSAGE_TYPE = "gateway.subscribe";
+
+// Connect error code numerical values used by the watcher. The full
+// enum lives in `@connectrpc/connect` but importing the runtime enum
+// would pull a large surface into this small module.
+const CONNECT_CODE_CANCELED = 1;
+const CONNECT_CODE_UNAUTHENTICATED = 16;
+
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+
+/**
+ * VerifiedEvent is the verified projection of a `GatewayEvent` handed
+ * to user handlers. The signature and payload-hash fields are dropped
+ * because verification has already succeeded; consumers only need the
+ * envelope plus the opaque payload bytes.
+ */
+export interface VerifiedEvent {
+	eventType: string;
+	eventId: string;
+	timestampMs: bigint;
+	requestId: string;
+	traceId: string;
+	payloadBytes: Uint8Array;
+}
+
+export type EventHandler = (event: VerifiedEvent) => void;
+
+export type ConnectionStatus =
+	| "idle"
+	| "connecting"
+	| "connected"
+	| "reconnecting"
+	| "offline";
+
+/**
+ * EventStreamStartOptions carries the live primitives the stream
+ * consumer cannot resolve by itself. Production code reads `core`,
+ * `keypair`, and `deviceSessionId` from the session store and the
+ * gateway public key from `lib/env`; tests inject a fake
+ * `EdgeGatewayClient` and deterministic `sleep`/`random` to drive
+ * backoff in fake-timer mode.
+ */
+export interface EventStreamStartOptions {
+	core: Core;
+	keypair: DeviceKeypair;
+	deviceSessionId: string;
+	gatewayResponsePublicKey: Uint8Array;
+	/** Custom transport client. Defaults to `createEdgeGatewayClient(GATEWAY_BASE_URL)`. */
+	client?: EdgeGatewayClient;
+	/** Sleep hook for tests; defaults to a real-time `setTimeout`. */
+	sleep?: (ms: number) => Promise<void>;
+	/** Random source for full-jitter backoff; defaults to `Math.random`. */
+	random?: () => number;
+	/** Function reporting `navigator.onLine`; defaults to the browser global. */
+	onlineProbe?: () => boolean;
+}
+
+/**
+ * SignatureError marks a verification failure (payload-hash mismatch
+ * or invalid Ed25519 signature). The stream loop classifies it as a
+ * forgery and reconnects through the same backoff path used for
+ * transient transport errors.
+ */
+export class SignatureError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SignatureError";
+	}
+}
+
+export class EventStream {
+	connectionStatus: ConnectionStatus = $state("idle");
+
+	private handlers = new Map<string, Set<EventHandler>>();
+	private controller: AbortController | null = null;
+	private running = false;
+
+	/**
+	 * on registers a handler for a specific event type. Returns a
+	 * disposer that removes the handler. Multiple handlers per type
+	 * are supported so future phases (battle, mail) can subscribe
+	 * alongside turn-ready without coordination.
+	 */
+	on(eventType: string, handler: EventHandler): () => void {
+		let bucket = this.handlers.get(eventType);
+		if (bucket === undefined) {
+			bucket = new Set();
+			this.handlers.set(eventType, bucket);
+		}
+		bucket.add(handler);
+		return () => {
+			const current = this.handlers.get(eventType);
+			if (current === undefined) {
+				return;
+			}
+			current.delete(handler);
+			if (current.size === 0) {
+				this.handlers.delete(eventType);
+			}
+		};
+	}
+
+	/**
+	 * start opens the stream. Calling start while the stream is
+	 * already running is a no-op so the root layout's `$effect`-based
+	 * lifecycle stays idempotent across re-renders.
+	 */
+	start(opts: EventStreamStartOptions): void {
+		if (this.running) {
+			return;
+		}
+		this.running = true;
+		this.controller = new AbortController();
+		void this.run(opts, this.controller.signal);
+	}
+
+	/**
+	 * stop tears down the stream. Used by the root layout on logout
+	 * or unmount. Re-calling start after stop opens a fresh stream.
+	 */
+	stop(): void {
+		this.running = false;
+		if (this.controller !== null) {
+			this.controller.abort();
+			this.controller = null;
+		}
+		this.connectionStatus = "idle";
+	}
+
+	/**
+	 * resetForTests is used by the Vitest harness to forget all
+	 * handlers and force the rune back to `idle` between cases.
+	 */
+	resetForTests(): void {
+		this.stop();
+		this.handlers.clear();
+	}
+
+	private async run(
+		opts: EventStreamStartOptions,
+		signal: AbortSignal,
+	): Promise<void> {
+		const sleep = opts.sleep ?? defaultSleep;
+		const random = opts.random ?? Math.random;
+		const onlineProbe = opts.onlineProbe ?? defaultOnlineProbe;
+		const client = opts.client ?? createEdgeGatewayClient(GATEWAY_BASE_URL);
+
+		let attempt = 0;
+		while (!signal.aborted && this.running) {
+			this.connectionStatus = "connecting";
+			let stream: AsyncIterable<GatewayEvent>;
+			try {
+				stream = await openStream(client, opts, signal);
+			} catch (err) {
+				if (signal.aborted) {
+					return;
+				}
+				if (handleAuthenticationError(err)) {
+					return;
+				}
+				this.connectionStatus = onlineProbe() ? "reconnecting" : "offline";
+				await sleep(backoffDelay(attempt, random));
+				attempt += 1;
+				continue;
+			}
+
+			let firstEventSeen = false;
+			let terminated = false;
+			try {
+				for await (const event of stream) {
+					if (signal.aborted) {
+						return;
+					}
+					this.verifyEvent(event, opts);
+					if (!firstEventSeen) {
+						firstEventSeen = true;
+						this.connectionStatus = "connected";
+						attempt = 0;
+					}
+					this.dispatch(event);
+				}
+				terminated = true;
+			} catch (err) {
+				if (signal.aborted) {
+					return;
+				}
+				if (handleAuthenticationError(err)) {
+					return;
+				}
+				this.connectionStatus = onlineProbe() ? "reconnecting" : "offline";
+				await sleep(backoffDelay(attempt, random));
+				attempt += 1;
+				continue;
+			}
+
+			if (terminated) {
+				// Clean end-of-stream on an authenticated session is the
+				// gateway's documented session-invalidation signal.
+				if (session.status === "authenticated") {
+					await session.signOut("revoked");
+					return;
+				}
+				this.connectionStatus = "idle";
+				return;
+			}
+		}
+	}
+
+	private verifyEvent(event: GatewayEvent, opts: EventStreamStartOptions): void {
+		if (!opts.core.verifyPayloadHash(event.payloadBytes, event.payloadHash)) {
+			throw new SignatureError("event payload_hash mismatch");
+		}
+		const ok = opts.core.verifyEvent(
+			opts.gatewayResponsePublicKey,
+			event.signature,
+			{
+				eventType: event.eventType,
+				eventId: event.eventId,
+				timestampMs: event.timestampMs,
+				requestId: event.requestId,
+				traceId: event.traceId,
+				payloadHash: event.payloadHash,
+			},
+		);
+		if (!ok) {
+			throw new SignatureError("event signature verification failed");
+		}
+	}
+
+	private dispatch(event: GatewayEvent): void {
+		const bucket = this.handlers.get(event.eventType);
+		if (bucket === undefined || bucket.size === 0) {
+			return;
+		}
+		const projection: VerifiedEvent = {
+			eventType: event.eventType,
+			eventId: event.eventId,
+			timestampMs: event.timestampMs,
+			requestId: event.requestId,
+			traceId: event.traceId,
+			payloadBytes: event.payloadBytes,
+		};
+		for (const handler of [...bucket]) {
+			try {
+				handler(projection);
+			} catch (err) {
+				console.info("events: handler threw", event.eventType, err);
+			}
+		}
+	}
+}
+
+async function openStream(
+	client: EdgeGatewayClient,
+	opts: EventStreamStartOptions,
+	signal: AbortSignal,
+): Promise<AsyncIterable<GatewayEvent>> {
+	const requestId = newRequestId();
+	const timestampMs = BigInt(Date.now());
+	const emptyPayload = new Uint8Array();
+	const payloadHash = await sha256(emptyPayload);
+	const canonical = opts.core.signRequest({
+		protocolVersion: PROTOCOL_VERSION,
+		deviceSessionId: opts.deviceSessionId,
+		messageType: SUBSCRIBE_MESSAGE_TYPE,
+		timestampMs,
+		requestId,
+		payloadHash,
+	});
+	const signature = await opts.keypair.sign(canonical);
+	const request = create(SubscribeEventsRequestSchema, {
+		protocolVersion: PROTOCOL_VERSION,
+		deviceSessionId: opts.deviceSessionId,
+		messageType: SUBSCRIBE_MESSAGE_TYPE,
+		timestampMs,
+		requestId,
+		payloadHash,
+		signature,
+		payloadBytes: emptyPayload,
+	});
+	return client.subscribeEvents(request, { signal });
+}
+
+function handleAuthenticationError(err: unknown): boolean {
+	if (!(err instanceof ConnectError)) {
+		return false;
+	}
+	if (err.code === CONNECT_CODE_CANCELED) {
+		return true;
+	}
+	if (err.code === CONNECT_CODE_UNAUTHENTICATED) {
+		void session.signOut("revoked");
+		return true;
+	}
+	return false;
+}
+
+function backoffDelay(attempt: number, random: () => number): number {
+	const cap = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** attempt);
+	return Math.floor(random() * cap);
+}
+
+function defaultSleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function defaultOnlineProbe(): boolean {
+	if (typeof navigator === "undefined") {
+		return true;
+	}
+	return navigator.onLine !== false;
+}
+
+async function sha256(payload: Uint8Array): Promise<Uint8Array> {
+	const digest = await crypto.subtle.digest(
+		"SHA-256",
+		payload as BufferSource,
+	);
+	return new Uint8Array(digest);
+}
+
+function newRequestId(): string {
+	if (typeof crypto.randomUUID === "function") {
+		return crypto.randomUUID();
+	}
+	const buf = new Uint8Array(16);
+	crypto.getRandomValues(buf);
+	let hex = "";
+	for (let i = 0; i < buf.length; i++) {
+		hex += buf[i]!.toString(16).padStart(2, "0");
+	}
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * eventStream is the singleton stream consumer the root layout starts
+ * once the session becomes authenticated and stops on logout. Tests
+ * call `resetForTests()` between cases.
+ */
+export const eventStream = new EventStream();

ui/frontend/src/lib/game-state.svelte.ts

@@ -24,6 +24,8 @@ import type { WrapMode } from "../map/world";
 
 const PREF_NAMESPACE = "game-prefs";
 const PREF_KEY_WRAP_MODE = (gameId: string) => `${gameId}/wrap-mode`;
+const PREF_KEY_LAST_VIEWED_TURN = (gameId: string) =>
+	`${gameId}/last-viewed-turn`;
 
 /**
  * GAME_STATE_CONTEXT_KEY is the Svelte context key the in-game shell
@@ -66,6 +68,17 @@ export class GameStateStore {
 	 * this flag is enough to keep the network silent.
 	 */
 	synthetic = $state(false);
+	/**
+	 * pendingTurn carries the latest server-side turn the user has not
+	 * yet opened: it is `> currentTurn` whenever the server reports a
+	 * new turn (either through a `game.turn.ready` push event after
+	 * boot, or through the boot-time discovery that the persisted
+	 * `lastViewedTurn` is behind the lobby's `current_turn`). The
+	 * layout's `$effect` renders a toast/banner when it is non-null;
+	 * `advanceToPending()` refreshes the store onto the new turn and
+	 * clears the rune.
+	 */
+	pendingTurn: number | null = $state(null);
 
 	private client: GalaxyClient | null = null;
 	private cache: Cache | null = null;
@@ -98,12 +111,21 @@ export class GameStateStore {
 		if (this.client === null || this.cache === null) {
 			throw new Error("game-state: setGame called before init");
 		}
+		// Only forget the pending indicator when the consumer is
+		// actually switching games. On the initial `setGame` after
+		// `init` the previous `gameId` is the empty string, and a
+		// concurrent `markPendingTurn` from a push event arriving
+		// while we were still bootstrapping must not be erased.
+		if (this.gameId !== "" && this.gameId !== gameId) {
+			this.pendingTurn = null;
+		}
 		this.gameId = gameId;
 		this.status = "loading";
 		this.error = null;
 		this.report = null;
 
 		this.wrapMode = await readWrapMode(this.cache, gameId);
+		const lastViewed = await readLastViewedTurn(this.cache, gameId);
 
 		try {
 			const summary = await this.findGame(gameId);
@@ -114,7 +136,68 @@ export class GameStateStore {
 			}
 			this.gameName = summary.gameName;
 			this.currentTurn = summary.currentTurn;
+			// If the persisted last-viewed turn is older than the
+			// server-side current turn, open the user on their last-seen
+			// snapshot and surface the gap through `pendingTurn` so the
+			// shell can render a "new turn available" affordance instead
+			// of silently auto-advancing.
+			if (
+				lastViewed !== null &&
+				lastViewed >= 0 &&
+				lastViewed < summary.currentTurn
+			) {
+				this.pendingTurn = summary.currentTurn;
+				await this.loadTurn(lastViewed);
+			} else {
+				await this.loadTurn(summary.currentTurn);
+			}
+		} catch (err) {
+			if (this.destroyed) return;
+			this.status = "error";
+			this.error = describe(err);
+		}
+	}
+
+	/**
+	 * markPendingTurn records a server-reported new turn (typically
+	 * delivered through `game.turn.ready`). Values that are not
+	 * strictly ahead of the latest known turn (current or already
+	 * pending) are ignored so a replayed event cannot regress the
+	 * indicator.
+	 */
+	markPendingTurn(turn: number): void {
+		const latest = this.pendingTurn ?? this.currentTurn;
+		if (turn > latest) {
+			this.pendingTurn = turn;
+		}
+	}
+
+	/**
+	 * advanceToPending re-queries the lobby record and loads the
+	 * report at the server's latest `current_turn`, then clears the
+	 * pending indicator. Unlike `setGame`, this skips the
+	 * `lastViewedTurn` lookup — the user has explicitly asked to
+	 * jump to the new turn, so any persisted bookmark from the
+	 * previous session is irrelevant. Failures keep the indicator
+	 * set so the user can retry from the same affordance.
+	 */
+	async advanceToPending(): Promise<void> {
+		if (this.pendingTurn === null || this.client === null) {
+			return;
+		}
+		this.status = "loading";
+		this.error = null;
+		try {
+			const summary = await this.findGame(this.gameId);
+			if (summary === null) {
+				this.status = "error";
+				this.error = `game ${this.gameId} is not in your list`;
+				return;
+			}
+			this.gameName = summary.gameName;
+			this.currentTurn = summary.currentTurn;
 			await this.loadTurn(summary.currentTurn);
+			this.pendingTurn = null;
 		} catch (err) {
 			if (this.destroyed) return;
 			this.status = "error";
@@ -219,6 +302,13 @@ export class GameStateStore {
 		this.report = report;
 		this.currentTurn = turn;
 		this.status = "ready";
+		if (this.cache !== null) {
+			await this.cache.put(
+				PREF_NAMESPACE,
+				PREF_KEY_LAST_VIEWED_TURN(this.gameId),
+				turn,
+			);
+		}
 	}
 
 	private installVisibilityListener(): void {
@@ -239,6 +329,20 @@ async function readWrapMode(cache: Cache, gameId: string): Promise<WrapMode> {
 	return "torus";
 }
 
+async function readLastViewedTurn(
+	cache: Cache,
+	gameId: string,
+): Promise<number | null> {
+	const stored = await cache.get<number>(
+		PREF_NAMESPACE,
+		PREF_KEY_LAST_VIEWED_TURN(gameId),
+	);
+	if (typeof stored !== "number" || !Number.isFinite(stored)) {
+		return null;
+	}
+	return stored;
+}
+
 function describe(err: unknown): string {
 	if (err instanceof GameStateError) {
 		return err.message;

ui/frontend/src/lib/i18n/locales/en.ts

@@ -7,10 +7,15 @@
 const en = {
 	"common.language": "language",
 	"common.loading": "loading…",
+	"common.dismiss": "dismiss",
 	"common.browser_not_supported_title": "browser not supported",
 	"common.browser_not_supported_body":
 		"Galaxy requires Ed25519 in WebCrypto. See supported browsers.",
 
+	"game.events.turn_ready.message": "turn {turn} is ready",
+	"game.events.turn_ready.action": "view now",
+	"game.events.signature_failed": "verification failed, reconnecting…",
+
 	"login.title": "sign in to Galaxy",
 	"login.email_label": "email",
 	"login.email_required": "email must not be empty",

ui/frontend/src/lib/i18n/locales/ru.ts

@@ -8,10 +8,15 @@ import type en from "./en";
 const ru: Record<keyof typeof en, string> = {
 	"common.language": "язык",
 	"common.loading": "загрузка…",
+	"common.dismiss": "закрыть",
 	"common.browser_not_supported_title": "браузер не поддерживается",
 	"common.browser_not_supported_body":
 		"Galaxy требует поддержки Ed25519 в WebCrypto. См. список поддерживаемых браузеров.",
 
+	"game.events.turn_ready.message": "ход {turn} готов",
+	"game.events.turn_ready.action": "открыть",
+	"game.events.signature_failed": "подпись повреждена, переподключение…",
+
 	"login.title": "вход в Galaxy",
 	"login.email_label": "электронная почта",
 	"login.email_required": "адрес не должен быть пустым",

ui/frontend/src/lib/revocation-watcher.ts

@@ -1,157 +0,0 @@
-// `startRevocationWatcher` opens an authenticated SubscribeEvents
-// stream against the gateway and treats any non-aborted termination
-// as a session-revocation signal: the watcher calls
-// `session.signOut("revoked")` so the root layout's anonymous redirect
-// returns the user to `/login` immediately.
-//
-// Phase 7 deliberately ignores event payloads — the per-event
-// dispatch (turn-ready toasts, mail invalidation, ...) lands in
-// Phase 24. The wire envelope shape and signing rules are identical
-// to `executeCommand`: the gateway's `canonicalSubscribeEventsValidation`
-// enforces the same v1 envelope shape, and the canonical signing
-// input is produced by `Core.signRequest`. The integration suite
-// exercises the same flow in
-// `integration/testenv/connect_client.go::SubscribeEvents` with the
-// `gateway.subscribe` literal.
-
-import { create } from "@bufbuild/protobuf";
-import { ConnectError } from "@connectrpc/connect";
-import { createEdgeGatewayClient } from "../api/connect";
-import { loadCore } from "../platform/core/index";
-import { SubscribeEventsRequestSchema } from "../proto/galaxy/gateway/v1/edge_gateway_pb";
-import { GATEWAY_BASE_URL } from "./env";
-import { session } from "./session-store.svelte";
-
-const PROTOCOL_VERSION = "v1";
-const SUBSCRIBE_MESSAGE_TYPE = "gateway.subscribe";
-
-/**
- * startRevocationWatcher opens a SubscribeEvents stream and returns a
- * stop function. Calling the stop function aborts the in-flight
- * stream silently; only stream terminations the watcher did not
- * initiate trigger `session.signOut("revoked")`.
- */
-export function startRevocationWatcher(): () => void {
-	const controller = new AbortController();
-	void runWatcher(controller.signal);
-	return () => controller.abort();
-}
-
-async function runWatcher(signal: AbortSignal): Promise<void> {
-	if (
-		session.status !== "authenticated" ||
-		session.keypair === null ||
-		session.deviceSessionId === null
-	) {
-		return;
-	}
-	const keypair = session.keypair;
-	const deviceSessionId = session.deviceSessionId;
-
-	let stream: AsyncIterable<unknown>;
-	try {
-		const core = await loadCore();
-		const requestId =
-			typeof crypto.randomUUID === "function"
-				? crypto.randomUUID()
-				: fallbackRequestId();
-		const timestampMs = BigInt(Date.now());
-		const emptyPayload = new Uint8Array();
-		const payloadHash = await sha256(emptyPayload);
-		const canonical = core.signRequest({
-			protocolVersion: PROTOCOL_VERSION,
-			deviceSessionId,
-			messageType: SUBSCRIBE_MESSAGE_TYPE,
-			timestampMs,
-			requestId,
-			payloadHash,
-		});
-		const signature = await keypair.sign(canonical);
-
-		const client = createEdgeGatewayClient(GATEWAY_BASE_URL);
-		const request = create(SubscribeEventsRequestSchema, {
-			protocolVersion: PROTOCOL_VERSION,
-			deviceSessionId,
-			messageType: SUBSCRIBE_MESSAGE_TYPE,
-			timestampMs,
-			requestId,
-			payloadHash,
-			signature,
-			payloadBytes: emptyPayload,
-		});
-		stream = client.subscribeEvents(request, { signal });
-	} catch (err) {
-		// A failure before the stream is opened (load core, signing,
-		// transport) is a transient setup error — log and bail out.
-		// Revocation is signalled later by the gateway closing an
-		// already-open stream.
-		if (!signal.aborted) {
-			console.info("session store: failed to open subscribe-events", err);
-		}
-		return;
-	}
-
-	try {
-		for await (const _event of stream) {
-			void _event;
-		}
-	} catch (err) {
-		// Stream errors arrive on three different paths:
-		//   1. our own AbortController fired (page navigated, layout
-		//      stopped the watcher) — `signal.aborted` is true;
-		//   2. the gateway revoked the session and Connect-Web maps
-		//      that to `Unauthenticated` / `PermissionDenied`;
-		//   3. transient network failure (Wi-Fi drop, server
-		//      restart) — anything else.
-		//
-		// Only branch 2 is a true revocation. Branch 1 is silent;
-		// branch 3 is logged but does not log the user out, so a
-		// flaky network does not bounce them back to /login.
-		if (signal.aborted) {
-			return;
-		}
-		const code = connectErrorCode(err);
-		if (code === ConnectErrorCode.Unauthenticated) {
-			await session.signOut("revoked");
-			return;
-		}
-		console.info("session store: subscribe-events stream errored", err);
-		return;
-	}
-	// Clean end-of-stream from the gateway is the documented
-	// `session_invalidation` signal: backend closes the push stream
-	// once the device session flips to revoked.
-	if (!signal.aborted && session.status === "authenticated") {
-		await session.signOut("revoked");
-	}
-}
-
-const ConnectErrorCode = {
-	Canceled: 1,
-	Unauthenticated: 16,
-} as const;
-
-function connectErrorCode(err: unknown): number | null {
-	if (err instanceof ConnectError) {
-		return err.code;
-	}
-	return null;
-}
-
-async function sha256(payload: Uint8Array): Promise<Uint8Array> {
-	const digest = await crypto.subtle.digest(
-		"SHA-256",
-		payload as BufferSource,
-	);
-	return new Uint8Array(digest);
-}
-
-function fallbackRequestId(): string {
-	const buf = new Uint8Array(16);
-	crypto.getRandomValues(buf);
-	let hex = "";
-	for (let i = 0; i < buf.length; i++) {
-		hex += buf[i]!.toString(16).padStart(2, "0");
-	}
-	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-}

ui/frontend/src/lib/toast-host.svelte

@@ -0,0 +1,109 @@
+<!--
+Single mounting point for the global toast slot, rendered once from
+the root layout. The host reads `toast.current` reactively and stays
+fully empty (zero DOM nodes inside the wrapper) when no toast is
+active so the surrounding shell layout is not perturbed.
+-->
+<script lang="ts">
+	import { i18n } from "$lib/i18n/index.svelte";
+	import { toast } from "$lib/toast.svelte";
+
+	function handleAction(): void {
+		const current = toast.current;
+		if (current === null) {
+			return;
+		}
+		const action = current.onAction;
+		toast.dismiss(current.id);
+		action?.();
+	}
+
+	function handleClose(): void {
+		if (toast.current === null) {
+			return;
+		}
+		toast.dismiss(toast.current.id);
+	}
+</script>
+
+{#if toast.current !== null}
+	<div class="toast-host" role="status" aria-live="polite">
+		<div class="toast" data-testid="toast">
+			<span class="toast-message" data-testid="toast-message">
+				{i18n.t(toast.current.messageKey, toast.current.messageParams)}
+			</span>
+			{#if toast.current.actionLabelKey !== undefined}
+				<button
+					type="button"
+					class="toast-action"
+					data-testid="toast-action"
+					onclick={handleAction}
+				>
+					{i18n.t(toast.current.actionLabelKey)}
+				</button>
+			{/if}
+			<button
+				type="button"
+				class="toast-close"
+				data-testid="toast-close"
+				aria-label={i18n.t("common.dismiss")}
+				onclick={handleClose}
+			>
+				×
+			</button>
+		</div>
+	</div>
+{/if}
+
+<style>
+	.toast-host {
+		position: fixed;
+		top: 1rem;
+		left: 50%;
+		transform: translateX(-50%);
+		z-index: 1000;
+		max-width: min(28rem, calc(100vw - 2rem));
+	}
+	.toast {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		padding: 0.6rem 0.85rem;
+		background: #1a2034;
+		color: #e8eaf6;
+		border: 1px solid #2c3354;
+		border-radius: 0.5rem;
+		box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
+		font-size: 0.9rem;
+	}
+	.toast-message {
+		flex: 1;
+		min-width: 0;
+	}
+	.toast-action {
+		background: transparent;
+		color: #8ab4f8;
+		border: none;
+		font-weight: 600;
+		cursor: pointer;
+		font-size: 0.8rem;
+		padding: 0.2rem 0.5rem;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+	}
+	.toast-action:hover {
+		text-decoration: underline;
+	}
+	.toast-close {
+		background: transparent;
+		color: #94a3b8;
+		border: none;
+		font-size: 1.1rem;
+		line-height: 1;
+		cursor: pointer;
+		padding: 0 0.25rem;
+	}
+	.toast-close:hover {
+		color: #e8eaf6;
+	}
+</style>

ui/frontend/src/lib/toast.svelte.ts

@@ -0,0 +1,97 @@
+// `ToastStore` is the single transient-notification primitive for the
+// SvelteKit shell. Phase 24 ships it together with the push-event
+// dispatch: the per-game layout shows one `Turn N is ready. View now.`
+// toast on a verified `game.turn.ready` event. Later phases reuse the
+// same store for mail / battle / lobby toasts (PLAN.md §"cross-cutting
+// shell").
+//
+// The store keeps **one** active toast at a time: a fresh `show()`
+// replaces the previous descriptor. This matches the UX intent of
+// "one loud notification at a time" — the rare cases where several
+// events arrive in quick succession are still observable, because
+// each replacement re-arms the timer and the user sees every payload
+// in turn.
+
+import type { TranslationKey } from "./i18n/index.svelte";
+
+/**
+ * ToastDescriptor describes one toast in flight. `messageKey` and
+ * `actionLabelKey` are typed against the i18n catalog so a missing
+ * translation key fails at compile time. `durationMs === null` (or
+ * `undefined`) makes the toast sticky — the user must dismiss it
+ * through the action button or another `show()` call.
+ */
+export interface ToastDescriptor {
+	id: string;
+	messageKey: TranslationKey;
+	messageParams?: Record<string, string>;
+	actionLabelKey?: TranslationKey;
+	onAction?: () => void;
+	durationMs?: number | null;
+}
+
+class ToastStore {
+	current: ToastDescriptor | null = $state(null);
+
+	private timer: ReturnType<typeof setTimeout> | null = null;
+	private counter = 0;
+
+	/**
+	 * show replaces the active toast with descriptor and returns its
+	 * fresh id. Pass that id to `dismiss(id)` from a delayed callback
+	 * to avoid dismissing a newer toast that already took its slot.
+	 */
+	show(descriptor: Omit<ToastDescriptor, "id">): string {
+		this.clearTimer();
+		this.counter += 1;
+		const id = String(this.counter);
+		const full: ToastDescriptor = { ...descriptor, id };
+		this.current = full;
+		if (
+			full.durationMs !== null &&
+			full.durationMs !== undefined &&
+			full.durationMs > 0
+		) {
+			const duration = full.durationMs;
+			this.timer = setTimeout(() => {
+				this.dismiss(id);
+			}, duration);
+		}
+		return id;
+	}
+
+	/**
+	 * dismiss clears the active toast. With an id, the call is a
+	 * no-op when the active toast has a different id — this guards
+	 * the auto-dismiss timer from clobbering a newer descriptor.
+	 */
+	dismiss(id?: string): void {
+		if (
+			id !== undefined &&
+			(this.current === null || this.current.id !== id)
+		) {
+			return;
+		}
+		this.clearTimer();
+		this.current = null;
+	}
+
+	/**
+	 * resetForTests forgets every in-flight descriptor and the id
+	 * counter. Production code never calls this.
+	 */
+	resetForTests(): void {
+		this.clearTimer();
+		this.current = null;
+		this.counter = 0;
+	}
+
+	private clearTimer(): void {
+		if (this.timer !== null) {
+			clearTimeout(this.timer);
+			this.timer = null;
+		}
+	}
+}
+
+export const toast = new ToastStore();

ui/frontend/src/routes/+layout.svelte

@@ -4,28 +4,66 @@
 	import { page } from "$app/state";
 	import { i18n } from "$lib/i18n/index.svelte";
 	import { session } from "$lib/session-store.svelte";
-	import { startRevocationWatcher } from "$lib/revocation-watcher";
+	import { eventStream } from "../api/events.svelte";
+	import { loadCore } from "../platform/core/index";
+	import { GATEWAY_RESPONSE_PUBLIC_KEY } from "$lib/env";
+	import ToastHost from "$lib/toast-host.svelte";
 
 	let { children } = $props();
 
-	let stopWatcher: (() => void) | null = null;
+	// `streamSessionId` records the device session id the event stream
+	// is currently bound to. The `$effect` below uses it to detect a
+	// re-login (different session id while still authenticated) and
+	// restart the stream against the fresh credentials.
+	let streamSessionId: string | null = null;
 
 	onMount(() => {
 		void session.init();
 		return () => {
-			if (stopWatcher !== null) {
-				stopWatcher();
-				stopWatcher = null;
-			}
+			eventStream.stop();
+			streamSessionId = null;
 		};
 	});
 
 	$effect(() => {
-		if (session.status === "authenticated" && stopWatcher === null) {
-			stopWatcher = startRevocationWatcher();
-		} else if (session.status !== "authenticated" && stopWatcher !== null) {
-			stopWatcher();
-			stopWatcher = null;
+		if (
+			session.status === "authenticated" &&
+			session.keypair !== null &&
+			session.deviceSessionId !== null &&
+			GATEWAY_RESPONSE_PUBLIC_KEY.length > 0
+		) {
+			const keypair = session.keypair;
+			const deviceSessionId = session.deviceSessionId;
+			if (streamSessionId !== deviceSessionId) {
+				if (streamSessionId !== null) {
+					eventStream.stop();
+				}
+				streamSessionId = deviceSessionId;
+				void (async (): Promise<void> => {
+					try {
+						const core = await loadCore();
+						// Bail out if the session flipped away from this id
+						// while we were loading core (logout, re-login).
+						if (
+							session.deviceSessionId !== deviceSessionId ||
+							session.status !== "authenticated"
+						) {
+							return;
+						}
+						eventStream.start({
+							core,
+							keypair,
+							deviceSessionId,
+							gatewayResponsePublicKey: GATEWAY_RESPONSE_PUBLIC_KEY,
+						});
+					} catch (err) {
+						console.info("layout: failed to start event stream", err);
+					}
+				})();
+			}
+		} else if (streamSessionId !== null) {
+			eventStream.stop();
+			streamSessionId = null;
 		}
 
 		const pathname = page.url.pathname;
@@ -57,6 +95,8 @@
 	{@render children()}
 {/if}
 
+<ToastHost />
+
 <style>
 	.status {
 		padding: 2rem;

ui/frontend/src/routes/games/[id]/+layout.svelte

@@ -90,6 +90,11 @@ fresh.
 		getSyntheticReport,
 		isSyntheticGameId,
 	} from "../../../api/synthetic-report";
+	import {
+		eventStream,
+		type VerifiedEvent,
+	} from "../../../api/events.svelte";
+	import { toast } from "$lib/toast.svelte";
 
 	let { children } = $props();
 
@@ -224,6 +229,60 @@ fresh.
 		return new Uint8Array(digest);
 	}
 
+	// `unsubTurnReady` carries the `eventStream.on(...)` disposer for
+	// the game-scoped turn-ready handler. The layout registers the
+	// handler once the local `GameStateStore` is initialised so an
+	// event arriving before `currentTurn` is known cannot misfire.
+	let unsubTurnReady: (() => void) | null = null;
+	const turnReadyDecoder = new TextDecoder("utf-8");
+
+	function parseTurnReadyPayload(
+		event: VerifiedEvent,
+	): { gameId: string; turn: number } | null {
+		try {
+			const text = turnReadyDecoder.decode(event.payloadBytes);
+			const json: unknown = JSON.parse(text);
+			if (typeof json !== "object" || json === null) {
+				return null;
+			}
+			const record = json as Record<string, unknown>;
+			const eventGameId = record.game_id;
+			const eventTurn = record.turn;
+			if (
+				typeof eventGameId !== "string" ||
+				typeof eventTurn !== "number" ||
+				!Number.isFinite(eventTurn)
+			) {
+				return null;
+			}
+			return { gameId: eventGameId, turn: eventTurn };
+		} catch {
+			return null;
+		}
+	}
+
+	let activeTurnReadyToastId: string | null = null;
+
+	$effect(() => {
+		const pending = gameState.pendingTurn;
+		if (pending === null) {
+			if (activeTurnReadyToastId !== null) {
+				toast.dismiss(activeTurnReadyToastId);
+				activeTurnReadyToastId = null;
+			}
+			return;
+		}
+		activeTurnReadyToastId = toast.show({
+			messageKey: "game.events.turn_ready.message",
+			messageParams: { turn: String(pending) },
+			actionLabelKey: "game.events.turn_ready.action",
+			onAction: () => {
+				void gameState.advanceToPending();
+			},
+			durationMs: null,
+		});
+	});
+
 	onMount(() => {
 		(async (): Promise<void> => {
 			// DEV-only synthetic-report path. The lobby's "Load
@@ -276,6 +335,19 @@ fresh.
 					deviceSessionId,
 					gatewayResponsePublicKey: GATEWAY_RESPONSE_PUBLIC_KEY,
 				});
+				// Register the `game.turn.ready` dispatch before the
+				// network roundtrips below so an event delivered
+				// while `gameState.init` is still in flight is not
+				// dropped by the singleton stream. `markPendingTurn`
+				// already protects against turns that do not advance
+				// past the current snapshot.
+				unsubTurnReady = eventStream.on("game.turn.ready", (event) => {
+					const parsed = parseTurnReadyPayload(event);
+					if (parsed === null || parsed.gameId !== gameId) {
+						return;
+					}
+					gameState.markPendingTurn(parsed.turn);
+				});
 				await Promise.all([
 					gameState.init({ client, cache, gameId }),
 					orderDraft.init({ cache, gameId }),
@@ -299,6 +371,10 @@ fresh.
 	});
 
 	onDestroy(() => {
+		if (unsubTurnReady !== null) {
+			unsubTurnReady();
+			unsubTurnReady = null;
+		}
 		gameState.dispose();
 		orderDraft.dispose();
 		selection.dispose();

ui/frontend/tests/e2e/fixtures/canon.ts

@@ -6,6 +6,7 @@
 // truth; this TS copy stays small enough to read against that test.
 
 const RESPONSE_DOMAIN_MARKER_V1 = "galaxy-response-v1";
+const EVENT_DOMAIN_MARKER_V1 = "galaxy-event-v1";
 
 export interface ResponseSigningFields {
 	protocolVersion: string;
@@ -15,6 +16,15 @@ export interface ResponseSigningFields {
 	payloadHash: Uint8Array;
 }
 
+export interface EventSigningFields {
+	eventType: string;
+	eventId: string;
+	timestampMs: bigint;
+	requestId: string;
+	traceId: string;
+	payloadHash: Uint8Array;
+}
+
 export function buildResponseSigningInput(
 	fields: ResponseSigningFields,
 ): Uint8Array {
@@ -28,6 +38,24 @@ export function buildResponseSigningInput(
 	return new Uint8Array(parts);
 }
 
+// `buildEventSigningInput` mirrors `ui/core/canon/event.go`
+// `BuildEventSigningInput`. The Go-side parity test
+// (`gateway/authn/parity_with_ui_core_test.go`) is the source of truth;
+// this TS copy stays close enough to that test to read against it.
+export function buildEventSigningInput(
+	fields: EventSigningFields,
+): Uint8Array {
+	const parts: number[] = [];
+	appendLengthPrefixedString(parts, EVENT_DOMAIN_MARKER_V1);
+	appendLengthPrefixedString(parts, fields.eventType);
+	appendLengthPrefixedString(parts, fields.eventId);
+	appendBigEndianUint64(parts, fields.timestampMs);
+	appendLengthPrefixedString(parts, fields.requestId);
+	appendLengthPrefixedString(parts, fields.traceId);
+	appendLengthPrefixedBytes(parts, fields.payloadHash);
+	return new Uint8Array(parts);
+}
+
 function appendLengthPrefixedString(dst: number[], value: string): void {
 	const bytes = new TextEncoder().encode(value);
 	appendLengthPrefixedBytes(dst, bytes);

ui/frontend/tests/e2e/fixtures/sign-event.ts

@@ -0,0 +1,94 @@
+// `forgeGatewayEventFrame` produces one Connect HTTP/1.1
+// server-streaming frame carrying a `GatewayEvent` signed with the
+// fixture private key. The Playwright `turn-ready.spec.ts` route
+// handler returns this body when the UI opens `SubscribeEvents` so
+// the production verification path (`core.verifyEvent`) accepts the
+// frame under the matching public key the dev server picks up via
+// `VITE_GATEWAY_RESPONSE_PUBLIC_KEY`.
+//
+// Connect HTTP/1.1 server-streaming framing per request:
+//   1 byte  flag    (0x00 = message)
+//   4 bytes length  (big-endian, payload size)
+//   N bytes payload (JSON-encoded GatewayEvent for the JSON codec)
+//
+// The route handler closes the response after one frame; the UI's
+// `events.svelte.ts` reconnect loop treats the abrupt end-of-body as
+// a transient error and backs off, which keeps the toast visible
+// long enough for the test to assert on it.
+
+import { create, toJsonString } from "@bufbuild/protobuf";
+import { webcrypto } from "node:crypto";
+import { GatewayEventSchema } from "../../../src/proto/galaxy/gateway/v1/edge_gateway_pb";
+import { buildEventSigningInput } from "./canon";
+import {
+	FIXTURE_PRIVATE_KEY_PKCS8_BASE64,
+	decodeBase64,
+} from "./gateway-key";
+
+export interface ForgedEventInput {
+	eventType: string;
+	eventId: string;
+	timestampMs: bigint;
+	requestId: string;
+	traceId: string;
+	payloadBytes: Uint8Array;
+}
+
+let cachedPrivateKey: CryptoKey | null = null;
+
+async function privateKey(): Promise<CryptoKey> {
+	if (cachedPrivateKey !== null) {
+		return cachedPrivateKey;
+	}
+	const pkcs8 = decodeBase64(FIXTURE_PRIVATE_KEY_PKCS8_BASE64);
+	cachedPrivateKey = await webcrypto.subtle.importKey(
+		"pkcs8",
+		pkcs8,
+		{ name: "Ed25519" },
+		false,
+		["sign"],
+	);
+	return cachedPrivateKey;
+}
+
+async function sha256(payload: Uint8Array): Promise<Uint8Array> {
+	const digest = await webcrypto.subtle.digest("SHA-256", payload);
+	return new Uint8Array(digest);
+}
+
+export async function forgeGatewayEventFrame(
+	input: ForgedEventInput,
+): Promise<Uint8Array> {
+	const payloadHash = await sha256(input.payloadBytes);
+	const canonical = buildEventSigningInput({
+		eventType: input.eventType,
+		eventId: input.eventId,
+		timestampMs: input.timestampMs,
+		requestId: input.requestId,
+		traceId: input.traceId,
+		payloadHash,
+	});
+	const signatureBuf = await webcrypto.subtle.sign(
+		{ name: "Ed25519" },
+		await privateKey(),
+		canonical,
+	);
+	const event = create(GatewayEventSchema, {
+		eventType: input.eventType,
+		eventId: input.eventId,
+		timestampMs: input.timestampMs,
+		payloadBytes: input.payloadBytes,
+		payloadHash,
+		signature: new Uint8Array(signatureBuf),
+		requestId: input.requestId,
+		traceId: input.traceId,
+	});
+	const body = new TextEncoder().encode(
+		toJsonString(GatewayEventSchema, event),
+	);
+	const frame = new Uint8Array(5 + body.length);
+	frame[0] = 0x00; // message frame
+	new DataView(frame.buffer).setUint32(1, body.length, false);
+	frame.set(body, 5);
+	return frame;
+}

ui/frontend/tests/e2e/turn-ready.spec.ts

@@ -0,0 +1,194 @@
+// Phase 24 end-to-end coverage for the push-event path. Boots an
+// authenticated session, mocks the gateway calls the in-game shell
+// makes (`lobby.my.games.list`, `user.games.report`), and serves one
+// signed `game.turn.ready` frame on the `SubscribeEvents` stream.
+// The test asserts the toast surfaces with the new turn, the action
+// button advances the store onto the new turn, and the header
+// reflects the freshly-loaded snapshot.
+
+import { fromJson, type JsonValue } from "@bufbuild/protobuf";
+import { expect, test, type Page } from "@playwright/test";
+import { ByteBuffer } from "flatbuffers";
+
+import { ExecuteCommandRequestSchema } from "../../src/proto/galaxy/gateway/v1/edge_gateway_pb";
+import { UUID } from "../../src/proto/galaxy/fbs/common";
+import { GameReportRequest } from "../../src/proto/galaxy/fbs/report";
+import { forgeExecuteCommandResponseJson } from "./fixtures/sign-response";
+import {
+	buildMyGamesListPayload,
+	type GameFixture,
+} from "./fixtures/lobby-fbs";
+import { buildReportPayload } from "./fixtures/report-fbs";
+import { forgeGatewayEventFrame } from "./fixtures/sign-event";
+
+const SESSION_ID = "phase-24-turn-ready-session";
+const GAME_ID = "11111111-2222-3333-4444-555555555555";
+
+interface MockState {
+	currentTurn: number;
+	reportRequests: Array<{ turn: number }>;
+	subscribeHits: number;
+}
+
+async function mockGateway(page: Page): Promise<MockState> {
+	const state: MockState = {
+		currentTurn: 4,
+		reportRequests: [],
+		subscribeHits: 0,
+	};
+
+	const baseGame = (): GameFixture => ({
+		gameId: GAME_ID,
+		gameName: "Phase 24 Game",
+		gameType: "private",
+		status: "running",
+		ownerUserId: "user-1",
+		minPlayers: 2,
+		maxPlayers: 8,
+		enrollmentEndsAtMs: BigInt(Date.now() + 86_400_000),
+		createdAtMs: BigInt(Date.now() - 86_400_000),
+		updatedAtMs: BigInt(Date.now()),
+		currentTurn: state.currentTurn,
+	});
+
+	await page.route(
+		"**/galaxy.gateway.v1.EdgeGateway/ExecuteCommand",
+		async (route) => {
+			const reqText = route.request().postData();
+			if (reqText === null) {
+				await route.fulfill({ status: 400 });
+				return;
+			}
+			const req = fromJson(
+				ExecuteCommandRequestSchema,
+				JSON.parse(reqText) as JsonValue,
+			);
+
+			let resultCode = "ok";
+			let payload: Uint8Array;
+			switch (req.messageType) {
+				case "lobby.my.games.list":
+					payload = buildMyGamesListPayload([baseGame()]);
+					break;
+				case "user.games.report": {
+					const decoded = GameReportRequest.getRootAsGameReportRequest(
+						new ByteBuffer(req.payloadBytes),
+					);
+					const turn = decoded.turn();
+					state.reportRequests.push({ turn });
+					payload = buildReportPayload({
+						turn,
+						mapWidth: 4000,
+						mapHeight: 4000,
+						localPlanets: [
+							{ number: 1, name: "Home", x: 1000, y: 1000 },
+						],
+					});
+					break;
+				}
+				default:
+					resultCode = "internal_error";
+					payload = new Uint8Array();
+			}
+
+			const body = await forgeExecuteCommandResponseJson({
+				requestId: req.requestId,
+				timestampMs: BigInt(Date.now()),
+				resultCode,
+				payloadBytes: payload,
+			});
+			await route.fulfill({
+				status: 200,
+				contentType: "application/json",
+				body,
+			});
+		},
+	);
+
+	// The first SubscribeEvents request from the root layout receives
+	// one signed `game.turn.ready` frame for turn 5; subsequent
+	// reconnect attempts (events.ts retries after the abrupt
+	// end-of-body) are held open indefinitely so the toast stays
+	// visible long enough for the test to interact with it.
+	await page.route(
+		"**/galaxy.gateway.v1.EdgeGateway/SubscribeEvents",
+		async (route) => {
+			state.subscribeHits += 1;
+			if (state.subscribeHits === 1) {
+				const payload = new TextEncoder().encode(
+					JSON.stringify({ game_id: GAME_ID, turn: 5 }),
+				);
+				const frame = await forgeGatewayEventFrame({
+					eventType: "game.turn.ready",
+					eventId: "evt-turn-ready-1",
+					timestampMs: BigInt(Date.now()),
+					requestId: "req-turn-ready-1",
+					traceId: "trace-turn-ready-1",
+					payloadBytes: payload,
+				});
+				await route.fulfill({
+					status: 200,
+					contentType: "application/connect+json",
+					body: Buffer.from(frame),
+				});
+				return;
+			}
+			await new Promise<void>(() => {});
+		},
+	);
+
+	return state;
+}
+
+async function bootSession(page: Page): Promise<void> {
+	await page.goto("/__debug/store");
+	await expect(page.getByTestId("debug-store-ready")).toBeVisible();
+	await page.waitForFunction(() => window.__galaxyDebug?.ready === true);
+	await page.evaluate(() => window.__galaxyDebug!.clearSession());
+	await page.evaluate(
+		(id) => window.__galaxyDebug!.setDeviceSessionId(id),
+		SESSION_ID,
+	);
+}
+
+test("signed game.turn.ready frame surfaces the toast", async ({ page }) => {
+	await mockGateway(page);
+
+	await bootSession(page);
+	await page.goto(`/games/${GAME_ID}/map`);
+
+	// Initial chrome reflects the bootstrap currentTurn=4.
+	await expect(page.getByTestId("active-view-map")).toHaveAttribute(
+		"data-status",
+		"ready",
+	);
+	await expect(page.getByTestId("game-shell-headline")).toContainText(
+		"turn 4",
+	);
+
+	// The signed push frame is delivered to the singleton event
+	// stream → the per-game layout handler marks pendingTurn=5 → the
+	// toast becomes visible carrying the new turn number and the
+	// `view now` action label.
+	await expect(page.getByTestId("toast")).toBeVisible({ timeout: 5_000 });
+	await expect(page.getByTestId("toast-message")).toContainText("5");
+	await expect(page.getByTestId("toast-action")).toBeVisible();
+});
+
+test("manual dismiss clears the turn-ready toast without advancing the view", async ({
+	page,
+}) => {
+	await mockGateway(page);
+
+	await bootSession(page);
+	await page.goto(`/games/${GAME_ID}/map`);
+
+	await expect(page.getByTestId("toast")).toBeVisible({ timeout: 5_000 });
+	await page.getByTestId("toast-close").click();
+	await expect(page.getByTestId("toast")).toBeHidden();
+	// `pendingTurn` is still set — the user simply chose not to
+	// advance — so the header continues to show the older turn.
+	await expect(page.getByTestId("game-shell-headline")).toContainText(
+		"turn 4",
+	);
+});

ui/frontend/tests/events.test.ts

@@ -0,0 +1,324 @@
+// Vitest coverage for the SubscribeEvents stream consumer in
+// `src/api/events.svelte.ts`. The tests drive the singleton through
+// its lifecycle with a `createRouterTransport` fake — the same
+// pattern `galaxy-client.test.ts` uses for unary calls, extended to
+// async-generator handlers for server-streaming RPCs.
+//
+// The session store is mocked so `signOut("revoked")` is observable
+// without instantiating the real keystore/IndexedDB chain.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+	Code,
+	ConnectError,
+	createClient,
+	createRouterTransport,
+} from "@connectrpc/connect";
+import {
+	EdgeGateway,
+	GatewayEventSchema,
+	type GatewayEvent,
+} from "../src/proto/galaxy/gateway/v1/edge_gateway_pb";
+
+let sessionStatus: "anonymous" | "authenticated" = "anonymous";
+const signOutSpy = vi.fn();
+vi.mock("../src/lib/session-store.svelte", () => ({
+	session: {
+		get status(): string {
+			return sessionStatus;
+		},
+		signOut: (...args: unknown[]) => signOutSpy(...args),
+	},
+}));
+
+// The import must come after vi.mock so the module reads the mocked
+// session reference.
+const {
+	eventStream,
+} = await import("../src/api/events.svelte");
+
+import type { Core } from "../src/platform/core/index";
+import type { DeviceKeypair } from "../src/platform/store/index";
+
+beforeEach(() => {
+	eventStream.resetForTests();
+	signOutSpy.mockReset();
+	sessionStatus = "anonymous";
+});
+
+afterEach(() => {
+	eventStream.resetForTests();
+});
+
+function mockCore(overrides?: Partial<Core>): Core {
+	return {
+		signRequest: () => new Uint8Array([1, 2, 3]),
+		verifyResponse: () => true,
+		verifyEvent: () => true,
+		verifyPayloadHash: () => true,
+		driveEffective: () => 0,
+		emptyMass: () => 0,
+		weaponsBlockMass: () => 0,
+		fullMass: () => 0,
+		speed: () => 0,
+		cargoCapacity: () => 0,
+		carryingMass: () => 0,
+		blockUpgradeCost: () => 0,
+		...overrides,
+	} as Core;
+}
+
+function mockKeypair(): DeviceKeypair {
+	return {
+		publicKey: new Uint8Array(32),
+		sign: async () => new Uint8Array(64),
+	};
+}
+
+function buildEvent(eventType: string, payload: Uint8Array): GatewayEvent {
+	return create(GatewayEventSchema, {
+		eventType,
+		eventId: `event-${eventType}-${Math.random().toString(16).slice(2, 8)}`,
+		timestampMs: 1n,
+		payloadBytes: payload,
+		payloadHash: new Uint8Array(32).fill(0xaa),
+		signature: new Uint8Array(64).fill(0xbb),
+		requestId: "req-1",
+		traceId: "trace-1",
+	});
+}
+
+function makeRouter(
+	streamFactory: () => AsyncIterable<GatewayEvent>,
+): ReturnType<typeof createClient<typeof EdgeGateway>> {
+	const transport = createRouterTransport(({ service }) => {
+		service(EdgeGateway, {
+			executeCommand() {
+				throw new Error("not used in this test");
+			},
+			async *subscribeEvents() {
+				for await (const e of streamFactory()) {
+					yield e;
+				}
+			},
+		});
+	});
+	return createClient(EdgeGateway, transport);
+}
+
+describe("EventStream", () => {
+	test("verified events reach the registered handler", async () => {
+		const handler = vi.fn();
+		eventStream.on("game.turn.ready", handler);
+
+		const event = buildEvent(
+			"game.turn.ready",
+			new TextEncoder().encode(JSON.stringify({ game_id: "g", turn: 2 })),
+		);
+		const client = makeRouter(async function* () {
+			yield event;
+		});
+
+		const sleep = vi.fn(async () => {});
+
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep,
+			random: () => 0,
+		});
+
+		await vi.waitFor(() => {
+			expect(handler).toHaveBeenCalled();
+		});
+		expect(handler).toHaveBeenCalledTimes(1);
+		expect(handler.mock.calls[0]?.[0].eventType).toBe("game.turn.ready");
+		eventStream.stop();
+	});
+
+	test("handlers for other event types are not invoked", async () => {
+		const turnHandler = vi.fn();
+		const mailHandler = vi.fn();
+		eventStream.on("game.turn.ready", turnHandler);
+		eventStream.on("mail.received", mailHandler);
+
+		const event = buildEvent(
+			"game.turn.ready",
+			new TextEncoder().encode("{}"),
+		);
+		const client = makeRouter(async function* () {
+			yield event;
+		});
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: async () => {},
+			random: () => 0,
+		});
+
+		await vi.waitFor(() => {
+			expect(turnHandler).toHaveBeenCalled();
+		});
+		expect(mailHandler).not.toHaveBeenCalled();
+		eventStream.stop();
+	});
+
+	test("unsubscribe removes the handler", async () => {
+		const handler = vi.fn();
+		const off = eventStream.on("game.turn.ready", handler);
+		off();
+
+		const event = buildEvent(
+			"game.turn.ready",
+			new TextEncoder().encode("{}"),
+		);
+		const client = makeRouter(async function* () {
+			yield event;
+		});
+		const sleepSpy = vi.fn(async () => {});
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: sleepSpy,
+			random: () => 0,
+		});
+
+		await vi.waitFor(() => {
+			// Stream finished — either status became idle, or the loop
+			// is at backoff after a clean close on an anonymous
+			// session (which goes straight to idle as well).
+			expect(eventStream.connectionStatus).toBe("idle");
+		});
+		expect(handler).not.toHaveBeenCalled();
+		eventStream.stop();
+	});
+
+	test("bad signature tears down the stream and reconnects", async () => {
+		const handler = vi.fn();
+		eventStream.on("game.turn.ready", handler);
+
+		let verifyCalls = 0;
+		const core = mockCore({
+			verifyEvent: () => {
+				verifyCalls += 1;
+				return verifyCalls > 1; // first event fails, then passes
+			},
+		});
+
+		let streamCalls = 0;
+		const client = makeRouter(async function* () {
+			streamCalls += 1;
+			yield buildEvent(
+				"game.turn.ready",
+				new TextEncoder().encode("{}"),
+			);
+		});
+
+		const sleepCalls: number[] = [];
+		eventStream.start({
+			core,
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: async (ms) => {
+				sleepCalls.push(ms);
+			},
+			random: () => 0, // full-jitter = 0 → instant retry
+		});
+
+		await vi.waitFor(() => {
+			expect(handler).toHaveBeenCalled();
+		});
+		// Two stream openings: first one rejected on bad signature,
+		// second one delivered the good event.
+		expect(streamCalls).toBeGreaterThanOrEqual(2);
+		// Backoff was scheduled between attempts.
+		expect(sleepCalls.length).toBeGreaterThanOrEqual(1);
+		eventStream.stop();
+	});
+
+	test("unauthenticated error signs the session out", async () => {
+		sessionStatus = "authenticated";
+		const client = makeRouter(async function* () {
+			yield* [];
+			throw new ConnectError("revoked", Code.Unauthenticated);
+		});
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: async () => {},
+			random: () => 0,
+		});
+
+		await vi.waitFor(() => {
+			expect(signOutSpy).toHaveBeenCalled();
+		});
+		expect(signOutSpy).toHaveBeenCalledWith("revoked");
+		eventStream.stop();
+	});
+
+	test("clean end-of-stream on an authenticated session is the revocation signal", async () => {
+		sessionStatus = "authenticated";
+		const client = makeRouter(async function* () {
+			yield* [];
+		});
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: async () => {},
+			random: () => 0,
+		});
+		await vi.waitFor(() => {
+			expect(signOutSpy).toHaveBeenCalledWith("revoked");
+		});
+		eventStream.stop();
+	});
+
+	test("connectionStatus transitions through connecting → connected → idle", async () => {
+		expect(eventStream.connectionStatus).toBe("idle");
+		const event = buildEvent(
+			"game.turn.ready",
+			new TextEncoder().encode("{}"),
+		);
+		const observed: string[] = [];
+		const client = makeRouter(async function* () {
+			yield event;
+		});
+		const handler = vi.fn(() => {
+			observed.push(eventStream.connectionStatus);
+		});
+		eventStream.on("game.turn.ready", handler);
+		eventStream.start({
+			core: mockCore(),
+			keypair: mockKeypair(),
+			deviceSessionId: "device-1",
+			gatewayResponsePublicKey: new Uint8Array(32),
+			client,
+			sleep: async () => {},
+			random: () => 0,
+		});
+		await vi.waitFor(() => {
+			expect(handler).toHaveBeenCalled();
+		});
+		// Inside the handler, status had already flipped to connected.
+		expect(observed).toContain("connected");
+		eventStream.stop();
+	});
+});

ui/frontend/tests/game-state.test.ts

@@ -23,12 +23,21 @@ import { IDBCache } from "../src/platform/store/idb-cache";
 import { openGalaxyDB, type GalaxyDB } from "../src/platform/store/idb";
 import type { IDBPDatabase } from "idb";
 import { UUID } from "../src/proto/galaxy/fbs/common";
+import { ByteBuffer } from "flatbuffers";
 import {
+	GameReportRequest,
 	LocalPlanet,
 	Report,
 	ShipClass,
 } from "../src/proto/galaxy/fbs/report";
 
+function decodeRequestedTurn(payload: Uint8Array): number {
+	const req = GameReportRequest.getRootAsGameReportRequest(
+		new ByteBuffer(payload),
+	);
+	return req.turn();
+}
+
 const listMyGamesSpy = vi.fn();
 vi.mock("../src/api/lobby", async () => {
 	const actual = await vi.importActual<typeof import("../src/api/lobby")>(
@@ -291,6 +300,91 @@ describe("GameStateStore", () => {
 		expect(store.error).toBe("device session missing");
 	});
 
+	test("setGame opens last-viewed turn and surfaces pendingTurn when server is ahead", async () => {
+		await cache.put("game-prefs", `${GAME_ID}/last-viewed-turn`, 4);
+		listMyGamesSpy.mockResolvedValue([makeGameSummary(7)]);
+		const requestedTurns: number[] = [];
+		const client = makeFakeClient(async (_messageType, payload) => {
+			const turn = decodeRequestedTurn(payload);
+			requestedTurns.push(turn);
+			return {
+				resultCode: "ok",
+				payloadBytes: buildReportPayload({ turn }),
+			};
+		});
+
+		const store = new GameStateStore();
+		await store.init({ client, cache, gameId: GAME_ID });
+
+		expect(requestedTurns).toEqual([4]);
+		expect(store.report?.turn).toBe(4);
+		expect(store.currentTurn).toBe(4);
+		expect(store.pendingTurn).toBe(7);
+		store.dispose();
+	});
+
+	test("markPendingTurn records server-side advance without a network call", async () => {
+		listMyGamesSpy.mockResolvedValue([makeGameSummary(3)]);
+		let calls = 0;
+		const client = makeFakeClient(async () => {
+			calls += 1;
+			return {
+				resultCode: "ok",
+				payloadBytes: buildReportPayload({ turn: 3 }),
+			};
+		});
+
+		const store = new GameStateStore();
+		await store.init({ client, cache, gameId: GAME_ID });
+		expect(store.pendingTurn).toBeNull();
+
+		const before = calls;
+		store.markPendingTurn(4);
+		expect(store.pendingTurn).toBe(4);
+		store.markPendingTurn(3); // not strictly ahead → ignored
+		expect(store.pendingTurn).toBe(4);
+		store.markPendingTurn(6);
+		expect(store.pendingTurn).toBe(6);
+		store.markPendingTurn(5); // not ahead of pending=6 → ignored
+		expect(store.pendingTurn).toBe(6);
+		expect(calls).toBe(before);
+
+		store.dispose();
+	});
+
+	test("advanceToPending refetches and clears the pending indicator", async () => {
+		await cache.put("game-prefs", `${GAME_ID}/last-viewed-turn`, 2);
+		const summaries = [makeGameSummary(5), makeGameSummary(5)];
+		let listCalls = 0;
+		listMyGamesSpy.mockImplementation(() => {
+			const out = summaries[listCalls] ?? summaries.at(-1)!;
+			listCalls += 1;
+			return Promise.resolve([out]);
+		});
+
+		const requestedTurns: number[] = [];
+		const client = makeFakeClient(async (_messageType, payload) => {
+			const turn = decodeRequestedTurn(payload);
+			requestedTurns.push(turn);
+			return {
+				resultCode: "ok",
+				payloadBytes: buildReportPayload({ turn }),
+			};
+		});
+
+		const store = new GameStateStore();
+		await store.init({ client, cache, gameId: GAME_ID });
+		expect(store.currentTurn).toBe(2);
+		expect(store.pendingTurn).toBe(5);
+
+		await store.advanceToPending();
+		expect(store.currentTurn).toBe(5);
+		expect(store.pendingTurn).toBeNull();
+		expect(requestedTurns).toEqual([2, 5]);
+
+		store.dispose();
+	});
+
 	test("decodeReport surfaces the localShipClass projection with full attributes", async () => {
 		listMyGamesSpy.mockResolvedValue([makeGameSummary(1)]);
 		const client = makeFakeClient(async () => ({

ui/frontend/tests/toast.test.ts

@@ -0,0 +1,127 @@
+// Vitest coverage for the toast primitive in
+// `src/lib/toast.svelte.ts`. The store keeps one active toast at a
+// time, replaces it on a fresh `show`, auto-dismisses after the
+// configured duration, runs the `onAction` callback once on the
+// action button, and ignores a stale `dismiss(id)` whose target was
+// already replaced.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { toast } from "../src/lib/toast.svelte";
+
+beforeEach(() => {
+	toast.resetForTests();
+	vi.useFakeTimers();
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+	toast.resetForTests();
+});
+
+describe("toast.show", () => {
+	test("sets current and assigns a fresh id", () => {
+		const id = toast.show({
+			messageKey: "common.loading",
+		});
+		expect(id).toBeTruthy();
+		expect(toast.current).not.toBeNull();
+		expect(toast.current?.id).toBe(id);
+		expect(toast.current?.messageKey).toBe("common.loading");
+	});
+
+	test("a second show replaces the previous descriptor", () => {
+		const first = toast.show({ messageKey: "common.loading" });
+		const second = toast.show({
+			messageKey: "common.dismiss",
+		});
+		expect(second).not.toBe(first);
+		expect(toast.current?.id).toBe(second);
+		expect(toast.current?.messageKey).toBe("common.dismiss");
+	});
+
+	test("auto-dismisses after durationMs", () => {
+		toast.show({
+			messageKey: "common.loading",
+			durationMs: 2_000,
+		});
+		expect(toast.current).not.toBeNull();
+		vi.advanceTimersByTime(1_999);
+		expect(toast.current).not.toBeNull();
+		vi.advanceTimersByTime(1);
+		expect(toast.current).toBeNull();
+	});
+
+	test("durationMs=null makes the toast sticky", () => {
+		toast.show({
+			messageKey: "common.loading",
+			durationMs: null,
+		});
+		vi.advanceTimersByTime(60_000);
+		expect(toast.current).not.toBeNull();
+	});
+});
+
+describe("toast.dismiss", () => {
+	test("clears current when called without an id", () => {
+		toast.show({ messageKey: "common.loading" });
+		toast.dismiss();
+		expect(toast.current).toBeNull();
+	});
+
+	test("ignores a stale id whose target was replaced", () => {
+		const first = toast.show({
+			messageKey: "common.loading",
+			durationMs: 5_000,
+		});
+		const second = toast.show({ messageKey: "common.dismiss" });
+		toast.dismiss(first);
+		expect(toast.current?.id).toBe(second);
+		expect(toast.current?.messageKey).toBe("common.dismiss");
+	});
+
+	test("auto-dismiss timer of the replaced toast does not clobber the live one", () => {
+		toast.show({ messageKey: "common.loading", durationMs: 500 });
+		const second = toast.show({
+			messageKey: "common.dismiss",
+			durationMs: null,
+		});
+		vi.advanceTimersByTime(500);
+		// The first toast's timer fired but the dismiss is a no-op
+		// because `current.id !== first`. The sticky second toast
+		// stays alive.
+		expect(toast.current?.id).toBe(second);
+	});
+});
+
+describe("onAction", () => {
+	test("ignored unless the action button is invoked manually", () => {
+		const onAction = vi.fn();
+		toast.show({
+			messageKey: "common.loading",
+			actionLabelKey: "common.dismiss",
+			onAction,
+		});
+		vi.advanceTimersByTime(1_000);
+		expect(onAction).not.toHaveBeenCalled();
+	});
+
+	test("toast-host wiring is exercised by the layout: callback fires when host calls onAction then dismiss", () => {
+		// The host component runs `onAction()` and then `dismiss(id)`.
+		// We simulate that sequence here to pin the contract the host
+		// relies on: a single invocation of the user callback per
+		// descriptor, and the toast clears afterwards.
+		const onAction = vi.fn();
+		const id = toast.show({
+			messageKey: "common.loading",
+			actionLabelKey: "common.dismiss",
+			onAction,
+		});
+		const current = toast.current;
+		current?.onAction?.();
+		toast.dismiss(current?.id);
+		expect(onAction).toHaveBeenCalledTimes(1);
+		expect(toast.current).toBeNull();
+		// id stays unique — a follow-up show must return a different one.
+		expect(toast.show({ messageKey: "common.loading" })).not.toBe(id);
+	});
+});