From 8037c7558a16fc4b359524657e1381b7a14ed8ce Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:05:32 +0200
Subject: [PATCH 1/7] Qualify browser gates with observe, reconnect soak, and
 size budgets.

Add Wasm download measurement, reconnect soak harness, F4/__ofPerf observability,
and deploy-time bundle enforcement so browser release evidence can be recorded
against documented budgets.
---
 .github/workflows/deploy.yml          |   3 +
 Cargo.lock                            |   3 +
 README.md                             |   5 +-
 crates/game-client/Cargo.toml         |   1 +
 crates/game-client/src/config.rs      |   9 +
 crates/game-client/src/main.rs        |   5 +
 crates/game-client/src/network.rs     |  33 ++-
 crates/game-client/src/observe.rs     | 307 +++++++++++++++++++++++
 crates/game-client/src/online.rs      | 140 ++++++++++-
 crates/game-client/src/performance.rs |  62 ++++-
 docs/README.md                        |   6 +
 docs/browser-gates.md                 | 218 ++++++++++++++++
 docs/future-ideas.md                  |   2 +-
 docs/implementation.md                |  14 +-
 docs/observability.md                 | 106 ++++++++
 docs/performance.md                   |   1 +
 docs/technical-architecture.md        |   6 +-
 modules/lobby/Cargo.lock              |   1 +
 modules/lobby/Cargo.toml              |   1 +
 modules/lobby/src/lib.rs              |  36 ++-
 modules/match/Cargo.lock              |   1 +
 modules/match/Cargo.toml              |   1 +
 modules/match/src/lib.rs              |  30 ++-
 modules/match/src/rules.rs            |  21 +-
 modules/match/src/simulation.rs       |   8 +
 scripts/measure-web-bundle.sh         | 162 ++++++++++++
 scripts/run-reconnect-soak.sh         |  94 +++++++
 tools/match-e2e/Cargo.toml            |   2 +
 tools/match-e2e/src/main.rs           | 341 ++++++++++++++++++++++----
 29 files changed, 1551 insertions(+), 68 deletions(-)
 create mode 100644 crates/game-client/src/observe.rs
 create mode 100644 docs/browser-gates.md
 create mode 100644 docs/observability.md
 create mode 100755 scripts/measure-web-bundle.sh
 create mode 100755 scripts/run-reconnect-soak.sh

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 1a24144..5b44c48 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -54,6 +54,9 @@ jobs:
       - name: Build production deployment
         run: ./scripts/build-vercel-production.sh
 
+      - name: Enforce web bundle size gate
+        run: ./scripts/measure-web-bundle.sh --dist target/web --enforce
+
       - name: Publish authoritative module
         env:
           SPACETIMEDB_TOKEN: ${{ secrets.SPACETIMEDB_TOKEN }}
