ui/phase-24: declare game.turn.ready as JSON-friendly catalog kind

TestBuildClientPushEventCoversCatalog required every catalog kind to
encode through a FlatBuffers `preMarshaledEvent`. game.turn.ready
intentionally rides on the JSON fallback because its payload is just
`{game_id, turn}` and the only consumer (Phase 24 UI handler) parses
JSON inline. Make the policy explicit through a jsonFriendlyKinds
allow-list so the test still asserts each kind is covered and a future
producer that picks the wrong encoding fails loudly.

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

backend/README.md

@@ -339,9 +339,18 @@ Admin-channel kinds (`runtime.*`) deliver email to
 routes land in `notification_routes` with `status='skipped'` and the
 operator log line records the configuration miss.
 
-`game.*` (`game.started`, `game.turn.ready`, `game.generation.failed`,
+`game.turn.ready` is emitted by `lobby.Service.OnRuntimeSnapshot`
-`game.finished`) and `mail.dead_lettered` are reserved kinds without a
+(`backend/internal/lobby/runtime_hooks.go`) whenever the engine's
-producer in the catalog; adding them is an additive change to the
+`current_turn` advances. The intent targets every active membership
+of the game, uses idempotency key `turn-ready:<game_id>:<turn>`, and
+carries the JSON payload `{game_id, turn}`. The catalog routes it
+through the push channel only — per-turn email would be spam — so
+the UI's signed `SubscribeEvents` stream
+(`ui/frontend/src/api/events.svelte.ts`) is the sole delivery path.
+
+The remaining `game.*` (`game.started`, `game.generation.failed`,
+`game.finished`) and `mail.dead_lettered` are reserved kinds without
+a producer in the catalog; adding them is an additive change to the
 catalog vocabulary and the migration CHECK constraint.
 
 Templates ship in English only; localisation belongs to clients that

backend/internal/lobby/lobby.go

@@ -109,6 +109,7 @@ const (
 	NotificationLobbyRaceNameRegistered = "lobby.race_name.registered"
 	NotificationLobbyRaceNamePending = "lobby.race_name.pending"
 	NotificationLobbyRaceNameExpired = "lobby.race_name.expired"
+	NotificationGameTurnReady = "game.turn.ready"
 )
 
 // Deps aggregates every collaborator the lobby Service depends on.

backend/internal/lobby/runtime_hooks.go

@@ -30,6 +30,7 @@ func (s *Service) OnRuntimeSnapshot(ctx context.Context, gameID uuid.UUID, snaps
 	if err != nil {
 		return err
 	}
+	prevTurn := game.RuntimeSnapshot.CurrentTurn
 	merged := mergeRuntimeSnapshot(game.RuntimeSnapshot, snapshot)
 	now := s.deps.Now().UTC()
 	updated, err := s.deps.Store.UpdateGameRuntimeSnapshot(ctx, gameID, merged, now)
@@ -55,9 +56,56 @@ func (s *Service) OnRuntimeSnapshot(ctx context.Context, gameID uuid.UUID, snaps
 		}
 	}
 	s.deps.Cache.PutGame(updated)
+	if merged.CurrentTurn > prevTurn {
+		s.publishTurnReady(ctx, gameID, merged.CurrentTurn)
+	}
 	return nil
 }
 
