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();