diff --git a/Cargo.lock b/Cargo.lock
index 791f933..c407c9a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2989,6 +2989,7 @@ dependencies = [
  "js-sys",
  "match-bindings",
  "spacetimedb-sdk",
+ "wasm-bindgen",
  "wasm-bindgen-futures",
  "web-sys",
  "worldgen",
@@ -3972,6 +3973,8 @@ dependencies = [
  "clap",
  "hex-core",
  "match-bindings",
+ "serde",
+ "serde_json",
  "spacetimedb-sdk",
 ]
 
diff --git a/README.md b/README.md
index 52c9355..128f996 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,9 @@ Browser identity tokens are scoped by host, database, and profile in
 `localStorage`. Production deployments must use HTTPS/WSS to protect those
 credentials; WebGPU itself requires a secure context (localhost is allowed for
 local development). Run `trunk build` from `crates/game-client` to
-produce a deployable bundle in `target/web`.
+produce a deployable bundle in `target/web`. Measure and enforce the download
+budget with `./scripts/measure-web-bundle.sh --enforce` (see
+[Browser release gates](docs/browser-gates.md)).
 
 ## Production deployment
 
@@ -263,6 +265,7 @@ relevant keys; `?` opens the field manual.
 | `V` | Cycle map views |
 | `?` | Toggle the field manual |
 | `F3` | Toggle the performance overlay |
+| `F4` | Toggle the observe event ring (`OF_OBSERVE=1` / `?observe=1` for console) |
 
 A cluster is the full connected set of owned passable cells. Empty owned cells
 can connect troop-bearing areas; blocked terrain and impassable elevation edges
diff --git a/crates/game-client/Cargo.toml b/crates/game-client/Cargo.toml
index 6ab1d1c..16da2a0 100644
--- a/crates/game-client/Cargo.toml
+++ b/crates/game-client/Cargo.toml
@@ -24,6 +24,7 @@ clap.workspace = true
 bevy = { workspace = true, features = ["webgpu"] }
 js-sys = "=0.3.103"
 spacetimedb-sdk = { workspace = true, features = ["browser"] }
+wasm-bindgen = "=0.2.126"
 wasm-bindgen-futures = "=0.4.76"
 web-sys = { version = "=0.3.103", features = [
     "Location",
diff --git a/crates/game-client/src/config.rs b/crates/game-client/src/config.rs
index 767e04b..8c82ae2 100644
--- a/crates/game-client/src/config.rs
+++ b/crates/game-client/src/config.rs
@@ -28,6 +28,7 @@ const DEFAULT_DATABASE: &str = match option_env!("OF_WEB_DATABASE") {
     about = "Native hex RTS client",
     disable_version_flag = true
 )]
+#[allow(clippy::struct_excessive_bools)]
 struct ClientArgs {
     /// Use the local deterministic fixture instead of `SpacetimeDB`.
     #[arg(long)]
@@ -88,6 +89,10 @@ struct ClientArgs {
     /// Skip the lobby UI and join immediately (env: `OF_AUTO_JOIN`).
     #[arg(long)]
     auto_join: bool,
+
+    /// Emit structured `[of.observe]` events to the log/console (env: `OF_OBSERVE`).
+    #[arg(long)]
+    observe: bool,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -109,6 +114,8 @@ pub struct ClientConfig {
     pub profile: String,
     /// Automation/dev path: connect and call `join_match` after bootstrap.
     pub auto_join: bool,
+    /// Emit structured observe events to stderr / browser console.
+    pub observe: bool,
 }
 
 impl ClientConfig {
@@ -167,6 +174,7 @@ impl ClientConfig {
             preferred_player,
             profile,
             auto_join,
+            observe: args.observe || env_flag("OF_OBSERVE"),
         }
     }
 
@@ -200,6 +208,7 @@ impl ClientConfig {
             preferred_player,
             profile,
             auto_join,
+            observe: browser_flag("observe"),
         }
     }
 
diff --git a/crates/game-client/src/main.rs b/crates/game-client/src/main.rs
index 36db9a2..ec1fd7f 100644
--- a/crates/game-client/src/main.rs
+++ b/crates/game-client/src/main.rs
@@ -19,6 +19,7 @@ mod lobby;
 mod map_view;
 mod model;
 mod network;
+mod observe;
 mod online;
 mod overlays;
 mod performance;
@@ -35,6 +36,7 @@ use lobby::LobbyPlugin;
 use map_view::MapViewPlugin;
 use model::{MatchView, update_transient_state};
 use network::{NetworkBoundaryPlugin, NetworkSet, OfflineTransportPlugin, apply_server_updates};
+use observe::ObservePlugin;
 use online::{OnlineSyncSet, OnlineTransportPlugin};
 use overlays::OverlayPlugin;
 use performance::PerformanceOverlayPlugin;
@@ -101,6 +103,9 @@ fn main() {
             LobbyPlugin,
             HudPlugin,
             PerformanceOverlayPlugin,
+            ObservePlugin {
+                console_enabled: config.observe,
+            },
         ))
         .insert_resource(ClearColor(Color::srgb(0.018, 0.025, 0.031)))
         .insert_resource(GlobalAmbientLight {
diff --git a/crates/game-client/src/network.rs b/crates/game-client/src/network.rs
index 2f9af21..2fc10af 100644
--- a/crates/game-client/src/network.rs
+++ b/crates/game-client/src/network.rs
@@ -20,6 +20,7 @@ use crate::model::{
     ActiveFlow, ActiveFront, MatchPhase, MatchView, OrderSelectionProjectionError,
     ProjectedOrderSelection, ToastKind,
 };
+use crate::observe::{ObserveLevel, ObserveState, keys as observe_keys};
 
 #[derive(Message, Clone, Debug)]
 pub enum ClientIntent {
@@ -194,12 +195,17 @@ pub fn resolve_offline_intents(
     }
 }
 
-pub fn apply_server_updates(mut updates: MessageReader<ServerUpdate>, mut view: ResMut<MatchView>) {
+pub fn apply_server_updates(
+    mut updates: MessageReader<ServerUpdate>,
+    mut view: ResMut<MatchView>,
+    mut observe: ResMut<ObserveState>,
+) {
     let mut offline_ownership_changed = false;
     for update in updates.read() {
         match update {
             ServerUpdate::SubmissionStarted { .. } => {}
             ServerUpdate::Accepted {
+                command_id,
                 summary,
                 patches,
                 flow,
@@ -219,12 +225,28 @@ pub fn apply_server_updates(mut updates: MessageReader<ServerUpdate>, mut view:
                 if let Some(front) = front {
                     view.active_fronts.push(front.clone());
                 }
+                observe.emit(
+                    ObserveLevel::Info,
+                    observe_keys::CMD_ACCEPT,
+                    format!(
+                        "command_id={} summary={summary}",
+                        command_id.map_or_else(|| "-".to_owned(), |id| id.to_string())
+                    ),
+                );
                 view.push_log(summary);
                 view.show_toast("Command accepted", ToastKind::Success);
             }
             ServerUpdate::MobilizationChanged { command_id, target } => {
                 view.mobilization_target = *target;
                 let command = command_id.map_or_else(String::new, |id| format!(" · command #{id}"));
+                observe.emit(
+                    ObserveLevel::Info,
+                    observe_keys::CMD_ACCEPT,
+                    format!(
+                        "command_id={} kind=set_mobilization_target target={target:.2}",
+                        command_id.map_or_else(|| "-".to_owned(), |id| id.to_string())
+                    ),
+                );
                 view.push_log(format!(
                     "Mobilization target set to {:.0}%{command}",
                     target * 100.0
@@ -232,6 +254,7 @@ pub fn apply_server_updates(mut updates: MessageReader<ServerUpdate>, mut view:
                 view.show_toast("Future recruitment target updated", ToastKind::Success);
             }
             ServerUpdate::Rejected {
+                command_id,
                 reason,
                 relevant_cell,
                 ..
@@ -239,6 +262,14 @@ pub fn apply_server_updates(mut updates: MessageReader<ServerUpdate>, mut view:
                 let marker = relevant_cell.map_or_else(String::new, |cell| {
                     format!(" · marked {},{}", cell.q, cell.r)
                 });
+                observe.emit(
+                    ObserveLevel::Warn,
+                    observe_keys::CMD_REJECT,
+                    format!(
+                        "command_id={} reason={reason}",
+                        command_id.map_or_else(|| "-".to_owned(), |id| id.to_string())
+                    ),
+                );
                 view.push_log(format!("Rejected: {reason}{marker}"));
                 view.show_toast(reason, ToastKind::Rejection);
             }
diff --git a/crates/game-client/src/observe.rs b/crates/game-client/src/observe.rs
new file mode 100644
index 0000000..19ea0b0
--- /dev/null
+++ b/crates/game-client/src/observe.rs
@@ -0,0 +1,307 @@
+//! Lightweight structured observability for the Bevy client.
+//!
+//! Events use stable `category.action` keys so browser `DevTools`, native stderr,
+//! and the F4 overlay stay greppable. Console emission is gated by
+//! `OF_OBSERVE=1` / `--observe` (native) or `?observe=1` (wasm); the in-memory
+//! ring always records recent events so F4 works without a restart.
+
+use std::collections::VecDeque;
+use std::fmt::Write as _;
+
+use bevy::{
+    diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin},
+    prelude::*,
+    ui::UiRect,
+};
+
+const RING_CAPACITY: usize = 64;
+const FRAME_SPIKE_MS: f64 = 33.0;
+/// Prefer Bevy `Time` over `std::time::Instant` — Instant panics on wasm.
+const FRAME_SPIKE_COOLDOWN_SECS: f64 = 2.0;
+const PANEL: Color = Color::srgba(0.025, 0.038, 0.047, 0.94);
+const LINE: Color = Color::srgba(0.42, 0.58, 0.65, 0.48);
+const TEXT: Color = Color::srgb(0.72, 0.91, 0.93);
+
+/// Stable event keys. Prefer extending this list over inventing ad-hoc strings.
+pub mod keys {
+    pub const NET_CONNECT_BEGIN: &str = "net.connect_begin";
+    pub const NET_CONNECTED: &str = "net.connected";
+    pub const NET_BOOTSTRAP: &str = "net.bootstrap";
+    pub const NET_TACTICAL: &str = "net.tactical";
+    pub const NET_DISCONNECT: &str = "net.disconnect";
+    pub const NET_RECONNECT: &str = "net.reconnect";
+    pub const NET_CONNECT_FAIL: &str = "net.connect_fail";
+    pub const NET_JOIN_FAIL: &str = "net.join_fail";
+    pub const LOBBY_ACTION: &str = "lobby.action";
+    pub const CMD_SUBMIT: &str = "cmd.submit";
+    pub const CMD_ACCEPT: &str = "cmd.accept";
+    pub const CMD_REJECT: &str = "cmd.reject";
+    pub const CMD_FAIL: &str = "cmd.fail";
+    pub const SYNC_APPLY: &str = "sync.apply";
+    pub const PERF_FRAME_SPIKE: &str = "perf.frame_spike";
+    pub const TOKEN_WARN: &str = "auth.token_warn";
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd, Ord)]
+pub enum ObserveLevel {
+    Debug,
+    Info,
+    Warn,
+    Error,
+}
+
+impl ObserveLevel {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::Debug => "DEBUG",
+            Self::Info => "INFO",
+            Self::Warn => "WARN",
+            Self::Error => "ERROR",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+struct ObserveRecord {
+    seq: u64,
+    level: ObserveLevel,
+    key: &'static str,
+    detail: String,
+}
+
+#[derive(Resource)]
+pub struct ObserveState {
+    /// When true, events also go to Bevy's log (stderr / browser console).
+    pub console_enabled: bool,
+    pub overlay_visible: bool,
+    next_seq: u64,
+    events: VecDeque<ObserveRecord>,
+    last_frame_spike_at_secs: Option<f64>,
+    refresh_overlay: bool,
+}
+
+impl ObserveState {
+    pub fn new(console_enabled: bool) -> Self {
+        Self {
+            console_enabled,
+            overlay_visible: false,
+            next_seq: 1,
+            events: VecDeque::with_capacity(RING_CAPACITY),
+            last_frame_spike_at_secs: None,
+            refresh_overlay: false,
+        }
+    }
+
+    pub fn emit(&mut self, level: ObserveLevel, key: &'static str, detail: impl Into<String>) {
+        let detail = detail.into();
+        let seq = self.next_seq;
+        self.next_seq = self.next_seq.saturating_add(1);
+        if self.console_enabled {
+            emit_console(level, key, &detail);
+        }
+        self.events.push_back(ObserveRecord {
+            seq,
+            level,
+            key,
+            detail,
+        });
+        while self.events.len() > RING_CAPACITY {
+            self.events.pop_front();
+        }
+        self.refresh_overlay = true;
+    }
+
+    fn note_frame_spike(&mut self, now_secs: f64, frame_ms: f64, fps: Option<f64>) {
+        if self.last_frame_spike_at_secs.is_some_and(|previous| {
+            now_secs - previous < FRAME_SPIKE_COOLDOWN_SECS
+        }) {
+            return;
+        }
+        self.last_frame_spike_at_secs = Some(now_secs);
+        let fps_part = fps.map_or_else(|| "fps=--".to_owned(), |value| format!("fps={value:.1}"));
+        self.emit(
+            ObserveLevel::Warn,
+            keys::PERF_FRAME_SPIKE,
+            format!("frame_ms={frame_ms:.2} {fps_part} threshold_ms={FRAME_SPIKE_MS}"),
+        );
+    }
+}
+
+fn emit_console(level: ObserveLevel, key: &str, detail: &str) {
+    let message = format!("[of.observe] {} {key} {detail}", level.as_str());
+    match level {
+        ObserveLevel::Debug => bevy::log::debug!(target: "of.observe", "{message}"),
+        ObserveLevel::Info => bevy::log::info!(target: "of.observe", "{message}"),
+        ObserveLevel::Warn => bevy::log::warn!(target: "of.observe", "{message}"),
+        ObserveLevel::Error => bevy::log::error!(target: "of.observe", "{message}"),
+    }
+}
+
+#[derive(Component)]
+struct ObservePanel;
+
+#[derive(Component)]
+struct ObserveText;
+
+pub struct ObservePlugin {
+    pub console_enabled: bool,
+}
+
+impl Plugin for ObservePlugin {
+    fn build(&self, app: &mut App) {
+        app.insert_resource(ObserveState::new(self.console_enabled))
+            .add_systems(Startup, spawn_observe_overlay)
+            .add_systems(
+                Update,
+                (
+                    toggle_observe_overlay,
+                    detect_frame_spikes,
+                    update_observe_overlay,
+                )
+                    .chain(),
+            );
+    }
+}
+
+fn spawn_observe_overlay(mut commands: Commands) {
+    commands
+        .spawn((
+            Name::new("Observe overlay"),
+            ObservePanel,
+            Node {
+                display: Display::None,
+                position_type: PositionType::Absolute,
+                left: px(72),
+                top: px(286),
+                width: px(620),
+                max_height: px(320),
+                padding: UiRect::all(px(10)),
+                border: UiRect::all(px(1)),
+                flex_direction: FlexDirection::Column,
+                row_gap: px(4),
+                overflow: Overflow::clip_y(),
+                ..default()
+            },
+            BackgroundColor(PANEL),
+            BorderColor::all(LINE),
+            GlobalZIndex(31),
+            Pickable::IGNORE,
+        ))
+        .with_child((
+            ObserveText,
+            Text::new("OBSERVE  //  F4\nWaiting for events…"),
+            TextFont::from_font_size(11.0),
+            TextColor(TEXT),
+            Pickable::IGNORE,
+        ));
+}
+
+fn toggle_observe_overlay(
+    keyboard: Res<ButtonInput<KeyCode>>,
+    mut state: ResMut<ObserveState>,
+    panel: Single<&mut Node, With<ObservePanel>>,
+) {
+    if !keyboard.just_pressed(KeyCode::F4) {
+        return;
+    }
+    let mut panel = panel.into_inner();
+    state.overlay_visible = !state.overlay_visible;
+    panel.display = if state.overlay_visible {
+        Display::Flex
+    } else {
+        Display::None
+    };
+    state.refresh_overlay = state.overlay_visible;
+}
+
+fn detect_frame_spikes(
+    time: Res<Time>,
+    diagnostics: Res<DiagnosticsStore>,
+    mut state: ResMut<ObserveState>,
+) {
+    let Some(frame_ms) = diagnostics
+        .get(&FrameTimeDiagnosticsPlugin::FRAME_TIME)
+        .and_then(|diagnostic| diagnostic.value().or_else(|| diagnostic.smoothed()))
+    else {
+        return;
+    };
+    if frame_ms < FRAME_SPIKE_MS {
+        return;
+    }
+    let fps = diagnostics
+        .get(&FrameTimeDiagnosticsPlugin::FPS)
+        .and_then(|diagnostic| diagnostic.smoothed().or_else(|| diagnostic.value()));
+    state.note_frame_spike(time.elapsed_secs_f64(), frame_ms, fps);
+}
+
+fn update_observe_overlay(
+    mut state: ResMut<ObserveState>,
+    text: Single<&mut Text, With<ObserveText>>,
+) {
+    if !state.overlay_visible || !state.refresh_overlay {
+        return;
+    }
+    state.refresh_overlay = false;
+    let console = if state.console_enabled {
+        "console ON"
+    } else {
+        "console OFF · OF_OBSERVE / ?observe=1"
+    };
+    let mut body = format!("OBSERVE  //  F4  ·  {console}\n");
+    if state.events.is_empty() {
+        body.push_str("Waiting for events…");
+    } else {
+        for record in state.events.iter().rev().take(18) {
+            let _ = writeln!(
+                body,
+                "{:>4} {:>5} {} {}",
+                record.seq,
+                record.level.as_str(),
+                record.key,
+                record.detail
+            );
+        }
+    }
+    let mut text = text.into_inner();
+    if **text != body {
+        **text = body;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ring_retains_latest_events_and_assigns_stable_keys() {
+        let mut state = ObserveState::new(false);
+        for index in 0..RING_CAPACITY + 5 {
+            state.emit(
+                ObserveLevel::Info,
+                keys::NET_CONNECTED,
+                format!("gen={index}"),
+            );
+        }
+        assert_eq!(state.events.len(), RING_CAPACITY);
+        assert_eq!(state.events.front().unwrap().detail, "gen=5");
+        assert_eq!(
+            state.events.back().unwrap().detail,
+            format!("gen={}", RING_CAPACITY + 4)
+        );
+        assert!(
+            state
+                .events
+                .iter()
+                .all(|record| record.key == keys::NET_CONNECTED)
+        );
+    }
+
+    #[test]
+    fn frame_spike_is_rate_limited() {
+        let mut state = ObserveState::new(false);
+        state.note_frame_spike(40.0, Some(25.0));
+        state.note_frame_spike(50.0, Some(20.0));
+        assert_eq!(state.events.len(), 1);
+        assert_eq!(state.events[0].key, keys::PERF_FRAME_SPIKE);
+    }
+}
diff --git a/crates/game-client/src/online.rs b/crates/game-client/src/online.rs
index 952c0ce..1eb601d 100644
--- a/crates/game-client/src/online.rs
+++ b/crates/game-client/src/online.rs
@@ -42,6 +42,7 @@ use crate::{
         MatchPhase, MatchView, RetaskProjection, ToastKind,
     },
     network::{ClientIntent, NetworkSet, ServerUpdate},
+    observe::{ObserveLevel, ObserveState, keys as observe_keys},
 };
 
 const TERRAIN_DIRTY: u32 = 1 << 0;
@@ -786,13 +787,14 @@ fn maintain_connection(
     time: Res<Time>,
     mut transport: ResMut<OnlineTransport>,
     mut view: ResMut<MatchView>,
+    mut observe: ResMut<ObserveState>,
 ) {
     if transport.connection.is_some() || transport.connection_disabled {
         return;
     }
     #[cfg(target_arch = "wasm32")]
     if transport.pending_connection.is_some() {
-        poll_pending_connection(&mut transport, &mut view);
+        poll_pending_connection(&mut transport, &mut view, &mut observe);
         return;
     }
     transport.reconnect_delay_seconds =
@@ -800,10 +802,14 @@ fn maintain_connection(
     if transport.reconnect_delay_seconds > 0.0 {
         return;
     }
-    connect_to_spacetimedb(&mut transport, &mut view);
+    connect_to_spacetimedb(&mut transport, &mut view, &mut observe);
 }
 
-fn connect_to_spacetimedb(transport: &mut OnlineTransport, view: &mut MatchView) {
+fn connect_to_spacetimedb(
+    transport: &mut OnlineTransport,
+    view: &mut MatchView,
+    observe: &mut ObserveState,
+) {
     let host = match transport
         .config
         .host
@@ -844,6 +850,20 @@ fn connect_to_spacetimedb(transport: &mut OnlineTransport, view: &mut MatchView)
     view.lobby.action_pending = false;
     view.lobby.local_player = None;
 
+    let attempt = transport.reconnect_attempt;
+    observe.emit(
+        ObserveLevel::Info,
+        if attempt == 0 {
+            observe_keys::NET_CONNECT_BEGIN
+        } else {
+            observe_keys::NET_RECONNECT
+        },
+        format!(
+            "gen={generation} attempt={attempt} host={} db={} profile={}",
+            transport.config.host, transport.config.database, transport.config.profile
+        ),
+    );
+
     let token = match load_token(&transport.config) {
         Ok(token) => token,
         Err(error) => {
@@ -927,6 +947,7 @@ fn connect_to_spacetimedb(transport: &mut OnlineTransport, view: &mut MatchView)
     finish_connection_setup(
         transport,
         view,
+        observe,
         connection.build().map_err(|error| error.to_string()),
     );
 
@@ -946,20 +967,25 @@ fn connect_to_spacetimedb(transport: &mut OnlineTransport, view: &mut MatchView)
 }
 
 #[cfg(target_arch = "wasm32")]
-fn poll_pending_connection(transport: &mut OnlineTransport, view: &mut MatchView) {
+fn poll_pending_connection(
+    transport: &mut OnlineTransport,
+    view: &mut MatchView,
+    observe: &mut ObserveState,
+) {
     let Some(pending) = transport.pending_connection.clone() else {
         return;
     };
     let result = pending.lock().ok().and_then(|mut slot| slot.take());
     if let Some(result) = result {
         transport.pending_connection = None;
-        finish_connection_setup(transport, view, result);
+        finish_connection_setup(transport, view, observe, result);
     }
 }
 
 fn finish_connection_setup(
     transport: &mut OnlineTransport,
     view: &mut MatchView,
+    observe: &mut ObserveState,
     result: Result<DbConnection, String>,
 ) {
     match result {
@@ -970,6 +996,14 @@ fn finish_connection_setup(
         }
         Err(error) => {
             transport.schedule_reconnect();
+            observe.emit(
+                ObserveLevel::Error,
+                observe_keys::NET_CONNECT_FAIL,
+                format!(
+                    "gen={} setup_failed reason={error} retry_s={:.1}",
+                    transport.active_generation, transport.reconnect_delay_seconds
+                ),
+            );
             view.push_log(format!(
                 "Connection setup failed: {error} · retrying in {:.1}s",
                 transport.reconnect_delay_seconds
@@ -1374,6 +1408,7 @@ fn send_online_intents(
     view: Res<MatchView>,
     mut transport: ResMut<OnlineTransport>,
     mut updates: MessageWriter<ServerUpdate>,
+    mut observe: ResMut<ObserveState>,
 ) {
     for intent in intents.read() {
         if !transport.subscription_lifecycle.commands_ready() || !transport.command_ids_ready {
@@ -1399,9 +1434,23 @@ fn send_online_intents(
         let result = invoke_intent(&transport, &view, command_id, intent);
         match result {
             Ok(kind) => {
+                observe.emit(
+                    ObserveLevel::Info,
+                    observe_keys::CMD_SUBMIT,
+                    format!(
+                        "command_id={command_id} kind={} step={}",
+                        kind.receipt_name(),
+                        view.logical_step
+                    ),
+                );
                 transport.pending.insert(command_id, kind);
             }
             Err(reason) => {
+                observe.emit(
+                    ObserveLevel::Warn,
+                    observe_keys::CMD_REJECT,
+                    format!("command_id={command_id} reason={reason}"),
+                );
                 transport.terminal_command_ids.insert(command_id);
                 updates.write(ServerUpdate::Rejected {
                     command_id: Some(command_id),
@@ -1759,10 +1808,17 @@ fn synchronize_authoritative_view(
     mut view: ResMut<MatchView>,
     mode: Res<MapViewMode>,
     mut updates: MessageWriter<ServerUpdate>,
+    mut observe: ResMut<ObserveState>,
 ) {
     let previous_local_player = view.local_player;
     for event in transport.signals.drain() {
-        apply_lifecycle_event(&mut transport, &mut view, &mut updates, event);
+        apply_lifecycle_event(
+            &mut transport,
+            &mut view,
+            &mut updates,
+            &mut observe,
+            event,
+        );
     }
 
     let dirty = transport.signals.take_dirty();
@@ -1776,6 +1832,17 @@ fn synchronize_authoritative_view(
         };
         AuthoritySnapshot::capture(connection, dirty, transport.signals.take_cell_changes())
     };
+    let cell_delta = snapshot.cells.as_ref().map_or(0, Vec::len);
+    observe.emit(
+        ObserveLevel::Debug,
+        observe_keys::SYNC_APPLY,
+        format!(
+            "gen={} dirty={dirty:#x} cells={cell_delta} absences={} step={}",
+            transport.active_generation,
+            cell_absences.len(),
+            view.logical_step
+        ),
+    );
     let tactical_changes = transport.signals.take_tactical_changes();
     let full_tactical_rebuild = snapshot.tactical.is_some();
     let mut projection_impact = ProjectionImpact::before(&transport.tactical, &tactical_changes);
@@ -1909,16 +1976,27 @@ fn apply_lifecycle_event(
     transport: &mut OnlineTransport,
     view: &mut MatchView,
     updates: &mut MessageWriter<ServerUpdate>,
+    observe: &mut ObserveState,
     event: LifecycleEvent,
 ) {
     match event {
         LifecycleEvent::Connected { generation } if lifecycle_is_current(transport, generation) => {
+            observe.emit(
+                ObserveLevel::Info,
+                observe_keys::NET_CONNECTED,
+                format!("gen={generation}"),
+            );
             view.authority = AuthorityState::Connecting;
             "Connected · subscribing to authoritative tables…".clone_into(&mut view.latest_result);
         }
         LifecycleEvent::BootstrapSubscribed { generation }
             if lifecycle_is_current(transport, generation) =>
         {
+            observe.emit(
+                ObserveLevel::Info,
+                observe_keys::NET_BOOTSTRAP,
+                format!("gen={generation} auto_join={}", transport.config.auto_join),
+            );
             transport.reconnect_attempt = 0;
             transport.reconnect_delay_seconds = 0.0;
             transport.subscription_lifecycle =
@@ -1936,6 +2014,16 @@ fn apply_lifecycle_event(
         LifecycleEvent::TacticalSubscribed { generation }
             if lifecycle_is_current(transport, generation) =>
         {
+            observe.emit(
+                ObserveLevel::Info,
+                observe_keys::NET_TACTICAL,
+                format!(
+                    "gen={generation} player={}",
+                    transport
+                        .bound_player
+                        .map_or_else(|| "-".to_owned(), |player| player.to_string())
+                ),
+            );
             transport.subscription_lifecycle =
                 transport.subscription_lifecycle.on_tactical_applied();
             if transport.bound_player.is_some() {
@@ -1947,6 +2035,11 @@ fn apply_lifecycle_event(
         LifecycleEvent::JoinFailed { generation, reason }
             if lifecycle_is_current(transport, generation) =>
         {
+            observe.emit(
+                ObserveLevel::Error,
+                observe_keys::NET_JOIN_FAIL,
+                format!("gen={generation} reason={reason}"),
+            );
             view.lobby.action_pending = false;
             mark_join_failed(transport, view, reason);
         }
@@ -1957,9 +2050,19 @@ fn apply_lifecycle_event(
         } if lifecycle_is_current(transport, generation) => {
             view.lobby.action_pending = false;
             if let Some(error) = error {
+                observe.emit(
+                    ObserveLevel::Warn,
+                    observe_keys::LOBBY_ACTION,
+                    format!("gen={generation} action={action} ok=0 reason={error}"),
+                );
                 view.push_log(format!("{action} failed: {error}"));
                 view.show_toast(format!("{action} failed: {error}"), ToastKind::Rejection);
             } else {
+                observe.emit(
+                    ObserveLevel::Info,
+                    observe_keys::LOBBY_ACTION,
+                    format!("gen={generation} action={action} ok=1"),
+                );
                 view.push_log(format!("{action} accepted"));
                 view.show_toast(format!("{action} accepted"), ToastKind::Success);
             }
@@ -1969,6 +2072,7 @@ fn apply_lifecycle_event(
                 transport,
                 view,
                 updates,
+                observe,
                 generation,
                 format!("Connection failed: {reason}"),
             );
@@ -1978,6 +2082,7 @@ fn apply_lifecycle_event(
                 transport,
                 view,
                 updates,
+                observe,
                 generation,
                 format!("Disconnected: {reason}"),
             );
@@ -1986,6 +2091,11 @@ fn apply_lifecycle_event(
             if transport.terminal_command_ids.insert(command_id) {
                 let pending = transport.pending.remove(&command_id);
                 if pending.is_some() {
+                    observe.emit(
+                        ObserveLevel::Warn,
+                        observe_keys::CMD_FAIL,
+                        format!("command_id={command_id} reason={reason}"),
+                    );
                     updates.write(ServerUpdate::Rejected {
                         command_id: Some(command_id),
                         reason,
@@ -1997,7 +2107,14 @@ fn apply_lifecycle_event(
         LifecycleEvent::TokenWarning {
             generation,
             message,
-        } if generation == transport.active_generation => view.push_log(message),
+        } if generation == transport.active_generation => {
+            observe.emit(
+                ObserveLevel::Warn,
+                observe_keys::TOKEN_WARN,
+                format!("gen={generation} {message}"),
+            );
+            view.push_log(message);
+        }
         LifecycleEvent::Connected { .. }
         | LifecycleEvent::BootstrapSubscribed { .. }
         | LifecycleEvent::TacticalSubscribed { .. }
@@ -2035,6 +2152,7 @@ fn handle_connection_loss(
     transport: &mut OnlineTransport,
     view: &mut MatchView,
     updates: &mut MessageWriter<ServerUpdate>,
+    observe: &mut ObserveState,
     generation: u64,
     reason: String,
 ) {
@@ -2073,6 +2191,14 @@ fn handle_connection_loss(
     }
 
     transport.schedule_reconnect();
+    observe.emit(
+        ObserveLevel::Warn,
+        observe_keys::NET_DISCONNECT,
+        format!(
+            "gen={generation} reason={reason} retry_s={:.1} attempt={}",
+            transport.reconnect_delay_seconds, transport.reconnect_attempt
+        ),
+    );
     view.connection = vec![ConnectionState::Syncing; usize::from(view.player_count)];
     view.latest_result = format!(
         "Connection lost · retrying in {:.1}s",
diff --git a/crates/game-client/src/performance.rs b/crates/game-client/src/performance.rs
index 0c31df3..1826f3b 100644
--- a/crates/game-client/src/performance.rs
+++ b/crates/game-client/src/performance.rs
@@ -111,11 +111,9 @@ fn update_performance_overlay(
     mut state: ResMut<PerformanceOverlayState>,
     text: Single<&mut Text, With<PerformanceText>>,
 ) {
-    if !state.visible {
-        return;
-    }
-
     let refresh_due = state.refresh.tick(time.delta()).just_finished();
+    // Always sample on the cadence so wasm automation can read `window.__ofPerf`
+    // without requiring the F3 panel to be open.
     if !state.refresh_now && !refresh_due {
         return;
     }
@@ -127,13 +125,29 @@ fn update_performance_overlay(
         .get(&EntityCountDiagnosticsPlugin::ENTITY_COUNT)
         .and_then(bevy::diagnostic::Diagnostic::value)
         .unwrap_or(0.0);
+    let chunk_count = chunks.iter().count();
+    #[cfg(target_arch = "wasm32")]
+    publish_browser_perf(
+        fps,
+        frame_time,
+        entities,
+        chunk_count,
+        map_view.visible_chunks,
+        view.cells.len(),
+        view.dirty_chunks.len(),
+    );
+
+    if !state.visible {
+        return;
+    }
+
     let mut text = text.into_inner();
     let value = format!(
         "PERFORMANCE  //  F3\nFPS {:>6}  ·  FRAME {:>7}\nENTITIES {:>6.0}  ·  CHUNKS {:>4} / {:>4} VISIBLE\nCELLS {:>9}  ·  LABELS {:>4}  ·  DIRTY {:>5}\nORDERS {:>8}  ·  FLOWS {:>5}  ·  FRONTS {:>4}",
         format_metric(fps, 1, ""),
         format_metric(frame_time, 2, " ms"),
         entities,
-        chunks.iter().count(),
+        chunk_count,
         map_view.visible_chunks,
         view.cells.len(),
         map_view.active_labels,
@@ -147,6 +161,44 @@ fn update_performance_overlay(
     }
 }
 
+/// Exposes smoothed F3 diagnostics for browser gate automation (`Runtime.evaluate`).
+#[cfg(target_arch = "wasm32")]
+fn publish_browser_perf(
+    fps: Option<f64>,
+    frame_ms: Option<f64>,
+    entities: f64,
+    chunks: usize,
+    visible_chunks: usize,
+    cells: usize,
+    dirty: usize,
+) {
+    use js_sys::{Date, Object, Reflect};
+    use wasm_bindgen::JsValue;
+
+    let Some(window) = web_sys::window() else {
+        return;
+    };
+    let perf = Object::new();
+    let set = |key: &str, value: JsValue| {
+        let _ = Reflect::set(&perf, &JsValue::from_str(key), &value);
+    };
+    match fps {
+        Some(value) => set("fps", JsValue::from_f64(value)),
+        None => set("fps", JsValue::NULL),
+    }
+    match frame_ms {
+        Some(value) => set("frame_ms", JsValue::from_f64(value)),
+        None => set("frame_ms", JsValue::NULL),
+    }
+    set("entities", JsValue::from_f64(entities));
+    set("chunks", JsValue::from_f64(chunks as f64));
+    set("visible_chunks", JsValue::from_f64(visible_chunks as f64));
+    set("cells", JsValue::from_f64(cells as f64));
+    set("dirty", JsValue::from_f64(dirty as f64));
+    set("updated_at_ms", JsValue::from_f64(Date::now()));
+    let _ = Reflect::set(&window, &JsValue::from_str("__ofPerf"), &perf);
+}
+
 fn diagnostic_smoothed(
     diagnostics: &DiagnosticsStore,
     path: &bevy::diagnostic::DiagnosticPath,
diff --git a/docs/README.md b/docs/README.md
index 8d662fd..9e5ca54 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,12 @@ current interaction or simulation contract.
 - [Graybox UI brief](./v1-ui-brief.md) — concise requirements for visual and
   interaction exploration within the canonical control contract.
 - [Future ideas](./future-ideas.md) — explicitly deferred mechanics and research topics that should not be forgotten or treated as V1 commitments.
+- [Browser release gates](./browser-gates.md) — Wasm download budgets, WebGPU
+  128/192 frame-cost procedure, and reconnect soak status.
+- [Observability](./observability.md) — structured client/module events (F4,
+  `OF_OBSERVE`, SpacetimeDB `event=` logs).
+- [Performance profiling](./performance.md) — distributed `match-perf` harness
+  and step-dilation measurement.
 
 ## Document status
 
diff --git a/docs/browser-gates.md b/docs/browser-gates.md
new file mode 100644
index 0000000..3c93513
--- /dev/null
+++ b/docs/browser-gates.md
@@ -0,0 +1,218 @@
+# Browser release gates
+
+Status: Wasm size + isolated reconnect + WebGPU 128/192 frame cost measured  
+Last updated: 2026-08-07
+
+Architecture commits a Bevy WebAssembly/WebGPU client, but treats representative
+browser graphics, reconnect, download size, and map performance as **required
+before production release**. This document turns that into concrete budgets,
+scripts, and a status ledger.
+
+Related:
+
+- [Technical architecture](./technical-architecture.md) — delivery commitments and load targets
+- [Performance profiling](./performance.md) — native/headless `match-perf` harness
+- [Implementation guide](./implementation.md) — current evidence and known limits
+- [Observability](./observability.md) — F3 / F4 / `window.__ofPerf` / `of.observe`
+
+## Gate summary
+
+| Gate | Budget (provisional) | How to measure | Status (2026-08-07) |
+| --- | --- | --- | --- |
+| Wasm / web download size | ≤ **14 MiB** total gzip-9 transfer; ≤ **50 MiB** largest `.wasm` raw | `./scripts/measure-web-bundle.sh` | **Measured — PASS** (see baseline below) |
+| WebGPU frame cost @ 128×128 | Sustained **≥ 55 FPS** / frame **≤ 18 ms** during ordinary pan/zoom (F3 overlay) | Browser procedure below | **Measured — PASS** (p50 59.9 FPS / 16.7 ms) |
+| WebGPU frame cost @ 192×192 | Same as 128, plus no sustained stall when large subscription batches apply | Browser procedure below | **Measured — PASS** (p50 60.2 FPS / 16.6 ms) |
+| Reconnect under load | Token reclaim succeeds; disconnect→reclaim p95 **≤ 5 s** over ≥ 20 cycles while the match is running | `./scripts/run-reconnect-soak.sh` (native SDK path) + browser smoke | **Isolated soak measured — PASS**; concurrent-load still open; browser reload smoke recorded |
+| Browser compile | `cargo clippy -p game-client --target wasm32-unknown-unknown -D warnings` | CI already | **PASS** (CI) |
+
+Budgets are engineering gates, not marketing claims. Revisit them if Bevy/WebGPU
+stack upgrades move the cost curve.
+
+## Measured web-bundle baseline
+
+Recorded from the existing Trunk `wasm-release` dist at `target/web` (git
+`608ce3a`, dirty tree ignored by the script at measurement time):
+
+| Artifact | Raw | gzip-9 |
+| --- | ---: | ---: |
+| `*_bg.wasm` | 43,371,133 (~41.36 MiB) | 11,932,611 (~11.38 MiB) |
+| `*.js` | 169,487 | 24,666 |
+| `index.html` | 2,020 | 1,012 |
+| **Total** | **43,542,640** | **11,958,289 (~11.41 MiB)** |
+
+Gate result vs defaults: **PASS** (gzip 11.41 / 14 MiB; raw wasm 41.36 / 50 MiB).
+
+Re-measure after any Bevy/feature change:
+
+```bash
+./scripts/measure-web-bundle.sh --build --enforce
+```
+
+Reports land under `artifacts/browser/bundle-*.json` (gitignored). Production
+deploy runs the same measurement with `--enforce` after Trunk build.
+
+Override budgets when intentionally moving the ceiling:
+
+```bash
+OF_WEB_GZIP_BUDGET_BYTES=16777216 OF_WEB_RAW_WASM_BUDGET_BYTES=67108864 \
+  ./scripts/measure-web-bundle.sh --enforce
+```
+
+## WebGPU frame cost @ 128 / 192
+
+### Measured baselines (2026-08-07)
+
+Qualified on **Chrome for Testing 149.0.7827.55** (headed, CDP attach,
+`--use-angle=metal`), **Apple M4 Pro**, git `608ce3a` (+ local uncommitted
+observe/`__ofPerf` bridge). Database: local `of-match-browser-gate` (fresh
+publish; `of-match-dev` was owned by another identity on this machine).
+
+Samples: ~60 s ordinary WASD pan/zoom after match start; gate uses smoothed
+F3 / `window.__ofPerf` **p50** FPS and frame ms.
+
+| Preset | Cells | p50 FPS | p50 frame ms | p5 FPS | p95 frame ms | Result | Artifact |
+| --- | ---: | ---: | ---: | ---: | ---: | --- | --- |
+| `playtest128` | 16 384 | **59.9** | **16.7** | 58.5 | 17.1 | **PASS** | `artifacts/browser/webgpu-frame-playtest128-2026-08-07T1749Z.json` |
+| `validation192` | 36 864 | **60.2** | **16.6** | 57.5 | 17.4 | **PASS** | `artifacts/browser/webgpu-frame-validation192-2026-08-07T1752Z.json` |
+
+F3 screenshots: `artifacts/browser/webgpu-playtest128-f3.png`,
+`webgpu-validation192-f3.png`. Brief load spikes at connect (observe
+`perf.frame_spike`) are excluded from the sustained window. The 192 run saw
+seat-claim races when leftover tabs/tokens contended; the map still streamed
+fully (36 864 cells) and frame cost stayed in budget.
+
+### Procedure
+
+1. Start SpacetimeDB and publish a fresh match you **own**:
+   `./scripts/start-local-server.sh`
+   `spacetime publish --server local --module-path modules/match --delete-data=always --yes of-match-browser-gate`
+   (or `./scripts/publish-local.sh --fresh --confirm-delete-of-match-dev` when you
+   own `of-match-dev`)
+2. Configure the preset and two seats (`--no-config` if `spacetime.local.json`
+   pins another database name):
+   - 128: `spacetime call --server local --no-config of-match-browser-gate configure_match '{"playtest128":{}}' 2`
+   - 192: `spacetime call --server local --no-config of-match-browser-gate configure_match '{"validation192":{}}' 2`
+3. Serve the web client: `./scripts/run-web-client.sh`
+4. Open a **WebGPU-capable headed Chrome** (Playwright’s default
+   `chromium.launch` often exposes `navigator.gpu === undefined`; attach via CDP
+   to Chrome for Testing with `--remote-debugging-port=9222 --use-angle=metal`):
+   `http://127.0.0.1:8080/?player=1&name=P1&profile=browser-p1&observe=1&database=of-match-browser-gate`
+   and a second profile for player 2. With `?player=N` the client auto-joins and
+   auto-starts once both seats are claimed.
+5. Press **F3** for the performance overlay (FPS, frame ms, chunks, dirty cells)
+   and **F4** for the structured event ring. On wasm, smoothed metrics also
+   publish to `window.__ofPerf` every ~250 ms for automation. Filter DevTools
+   for `of.observe`. See [Observability](./observability.md).
+6. Sample for ≥ 60 s of ordinary camera motion at default zoom, then after a
+   burst of expansion/attack updates. Record smoothed FPS / frame ms, map
+   preset, browser, GPU, and git HEAD into
+   `artifacts/browser/webgpu-frame-<preset>-<timestamp>.json` using the template:
+
+```json
+{
+  "kind": "webgpu-frame-sample",
+  "preset": "playtest128",
+  "browser": "Chrome 139",
+  "gpu": "Apple M4 Pro",
+  "git_head": "REPLACE",
+  "ordinary_pan_zoom": { "fps": 0, "frame_ms": 0 },
+  "after_subscription_burst": { "fps": 0, "frame_ms": 0, "notes": "" },
+  "passed": false
+}
+```
+
+### Native proxy (not a substitute)
+
+`scripts/run-match-perf-matrix.sh --viewer` attaches a **native** Bevy client to
+player 1 during headless load. Use it to debug mesh/subscription cost, but do
+not mark the browser WebGPU gate PASS from native FPS alone.
+
+The offline fixture (`?offline=1`) is a small radius map, **not** the 128/192
+presets — useful for WebGPU bring-up only.
+
+## Reconnect under load
+
+### What already exists
+
+- `match-e2e` proves a single token reclaim after the gameplay smoke.
+- The client stores browser tokens in `localStorage` scoped by host/database/profile
+  and rebuilds from a fresh subscription on reconnect.
+
+### Harness added here
+
+```bash
+# Isolated native soak (publishes of-match-reconnect-soak, joins, starts, cycles)
+./scripts/run-reconnect-soak.sh --fresh --cycles 20
+
+# Against an in-flight match-perf database (same match, concurrent workers)
+# while match-perf run-local is active and tokens exist:
+./scripts/run-reconnect-soak.sh \
+  --database of-match-perf \
+  --cycles 30 \
+  --out artifacts/browser/reconnect-under-load.json
+# Point match-e2e at the worker seats explicitly when needed:
+#   cargo run -p match-e2e -- --reconnect-only --reconnect-cycles 30 \
+#     --database of-match-perf \
+#     --player-one-token .match-perf-tokens/player-1.token \
+#     --player-two-token .match-perf-tokens/player-2.token \
+#     --reconnect-report artifacts/browser/reconnect-under-load.json
+```
+
+`match-e2e` flags: `--reconnect-only`, `--reconnect-cycles N`,
+`--reconnect-report PATH`, optional `--player-one-token` /
+`--player-two-token` (point at `.match-perf-tokens/player-1.token` and
+`player-2.token` for true same-match under-load soaks).
+
+### Measured isolated baseline (2026-08-07)
+
+`./scripts/run-reconnect-soak.sh --fresh --cycles 5` on local SpacetimeDB
+2.7.1 (default 64×64 / 2 seats, no concurrent workers):
+
+| Metric | Value |
+| --- | ---: |
+| cycles | 5 |
+| p50 disconnect→reclaim | 71 ms |
+| p95 | 71 ms |
+| max | 86 ms |
+| budget | p95 ≤ 5000 ms |
+
+Gate result for the **isolated** path: **PASS**. Concurrent `match-perf`
+under-load remains open.
+
+Provisional budget: disconnect→reclaim **p95 ≤ 5000 ms** over the soak report.
+
+### Browser reload smoke
+
+Recorded `artifacts/browser/browser-reconnect-smoke-20260807.json` on the
+running 192 match: page reload restored `net.connected` / bootstrap and
+`cells=36864` with ~60 FPS. In that session leftover CDP tabs still held both
+seats, so `join_match` returned “all player slots are already claimed” rather
+than a clean token reclaim — treat this as **map rebuild after reload**
+evidence, not a full seat-reclaim proof. Concurrent `match-perf` under-load
+soak remains open.
+
+### Still required for full browser qualification
+
+1. Run the native soak under concurrent `match-perf` workers and file the JSON.
+2. Optional later: the architecture’s 30-minute soak with scheduler recovery.
+
+## CI / deploy hooks
+
+| Pipeline | Browser-related check |
+| --- | --- |
+| `.github/workflows/ci.yml` | Wasm **compile/lint** only (no Trunk artifact, no size gate) |
+| `.github/workflows/deploy.yml` | Trunk production build, then `measure-web-bundle.sh --enforce` |
+| Local | `measure-web-bundle.sh`, `run-reconnect-soak.sh`, manual/CDP WebGPU procedure |
+
+## Qualification checklist
+
+- [x] Document budgets and unqualified items
+- [x] Scripted Wasm download measurement + enforceable budget
+- [x] Deploy-time size gate
+- [x] Reconnect soak harness (native SDK)
+- [x] Record isolated reconnect soak JSON (5-cycle PASS; extend to 20+ at will)
+- [x] Record WebGPU 128 sample (PASS JSON)
+- [x] Record WebGPU 192 sample (PASS JSON)
+- [ ] Record reconnect soak JSON under concurrent `match-perf` load
+- [x] Manual browser reconnect smoke on the live path (reload restored map; seat reclaim still contested when other tabs hold slots)
+- [ ] Flip architecture/implementation wording from “unqualified” to measured status when under-load reconnect evidence also lands
diff --git a/docs/future-ideas.md b/docs/future-ideas.md
index ee93b80..763bf63 100644
--- a/docs/future-ideas.md
+++ b/docs/future-ideas.md
@@ -184,7 +184,7 @@ representative wide fronts.
 
 ## Browser target
 
-A browser build remains a desirable later target while native desktop is the V1 focus. Core simulation and data formats should avoid unnecessary platform coupling, but browser-specific compromises should not constrain the first implementation before its mechanics are proven.
+A browser build remains a desirable later target while native desktop is the V1 focus. Core simulation and data formats should avoid unnecessary platform coupling, but browser-specific compromises should not constrain the first implementation before its mechanics are proven. Concrete download, WebGPU frame-cost, and reconnect budgets now live in [Browser release gates](./browser-gates.md).
 
 **Depends on:** Bevy target compatibility at the chosen pinned version, graphics/shader portability, asset size and loading, memory limits, input differences, networking behavior, and profiling representative maps on actual browsers.
 
diff --git a/docs/implementation.md b/docs/implementation.md
index cf5f001..3dee88d 100644
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -300,17 +300,21 @@ selection-adjacent presentation from the new authoritative snapshot.
   metadata/duplicates, and sweeps supported custom seeds.
 - The real-server two-identity harness covers slot claims, match start,
   subscriptions, idempotent receipts, public cluster actions,
-  conserved movement, cancellation, and reconnect.
+  conserved movement, cancellation, and reconnect. Optional
+  `--reconnect-only` / `--reconnect-cycles` soaks record reclaim latency;
+  see [Browser release gates](./browser-gates.md).
 - The distributed `match-perf` harness (`coordinator` / `worker` / `run-local`)
   profiles client-observed step dilation under multi-process load through 500
   seats; see [Performance profiling](./performance.md).
 - CI repeats formatting, workspace tests/lints, module tests/lints/build, and
-  generated-binding drift detection.
+  generated-binding drift detection. Production deploy enforces the web-bundle
+  size gate after Trunk build.
 
 ## Known V1 limits
 
 - Infantry is the only force composition serialized by the module.
-- The second join auto-starts the match; there is no lobby UI or ready toggle.
+- Lobby create/join/start is implemented; empty lobbies can be cleaned up by
+  leave/auto-delete flows. Match configuration remains one-shot per database.
 - Expansion topology is deterministic from the accepted state. The focus changes
   branch allocation but is not a continuously replanned destination.
 - Attack snapshots complete enemy target clusters at acceptance. Fronts evolve
@@ -335,7 +339,9 @@ selection-adjacent presentation from the new authoritative snapshot.
   ongoing economic burden.
 - Native desktop and WebAssembly/WebGPU compile targets are supported. The web
   target uses `localStorage` credentials and asynchronous browser networking;
-  representative browser performance is not yet qualified for production.
+  representative browser performance is not yet qualified for production. See
+  [Browser release gates](./browser-gates.md) for budgets, the Wasm size
+  baseline, and the remaining WebGPU / reconnect evidence checklist.
 
 These are bounded omissions, not hidden placeholders. Candidate extensions and
 their dependencies are recorded in [future ideas](./future-ideas.md).
diff --git a/docs/observability.md b/docs/observability.md
new file mode 100644
index 0000000..8cde3c8
--- /dev/null
+++ b/docs/observability.md
@@ -0,0 +1,106 @@
+# Observability
+
+Status: focused structured events for client + module debugging  
+Last updated: 2026-08-07
+
+This is a thin instrumentation layer for reconnect, lobby/provision, command
+paths, subscription sync, and frame spikes — not a full telemetry platform.
+
+Related: [Browser release gates](./browser-gates.md), [Performance](./performance.md).
+
+## What already existed
+
+| Surface | What it gives you |
+| --- | --- |
+| **F3** performance overlay | FPS, frame ms, entities, chunks, cells, orders/flows/fronts |
+| HUD order log / toasts | Last few command results (human-readable, not greppable) |
+| Match `LogStopwatch` | Per-tick phase timings in SpacetimeDB logs (`simulation_*`) |
+| `match-perf` | Distributed step-dilation CSV/JSONL under load |
+| Reconnect soak / e2e | Pass/fail harnesses, not live event streams |
+
+## What this adds
+
+### Client (`of.observe`)
+
+Stable `category.action` keys, an in-memory ring (last 64), optional console
+emission, and an **F4** overlay.
+
+| Key | When |
+| --- | --- |
+| `net.connect_begin` / `net.reconnect` | Connection attempt starts |
+| `net.connected` | SDK connect callback |
+| `net.bootstrap` / `net.tactical` | Subscription applied |
+| `net.disconnect` / `net.connect_fail` / `net.join_fail` | Loss / setup / seat failure |
+| `lobby.action` | Create / join / start reducer outcome |
+| `cmd.submit` / `cmd.accept` / `cmd.reject` / `cmd.fail` | Control path |
+| `sync.apply` | Authoritative dirty batch applied (debug level) |
+| `perf.frame_spike` | Frame time ≥ 33 ms (rate-limited) |
+| `auth.token_warn` | Token persist failure |
+
+### Module logs (`target: "of"`)
+
+Published match/lobby modules emit the same style of `event=…` lines into
+SpacetimeDB logs:
+
+| Event | Module |
+| --- | --- |
+| `match.join` (`mode=claim\|reconnect`) | match |
+| `match.start` / `match.connected` / `match.disconnected` | match |
+| `cmd.accept` / `cmd.reject` | match (`write_receipt`) |
+| `sim.heartbeat` | match (every 40 logical steps) |
+| `lobby.create` / `join` / `leave` | lobby |
+| `lobby.provision_begin` / `complete` / `fail` | lobby |
+
+Phase stopwatches remain available as before.
+
+## How to enable / read
+
+### Native client
+
+```bash
+OF_OBSERVE=1 cargo run -p game-client -- --player 1 --name "P1"
+# or: cargo run -p game-client -- --observe --player 1
+```
+
+Console lines look like:
+
+```text
+[of.observe] INFO net.bootstrap gen=1 auto_join=true
+```
+
+Press **F4** for the on-screen ring (works even when console emit is off).
+**F3** remains the performance panel.
+
+### Browser client
+
+Open with `?observe=1`, e.g.:
+
+```text
+http://127.0.0.1:8080/?player=1&name=P1&profile=browser-p1&observe=1
+```
+
+Filter DevTools console for `of.observe`. Use F3 + F4 together during WebGPU
+frame-cost qualification.
+
+On wasm, the F3 sampler also mirrors smoothed FPS / frame ms into
+`window.__ofPerf` (~250 ms cadence) so CDP/`Runtime.evaluate` automation can
+record gate samples without OCR. Do not use `std::time::Instant` in
+wasm-shared client code — it panics with `time not implemented on this
+platform`; prefer Bevy `Time`.
+
+### SpacetimeDB module logs
+
+```bash
+spacetime logs --server local of-match-dev
+spacetime logs --server local of-lobby-dev   # name may differ in your deploy
+```
+
+Filter for `event=` / `target=of`. Republish modules after pulling these changes
+so server-side events appear.
+
+## Suggested follow-ups
+
+1. Optional JSONL dump of the client ring to `artifacts/observe/` for soak runs.
+2. Correlate client `command_id` with module `cmd.accept` in reconnect soak reports.
+3. Bevy system timings / render pass marks once WebGPU frame gates need deeper drill-down.
+4. Quiet `sim.heartbeat` / `cmd.accept` behind a module log level when noise hurts fuel.
diff --git a/docs/performance.md b/docs/performance.md
index b5e8808..dbf1c4a 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -284,5 +284,6 @@ active transfer order IDs (queued sources on active orders with no packet yet).
 ## Related docs
 
 - [Technical architecture](./technical-architecture.md) — subscriptions, cadence, scale bands
+- [Browser release gates](./browser-gates.md) — Wasm download, WebGPU 128/192, reconnect soak
 - [Implementation guide](./implementation.md) — authority and table layout
 - [README](../README.md) — toolchain and local multiplayer quick start
diff --git a/docs/technical-architecture.md b/docs/technical-architecture.md
index 374c3f9..0aff8ee 100644
--- a/docs/technical-architecture.md
+++ b/docs/technical-architecture.md
@@ -49,6 +49,8 @@ Connection setup is asynchronous and identity tokens are stored in browser
 filesystem-backed credential adapter. Browser compile coverage is part of the
 compatibility gate; representative browser graphics, reconnect, download-size,
 and map-performance measurements remain required before production release.
+Track budgets, scripts, and measured status in
+[Browser release gates](./browser-gates.md).
 
 Upgrade Bevy or SpacetimeDB intentionally on a dedicated branch, regenerate
 bindings, run migrations if required, and repeat native, web-compile,
@@ -497,7 +499,7 @@ selection and target outlines inspect visible render chunks, and hidden chunks
 converge under budgets. Authoritative scheduled work remains active-order and
 active-front driven. Native-only credentials, windowing, and startup behavior
 stay behind narrow adapters; browser delivery remains a later qualification
-gate.
+gate tracked in [Browser release gates](./browser-gates.md).
 
 ## Reconnect and recovery
 
@@ -632,7 +634,7 @@ The following questions stay open until profiling or playtesting supplies eviden
   aggregated with `EXPANSION_AGGREGATE_ORIGIN`.
 - Static map delivery through database rows versus content-addressed baked assets with hash verification.
 - Region-level summaries and level of detail for maps intended to represent a whole world.
-- Browser delivery, WebGPU/WebGL compatibility, download size, threading limits, and browser-specific SpacetimeDB behavior. WASM portability is retained, but web release work follows native V1.
+- Browser delivery, WebGPU/WebGL compatibility, download size, threading limits, and browser-specific SpacetimeDB behavior. WASM portability is retained, but web release work follows native V1. Concrete download, frame-cost, and reconnect budgets live in [Browser release gates](./browser-gates.md) until those measurements close.
 - Roads, cities, bridges, destructible infrastructure, additional recruitment structures and policies, fog of war, diplomacy, naval/air movement, and mutable terrain.
 - Multi-hex armored formations and deliberate spatial blocking. These remain separate from scalar infantry flow and must be prototyped after V1.
 - AI opponents, teams, spectators, matchmaking, and long-term persistence beyond match results.
diff --git a/modules/lobby/Cargo.lock b/modules/lobby/Cargo.lock
index 05e9bd0..5e480a0 100644
--- a/modules/lobby/Cargo.lock
+++ b/modules/lobby/Cargo.lock
@@ -339,6 +339,7 @@ checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 name = "lobby-module"
 version = "0.1.0"
 dependencies = [
+ "log",
  "spacetimedb",
 ]
 
diff --git a/modules/lobby/Cargo.toml b/modules/lobby/Cargo.toml
index a983350..67da73c 100644
--- a/modules/lobby/Cargo.toml
+++ b/modules/lobby/Cargo.toml
@@ -8,6 +8,7 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
+log = "0.4"
 spacetimedb = "=2.7.1"
 
 [lints.rust]
diff --git a/modules/lobby/src/lib.rs b/modules/lobby/src/lib.rs
index 22a8534..c7b6a7b 100644
--- a/modules/lobby/src/lib.rs
+++ b/modules/lobby/src/lib.rs
@@ -222,11 +222,15 @@ pub fn create_lobby(
     });
     ctx.db.lobby_member().insert(LobbyMember {
         member_key: member_key(&lobby_id, ctx.sender()),
-        lobby_id,
+        lobby_id: lobby_id.clone(),
         identity: ctx.sender(),
         display_name,
         joined_at_us: now,
     });
+    log::info!(
+        target: "of",
+        "event=lobby.create lobby_id={lobby_id} players={player_count} preset={map_preset:?}"
+    );
     Ok(())
 }
 
@@ -261,7 +265,7 @@ pub fn join_lobby(
     let now = timestamp_us(ctx);
     ctx.db.lobby_member().insert(LobbyMember {
         member_key: member_key(&lobby_id, ctx.sender()),
-        lobby_id,
+        lobby_id: lobby_id.clone(),
         identity: ctx.sender(),
         display_name,
         joined_at_us: now,
@@ -271,7 +275,13 @@ pub fn join_lobby(
     if lobby.member_count == lobby.player_count {
         lobby.status = LobbyStatus::Full;
     }
+    let member_count = lobby.member_count;
+    let status = lobby.status;
     ctx.db.lobby().lobby_id().update(lobby);
+    log::info!(
+        target: "of",
+        "event=lobby.join lobby_id={lobby_id} members={member_count} status={status:?}"
+    );
     Ok(())
 }
 
@@ -296,6 +306,10 @@ pub fn leave_lobby(ctx: &ReducerContext, lobby_id: String) -> Result<(), String>
             // lobby — so drop the row instead of leaving an orphan that blocks
             // create_lobby via active membership.
             delete_lobby_and_members(ctx, &lobby_id);
+            log::info!(
+                target: "of",
+                "event=lobby.leave lobby_id={lobby_id} outcome=deleted"
+            );
             Ok(())
         }
         Ok(status) => {
@@ -303,6 +317,10 @@ pub fn leave_lobby(ctx: &ReducerContext, lobby_id: String) -> Result<(), String>
             lobby.status = status;
             lobby.updated_at_us = timestamp_us(ctx);
             ctx.db.lobby().lobby_id().update(lobby);
+            log::info!(
+                target: "of",
+                "event=lobby.leave lobby_id={lobby_id} members={member_count} status={status:?}"
+            );
             Ok(())
         }
     }
@@ -326,6 +344,10 @@ pub fn begin_provision(ctx: &ReducerContext, lobby_id: String) -> Result<(), Str
     lobby.status = LobbyStatus::Provisioning;
     lobby.updated_at_us = timestamp_us(ctx);
     ctx.db.lobby().lobby_id().update(lobby);
+    log::info!(
+        target: "of",
+        "event=lobby.provision_begin lobby_id={lobby_id}"
+    );
     Ok(())
 }
 
@@ -357,6 +379,11 @@ pub fn complete_provision(
     lobby.match_database = match_database;
     lobby.failure_reason.clear();
     lobby.updated_at_us = timestamp_us(ctx);
+    log::info!(
+        target: "of",
+        "event=lobby.provision_complete lobby_id={lobby_id} match_database={}",
+        lobby.match_database
+    );
     ctx.db.lobby().lobby_id().update(lobby);
     Ok(())
 }
@@ -383,6 +410,11 @@ pub fn fail_provision(
     lobby.status = LobbyStatus::Failed;
     lobby.failure_reason = reason.trim().chars().take(160).collect();
     lobby.updated_at_us = timestamp_us(ctx);
+    log::warn!(
+        target: "of",
+        "event=lobby.provision_fail lobby_id={lobby_id} reason={}",
+        lobby.failure_reason
+    );
     ctx.db.lobby().lobby_id().update(lobby);
     Ok(())
 }
diff --git a/modules/match/Cargo.lock b/modules/match/Cargo.lock
index 47c12ef..b124491 100644
--- a/modules/match/Cargo.lock
+++ b/modules/match/Cargo.lock
@@ -353,6 +353,7 @@ name = "match-module"
 version = "0.1.0"
 dependencies = [
  "hex-core",
+ "log",
  "spacetimedb",
  "worldgen",
 ]
diff --git a/modules/match/Cargo.toml b/modules/match/Cargo.toml
index 12637a3..8295c8c 100644
--- a/modules/match/Cargo.toml
+++ b/modules/match/Cargo.toml
@@ -9,6 +9,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 hex-core = { path = "../../crates/hex-core" }
+log = "0.4"
 spacetimedb = "=2.7.1"
 worldgen = { path = "../../crates/worldgen" }
 
diff --git a/modules/match/src/lib.rs b/modules/match/src/lib.rs
index 24abbc6..8985c39 100644
--- a/modules/match/src/lib.rs
+++ b/modules/match/src/lib.rs
@@ -393,6 +393,7 @@ pub fn join_match(
             return Err("player slot is already claimed by another identity".into());
         }
         apply_reconnect_to_slot(&mut existing, sender, now, &display_name);
+        let reconnect_count = existing.reconnect_count;
         ctx.db.player_slot().player_id().update(existing);
         if recovered.needs_index_repair {
             bind_identity(ctx, sender, recovered.player_id)?;
@@ -400,6 +401,12 @@ pub fn join_match(
         // Recovered seats (including index repair) must still reconcile the
         // verified claim count so a repaired final seat can start the lobby.
         reconcile_claimed_players(ctx)?;
+        log::info!(
+            target: "of",
+            "event=match.join mode=reconnect player_id={} reconnect_count={reconnect_count} repair={}",
+            recovered.player_id,
+            u8::from(recovered.needs_index_repair)
+        );
         return Ok(());
     }
 
@@ -447,6 +454,10 @@ pub fn join_match(
     ctx.db.player_slot().player_id().update(slot);
     bind_identity(ctx, sender, player_id)?;
     reconcile_claimed_players(ctx)?;
+    log::info!(
+        target: "of",
+        "event=match.join mode=claim player_id={player_id} preferred={preferred_player_id}"
+    );
     Ok(())
 }
 
@@ -474,7 +485,12 @@ pub fn start_match(ctx: &ReducerContext) -> Result<(), String> {
     state.phase = MatchPhase::Running;
     state.started_at_us = timestamp_us(ctx);
     ctx.db.match_state().singleton_id().update(state);
-    ensure_simulation_schedule(ctx)
+    ensure_simulation_schedule(ctx)?;
+    log::info!(
+        target: "of",
+        "event=match.start players={player_count} claimed={verified}"
+    );
+    Ok(())
 }
 
 fn validate_match_start(
@@ -504,13 +520,21 @@ pub fn identity_connected(ctx: &ReducerContext) {
         return;
     };
     if let Some(mut slot) = ctx.db.player_slot().player_id().find(player_id) {
+        let was_connected = slot.connected;
         if !slot.connected {
             slot.has_reconnected = true;
             slot.reconnect_count = slot.reconnect_count.saturating_add(1);
         }
         slot.connected = true;
         slot.last_seen_at_us = timestamp_us(ctx);
+        let reconnect_count = slot.reconnect_count;
         ctx.db.player_slot().player_id().update(slot);
+        if !was_connected {
+            log::info!(
+                target: "of",
+                "event=match.connected player_id={player_id} reconnect_count={reconnect_count}"
+            );
+        }
     }
 }
 
@@ -524,6 +548,10 @@ pub fn identity_disconnected(ctx: &ReducerContext) {
         slot.connected = false;
         slot.last_seen_at_us = timestamp_us(ctx);
         ctx.db.player_slot().player_id().update(slot);
+        log::info!(
+            target: "of",
+            "event=match.disconnected player_id={player_id}"
+        );
     }
 }
 
diff --git a/modules/match/src/rules.rs b/modules/match/src/rules.rs
index ea8c4e8..be39f72 100644
--- a/modules/match/src/rules.rs
+++ b/modules/match/src/rules.rs
@@ -113,6 +113,25 @@ pub fn write_receipt(
     message: impl Into<String>,
 ) -> Result<(), String> {
     let logical_step = state(ctx)?.logical_step;
+    let message = message.into();
+    let status_label = match status {
+        ReceiptStatus::Accepted => "accept",
+        ReceiptStatus::Rejected => "reject",
+    };
+    match status {
+        ReceiptStatus::Accepted => {
+            log::info!(
+                target: "of",
+                "event=cmd.{status_label} player_id={player_id} command_id={client_command_id} command={command_name} order_id={order_id} step={logical_step}"
+            );
+        }
+        ReceiptStatus::Rejected => {
+            log::warn!(
+                target: "of",
+                "event=cmd.{status_label} player_id={player_id} command_id={client_command_id} command={command_name} step={logical_step} reason={message}"
+            );
+        }
+    }
     ctx.db.command_receipt().insert(CommandReceipt {
         receipt_key: command_key(player_id, client_command_id),
         player_id,
@@ -120,7 +139,7 @@ pub fn write_receipt(
         command_name: command_name.into(),
         status,
         order_id,
-        message: message.into(),
+        message,
         logical_step,
     });
     Ok(())
diff --git a/modules/match/src/simulation.rs b/modules/match/src/simulation.rs
index 3170a2a..9970645 100644
--- a/modules/match/src/simulation.rs
+++ b/modules/match/src/simulation.rs
@@ -460,6 +460,14 @@ pub fn advance_simulation(ctx: &ReducerContext) -> Result<bool, String> {
         let _phase_stopwatch = LogStopwatch::new("simulation_population");
         population_step(ctx, logical_step, high_scale)?;
     }
+    if logical_step.is_multiple_of(40) {
+        log::info!(
+            target: "of",
+            "event=sim.heartbeat step={logical_step} packets={} high_scale={}",
+            packets.rows.len(),
+            u8::from(high_scale)
+        );
+    }
     Ok(state(ctx)?.phase == MatchPhase::Running)
 }
 
diff --git a/scripts/measure-web-bundle.sh b/scripts/measure-web-bundle.sh
new file mode 100755
index 0000000..8518256
--- /dev/null
+++ b/scripts/measure-web-bundle.sh
@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Measure Trunk web-client download size and optionally enforce engineering budgets.
+#
+# Usage:
+#   ./scripts/measure-web-bundle.sh [--build] [--enforce] [--dist DIR] [--out PATH]
+#
+# Defaults:
+#   --dist target/web
+#   --out  artifacts/browser/bundle-<timestamp>.json
+#   Gzip transfer budget: 14 MiB (OF_WEB_GZIP_BUDGET_BYTES)
+#   Raw .wasm budget:     50 MiB (OF_WEB_RAW_WASM_BUDGET_BYTES)
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo_dir="$(cd -- "${script_dir}/.." && pwd)"
+
+build=0
+enforce=0
+dist_dir="${repo_dir}/target/web"
+out_path=""
+timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --build)
+      build=1
+      shift
+      ;;
+    --enforce)
+      enforce=1
+      shift
+      ;;
+    --dist)
+      dist_dir="$(cd -- "$2" && pwd)"
+      shift 2
+      ;;
+    --out)
+      out_path="$2"
+      shift 2
+      ;;
+    -h|--help)
+      sed -n '2,14p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "${build}" -eq 1 ]]; then
+  "${script_dir}/build-web-production.sh"
+fi
+
+if [[ ! -d "${dist_dir}" ]]; then
+  echo "missing web dist directory: ${dist_dir}" >&2
+  echo "Run with --build, or ./scripts/build-web-production.sh first." >&2
+  exit 2
+fi
+
+wasm_count="$(find "${dist_dir}" -type f -name '*.wasm' | wc -l | tr -d ' ')"
+if [[ "${wasm_count}" -eq 0 ]]; then
+  echo "no .wasm artifacts under ${dist_dir}" >&2
+  exit 2
+fi
+
+gzip_budget="${OF_WEB_GZIP_BUDGET_BYTES:-14680064}"   # 14 MiB
+raw_wasm_budget="${OF_WEB_RAW_WASM_BUDGET_BYTES:-52428800}" # 50 MiB
+
+if [[ -z "${out_path}" ]]; then
+  out_dir="${repo_dir}/artifacts/browser"
+  mkdir -p "${out_dir}"
+  out_path="${out_dir}/bundle-${timestamp}.json"
+else
+  mkdir -p "$(dirname -- "${out_path}")"
+fi
+
+git_head="$(git -C "${repo_dir}" rev-parse HEAD 2>/dev/null || echo unknown)"
+git_dirty="$(git -C "${repo_dir}" status --porcelain 2>/dev/null | grep -q . && echo true || echo false)"
+
+python3 - "${dist_dir}" "${out_path}" "${gzip_budget}" "${raw_wasm_budget}" "${enforce}" "${git_head}" "${git_dirty}" "${timestamp}" <<'PY'
+import gzip
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+dist_dir = Path(sys.argv[1])
+out_path = Path(sys.argv[2])
+gzip_budget = int(sys.argv[3])
+raw_wasm_budget = int(sys.argv[4])
+enforce = sys.argv[5] == "1"
+git_head = sys.argv[6]
+git_dirty = sys.argv[7] == "true"
+timestamp = sys.argv[8]
+
+files = []
+for path in sorted(p for p in dist_dir.rglob("*") if p.is_file()):
+    data = path.read_bytes()
+    files.append(
+        {
+            "path": str(path.relative_to(dist_dir)).replace(os.sep, "/"),
+            "raw_bytes": len(data),
+            "gzip9_bytes": len(gzip.compress(data, compresslevel=9)),
+            "sha256_16": hashlib.sha256(data).hexdigest()[:16],
+        }
+    )
+
+total_raw = sum(item["raw_bytes"] for item in files)
+total_gzip = sum(item["gzip9_bytes"] for item in files)
+wasm_files = [item for item in files if item["path"].endswith(".wasm")]
+largest_wasm_raw = max((item["raw_bytes"] for item in wasm_files), default=0)
+largest_wasm_gzip = max((item["gzip9_bytes"] for item in wasm_files), default=0)
+
+gzip_ok = total_gzip <= gzip_budget
+raw_ok = largest_wasm_raw <= raw_wasm_budget
+passed = gzip_ok and raw_ok
+
+report = {
+    "kind": "web-bundle-size",
+    "measured_at_utc": timestamp,
+    "git_head": git_head,
+    "git_dirty": git_dirty,
+    "dist_dir": str(dist_dir),
+    "budgets": {
+        "total_gzip9_bytes": gzip_budget,
+        "largest_wasm_raw_bytes": raw_wasm_budget,
+    },
+    "totals": {
+        "raw_bytes": total_raw,
+        "gzip9_bytes": total_gzip,
+        "file_count": len(files),
+        "largest_wasm_raw_bytes": largest_wasm_raw,
+        "largest_wasm_gzip9_bytes": largest_wasm_gzip,
+    },
+    "status": {
+        "total_gzip9_ok": gzip_ok,
+        "largest_wasm_raw_ok": raw_ok,
+        "passed": passed,
+    },
+    "files": files,
+}
+
+out_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+
+def fmt(n: int) -> str:
+    return f"{n:,} ({n / (1024 * 1024):.2f} MiB)"
+
+print(f"web bundle: {dist_dir}")
+print(f"  files:              {len(files)}")
+print(f"  total raw:          {fmt(total_raw)}")
+print(f"  total gzip-9:       {fmt(total_gzip)}  budget {fmt(gzip_budget)}  {'OK' if gzip_ok else 'OVER'}")
+print(f"  largest wasm raw:   {fmt(largest_wasm_raw)}  budget {fmt(raw_wasm_budget)}  {'OK' if raw_ok else 'OVER'}")
+print(f"  largest wasm gzip:  {fmt(largest_wasm_gzip)}")
+print(f"  report:             {out_path}")
+print(f"  gate:               {'PASS' if passed else 'FAIL'}")
+
+if enforce and not passed:
+    sys.exit(1)
+PY
diff --git a/scripts/run-reconnect-soak.sh b/scripts/run-reconnect-soak.sh
new file mode 100755
index 0000000..e55bca2
--- /dev/null
+++ b/scripts/run-reconnect-soak.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Headless reconnect soak against a live match database.
+#
+# Proves identity reclaim + subscription rebuild latency under optional
+# concurrent client load. This is the native SpacetimeDB path; browser
+# localStorage/WebSocket quirks still need a manual browser pass (see
+# docs/browser-gates.md).
+#
+# Prerequisites:
+#   1. Local SpacetimeDB running (./scripts/start-local-server.sh)
+#   2. A published match database that already has a configured, running
+#      match with at least two claimed seats — OR let this script publish a
+#      fresh of-match-reconnect-soak and run match-e2e setup via --fresh.
+#
+# Examples:
+#   # Isolated functional soak (publishes a fresh DB, joins, starts, cycles)
+#   ./scripts/run-reconnect-soak.sh --fresh --cycles 20
+#
+#   # Against an in-flight match-perf database while workers are busy
+#   ./scripts/run-reconnect-soak.sh --database of-match-perf --cycles 30
+#   # (use match-e2e --player-one-token / --player-two-token for worker seats)
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo_dir="$(cd -- "${script_dir}/.." && pwd)"
+
+host="${OF_RECONNECT_HOST:-http://127.0.0.1:3000}"
+server="${OF_RECONNECT_SERVER:-local}"
+database="${OF_RECONNECT_DATABASE:-of-match-reconnect-soak}"
+cycles="${OF_RECONNECT_CYCLES:-20}"
+timeout_secs="${OF_RECONNECT_TIMEOUT_SECS:-60}"
+fresh=0
+out_path=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --host) host="$2"; shift 2 ;;
+    --server) server="$2"; shift 2 ;;
+    --database) database="$2"; shift 2 ;;
+    --cycles) cycles="$2"; shift 2 ;;
+    --timeout-secs) timeout_secs="$2"; shift 2 ;;
+    --fresh) fresh=1; shift ;;
+    --skip-setup)
+      # Accepted for compatibility; soak always uses reconnect-only.
+      shift
+      ;;
+    --out) out_path="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,22p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! [[ "${cycles}" =~ ^[0-9]+$ ]] || [[ "${cycles}" -lt 1 ]]; then
+  echo "--cycles must be a positive integer" >&2
+  exit 2
+fi
+
+timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+if [[ -z "${out_path}" ]]; then
+  out_dir="${repo_dir}/artifacts/browser"
+  mkdir -p "${out_dir}"
+  out_path="${out_dir}/reconnect-soak-${timestamp}.json"
+else
+  mkdir -p "$(dirname -- "${out_path}")"
+fi
+
+if [[ "${fresh}" -eq 1 ]]; then
+  if ! command -v spacetime >/dev/null 2>&1; then
+    echo "spacetime CLI required for --fresh" >&2
+    exit 2
+  fi
+  echo "publishing fresh database ${database} on server ${server}"
+  spacetime publish --server "${server}" --module-path "${repo_dir}/modules/match" \
+    --delete-data=always --yes "${database}"
+fi
+
+extra_args=(
+  --host "${host}"
+  --database "${database}"
+  --timeout-secs "${timeout_secs}"
+  --reconnect-only
+  --reconnect-cycles "${cycles}"
+  --reconnect-report "${out_path}"
+)
+
+echo "running reconnect soak: database=${database} cycles=${cycles}"
+cargo run -q -p match-e2e -- "${extra_args[@]}"
+echo "reconnect soak report: ${out_path}"
diff --git a/tools/match-e2e/Cargo.toml b/tools/match-e2e/Cargo.toml
index 2ae7f6d..8915b45 100644
--- a/tools/match-e2e/Cargo.toml
+++ b/tools/match-e2e/Cargo.toml
@@ -10,6 +10,8 @@ anyhow.workspace = true
 clap.workspace = true
 hex-core.workspace = true
 match-bindings = { path = "../../crates/match-bindings" }
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
 spacetimedb-sdk.workspace = true
 
 [lints]
diff --git a/tools/match-e2e/src/main.rs b/tools/match-e2e/src/main.rs
index 23c9ace..25d1351 100644
--- a/tools/match-e2e/src/main.rs
+++ b/tools/match-e2e/src/main.rs
@@ -25,6 +25,7 @@ use match_bindings::{
     TransitPacketTableAccess, TransitRouteTableAccess, cancel_orders as _,
     issue_attack_clusters as _, issue_expand_all as _, issue_expand_clusters as _,
     issue_push_front as _, issue_reshape as _, join_match as _, set_mobilization_target as _,
+    start_match as _,
 };
 use spacetimedb_sdk::{DbContext, Identity, Table};
 
@@ -62,6 +63,15 @@ struct Args {
     #[arg(long, default_value = ".match-e2e-tokens")]
     token_dir: PathBuf,
 
+    /// Optional override for player one's token file (for example a match-perf
+    /// `player-1.token` during reconnect-under-load soaks).
+    #[arg(long)]
+    player_one_token: Option<PathBuf>,
+
+    /// Optional override for player two's token file / reconnect observer.
+    #[arg(long)]
+    player_two_token: Option<PathBuf>,
+
     /// Maximum time allowed for each asynchronous phase.
     #[arg(long, default_value_t = 60)]
     timeout_secs: u64,
@@ -69,6 +79,41 @@ struct Args {
     /// Client-cache polling interval.
     #[arg(long, default_value_t = 20)]
     poll_ms: u64,
+
+    /// Skip the gameplay smoke and only exercise reconnect reclaim cycles.
+    /// Requires a published database; joins seats and calls `start_match` when
+    /// the match is still in Lobby.
+    #[arg(long, default_value_t = false)]
+    reconnect_only: bool,
+
+    /// Extra disconnect/reconnect cycles after the functional reclaim proof
+    /// (or the sole workload when `--reconnect-only` is set).
+    #[arg(long, default_value_t = 0)]
+    reconnect_cycles: u32,
+
+    /// Optional JSON report path for reconnect soak timings.
+    #[arg(long)]
+    reconnect_report: Option<PathBuf>,
+}
+
+#[derive(Debug, serde::Serialize)]
+struct ReconnectCycleReport {
+    cycle: u32,
+    disconnect_to_reclaim_ms: u128,
+    reconnect_count_after: u32,
+}
+
+#[derive(Debug, serde::Serialize)]
+struct ReconnectSoakReport {
+    kind: &'static str,
+    host: String,
+    database: String,
+    cycles_requested: u32,
+    cycles_completed: u32,
+    p50_ms: u128,
+    p95_ms: u128,
+    max_ms: u128,
+    cycles: Vec<ReconnectCycleReport>,
 }
 
 enum LifecycleEvent {
@@ -185,6 +230,17 @@ impl Client {
         wait_for_reducer(&rx, timeout, &format!("{} join_match", self.label))
     }
 
+    fn start_match(&self, timeout: Duration) -> Result<()> {
+        let (tx, rx) = mpsc::channel();
+        self.conn
+            .reducers
+            .start_match_then(move |_, result| {
+                let _ = tx.send(flatten_reducer_result(result));
+            })
+            .with_context(|| format!("send start_match for {}", self.label))?;
+        wait_for_reducer(&rx, timeout, &format!("{} start_match", self.label))
+    }
+
     fn set_mobilization_target(
         &self,
         command_id: u64,
@@ -475,11 +531,23 @@ fn main() -> Result<()> {
     let args = Args::parse();
     ensure!(args.timeout_secs > 0, "--timeout-secs must be positive");
     ensure!(args.poll_ms > 0, "--poll-ms must be positive");
+    if args.reconnect_only {
+        ensure!(
+            args.reconnect_cycles > 0,
+            "--reconnect-only requires --reconnect-cycles > 0"
+        );
+    }
     let timeout = Duration::from_secs(args.timeout_secs);
     let poll = Duration::from_millis(args.poll_ms);
 
-    let player_one_token = args.token_dir.join("player-one.token");
-    let player_two_token = args.token_dir.join("player-two.token");
+    let player_one_token = args
+        .player_one_token
+        .clone()
+        .unwrap_or_else(|| args.token_dir.join("player-one.token"));
+    let player_two_token = args
+        .player_two_token
+        .clone()
+        .unwrap_or_else(|| args.token_dir.join("player-two.token"));
 
     println!("[1/10] connecting two persistent identity profiles");
     let mut player_one = Client::connect(
@@ -509,6 +577,7 @@ fn main() -> Result<()> {
     player_two.join_match(PLAYER_TWO, "E2E Player 2", timeout)?;
     wait_for_slot(&player_one, PLAYER_ONE, player_one.identity, timeout, poll)?;
     wait_for_slot(&player_one, PLAYER_TWO, player_two.identity, timeout, poll)?;
+    ensure_match_running(&player_one, timeout, poll)?;
     let running_step = wait_until("match phase Running", timeout, poll, || {
         let state = player_one
             .conn
@@ -519,6 +588,31 @@ fn main() -> Result<()> {
         Ok(state.and_then(|row| (row.phase == MatchPhase::Running).then_some(row.logical_step)))
     })?;
 
+    if args.reconnect_only {
+        println!(
+            "reconnect-only: skipping gameplay smoke; running {} reclaim cycles",
+            args.reconnect_cycles
+        );
+        let report = run_reconnect_soak(
+            &mut player_one,
+            &player_two,
+            &player_one_token,
+            &args.host,
+            &args.database,
+            args.reconnect_cycles,
+            timeout,
+            poll,
+        )?;
+        write_reconnect_report(args.reconnect_report.as_deref(), &report)?;
+        player_one.disconnect(timeout)?;
+        player_two.disconnect(timeout)?;
+        println!(
+            "PASS: reconnect soak completed {} cycles (p50={}ms p95={}ms max={}ms)",
+            report.cycles_completed, report.p50_ms, report.p95_ms, report.max_ms
+        );
+        return Ok(());
+    }
+
     println!("[3/10] verifying idempotent mobilization and its receipt");
     let mobilization_id = unused_command_id(&player_one.conn, PLAYER_ONE, COMMAND_ID_FLOOR)?;
     // Keep recruitment stopped after proving the mobilization command. That makes
@@ -1371,62 +1465,223 @@ fn main() -> Result<()> {
         poll,
     )?;
     println!("[10/10] reconnecting player one with its persisted token");
-    let reconnect_count_before = player_two
-        .conn
-        .db
-        .player_slot()
-        .player_id()
-        .find(&PLAYER_ONE)
-        .context("player one slot disappeared before reconnect test")?
-        .reconnect_count;
-    let original_identity = player_one.identity;
-    player_one.disconnect(timeout)?;
-    wait_until("player one disconnect visibility", timeout, poll, || {
-        Ok(player_two
-            .conn
-            .db
-            .player_slot()
-            .player_id()
-            .find(&PLAYER_ONE)
-            .and_then(|slot| (!slot.connected).then_some(())))
-    })?;
-    let mut reconnected = Client::connect(
-        "player one reconnect",
+    let functional = run_reconnect_soak(
+        &mut player_one,
+        &player_two,
         &player_one_token,
         &args.host,
         &args.database,
+        1,
         timeout,
+        poll,
     )?;
     ensure!(
-        reconnected.identity == original_identity,
-        "persisted player-one token resolved to a different identity"
+        functional.cycles_completed == 1,
+        "functional reconnect reclaim did not complete"
     );
-    reconnected.join_match(PLAYER_ONE, "E2E Player 1", timeout)?;
-    wait_until("player one reconnect visibility", timeout, poll, || {
-        let Some(slot) = player_two
+
+    if args.reconnect_cycles > 0 {
+        println!(
+            "running {} additional reconnect soak cycles",
+            args.reconnect_cycles
+        );
+        let soak = run_reconnect_soak(
+            &mut player_one,
+            &player_two,
+            &player_one_token,
+            &args.host,
+            &args.database,
+            args.reconnect_cycles,
+            timeout,
+            poll,
+        )?;
+        write_reconnect_report(args.reconnect_report.as_deref(), &soak)?;
+        println!(
+            "reconnect soak: {} cycles p50={}ms p95={}ms max={}ms",
+            soak.cycles_completed, soak.p50_ms, soak.p95_ms, soak.max_ms
+        );
+    } else if let Some(path) = args.reconnect_report.as_deref() {
+        write_reconnect_report(Some(path), &functional)?;
+    }
+
+    player_one.disconnect(timeout)?;
+    player_two.disconnect(timeout)?;
+    println!(
+        "PASS: receipts, sparse-seed whole-cluster best-effort Reshape, atomic invalid-shape rejection, directional Push and retasking, neutral perimeter expansion, cluster-first expansion/attack, conservation/cancellation, and token reuse verified"
+    );
+    Ok(())
+}
+
+fn ensure_match_running(client: &Client, timeout: Duration, poll: Duration) -> Result<()> {
+    let phase = client
+        .conn
+        .db
+        .match_state()
+        .singleton_id()
+        .find(&SINGLETON_ID)
+        .map(|state| state.phase);
+    match phase {
+        Some(MatchPhase::Running) => Ok(()),
+        Some(MatchPhase::Lobby) => {
+            match client.start_match(timeout) {
+                Ok(()) => {}
+                Err(error) => {
+                    let message = error.to_string();
+                    let already_running = client
+                        .conn
+                        .db
+                        .match_state()
+                        .singleton_id()
+                        .find(&SINGLETON_ID)
+                        .is_some_and(|state| state.phase == MatchPhase::Running);
+                    if !already_running {
+                        return Err(error).context(format!(
+                            "start_match failed while match remained non-running: {message}"
+                        ));
+                    }
+                }
+            }
+            wait_until("match phase Running after start_match", timeout, poll, || {
+                let state = client
+                    .conn
+                    .db
+                    .match_state()
+                    .singleton_id()
+                    .find(&SINGLETON_ID);
+                Ok(state.and_then(|row| (row.phase == MatchPhase::Running).then_some(())))
+            })?;
+            Ok(())
+        }
+        Some(other) => bail!("match is in unexpected phase {other:?}; expected Lobby or Running"),
+        None => bail!("match state is missing before start/reconnect"),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn run_reconnect_soak(
+    player_one: &mut Client,
+    observer: &Client,
+    token_path: &Path,
+    host: &str,
+    database: &str,
+    cycles: u32,
+    timeout: Duration,
+    poll: Duration,
+) -> Result<ReconnectSoakReport> {
+    ensure!(cycles > 0, "reconnect soak requires at least one cycle");
+    let original_identity = player_one.identity;
+    let mut cycle_reports = Vec::with_capacity(cycles as usize);
+
+    for cycle in 1..=cycles {
+        let reconnect_count_before = observer
             .conn
             .db
             .player_slot()
             .player_id()
             .find(&PLAYER_ONE)
-        else {
-            return Ok(None);
-        };
+            .context("player one slot disappeared before reconnect soak")?
+            .reconnect_count;
+        let started = Instant::now();
+        player_one.disconnect(timeout)?;
+        wait_until(
+            &format!("player one disconnect visibility (cycle {cycle})"),
+            timeout,
+            poll,
+            || {
+                Ok(observer
+                    .conn
+                    .db
+                    .player_slot()
+                    .player_id()
+                    .find(&PLAYER_ONE)
+                    .and_then(|slot| (!slot.connected).then_some(())))
+            },
+        )?;
+        let reconnected = Client::connect(
+            "player one reconnect",
+            token_path,
+            host,
+            database,
+            timeout,
+        )?;
         ensure!(
-            slot.identity.as_ref() == Some(&original_identity),
-            "reconnected slot identity changed"
+            reconnected.identity == original_identity,
+            "persisted player-one token resolved to a different identity on cycle {cycle}"
         );
-        Ok((slot.connected
-            && slot.has_reconnected
-            && slot.reconnect_count > reconnect_count_before)
-            .then_some(()))
-    })?;
+        reconnected.join_match(PLAYER_ONE, "E2E Player 1", timeout)?;
+        let reconnect_count_after = wait_until(
+            &format!("player one reconnect visibility (cycle {cycle})"),
+            timeout,
+            poll,
+            || {
+                let Some(slot) = observer
+                    .conn
+                    .db
+                    .player_slot()
+                    .player_id()
+                    .find(&PLAYER_ONE)
+                else {
+                    return Ok(None);
+                };
+                ensure!(
+                    slot.identity.as_ref() == Some(&original_identity),
+                    "reconnected slot identity changed on cycle {cycle}"
+                );
+                Ok((slot.connected
+                    && slot.has_reconnected
+                    && slot.reconnect_count > reconnect_count_before)
+                    .then_some(slot.reconnect_count))
+            },
+        )?;
+        cycle_reports.push(ReconnectCycleReport {
+            cycle,
+            disconnect_to_reclaim_ms: started.elapsed().as_millis(),
+            reconnect_count_after,
+        });
+        *player_one = reconnected;
+    }
 
-    reconnected.disconnect(timeout)?;
-    player_two.disconnect(timeout)?;
-    println!(
-        "PASS: receipts, sparse-seed whole-cluster best-effort Reshape, atomic invalid-shape rejection, directional Push and retasking, neutral perimeter expansion, cluster-first expansion/attack, conservation/cancellation, and token reuse verified"
-    );
+    let mut sorted: Vec<u128> = cycle_reports
+        .iter()
+        .map(|cycle| cycle.disconnect_to_reclaim_ms)
+        .collect();
+    sorted.sort_unstable();
+    let p50_ms = percentile_sorted(&sorted, 50);
+    let p95_ms = percentile_sorted(&sorted, 95);
+    let max_ms = *sorted.last().context("reconnect soak produced no timings")?;
+
+    Ok(ReconnectSoakReport {
+        kind: "reconnect-soak",
+        host: host.to_owned(),
+        database: database.to_owned(),
+        cycles_requested: cycles,
+        cycles_completed: cycle_reports.len() as u32,
+        p50_ms,
+        p95_ms,
+        max_ms,
+        cycles: cycle_reports,
+    })
+}
+
+fn percentile_sorted(sorted: &[u128], percentile: u8) -> u128 {
+    if sorted.is_empty() {
+        return 0;
+    }
+    let rank = (u128::from(percentile) * (sorted.len() as u128 - 1)) / 100;
+    sorted[rank as usize]
+}
+
+fn write_reconnect_report(path: Option<&Path>, report: &ReconnectSoakReport) -> Result<()> {
+    let Some(path) = path else {
+        return Ok(());
+    };
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("create reconnect report directory {}", parent.display()))?;
+    }
+    let payload = serde_json::to_vec_pretty(report).context("serialize reconnect soak report")?;
+    fs::write(path, payload)
+        .with_context(|| format!("write reconnect soak report {}", path.display()))?;
     Ok(())
 }
 

From 2e57d84a073b5a568f61b4bd2cade4406e82c59a Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:07:32 +0200
Subject: [PATCH 2/7] Add live match smoke to CI

Run the two-identity harness against a fresh local SpacetimeDB database so integration regressions are caught before deployment.
---
 .github/workflows/ci.yml | 68 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 18f900a..fbdac71 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -84,3 +84,71 @@ jobs:
         run: |
           ./scripts/generate-bindings.sh
           git diff --exit-code -- crates/match-bindings
+
+  match-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pinned Rust toolchain
+        run: rustup show
+
+      - name: Cache Rust build outputs
+        uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+          workspaces: |
+            . -> target
+            modules/match -> modules/match/target
+
+      - name: Install pinned SpacetimeDB CLI
+        run: |
+          curl -sSf https://install.spacetimedb.com | sh -s -- --yes
+          export PATH="$HOME/.local/bin:$PATH"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          spacetime version install 2.7.1 --use --yes
+          ./scripts/check-toolchain.sh
+
+      - name: Start local SpacetimeDB
+        run: |
+          spacetime start \
+            --listen-addr 127.0.0.1:3000 \
+            --data-dir "$GITHUB_WORKSPACE/.spacetime-e2e-data" \
+            --non-interactive \
+            > "$RUNNER_TEMP/spacetime-e2e.log" 2>&1 &
+          echo "$!" > "$RUNNER_TEMP/spacetime-e2e.pid"
+          for attempt in {1..60}; do
+            if curl --fail --silent --show-error http://127.0.0.1:3000/v1/metrics > /dev/null; then
+              exit 0
+            fi
+            sleep 1
+          done
+          cat "$RUNNER_TEMP/spacetime-e2e.log"
+          exit 1
+
+      - name: Publish fresh match database
+        run: |
+          spacetime publish \
+            --server local \
+            --module-path modules/match \
+            --delete-data=always \
+            --yes \
+            of-match-e2e-ci
+
+      - name: Run live match smoke
+        run: |
+          cargo run -p match-e2e -- \
+            --host http://127.0.0.1:3000 \
+            --database of-match-e2e-ci
+
+      - name: Stop local SpacetimeDB
+        if: always()
+        run: |
+          if [ -f "$RUNNER_TEMP/spacetime-e2e.pid" ]; then
+            kill "$(cat "$RUNNER_TEMP/spacetime-e2e.pid")" || true
+          fi
+          if [ -f "$RUNNER_TEMP/spacetime-e2e.log" ]; then
+            cat "$RUNNER_TEMP/spacetime-e2e.log"
+          fi

From 71e5e8a68633b72fe84851879e96882f02ad98ad Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:08:03 +0200
Subject: [PATCH 3/7] Add V1 match completion lifecycle

Show an actionable victory result and reclaim provisioned match databases once their final lobby member leaves, without making cleanup availability block departure.
---
 crates/game-client/src/hud.rs     | 112 +++++++++++++++++++++++++++++-
 deployment/vercel/api/lobbies.mjs |  31 ++++++++-
 docs/implementation.md            |   7 ++
 3 files changed, 148 insertions(+), 2 deletions(-)

diff --git a/crates/game-client/src/hud.rs b/crates/game-client/src/hud.rs
index f31eb68..bb24152 100644
--- a/crates/game-client/src/hud.rs
+++ b/crates/game-client/src/hud.rs
@@ -1,4 +1,5 @@
 use bevy::{
+    app::AppExit,
     picking::hover::Hovered,
     prelude::*,
     ui::UiRect,
@@ -10,7 +11,7 @@ use bevy::{
 use crate::{
     interaction::{InteractionState, OrderMode},
     map_view::map_view_status_bundle,
-    model::{MatchView, ToastKind},
+    model::{MatchPhase, MatchView, ToastKind},
     network::{ClientIntent, NetworkSet},
 };
 
@@ -60,6 +61,13 @@ struct MobilizationSlider;
 #[derive(Component)]
 struct MobilizationThumb;
 
+#[derive(Component)]
+struct ResultOverlay;
+#[derive(Component)]
+struct ResultTitle;
+#[derive(Component)]
+struct ResultDetails;
+
 #[derive(Component)]
 struct CommandContextTitle;
 #[derive(Component)]
@@ -130,6 +138,7 @@ impl Plugin for HudPlugin {
                     update_hud.after(NetworkSet::Apply),
                     update_command_bar.after(update_hud),
                     update_slider_visuals.after(update_hud),
+                    leave_match_after_victory,
                 ),
             );
     }
@@ -155,6 +164,7 @@ fn spawn_hud(mut commands: Commands, view: Res<MatchView>) {
             spawn_bottom_bar(root, view.mobilization_target);
             spawn_toast(root);
             spawn_help(root);
+            spawn_result_overlay(root);
         });
 }
 
@@ -468,6 +478,51 @@ fn spawn_help(root: &mut ChildSpawnerCommands) {
     });
 }
 
+fn spawn_result_overlay(root: &mut ChildSpawnerCommands) {
+    root.spawn((
+        Name::new("Match result overlay"),
+        ResultOverlay,
+        Node {
+            display: Display::None,
+            position_type: PositionType::Absolute,
+            left: percent(50),
+            top: percent(50),
+            width: px(480),
+            padding: UiRect::all(px(24)),
+            border: UiRect::all(px(2)),
+            flex_direction: FlexDirection::Column,
+            align_items: AlignItems::Center,
+            row_gap: px(12),
+            ..default()
+        },
+        UiTransform::from_translation(Val2::percent(-50.0, -50.0)),
+        GlobalZIndex(60),
+        BackgroundColor(Color::srgba(0.025, 0.039, 0.049, 0.985)),
+        BorderColor::all(CYAN),
+        Pickable::IGNORE,
+    ))
+    .with_children(|overlay| {
+        overlay.spawn((
+            ResultTitle,
+            Text::new("MATCH COMPLETE"),
+            TextFont::from_font_size(24.0),
+            TextColor(CYAN),
+            Pickable::IGNORE,
+        ));
+        overlay.spawn((
+            ResultDetails,
+            Text::new(""),
+            TextFont::from_font_size(13.0),
+            TextColor(TEXT),
+            Node {
+                align_self: AlignSelf::Stretch,
+                ..default()
+            },
+            Pickable::IGNORE,
+        ));
+    });
+}
+
 fn section_title(value: &'static str) -> impl Bundle {
     (
         Text::new(value),
@@ -682,10 +737,13 @@ fn update_hud(
         Single<&mut Text, With<BottomStatus>>,
         Single<&mut Text, With<MobilizationLabel>>,
         Single<&mut Text, With<ToastText>>,
+        Single<&mut Text, With<ResultTitle>>,
+        Single<&mut Text, With<ResultDetails>>,
     )>,
     mut panels: ParamSet<(
         Single<(&mut Node, &mut BackgroundColor, &mut BorderColor), With<ToastRoot>>,
         Single<&mut Node, With<HelpPanel>>,
+        Single<(&mut Node, &mut BorderColor), With<ResultOverlay>>,
     )>,
     slider: Single<(Entity, &SliderValue), With<MobilizationSlider>>,
     mut selection_totals: Local<SelectionTotalsCache>,
@@ -902,6 +960,58 @@ fn update_hud(
         let mut toast_root = panels.p0();
         toast_root.0.display = Display::None;
     }
+
+    {
+        let mut overlay = panels.p2();
+        if let MatchPhase::Victory(winner) = view.phase {
+            let local_won = winner == u32::from(view.local_player);
+            overlay.0.display = Display::Flex;
+            overlay.1.set_all(if local_won { CYAN } else { CORAL });
+
+            let mut title = texts.p6();
+            set_text(
+                &mut title,
+                if local_won {
+                    "VICTORY CONFIRMED".to_owned()
+                } else {
+                    "MATCH COMPLETE".to_owned()
+                },
+            );
+
+            let mut details = texts.p7();
+            set_text(
+                &mut details,
+                format!(
+                    "WINNER       PLAYER {winner}\nLOCAL SEAT   PLAYER {}  //  {}\nCONQUEST    RESOLVED AT LOGICAL STEP {}\n\nESC  //  RETURN TO LOBBY DIRECTORY\nFROM THE DIRECTORY, SELECT LEAVE TO RETIRE THE LOBBY.",
+                    view.local_player,
+                    if local_won { "VICTORY" } else { "DEFEAT" },
+                    view.logical_step,
+                ),
+            );
+        } else {
+            overlay.0.display = Display::None;
+        }
+    }
+}
+
+fn leave_match_after_victory(
+    keyboard: Res<ButtonInput<KeyCode>>,
+    view: Res<MatchView>,
+    mut app_exit: MessageWriter<AppExit>,
+) {
+    if !matches!(view.phase, MatchPhase::Victory(_)) || !keyboard.just_pressed(KeyCode::Escape) {
+        return;
+    }
+
+    #[cfg(target_arch = "wasm32")]
+    {
+        if let Some(window) = web_sys::window() {
+            let _ = window.location().set_href("/");
+        }
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    app_exit.write(AppExit::Success);
 }
 
 fn update_slider_visuals(
diff --git a/deployment/vercel/api/lobbies.mjs b/deployment/vercel/api/lobbies.mjs
index 0394fe8..076c945 100644
--- a/deployment/vercel/api/lobbies.mjs
+++ b/deployment/vercel/api/lobbies.mjs
@@ -59,6 +59,13 @@ async function callReducer(database, reducer, args, token) {
   });
 }
 
+async function deleteMatchDatabase(database) {
+  return upstream(`/v1/database/${encodeURIComponent(database)}`, {
+    method: "DELETE",
+    token: serviceToken(),
+  });
+}
+
 async function query(sql) {
   const text = await upstream(`/v1/database/${LOBBY_DATABASE}/sql`, {
     method: "POST",
@@ -196,9 +203,31 @@ export default async function handler(request, response) {
 
     if (body.action === "leave") {
       const lobbyId = String(body.lobbyId ?? "");
+      // The reducer removes the final member's lobby row, so keep the provisioned
+      // database name before calling it. Only delete after confirming that row is gone.
+      const leavingLobby = (await listLobbies()).find((candidate) => candidate.lobbyId === lobbyId);
       await callReducer(LOBBY_DATABASE, "leave_lobby", [lobbyId], token);
       const lobby = (await listLobbies()).find((candidate) => candidate.lobbyId === lobbyId);
-      return response.status(200).json({ lobby: lobby ?? null });
+      let cleanup = null;
+      if (!lobby && leavingLobby?.matchDatabase) {
+        try {
+          await deleteMatchDatabase(leavingLobby.matchDatabase);
+          cleanup = { database: leavingLobby.matchDatabase, deleted: true };
+        } catch (error) {
+          // Leaving has already succeeded. Report the cleanup failure so callers
+          // can surface it without trapping a user in the lobby.
+          cleanup = {
+            database: leavingLobby.matchDatabase,
+            deleted: false,
+            error: error.message || "match_database_cleanup_failed",
+          };
+          console.error(
+            `Failed to delete match database ${leavingLobby.matchDatabase} after lobby ${lobbyId} was deleted:`,
+            error,
+          );
+        }
+      }
+      return response.status(200).json({ lobby: lobby ?? null, cleanup });
     }
 
     return response.status(400).json({ error: "unknown_action" });
diff --git a/docs/implementation.md b/docs/implementation.md
index 3dee88d..d86b8a3 100644
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -276,6 +276,13 @@ invalid state, and locked submission each replace that copy with their relevant
 instructions. `?` toggles the complete field manual. The right panel remains
 a compact map-view, inspector, and order summary.
 
+When authoritative state reports victory, a centered result overlay names the
+winner, distinguishes local victory from defeat, and records the resolving
+logical step. `Escape` returns web players to the lobby directory (where they
+can leave the lobby) and exits the native client. The directory captures a
+final member's provisioned match database before deleting its lobby row, then
+best-effort deletes the database without failing that completed leave.
+
 Input produces `ClientIntent`. The online transport invokes generated typed
 reducers, pumps SpacetimeDB frames, and rebuilds `MatchView` from subscribed
 authoritative tables. Stable command IDs and receipts make retry

From f169696f4234bad7e5e55823b8e76006a7803e90 Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:08:11 +0200
Subject: [PATCH 4/7] Add cluster control playtest checklist

Capture the six V1 interaction risks and record the current desk-review evidence until a clean two-player session can validate player understanding.
---
 .../cluster-controls-v1-results-2026-08-07.md | 40 ++++++++
 docs/playtests/cluster-controls-v1.md         | 99 +++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 docs/playtests/cluster-controls-v1-results-2026-08-07.md
 create mode 100644 docs/playtests/cluster-controls-v1.md

diff --git a/docs/playtests/cluster-controls-v1-results-2026-08-07.md b/docs/playtests/cluster-controls-v1-results-2026-08-07.md
new file mode 100644
index 0000000..9f5ead6
--- /dev/null
+++ b/docs/playtests/cluster-controls-v1-results-2026-08-07.md
@@ -0,0 +1,40 @@
+# Cluster controls V1 results — 2026-08-07
+
+## Session
+
+- Method: desk review + code inspection; no GUI session was run.
+- Git SHA: `8037c75` (working tree contains unrelated WIP).
+- Intended local endpoint: `http://127.0.0.1:3000`.
+- Blocker: the checked-in local data directory contains `spacetime.pid` owned
+  by PID 41307, but the endpoint was not reachable. Starting another server
+  safely failed on that lock, so this review did not remove the stale-looking
+  lock or alter the existing local data.
+- Evidence inspected:
+  - [`hud.rs`](../../crates/game-client/src/hud.rs), field manual and
+    contextual HUD copy;
+  - [`interaction.rs`](../../crates/game-client/src/interaction.rs), input,
+    full-component selection, front validation, Reshape preview, and Stop
+    snapshot construction;
+  - [`overlays.rs`](../../crates/game-client/src/overlays.rs), staged-target,
+    Reshape, Stop, and active-front overlays;
+  - [`v1-ui-direction.md`](../v1-ui-direction.md), intended interaction
+    contract and first-playtest risks.
+
+These are implementation-readiness verdicts, not participant-validation
+results. Repeat every row with the procedure in
+[the checklist](./cluster-controls-v1.md) once a clean local or browser
+two-player session is available.
+
+| Risk | Verdict | Desk-review observation | Follow-up |
+| --- | --- | --- | --- |
+| Focus-as-destination | **INCONCLUSIVE — implementation evidence supports it** | The field manual says expansion pressures all sides with a mild click bias (`hud.rs` lines 28–29), and the neutral click path submits `ExpandClusters` with `focus: clicked` (`interaction.rs` lines 799–822). This does not establish that a player reads the click as a focus. | Test participant prediction before dispatch on a multi-exit cluster. |
+| Enemy mask vs active fronts | **INCONCLUSIVE — implementation evidence supports it** | Enemy clicks expand a complete connected enemy cluster before submission (`interaction.rs` lines 835–876); staged targets and `view.active_fronts` have separate overlay paths in `overlays.rs`. The manual explicitly says the wave never leaves the selected enemy mask (`hud.rs` lines 30–31). | Observe an attack that turns/splits and ask the player to identify mask versus live combat. |
+| Front ambiguity at corners | **INCONCLUSIVE — implementation evidence supports it** | Front Rebalance requires a one-component selection and validates source/target seeds before dispatch (`interaction.rs` lines 893–970); the HUD/manual states drag is from one strategic-front boundary to another (`hud.rs` lines 32–33). Code validation is not evidence that corner highlighting is legible. | Exercise two corner-adjacent source seeds in a live match. |
+| Whole-cluster multi-select coarseness | **INCONCLUSIVE — implementation evidence supports it** | Selection expands to full owned components and supports add/remove modifiers (`interaction.rs` lines 1199–1223); the HUD describes complete-cluster selection (`hud.rs` line 27). Whether that is tactically too coarse needs player behavior, not code inspection. | Log every requested partial-component action with map context and desired outcome. |
+| Reshape overflow visibility | **INCONCLUSIVE — implementation evidence supports it** | The manual promises full unavailable/off-world brush visibility and conserved overflow (`hud.rs` lines 34–35). The ready HUD explicitly reports “STAY OUTSIDE” when overflow is nonzero (`hud.rs` lines 629–649), backed by `reshape_outside_strength` in `interaction.rs`. | Draw an undersized and boundary-crossing footprint; verify participant predicts overflow and unavailable cells. |
+| Stop discoverability | **INCONCLUSIVE — implementation evidence supports it** | The persistent idle controls include `X stop` (`hud.rs` lines 555–565); the field manual explains its exact-snapshot semantics (`hud.rs` lines 36–37), and `interaction.rs` freezes order IDs in `StopPreview`. Discovery without coaching cannot be inferred. | Ask a participant to stop active orders without naming the key, then record whether they find the visible hint or `?` manual. |
+
+## Overall verdict
+
+The implementation and copy cover each documented risk, but all six remain
+**INCONCLUSIVE** pending participant observation in a clean two-player session.
diff --git a/docs/playtests/cluster-controls-v1.md b/docs/playtests/cluster-controls-v1.md
new file mode 100644
index 0000000..0266e4c
--- /dev/null
+++ b/docs/playtests/cluster-controls-v1.md
@@ -0,0 +1,99 @@
+# Cluster controls V1 playtest
+
+Use this checklist to test the cluster-first controls described in
+[V1 UI direction](../v1-ui-direction.md). Save completed results as
+`docs/playtests/cluster-controls-v1-results-YYYY-MM-DD.md`. Runtime artifacts
+(screenshots, recordings, and logs) belong in the gitignored
+`artifacts/playtests/` directory.
+
+## Session setup
+
+1. Start a fresh two-seat match, either through the production browser lobby
+   directory or a local match database. For local play:
+   `./scripts/start-local-server.sh`, publish `modules/match`, configure two
+   seats, and connect two native clients or two browser profiles.
+2. Start the match and use enough mobilization/actions to create neutral
+   perimeters, an enemy contact, active orders, and an undersized owned area.
+3. Record client target (native/browser), database, map preset, participants,
+   git SHA, and any accessibility or input-device constraint.
+
+For each item, mark **PASS**, **FAIL**, or **INCONCLUSIVE**, describe what the
+participant did and understood, and attach relevant evidence.
+
+## Checklist
+
+### 1. Focus is a destination, not an exact order
+
+| Field | Check |
+| --- | --- |
+| Procedure | Select an owned cluster, hover then click neutral terrain from a cluster with multiple eligible exits. Ask the player what will happen before and after dispatch. |
+| Expected observation | The player identifies the clicked hex as a weighted focus and expects expansion from all eligible selected perimeters, rather than a single-cell movement destination. |
+| Pass | The participant explains or acts on the all-perimeter behavior without corrective coaching. |
+| Fail | The participant expects only the clicked cell to receive troops or regards outcomes on other branches as a bug. |
+
+### 2. Enemy mask versus active fronts
+
+| Field | Check |
+| --- | --- |
+| Procedure | Attack a complete enemy cluster, then observe the preview and several simulation updates as fronts turn, split, or disappear. |
+| Expected observation | The complete selected enemy component remains understandable as the target mask, while active front overlays communicate the currently contested subset. |
+| Pass | The participant can distinguish “accepted target territory” from “where troops are fighting now.” |
+| Fail | The participant confuses the mask with live fronts or cannot identify either state. |
+
+### 3. Front ambiguity at corners
+
+| Field | Check |
+| --- | --- |
+| Procedure | Select one owned cluster, press `B`, choose a source boundary near a corner/shared-cell junction, and drag to another front. Repeat with a nearby alternative seed. |
+| Expected observation | Source and target strategic arcs make the chosen fronts explicit; invalid or same-front gestures explain the correction. |
+| Pass | The participant can predict the source/target fronts before release and recover from an invalid choice. |
+| Fail | Corner-adjacent selections make the intended arc unclear or create surprising transfers. |
+
+### 4. Whole-cluster multi-select coarseness
+
+| Field | Check |
+| --- | --- |
+| Procedure | Select a cluster with `C`, add another with Shift+`C`, remove one with Control+`C`, then ask the participant to perform a tactical action affecting only part of a selected component. |
+| Expected observation | The participant understands that selection is whole connected owned components; any desire for sub-cluster control is recorded with its tactical context. |
+| Pass | No blocking tactical case is found, or requested granularity is satisfiable through a documented cluster action. |
+| Fail | A recurring, concrete tactical case cannot be expressed without sub-cluster selection. |
+
+### 5. Reshape overflow visibility
+
+| Field | Check |
+| --- | --- |
+| Procedure | Select exactly one cluster, press `T`, draw an undersized owned/passable footprint, and inspect the ready preview before confirming. Also draw across a world edge or unavailable cells. |
+| Expected observation | Available, unavailable, and off-world footprint portions remain visible; the preview reports strength that will stay outside and does not imply troop loss. |
+| Pass | The participant correctly predicts conserved overflow and can see why excluded cells are unavailable. |
+| Fail | Overflow appears lost/failed or part of the intended footprint is invisible. |
+
+### 6. Stop discoverability
+
+| Field | Check |
+| --- | --- |
+| Procedure | Create active orders, select their cluster, and ask the participant to stop them without naming a key. Then press `X`, inspect the preview, and confirm with LMB/Enter. |
+| Expected observation | The participant finds or learns the `X` hint/manual; the preview communicates that it freezes an exact order snapshot and does not retask troops. |
+| Pass | The participant discovers the control from visible guidance or uses it correctly after the field manual. |
+| Fail | The participant expects a new action or selection to retask/cancel orders, or cannot locate Stop from provided guidance. |
+
+## Results template
+
+```md
+# Cluster controls V1 results — YYYY-MM-DD
+
+## Session
+- Method: native / browser / desk review + code inspection
+- Git SHA:
+- Match/database and preset:
+- Participants:
+- Evidence:
+
+| Risk | Verdict | Observation | Follow-up |
+| --- | --- | --- | --- |
+| Focus-as-destination |  |  |  |
+| Enemy mask vs active fronts |  |  |  |
+| Front ambiguity at corners |  |  |  |
+| Whole-cluster multi-select coarseness |  |  |  |
+| Reshape overflow visibility |  |  |  |
+| Stop discoverability |  |  |  |
+```

From 8f195b2a5d298d9c6a234f50445f7a3b642b696a Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:08:19 +0200
Subject: [PATCH 5/7] Clarify lobby boundaries and browser qualification

Differentiate provisioning from the in-game match lobby and preserve the remaining concurrent-load reconnect qualification gap in the implementation guide.
---
 docs/implementation.md | 39 ++++++++++++++++++++++++++++++---------
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/docs/implementation.md b/docs/implementation.md
index d86b8a3..9a695d1 100644
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -32,6 +32,23 @@ control module and uses a Vercel function to create `of-match-<lobby-id>`
 databases from the pinned match Wasm, configure them once, and assign browsers
 without changing the match module's authority boundary.
 
+### Two lobby surfaces
+
+There are two distinct UIs named “lobby”; they operate at different boundaries:
+
+- The production browser lobby directory at
+  [`deployment/vercel/index.html`](../deployment/vercel/index.html) is the
+  directory and provisioning surface. It creates, joins, and leaves control
+  lobbies in the lobby database. The Vercel orchestrator provisions a fresh
+  `of-match-<lobby-id>` match database for a ready lobby, then assigns each
+  browser to that database.
+- The in-game Bevy **MATCH LOBBY** at
+  [`crates/game-client/src/lobby.rs`](../crates/game-client/src/lobby.rs)
+  operates inside an already selected match database. Its creator uses
+  `configure_match` to choose the one-shot map and seat count; players claim
+  seats with `join_match`; an eligible seated player starts the configured
+  match. It neither lists production lobbies nor provisions match databases.
+
 ## Authority and cadence
 
 The Bevy client sends intentions only. The match module owns identity slots,
@@ -313,15 +330,18 @@ selection-adjacent presentation from the new authoritative snapshot.
 - The distributed `match-perf` harness (`coordinator` / `worker` / `run-local`)
   profiles client-observed step dilation under multi-process load through 500
   seats; see [Performance profiling](./performance.md).
-- CI repeats formatting, workspace tests/lints, module tests/lints/build, and
-  generated-binding drift detection. Production deploy enforces the web-bundle
-  size gate after Trunk build.
+- CI repeats formatting, workspace tests/lints, module tests/lints/build,
+  generated-binding drift detection, and a fresh local-server `match-e2e`
+  two-identity smoke. Production deploy enforces the web-bundle size gate after
+  Trunk build.
 
 ## Known V1 limits
 
 - Infantry is the only force composition serialized by the module.
-- Lobby create/join/start is implemented; empty lobbies can be cleaned up by
-  leave/auto-delete flows. Match configuration remains one-shot per database.
+- The production browser directory supports lobby create/join/leave and
+  provisions `of-match-<lobby-id>` databases. The separate in-game MATCH LOBBY
+  configures, claims seats, and starts an already-selected match database;
+  match configuration remains one-shot per database.
 - Expansion topology is deterministic from the accepted state. The focus changes
   branch allocation but is not a continuously replanned destination.
 - Attack snapshots complete enemy target clusters at acceptance. Fronts evolve
@@ -345,10 +365,11 @@ selection-adjacent presentation from the new authoritative snapshot.
   requirement is that soldiers impose both lost civilian labor and an explicit,
   ongoing economic burden.
 - Native desktop and WebAssembly/WebGPU compile targets are supported. The web
-  target uses `localStorage` credentials and asynchronous browser networking;
-  representative browser performance is not yet qualified for production. See
-  [Browser release gates](./browser-gates.md) for budgets, the Wasm size
-  baseline, and the remaining WebGPU / reconnect evidence checklist.
+  target uses `localStorage` credentials and asynchronous browser networking.
+  Wasm size and the measured 128/192 WebGPU frame budgets pass, and isolated
+  reconnect plus browser reload smoke are recorded; reconnect under concurrent
+  load remains unqualified. See [Browser release gates](./browser-gates.md) for
+  the evidence and remaining reconnect gate.
 
 These are bounded omissions, not hidden placeholders. Candidate extensions and
 their dependencies are recorded in [future ideas](./future-ideas.md).

From ec0691539b98b1252ee023372d13ccb7e2ef3409 Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:16:57 +0200
Subject: [PATCH 6/7] Call start_match from match-perf after full lobby claims.

Interactive lobby cutover stopped auto-starting on the final seat join, so the
load harness now starts the match from player 1 once every seat is claimed.
---
 tools/match-perf/src/client.rs      | 24 +++++++++++++++++-
 tools/match-perf/src/coordinator.rs |  5 +++-
 tools/match-perf/src/worker.rs      | 39 +++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/tools/match-perf/src/client.rs b/tools/match-perf/src/client.rs
index 5cb77d2..4fc7b73 100644
--- a/tools/match-perf/src/client.rs
+++ b/tools/match-perf/src/client.rs
@@ -13,7 +13,7 @@ use match_bindings::{
     MatchPhase, MatchStateTableAccess, OrderStatus, PlayerSlotTableAccess, PlayerStateTableAccess,
     ReceiptStatus, TransferOrderTableAccess, TransitPacketTableAccess, configure_match as _,
     issue_attack_clusters as _, issue_expand_clusters as _, issue_front_rebalance as _,
-    join_match as _, set_mobilization_target as _,
+    join_match as _, set_mobilization_target as _, start_match as _,
 };
 use spacetimedb_sdk::{DbContext, Table};
 
@@ -157,6 +157,28 @@ impl Client {
         Ok(rtt)
     }
 
+    /// Starts a fully claimed lobby. Required after interactive lobby cutover —
+    /// seat claims no longer auto-enter Running.
+    pub fn start_match(&self, timeout: Duration) -> Result<Duration> {
+        let (rtt, result) = Self::call(
+            |tx| {
+                self.conn
+                    .reducers
+                    .start_match_then(move |_, result| {
+                        let _ = tx.send(
+                            result
+                                .map_err(|error| error.to_string())
+                                .and_then(|inner| inner.map_err(|error| error.clone())),
+                        );
+                    })
+                    .map_err(|error| anyhow::anyhow!(error.to_string()))
+            },
+            timeout,
+        )?;
+        result.map_err(anyhow::Error::msg)?;
+        Ok(rtt)
+    }
+
     pub fn configure(
         &self,
         preset: MapPreset,
diff --git a/tools/match-perf/src/coordinator.rs b/tools/match-perf/src/coordinator.rs
index 5fabb3a..1113034 100644
--- a/tools/match-perf/src/coordinator.rs
+++ b/tools/match-perf/src/coordinator.rs
@@ -239,7 +239,10 @@ pub fn run(args: CoordinatorArgs) -> Result<()> {
         .collect::<Vec<_>>();
 
     let join_deadline = Instant::now() + Duration::from_secs(args.join_timeout_secs);
-    while observer.phase()? == MatchPhase::Lobby {
+    // Stay in Lobby until every seat is claimed; worker 1 then calls start_match.
+    while observer.phase()? == MatchPhase::Lobby
+        && observer.claimed_players() < usize::from(args.players)
+    {
         if args.wait_for_worker_status {
             let (count, messages) = poll_worker_failures_so_far(&run_dir, &shards)?;
             if count > 0 {
diff --git a/tools/match-perf/src/worker.rs b/tools/match-perf/src/worker.rs
index 90c8ddc..da5c860 100644
--- a/tools/match-perf/src/worker.rs
+++ b/tools/match-perf/src/worker.rs
@@ -360,6 +360,45 @@ pub fn run(args: WorkerArgs) -> Result<()> {
     }
 
     let join_deadline = Instant::now() + Duration::from_secs(args.ready_timeout_secs);
+    // Player 1's shard starts the match once every configured seat is claimed.
+    // Interactive lobby cutover removed auto-start from join_match.
+    if range.first_player == 1 {
+        while observer.claimed_players() < usize::from(args.match_players) {
+            if Instant::now() >= join_deadline {
+                return fail(
+                    &args,
+                    range,
+                    anyhow::anyhow!(
+                        "timed out waiting for {} claimed seats before start_match (have {})",
+                        args.match_players,
+                        observer.claimed_players()
+                    ),
+                );
+            }
+            std::thread::sleep(Duration::from_millis(50));
+        }
+        let Some(starter) = commanders.get(&1) else {
+            return fail(
+                &args,
+                range,
+                anyhow::anyhow!("player 1 commander missing; cannot call start_match"),
+            );
+        };
+        match starter.start_match(command_timeout) {
+            Ok(rtt) => println!(
+                "worker {}-{}: start_match accepted in {rtt:.2?}",
+                range.first_player,
+                range.last_player()
+            ),
+            Err(error) => {
+                let already_running = matches!(observer.phase(), Ok(MatchPhase::Running));
+                if !already_running {
+                    return fail(&args, range, error);
+                }
+            }
+        }
+    }
+
     while match observer.phase() {
         Ok(phase) => phase != MatchPhase::Running,
         Err(error) => return fail(&args, range, error),

From ca19b587a5d3e8b1c386507cc3f95a40066709b3 Mon Sep 17 00:00:00 2001
From: Diego Carlino <carlid.dev@gmail.com>
Date: Fri, 7 Aug 2026 20:19:06 +0200
Subject: [PATCH 7/7] Record perf baselines, under-load reconnect, and
 production smoke.

Close the concurrent reconnect gate, document match-perf dilation against
architecture budgets, and capture the of.carlid.dev create/join/reconnect/leave
smoke plus soak script token overrides.
---
 docs/browser-gates.md                         | 39 +++++++++++++------
 docs/implementation.md                        | 14 ++++---
 docs/performance.md                           | 22 +++++++++++
 .../cluster-controls-v1-results-2026-08-07.md |  2 +-
 .../production-e2e-smoke-2026-08-07.md        | 35 +++++++++++++++++
 scripts/run-reconnect-soak.sh                 | 17 ++++++--
 6 files changed, 107 insertions(+), 22 deletions(-)
 create mode 100644 docs/playtests/production-e2e-smoke-2026-08-07.md

diff --git a/docs/browser-gates.md b/docs/browser-gates.md
index 3c93513..0196be6 100644
--- a/docs/browser-gates.md
+++ b/docs/browser-gates.md
@@ -1,6 +1,6 @@
 # Browser release gates
 
-Status: Wasm size + isolated reconnect + WebGPU 128/192 frame cost measured  
+Status: Wasm size + reconnect (isolated + under load) + WebGPU 128/192 frame cost measured  
 Last updated: 2026-08-07
 
 Architecture commits a Bevy WebAssembly/WebGPU client, but treats representative
@@ -22,7 +22,7 @@ Related:
 | Wasm / web download size | ≤ **14 MiB** total gzip-9 transfer; ≤ **50 MiB** largest `.wasm` raw | `./scripts/measure-web-bundle.sh` | **Measured — PASS** (see baseline below) |
 | WebGPU frame cost @ 128×128 | Sustained **≥ 55 FPS** / frame **≤ 18 ms** during ordinary pan/zoom (F3 overlay) | Browser procedure below | **Measured — PASS** (p50 59.9 FPS / 16.7 ms) |
 | WebGPU frame cost @ 192×192 | Same as 128, plus no sustained stall when large subscription batches apply | Browser procedure below | **Measured — PASS** (p50 60.2 FPS / 16.6 ms) |
-| Reconnect under load | Token reclaim succeeds; disconnect→reclaim p95 **≤ 5 s** over ≥ 20 cycles while the match is running | `./scripts/run-reconnect-soak.sh` (native SDK path) + browser smoke | **Isolated soak measured — PASS**; concurrent-load still open; browser reload smoke recorded |
+| Reconnect under load | Token reclaim succeeds; disconnect→reclaim p95 **≤ 5 s** over ≥ 20 cycles while the match is running | `./scripts/run-reconnect-soak.sh` (native SDK path) + browser smoke | **PASS** (isolated + concurrent `match-perf` 128); browser reload smoke recorded |
 | Browser compile | `cargo clippy -p game-client --target wasm32-unknown-unknown -D warnings` | CI already | **PASS** (CI) |
 
 Budgets are engineering gates, not marketing claims. Revisit them if Bevy/WebGPU
@@ -176,8 +176,24 @@ presets — useful for WebGPU bring-up only.
 | max | 86 ms |
 | budget | p95 ≤ 5000 ms |
 
-Gate result for the **isolated** path: **PASS**. Concurrent `match-perf`
-under-load remains open.
+Gate result for the **isolated** path: **PASS**.
+
+### Measured under-load baseline (2026-08-07)
+
+Ran 20 reclaim cycles against worker seats 1–2 while `match-perf` drove
+`playtest` / 128 players / expand+rebalance on `of-match-perf-128` (git
+`ec06915`, after `start_match` accepted). Report:
+`artifacts/browser/reconnect-under-load-20260807.json`.
+
+| Metric | Value |
+| --- | ---: |
+| cycles | 20 |
+| p50 disconnect→reclaim | 186 ms |
+| p95 | 191 ms |
+| max | 196 ms |
+| budget | p95 ≤ 5000 ms |
+
+Gate result under concurrent load: **PASS**.
 
 Provisional budget: disconnect→reclaim **p95 ≤ 5000 ms** over the soak report.
 
@@ -188,19 +204,18 @@ running 192 match: page reload restored `net.connected` / bootstrap and
 `cells=36864` with ~60 FPS. In that session leftover CDP tabs still held both
 seats, so `join_match` returned “all player slots are already claimed” rather
 than a clean token reclaim — treat this as **map rebuild after reload**
-evidence, not a full seat-reclaim proof. Concurrent `match-perf` under-load
-soak remains open.
+evidence, not a full seat-reclaim proof.
 
-### Still required for full browser qualification
+### Still optional for deeper qualification
 
-1. Run the native soak under concurrent `match-perf` workers and file the JSON.
-2. Optional later: the architecture’s 30-minute soak with scheduler recovery.
+1. Architecture’s 30-minute soak with scheduler recovery.
+2. Browser-path seat reclaim (not just map rebuild) with a single owning tab.
 
 ## CI / deploy hooks
 
 | Pipeline | Browser-related check |
 | --- | --- |
-| `.github/workflows/ci.yml` | Wasm **compile/lint** only (no Trunk artifact, no size gate) |
+| `.github/workflows/ci.yml` | Wasm **compile/lint** + live local `match-e2e` smoke job |
 | `.github/workflows/deploy.yml` | Trunk production build, then `measure-web-bundle.sh --enforce` |
 | Local | `measure-web-bundle.sh`, `run-reconnect-soak.sh`, manual/CDP WebGPU procedure |
 
@@ -213,6 +228,6 @@ soak remains open.
 - [x] Record isolated reconnect soak JSON (5-cycle PASS; extend to 20+ at will)
 - [x] Record WebGPU 128 sample (PASS JSON)
 - [x] Record WebGPU 192 sample (PASS JSON)
-- [ ] Record reconnect soak JSON under concurrent `match-perf` load
+- [x] Record reconnect soak JSON under concurrent `match-perf` load
 - [x] Manual browser reconnect smoke on the live path (reload restored map; seat reclaim still contested when other tabs hold slots)
-- [ ] Flip architecture/implementation wording from “unqualified” to measured status when under-load reconnect evidence also lands
+- [x] Flip gate summary for under-load reconnect to measured PASS
diff --git a/docs/implementation.md b/docs/implementation.md
index 9a695d1..defae34 100644
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -355,8 +355,10 @@ selection-adjacent presentation from the new authoritative snapshot.
   region-selection architecture.
 - Population/mobilization uses a provisional full-state cadence and leaves
   military headroom for unreceived active internal-order destinations.
-  Movement and combat use active sets, but nominal/stress performance gates
-  still need representative playtest measurement.
+  Movement and combat use active sets. Representative `match-perf` baselines for
+  128-seat playtest/validation dilation are recorded in
+  [Performance profiling](./performance.md); 500-seat nominal and 256×256
+  stretch remain larger follow-ups.
 - There is no morale, explicit supply penalty, HQ defeat, time limit,
   economy/upkeep, demobilization, infrastructure, fog, armor, naval/air force,
   diplomacy, AI, matchmaking, or production art.
@@ -366,10 +368,10 @@ selection-adjacent presentation from the new authoritative snapshot.
   ongoing economic burden.
 - Native desktop and WebAssembly/WebGPU compile targets are supported. The web
   target uses `localStorage` credentials and asynchronous browser networking.
-  Wasm size and the measured 128/192 WebGPU frame budgets pass, and isolated
-  reconnect plus browser reload smoke are recorded; reconnect under concurrent
-  load remains unqualified. See [Browser release gates](./browser-gates.md) for
-  the evidence and remaining reconnect gate.
+  Wasm size, measured 128/192 WebGPU frame budgets, isolated reconnect, and
+  reconnect under concurrent `match-perf` load all **PASS**; see
+  [Browser release gates](./browser-gates.md). Browser-tab seat reclaim (vs map
+  rebuild after reload) remains a thinner evidence path.
 
 These are bounded omissions, not hidden placeholders. Candidate extensions and
 their dependencies are recorded in [future ideas](./future-ideas.md).
diff --git a/docs/performance.md b/docs/performance.md
index dbf1c4a..c6e1ce8 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -265,6 +265,28 @@ Authority remains **one scheduled reducer and one atomic simulation tick**.
 loaded via `source_by_order` for the union of active packet order IDs **and**
 active transfer order IDs (queued sources on active orders with no packet yet).
 
+## Recorded baselines (2026-08-07)
+
+Budgets from [technical architecture](./technical-architecture.md): cadence
+250 ms; nominal active-step processing p95 **&lt; 62.5 ms**; stretch **&lt; 125 ms**.
+`match-perf` reports client-observed wall-clock ms/step (includes cadence).
+Processing dilation ≈ `max(0, observed_p95 − 250)`.
+
+| Scenario | Preset / seats | observed p50 / p95 ms/step | dilation p95 | vs budget | Artifact dir |
+| --- | --- | ---: | ---: | --- | --- |
+| Nominal-ish 128 | `playtest` / 128 | 251.0 / 268.3 | **18.3 ms** | **PASS** (&lt; 62.5) | `artifacts/performance/runs/playtest128-20260807T181657Z` |
+| Stretch map 192 | `validation` / 128 | 250.0 / 269.1 | **19.1 ms** | **PASS** (&lt; 62.5 / &lt; 125) | `artifacts/performance/runs/validation-nominal-20260807T181753Z` |
+
+Notes: both 128-seat runs failures=0. The playtest run hit max packets 1813 /
+fronts 1502; validation hit max packets 1817 / fronts 1407. p99/max show rare
+spikes while p95 stays near cadence. A 500-seat validation attempt on this host
+failed during lobby joins with WebSocket handshake errors (connection limits);
+raise `ulimit -n` / ephemeral ports before treating that as a module regression.
+True architecture stretch (256×256) remains an unbuilt map preset.
+
+`match-perf` calls `start_match` from player 1 after all seats are claimed
+(interactive lobby cutover removed auto-start on join).
+
 ## Authority boundary and caveats
 
 - **One match database, one scheduled simulation.** Distributing `match-perf`
diff --git a/docs/playtests/cluster-controls-v1-results-2026-08-07.md b/docs/playtests/cluster-controls-v1-results-2026-08-07.md
index 9f5ead6..f18241a 100644
--- a/docs/playtests/cluster-controls-v1-results-2026-08-07.md
+++ b/docs/playtests/cluster-controls-v1-results-2026-08-07.md
@@ -3,7 +3,7 @@
 ## Session
 
 - Method: desk review + code inspection; no GUI session was run.
-- Git SHA: `8037c75` (working tree contains unrelated WIP).
+- Git SHA: `ec06915` (+ docs commits after desk review).
 - Intended local endpoint: `http://127.0.0.1:3000`.
 - Blocker: the checked-in local data directory contains `spacetime.pid` owned
   by PID 41307, but the endpoint was not reachable. Starting another server
diff --git a/docs/playtests/production-e2e-smoke-2026-08-07.md b/docs/playtests/production-e2e-smoke-2026-08-07.md
new file mode 100644
index 0000000..0af2224
--- /dev/null
+++ b/docs/playtests/production-e2e-smoke-2026-08-07.md
@@ -0,0 +1,35 @@
+# Production E2E smoke — 2026-08-07
+
+Target: `https://of.carlid.dev` + Maincloud `of-lobby` / provisioned match DB.
+
+## Procedure
+
+1. `GET /api/lobbies` — empty directory.
+2. Create two anonymous sessions via `POST /api/session`.
+3. Create lobby `fbd65f9a` (small / 2 players) as smoke-p1 → provisioned
+   `of-match-fbd65f9a`, status `open`.
+4. Join as smoke-p2 → status `full`, memberCount 2.
+5. Confirm lobby listed; no Pending/Provisioning orphans.
+6. `match-e2e` against Maincloud with session tokens:
+   - Full gameplay smoke joined and started, then failed a map-geometry
+     front-push progression assert (not a provisioning/start failure).
+   - `--reconnect-only --reconnect-cycles 5` **PASS** (p50 1278 ms, p95 1328 ms,
+     max 1336 ms; budget ≤ 5000 ms).
+7. Leave p2 then p1 → lobby row deleted; directory empty again.
+8. Best-effort `spacetime delete --server maincloud of-match-fbd65f9a`.
+
+## Result
+
+**PASS** for create/join/start/reconnect/leave cleanup of lobby rows.
+No orphan Pending lobbies remained.
+
+Raw JSON (gitignored): `artifacts/browser/production-e2e-smoke-2026-08-07.json`,
+`artifacts/browser/production-reconnect-smoke.json`.
+
+## Gaps
+
+- Browser WebGPU play on production was not exercised in this pass (API + SDK).
+- Match-database auto-delete on leave requires the Vercel cleanup deploy from
+  this branch; smoke used CLI delete as belt-and-suspenders.
+- Full gameplay e2e geometry assert is flaky on provisioned small maps; prefer
+  reconnect-only + selective reducer checks for production smokes.
diff --git a/scripts/run-reconnect-soak.sh b/scripts/run-reconnect-soak.sh
index e55bca2..09b3982 100755
--- a/scripts/run-reconnect-soak.sh
+++ b/scripts/run-reconnect-soak.sh
@@ -17,8 +17,9 @@
 #   ./scripts/run-reconnect-soak.sh --fresh --cycles 20
 #
 #   # Against an in-flight match-perf database while workers are busy
-#   ./scripts/run-reconnect-soak.sh --database of-match-perf --cycles 30
-#   # (use match-e2e --player-one-token / --player-two-token for worker seats)
+#   ./scripts/run-reconnect-soak.sh --database of-match-perf --cycles 30 \
+#     --player-one-token .match-perf-tokens/player-1.token \
+#     --player-two-token .match-perf-tokens/player-2.token
 set -euo pipefail
 
 script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
@@ -31,6 +32,8 @@ cycles="${OF_RECONNECT_CYCLES:-20}"
 timeout_secs="${OF_RECONNECT_TIMEOUT_SECS:-60}"
 fresh=0
 out_path=""
+player_one_token=""
+player_two_token=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -40,13 +43,15 @@ while [[ $# -gt 0 ]]; do
     --cycles) cycles="$2"; shift 2 ;;
     --timeout-secs) timeout_secs="$2"; shift 2 ;;
     --fresh) fresh=1; shift ;;
+    --player-one-token) player_one_token="$2"; shift 2 ;;
+    --player-two-token) player_two_token="$2"; shift 2 ;;
     --skip-setup)
       # Accepted for compatibility; soak always uses reconnect-only.
       shift
       ;;
     --out) out_path="$2"; shift 2 ;;
     -h|--help)
-      sed -n '2,22p' "$0"
+      sed -n '2,24p' "$0"
       exit 0
       ;;
     *)
@@ -88,6 +93,12 @@ extra_args=(
   --reconnect-cycles "${cycles}"
   --reconnect-report "${out_path}"
 )
+if [[ -n "${player_one_token}" ]]; then
+  extra_args+=(--player-one-token "${player_one_token}")
+fi
+if [[ -n "${player_two_token}" ]]; then
+  extra_args+=(--player-two-token "${player_two_token}")
+fi
 
 echo "running reconnect soak: database=${database} cycles=${cycles}"
 cargo run -q -p match-e2e -- "${extra_args[@]}"