+// publishTurnReady fans out a `game.turn.ready` notification to every
+// active member of the game once the engine reports a new
+// `current_turn`. The intent is best-effort: a publisher failure is
+// logged at warn level (matching the rest of OnRuntimeSnapshot's
+// notification calls) and does not abort the snapshot bookkeeping.
+// Idempotency is anchored on (game_id, turn), so a duplicate snapshot
+// for the same turn collapses into a single notification at the
+// notification.Submit boundary.
+func (s *Service) publishTurnReady(ctx context.Context, gameID uuid.UUID, turn int32) {
+	memberships, err := s.deps.Store.ListMembershipsForGame(ctx, gameID)
+	if err != nil {
+		s.deps.Logger.Warn("turn-ready notification: list memberships failed",
+			zap.String("game_id", gameID.String()),
+			zap.Int32("turn", turn),
+			zap.Error(err))
+		return
+	}
+	recipients := make([]uuid.UUID, 0, len(memberships))
+	for _, m := range memberships {
+		if m.Status != MembershipStatusActive {
+			continue
+		}
+		recipients = append(recipients, m.UserID)
+	}
+	if len(recipients) == 0 {
+		return
+	}
+	intent := LobbyNotification{
+		Kind:           NotificationGameTurnReady,
+		IdempotencyKey: fmt.Sprintf("turn-ready:%s:%d", gameID, turn),
+		Recipients:     recipients,
+		Payload: map[string]any{
+			"game_id": gameID.String(),
+			"turn":    turn,
+		},
+	}
+	if pubErr := s.deps.Notification.PublishLobbyEvent(ctx, intent); pubErr != nil {
+		s.deps.Logger.Warn("turn-ready notification failed",
+			zap.String("game_id", gameID.String()),
+			zap.Int32("turn", turn),
+			zap.Error(pubErr))
+	}
+}
+
 // OnGameFinished completes the game lifecycle: marks the game as
 // `finished`, evaluates capable-finish per active member, and
 // transitions reservation rows to either `pending_registration`

backend/internal/lobby/runtime_hooks_test.go

@@ -0,0 +1,207 @@
+package lobby_test
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"galaxy/backend/internal/config"
+	"galaxy/backend/internal/lobby"
+
+	"github.com/google/uuid"
+)
+
+// capturingPublisher records every `LobbyNotification` intent that the
+// lobby service emits, so a test can assert the producer side without
+// running the real notification.Submit pipeline.
+type capturingPublisher struct {
+	mu    sync.Mutex
+	items []lobby.LobbyNotification
+}
+
+func (p *capturingPublisher) PublishLobbyEvent(_ context.Context, ev lobby.LobbyNotification) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.items = append(p.items, ev)
+	return nil
+}
+
+func (p *capturingPublisher) byKind(kind string) []lobby.LobbyNotification {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	out := make([]lobby.LobbyNotification, 0, len(p.items))
+	for _, ev := range p.items {
+		if ev.Kind == kind {
+			out = append(out, ev)
+		}
+	}
+	return out
+}
+
+// newServiceWithPublisher mirrors `newServiceForTest` but lets the
+// caller inject a custom NotificationPublisher; the runtime-hooks
+// emit path needs to observe intents directly.
+func newServiceWithPublisher(t *testing.T, db *sql.DB, now func() time.Time, max int32, publisher lobby.NotificationPublisher) *lobby.Service {
+	t.Helper()
+	store := lobby.NewStore(db)
+	cache := lobby.NewCache()
+	if err := cache.Warm(context.Background(), store); err != nil {
+		t.Fatalf("warm cache: %v", err)
+	}
+	svc, err := lobby.NewService(lobby.Deps{
+		Store:        store,
+		Cache:        cache,
+		Notification: publisher,
+		Entitlement:  stubEntitlement{max: max},
+		Config: config.LobbyConfig{
+			SweeperInterval:        time.Second,
+			PendingRegistrationTTL: time.Hour,
+			InviteDefaultTTL:       time.Hour,
+		},
+		Now: now,
+	})
+	if err != nil {
+		t.Fatalf("new service: %v", err)
+	}
+	return svc
+}
+
+// TestOnRuntimeSnapshotEmitsTurnReady verifies that an engine snapshot
+// advancing `current_turn` fans out a `game.turn.ready` intent to every
+// active member, that the idempotency key is anchored on (game_id, turn),
+// and that a snapshot with the same turn does not re-emit.
+func TestOnRuntimeSnapshotEmitsTurnReady(t *testing.T) {
+	db := startPostgres(t)
+	now := time.Now().UTC()
+	clock := func() time.Time { return now }
+	publisher := &capturingPublisher{}
+	svc := newServiceWithPublisher(t, db, clock, 5, publisher)
+
+	owner := uuid.New()
+	seedAccount(t, db, owner)
+
+	game, err := svc.CreateGame(context.Background(), lobby.CreateGameInput{
+		OwnerUserID:         &owner,
+		Visibility:          lobby.VisibilityPrivate,
+		GameName:            "Turn-Ready Fan-Out",
+		MinPlayers:          1,
+		MaxPlayers:          4,
+		StartGapHours:       1,
+		StartGapPlayers:     1,
+		EnrollmentEndsAt:    now.Add(time.Hour),
+		TurnSchedule:        "0 0 * * *",
+		TargetEngineVersion: "1.0.0",
+	})
+	if err != nil {
+		t.Fatalf("create game: %v", err)
+	}
+	if _, err := svc.OpenEnrollment(context.Background(), &owner, false, game.GameID); err != nil {
+		t.Fatalf("open enrollment: %v", err)
+	}
+
+	// Seed two active members through the store so the test focuses on
+	// the runtime hook, not the membership state machine.
+	store := lobby.NewStore(db)
+	canonicalPolicy, err := lobby.NewPolicy()
+	if err != nil {
+		t.Fatalf("new policy: %v", err)
+	}
+	memberA := uuid.New()
+	memberB := uuid.New()
+	seedAccount(t, db, memberA)
+	seedAccount(t, db, memberB)
+	for i, m := range []uuid.UUID{memberA, memberB} {
+		race := fmt.Sprintf("Race%d", i+1)
+		canonical, err := canonicalPolicy.Canonical(race)
+		if err != nil {
+			t.Fatalf("canonical %q: %v", race, err)
+		}
+		if _, err := db.ExecContext(context.Background(), `
+			INSERT INTO backend.memberships (
+				membership_id, game_id, user_id, race_name, canonical_key, status
+			) VALUES ($1, $2, $3, $4, $5, 'active')
+		`, uuid.New(), game.GameID, m, race, string(canonical)); err != nil {
+			t.Fatalf("seed membership %s: %v", m, err)
+		}
+	}
+	if err := svc.Cache().Warm(context.Background(), store); err != nil {
+		t.Fatalf("re-warm cache: %v", err)
+	}
+	if _, err := svc.ReadyToStart(context.Background(), &owner, false, game.GameID); err != nil {
+		t.Fatalf("ready-to-start: %v", err)
+	}
+	if _, err := svc.Start(context.Background(), &owner, false, game.GameID); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+
+	// First snapshot: prev=0, current_turn=1 → emit on the very first
+	// turn after the engine starts producing.
+	if err := svc.OnRuntimeSnapshot(context.Background(), game.GameID, lobby.RuntimeSnapshot{
+		CurrentTurn:   1,
+		RuntimeStatus: "running",
+	}); err != nil {
+		t.Fatalf("on-runtime-snapshot 1: %v", err)
+	}
+	intents := publisher.byKind(lobby.NotificationGameTurnReady)
+	if len(intents) != 1 {
+		t.Fatalf("after turn 1 want 1 turn-ready intent, got %d", len(intents))
+	}
+	first := intents[0]
+	wantKey := fmt.Sprintf("turn-ready:%s:1", game.GameID)
+	if first.IdempotencyKey != wantKey {
+		t.Errorf("turn 1 idempotency key = %q, want %q", first.IdempotencyKey, wantKey)
+	}
+	if got := first.Payload["turn"]; got != int32(1) {
+		t.Errorf("turn 1 payload turn = %v, want 1", got)
+	}
+	if got := first.Payload["game_id"]; got != game.GameID.String() {
+		t.Errorf("turn 1 payload game_id = %v, want %s", got, game.GameID)
+	}
+	if len(first.Recipients) != 2 {
+		t.Errorf("turn 1 recipients = %d, want 2", len(first.Recipients))
+	}
+	recipientSet := map[uuid.UUID]struct{}{}
+	for _, r := range first.Recipients {
+		recipientSet[r] = struct{}{}
+	}
+	if _, ok := recipientSet[memberA]; !ok {
+		t.Errorf("turn 1 missing memberA in recipients")
+	}
+	if _, ok := recipientSet[memberB]; !ok {
+		t.Errorf("turn 1 missing memberB in recipients")
+	}
+
+	// Same turn re-delivered (duplicate snapshot, gateway replay) must
+	// not re-emit at the lobby layer: prev catches up to merged.
+	if err := svc.OnRuntimeSnapshot(context.Background(), game.GameID, lobby.RuntimeSnapshot{
+		CurrentTurn:   1,
+		RuntimeStatus: "running",
+	}); err != nil {
+		t.Fatalf("on-runtime-snapshot 1 replay: %v", err)
+	}
+	if got := len(publisher.byKind(lobby.NotificationGameTurnReady)); got != 1 {
+		t.Fatalf("after duplicate turn 1 want 1 intent, got %d", got)
+	}
+
+	// Next turn advances → second emit with key anchored on turn 2.
+	if err := svc.OnRuntimeSnapshot(context.Background(), game.GameID, lobby.RuntimeSnapshot{
+		CurrentTurn:   2,
+		RuntimeStatus: "running",
+	}); err != nil {
+		t.Fatalf("on-runtime-snapshot 2: %v", err)
+	}
+	intents = publisher.byKind(lobby.NotificationGameTurnReady)
+	if len(intents) != 2 {
+		t.Fatalf("after turn 2 want 2 turn-ready intents, got %d", len(intents))
+	}
+	wantKey2 := fmt.Sprintf("turn-ready:%s:2", game.GameID)
+	if intents[1].IdempotencyKey != wantKey2 {
+		t.Errorf("turn 2 idempotency key = %q, want %q", intents[1].IdempotencyKey, wantKey2)
+	}
+	if got := intents[1].Payload["turn"]; got != int32(2) {
+		t.Errorf("turn 2 payload turn = %v, want 2", got)
+	}
+}

backend/internal/notification/catalog.go

@@ -17,6 +17,7 @@ const (
 	KindRuntimeImagePullFailed = "runtime.image_pull_failed"
 	KindRuntimeContainerStartFailed = "runtime.container_start_failed"
 	KindRuntimeStartConfigInvalid = "runtime.start_config_invalid"
+	KindGameTurnReady = "game.turn.ready"
 )
 
 // CatalogEntry describes the per-kind delivery policy: which channels
@@ -95,6 +96,9 @@ var catalog = map[string]CatalogEntry{
 		Admin: true,
 		MailTemplateID: KindRuntimeStartConfigInvalid,
 	},
+	KindGameTurnReady: {
+		Channels: []string{ChannelPush},
+	},
 }
 
 // LookupCatalog returns the per-kind policy and a boolean reporting
@@ -123,5 +127,6 @@ func SupportedKinds() []string {
 		KindRuntimeImagePullFailed,
 		KindRuntimeContainerStartFailed,
 		KindRuntimeStartConfigInvalid,
+		KindGameTurnReady,
 	}
 }

backend/internal/notification/catalog_test.go

@@ -39,6 +39,7 @@ func TestCatalogChannels(t *testing.T) {
 		KindRuntimeImagePullFailed:      {ChannelEmail},
 		KindRuntimeContainerStartFailed: {ChannelEmail},
 		KindRuntimeStartConfigInvalid:   {ChannelEmail},
+		KindGameTurnReady:               {ChannelPush},
 	}
 	for kind, want := range expect {
 		entry, ok := LookupCatalog(kind)

backend/internal/notification/events_test.go

@@ -9,9 +9,25 @@ import (
 	"github.com/google/uuid"
 )
 
+// jsonFriendlyKinds lists catalog kinds whose payload is small and
+// stable enough that the gateway-bound encoding stays JSON instead of
+// FlatBuffers. The default for new producers is still FB; declaring a
+// kind here is a deliberate decision baked into the build target's
+// payload contract.
+//
+// `game.turn.ready` ships `{game_id, turn}` only, the UI parses it
+// inline in `routes/games/[id]/+layout.svelte` (Phase 24), and no
+// other consumer reads the payload — adopting the FB encoder would
+// require a new TS notification stub set and the regen tooling for
+// `pkg/schema/fbs/notification.fbs` without buying anything.
+var jsonFriendlyKinds = map[string]bool{
+	KindGameTurnReady: true,
+}
+
 // TestBuildClientPushEventCoversCatalog asserts that every catalog kind
-// returns a typed FB event (preMarshaledEvent) and that an unknown kind
+// is exercised by this test, that FB-typed kinds return a
-// falls through to the JSON safety net.
+// `preMarshaledEvent`, and that JSON-friendly kinds (see
+// `jsonFriendlyKinds` above) return a `push.JSONEvent`.
 func TestBuildClientPushEventCoversCatalog(t *testing.T) {
 	t.Parallel()
 
@@ -57,6 +73,10 @@ func TestBuildClientPushEventCoversCatalog(t *testing.T) {
 			"game_id": gameID.String(),
 			"reason":  "missing engine version",
 		}},
+		{"game turn ready", KindGameTurnReady, map[string]any{
+			"game_id": gameID.String(),
+			"turn":    int32(7),
+		}},
 	}
 
 	seenKinds := map[string]bool{}
@@ -78,8 +98,10 @@ func TestBuildClientPushEventCoversCatalog(t *testing.T) {
 			if len(bytes) == 0 {
 				t.Fatalf("Marshal returned empty bytes")
 			}
-			if _, isJSON := event.(push.JSONEvent); isJSON {
+			_, isJSON := event.(push.JSONEvent)
-				t.Fatalf("expected typed FB event for %s, got JSONEvent", tt.kind)
+			wantJSON := jsonFriendlyKinds[tt.kind]
+			if isJSON != wantJSON {
+				t.Fatalf("kind %s: JSONEvent=%v, want JSONEvent=%v", tt.kind, isJSON, wantJSON)
 			}
 		})
 		seenKinds[tt.kind] = true

backend/internal/postgres/migrations/00001_init.sql

@@ -605,7 +605,8 @@ CREATE TABLE notifications (
             'lobby.race_name.registered', 'lobby.race_name.pending',
             'lobby.race_name.expired',
             'runtime.image_pull_failed', 'runtime.container_start_failed',
-            'runtime.start_config_invalid'
+            'runtime.start_config_invalid',
+            'game.turn.ready'
         ))
 );
 

docs/FUNCTIONAL.md

@@ -672,13 +672,19 @@ runtime status, per-player stats). The engine's "game finished"
 report drives the `running → finished` transition ([Section 3.5](#35-cancellation-and-finish))
 and triggers Race Name Directory promotions ([Section 5](#5-race-name-directory)).
 
-The `game.*` notification kinds (`game.started`, `game.turn.ready`,
+Among the `game.*` notification kinds, `game.turn.ready` is wired:
-`game.generation.failed`, `game.finished`) are reserved in the
+`lobby.Service.OnRuntimeSnapshot` (`backend/internal/lobby/runtime_hooks.go`)
-documentation but have **no producer** in the codebase today; the
+emits one intent per advancing `current_turn`, addressed to every
-notification catalog explicitly omits them (`backend/internal/notification/catalog.go`).
+active membership of the game, with idempotency key
-Adding a producer is purely additive: register the kind in the
+`turn-ready:<game_id>:<turn>` and JSON payload `{game_id, turn}`. The
-catalog, populate `MailTemplateID` if email fan-out is desired, and
+catalog routes the intent through the push channel only; email is
-have the appropriate domain module call `notification.Submit`.
+deliberately omitted to avoid per-turn spam.
+
+The remaining `game.*` kinds (`game.started`, `game.generation.failed`,
+`game.finished`) and `mail.dead_lettered` are reserved without a
+producer; adding one is purely additive (register the kind in the
+catalog, extend the migration `CHECK` constraint, and call
+`notification.Submit` from the appropriate domain module).
 
 ### 6.6 Cross-references
 

docs/FUNCTIONAL_ru.md

@@ -690,14 +690,19 @@ status, per-player-stats). Engine-отчёт "game finished" гонит
 ([Раздел 3.5](#35-отмена-и-завершение)) и триггерит Race Name
 Directory-промоушен ([Раздел 5](#5-реестр-названий-рас)).
 
-`game.*`-виды уведомлений (`game.started`, `game.turn.ready`,
+Из `game.*`-видов уведомлений подключён `game.turn.ready`:
-`game.generation.failed`, `game.finished`) зарезервированы в
+`lobby.Service.OnRuntimeSnapshot` (`backend/internal/lobby/runtime_hooks.go`)
-документации, но **не имеют поставщика** в кодовой базе сегодня;
+выпускает один intent на каждое увеличение `current_turn`, адресуя
-notification-каталог явно их опускает
+его всем активным membership-ам игры, с idempotency-ключом
-(`backend/internal/notification/catalog.go`). Добавление поставщика
+`turn-ready:<game_id>:<turn>` и JSON-payload-ом `{game_id, turn}`.
-аддитивно: зарегистрировать вид в каталоге, заполнить
+Каталог направляет intent только в push-канал; email-фан-аут
-`MailTemplateID`, если нужен email-веер, и заставить нужный
+сознательно опущен, чтобы избежать спама на каждом ходе.
-доменный модуль вызвать `notification.Submit`.
+
+Остальные `game.*`-виды (`game.started`, `game.generation.failed`,
+`game.finished`) и `mail.dead_lettered` зарезервированы без поставщика;
+добавление поставщика чисто аддитивное (зарегистрировать вид в
+каталоге, расширить `CHECK`-констрейнт миграции и вызвать
+`notification.Submit` из подходящего доменного модуля).
 
 ### 6.6 Перекрёстные ссылки
 

ui/PLAN.md

@@ -2581,40 +2581,95 @@ Decisions during stage:
     `game.table.*` so the two surfaces evolve independently. ≈90 new
     keys, en + ru in lockstep.
 
-## Phase 24. Push Events — Turn-Ready
+## ~~Phase 24. Push Events — Turn-Ready~~
 
-Status: pending.
+Status: done.
 
 Goal: subscribe to the server push stream and refresh client state
 when a turn-ready event arrives.
 
-Artifacts:
+Artifacts (delivered):
 
-- `ui/frontend/src/api/events.ts` push-stream subscription wired
+- `ui/frontend/src/api/events.svelte.ts` — single
-  through `GalaxyClient.subscribeEvents` and Connect server-streaming
+  `SubscribeEvents` consumer per session. Absorbs the previous
-- on `game.turn.ready` event: invalidate `(game_id, current_turn)`
+  `revocation-watcher.ts` (now deleted) so there is exactly one
-  cache entries and trigger a fresh report fetch
+  authenticated stream per device session; clean end-of-stream and
-- a top-of-screen toast: `Turn N+1 is ready. View now.` with a button
+  `Unauthenticated` ConnectError both funnel into
-  that re-renders the active view against the new turn
+  `session.signOut("revoked")`. Exposes a `connectionStatus` rune
-- mandatory event signature verification through `ui/core` — any
+  for the future header indicator.
-  verification failure tears down the stream and reconnects with
+- `ui/frontend/src/lib/toast.svelte.ts` and `toast-host.svelte` —
-  exponential backoff
+  single-slot transient-notification primitive mounted from the
+  root layout; later phases (battle, mail) reuse it.
+- `GameStateStore` gained `pendingTurn`, `markPendingTurn`,
+  `advanceToPending`, and a persisted `lastViewedTurn` so a boot
+  with `lastViewedTurn < currentTurn` opens the user on the
+  last-seen snapshot and surfaces the gap through the same toast
+  affordance as a live push event.
+- Backend producer: `lobby.Service.OnRuntimeSnapshot` emits
+  `game.turn.ready` on every `current_turn` advance, addressed to
+  every active membership, idempotency key
+  `turn-ready:<game_id>:<turn>`, payload `{game_id, turn}`.
+  Catalog routes it through the push channel only.
+- Mandatory event-signature verification through `ui/core`:
+  `core.verifyPayloadHash` + `core.verifyEvent` on every frame.
+  Verification failure tears the stream down and reconnects with
+  full-jitter exponential backoff (base 1 s, ceiling 30 s,
+  unbounded retries).
+- Topic doc: `ui/docs/events.md`.
 
 Dependencies: Phases 23, 4 (Connect streaming in gateway).
 
-Acceptance criteria:
+Decisions baked back in (this stage):
 
-- a server-side turn cutoff produces a toast within one second;
+- **Minimum traffic on `game.turn.ready`.** The event flips
-- accepting the toast refreshes the active view to the new turn's data
+  `gameState.pendingTurn` only; the report for the new turn is not
-  without a full page reload;
+  fetched until the user activates the toast's "view now" action.
-- a forged event (test fixture with bad signature) is rejected and the
+  This is the same affordance the boot-time `lastViewedTurn < currentTurn`
-  stream reconnects.
+  branch surfaces, so a player who returns after several turns sees
+  one "view now" path instead of an auto-jump.
+- **Revocation-watcher folded into `events.svelte.ts`.** A single
+  SubscribeEvents stream now serves both per-event dispatch and
+  revocation detection. Two parallel streams per session would
+  double the gateway hub load and ambiguate the
+  `session_invalidation` clean-close signal.
+- **Integration test scope.** Backend producer is covered by
+  `lobby/runtime_hooks_test.go` (testcontainers); UI consumer by
+  `tests/events.test.ts` and the Playwright e2e in
+  `tests/e2e/turn-ready.spec.ts`. A dedicated
+  `integration/turn_ready_flow_test.go` was not added because
+  triggering `OnRuntimeSnapshot` end-to-end through the running
+  runtime container would require a test-only admin endpoint, and
+  the existing `TestNotificationFlow_LobbyInvite` already exercises
+  the backend → gateway → stream path for another notification
+  kind on the exact same producer mechanism.
 
-Targeted tests:
+Acceptance criteria (met):
 
-- Vitest unit tests for `events.ts` handling subscribe, event
+- a server-side turn cutoff produces a toast within one second
-  dispatch, error backoff;
+  (Phase 24's stream propagation; the producer side ships with the
-- Playwright e2e: trigger a server turn, observe toast and refresh.
+  backend changes above);
+- activating the toast refreshes the active view to the new turn's
+  data without a full page reload
+  (`gameState.advanceToPending` → fresh `lobby.my.games.list` +
+  `user.games.report` round-trip);
+- a forged event (Vitest fixture with bad signature or
+  payload-hash mismatch) is rejected and the stream reconnects
+  through full-jitter backoff.
+
+Targeted tests (delivered):
+
+- Vitest: `tests/events.test.ts` (verified dispatch, type
+  filtering, bad-signature reconnect, `Unauthenticated` sign-out,
+  clean end-of-stream sign-out, connection-status transitions);
+  `tests/toast.test.ts`; extensions in `tests/game-state.test.ts`
+  for `pendingTurn` / `lastViewedTurn` / `advanceToPending`.
+- Backend: `internal/notification/catalog_test.go` (kind +
+  channels); `internal/lobby/runtime_hooks_test.go`
+  (testcontainers, capturing publisher, idempotency on duplicate
+  snapshots).
+- Playwright: `tests/e2e/turn-ready.spec.ts` (signed
+  `game.turn.ready` frame surfaces the toast, manual dismiss
+  clears it).
 
 ## Phase 25. Sync Protocol — Order Queue, Retry, Conflict
 

ui/docs/events.md

@@ -0,0 +1,118 @@
+# UI events stream (`api/events.svelte.ts`)
+
+This document describes how the SvelteKit frontend consumes the
+gateway's `SubscribeEvents` server-streaming RPC. The single
+authenticated session keeps **one** stream open through the
+`EventStream` singleton declared in `src/api/events.svelte.ts`; the
+root layout starts it once the session reaches `authenticated` and
+stops it on sign-out.
+
+## Why a single consumer
+
+Before Phase 24, the watcher in `lib/revocation-watcher.ts` opened a
+parallel stream just to observe session revocation. Phase 24 folds
+that watcher into `EventStream` so that:
+
+- there is only **one** SubscribeEvents connection per session
+  (avoids doubling the gateway hub load);
+- both clean end-of-stream on an authenticated session and an
+  `Unauthenticated` ConnectError funnel through one
+  `session.signOut("revoked")` call site;
+- per-event-type dispatch (turn-ready toasts, lobby/mail/battle
+  notifications later) shares the same verification path.
+
+## Lifecycle
+
+```
+SessionStore.status = "authenticated"
+    ↓ (root layout $effect)
+EventStream.start({ core, keypair, deviceSessionId, gatewayResponsePublicKey })
+    ↓
+loop: open SubscribeEvents → verify each frame → dispatch to handlers
+    ↓
+EventStream.stop()  (on logout, unmount, or session id change)
+```
+
+`start` is idempotent for the same session: re-calling while the
+stream is running is a no-op. The root layout detects a session id
+flip (re-login on the same tab) by storing the bound id and calling
+`stop()` + `start()` against the fresh credentials.
+
+## Frame handling
+
+Every `GatewayEvent` is verified before dispatch:
+
+1. `core.verifyPayloadHash(payloadBytes, payloadHash)` — the SHA-256
+   digest of `payloadBytes` must equal `payloadHash`. A mismatch is
+   treated as a forgery.
+2. `core.verifyEvent(gatewayResponsePublicKey, signature, fields)` —
+   Ed25519 verification using the canonical signing input defined in
+   `ui/core/canon/event.go` (mirrored by `gateway/authn/event.go`).
+3. On success the verified projection (`VerifiedEvent`) is passed to
+   every handler registered via `eventStream.on(eventType, handler)`.
+
+Any verification failure throws `SignatureError`, which falls into
+the same retry path as a transport error: the loop classifies it as
+transient, tears the stream down, and reconnects with full-jitter
+exponential backoff (base 1 s, ceiling 30 s, unbounded retries).
+
+## Connection status
+
+`EventStream.connectionStatus` is a Svelte rune with five values:
+
+- `idle` — stream not running.
+- `connecting` — `subscribeEvents()` issued, no frame received yet.
+- `connected` — first frame verified and dispatched, attempt counter
+  reset to zero.
+- `reconnecting` — transient failure, backoff in flight.
+- `offline` — `navigator.onLine === false` at the moment of failure.
+
+The header connection-state indicator planned in `PLAN.md`
+cross-cutting shell reads this rune; it is not part of Phase 24 but
+the rune is wired now so a later phase can add the dot without
+touching this module.
+
+## Revocation semantics
+
+Two paths lead to `session.signOut("revoked")`:
+
+- a `ConnectError` with code `Unauthenticated`: the gateway rejected
+  the stream credentials (revoked device session);
+- a clean end-of-stream while `session.status === "authenticated"`:
+  the gateway's documented `session_invalidation` signal closes the
+  stream once the device session flips to revoked.
+
+Any other error (network drop, gateway 5xx, transient close,
+signature failure) keeps the session alive and triggers backoff +
+reconnect.
+
+## Adding a new event type
+
+1. Register a handler from the consumer module:
+   ```ts
+   const off = eventStream.on("mail.received", (event) => {
+       // parse event.payloadBytes
+   });
+   onDestroy(off);
+   ```
+2. If the handler reads scoped data (per-game, per-route), register
+   from a layout that owns that scope and pass the gameId via a
+   closure. The handler should filter events whose payload does not
+   match its scope (see `routes/games/[id]/+layout.svelte` for the
+   `game.turn.ready` filter).
+3. The payload encoding is owned by the producer side: the
+   `game.turn.ready` event uses JSON `{game_id, turn}`. Document
+   the schema next to the producer (e.g. `backend/README.md` §10).
+
+## Tests
+
+- Unit (Vitest): `tests/events.test.ts` mocks the transport via
+  `createRouterTransport` and covers verified dispatch, type
+  filtering, bad-signature reconnect, `Unauthenticated` sign-out,
+  clean end-of-stream sign-out, and connection-status transitions.
+- E2E (Playwright): `tests/e2e/turn-ready.spec.ts` serves a signed
+  `game.turn.ready` frame through `page.route`, asserts the toast
+  surfaces, and verifies manual dismiss without advance. The
+  advance roundtrip (toast → click "view now" → fresh report) is
+  covered by Vitest at the store level because it is sensitive to
+  Playwright-side network ordering.

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) {
+			eventStream.stop();
-				stopWatcher();
+			streamSessionId = null;
-				stopWatcher = null;
-			}
 		};
 	});
 
 	$effect(() => {
-		if (session.status === "authenticated" && stopWatcher === null) {
+		if (
-			stopWatcher = startRevocationWatcher();
+			session.status === "authenticated" &&
-		} else if (session.status !== "authenticated" && stopWatcher !== null) {
+			session.keypair !== null &&
-			stopWatcher();
+			session.deviceSessionId !== null &&
-			stopWatcher = 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);
+	});
+});