aetheris_client_wasm/

lib.rs

//! Aetheris WASM client logic.
//!
//! This crate implements the browser-based client for the Aetheris Engine,
//! using `WebWorkers` for multi-threaded execution and `WebGPU` for rendering.

#![warn(clippy::all, clippy::pedantic)]
// Required to declare `#[thread_local]` statics on nightly (wasm32 target).
// This feature gate is only active when compiling for WASM — see the
// `_TLS_ANCHOR` declaration below.
#![cfg_attr(
    all(target_arch = "wasm32", feature = "nightly"),
    feature(thread_local)
)]

pub mod auth;
pub mod shared_world;
pub mod world_state;

#[cfg(target_arch = "wasm32")]
pub mod metrics;

#[cfg(test)]
#[cfg(target_arch = "wasm32")]
pub mod smoke_test;

/// Protobuf message types generated from `auth.proto` (prost only — no service stubs).
/// Used by `auth.rs` so it doesn't need the `aetheris-protocol` `grpc` feature,
/// which would pull in `tonic::transport` and hence `mio` (incompatible with wasm32).
pub mod auth_proto {
    #![allow(clippy::must_use_candidate, clippy::doc_markdown)]
    tonic::include_proto!("aetheris.auth.v1");
}

#[cfg(target_arch = "wasm32")]
pub mod transport;

#[cfg(test)]
pub mod transport_mock;

#[cfg(target_arch = "wasm32")]
pub mod render;

#[cfg(any(target_arch = "wasm32", test))]
pub mod render_primitives;

#[cfg(any(target_arch = "wasm32", test))]
pub mod assets;

#[cfg(target_arch = "wasm32")]
#[cfg_attr(feature = "nightly", thread_local)]
static _TLS_ANCHOR: u8 = 0;

use std::sync::atomic::AtomicUsize;
#[cfg(target_arch = "wasm32")]
use std::sync::atomic::Ordering;

#[allow(dead_code)]
static NEXT_WORKER_ID: AtomicUsize = AtomicUsize::new(1);

#[cfg(target_arch = "wasm32")]
thread_local! {
    static WORKER_ID: usize = NEXT_WORKER_ID.fetch_add(1, Ordering::Relaxed);
}

/// Helper to get `performance.now()` in both Window and Worker contexts.
#[must_use]
pub fn performance_now() -> f64 {
    #[cfg(target_arch = "wasm32")]
    {
        use wasm_bindgen::JsCast;
        let global = js_sys::global();

        // Try WorkerGlobalScope first
        if let Ok(worker) = global.clone().dyn_into::<web_sys::WorkerGlobalScope>() {
            return worker.performance().map(|p| p.now()).unwrap_or(0.0);
        }

        // Try Window
        if let Ok(window) = global.dyn_into::<web_sys::Window>() {
            return window.performance().map(|p| p.now()).unwrap_or(0.0);
        }

        // Fallback to Date
        js_sys::Date::now()
    }
    #[cfg(not(target_arch = "wasm32"))]
    {
        0.0
    }
}

#[allow(dead_code)]
pub(crate) fn get_worker_id() -> usize {
    #[cfg(target_arch = "wasm32")]
    {
        WORKER_ID.with(|&id| id)
    }
    #[cfg(not(target_arch = "wasm32"))]
    {
        0
    }
}

#[cfg(target_arch = "wasm32")]
mod wasm_impl {
    use crate::assets;
    use crate::metrics::with_collector;
    use crate::performance_now;
    use crate::render::RenderState;
    use crate::shared_world::{MAX_ENTITIES, SabSlot, SharedWorld};
    use crate::transport::WebTransportBridge;
    use crate::world_state::ClientWorld;
    use aetheris_encoder_serde::SerdeEncoder;
    use aetheris_protocol::events::{NetworkEvent, ReplicationEvent};
    use aetheris_protocol::traits::{Encoder, GameTransport, WorldState};
    use aetheris_protocol::types::{
        ClientId, ComponentKind, InputCommand, NetworkId, PlayerInputKind,
    };
    use wasm_bindgen::prelude::*;

    #[wasm_bindgen]
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub enum ConnectionState {
        Disconnected,
        Connecting,
        InGame,
        Reconnecting,
        Failed,
    }

    /// A snapshot of the world for interpolation.
    #[derive(Clone)]
    pub struct SimulationSnapshot {
        pub tick: u64,
        pub entities: Vec<SabSlot>,
    }

    /// Global state held by the WASM instance.
    #[wasm_bindgen]
    pub struct AetherisClient {
        pub(crate) shared_world: SharedWorld,
        pub(crate) world_state: ClientWorld,
        pub(crate) render_state: Option<RenderState>,
        pub(crate) transport: Option<Box<dyn GameTransport>>,
        pub(crate) worker_id: usize,
        pub(crate) session_token: Option<String>,

        // Interpolation state (Render Worker only)
        pub(crate) snapshots: std::collections::VecDeque<SimulationSnapshot>,

        // Network metrics
        pub(crate) last_rtt_ms: f64,
        ping_counter: u64,

        reassembler: aetheris_protocol::Reassembler,
        connection_state: ConnectionState,
        reconnect_attempts: u32,
        playground_rotation_enabled: bool,
        playground_next_network_id: u64,
        first_playground_tick: bool,

        // Reusable buffer for zero-allocation rendering (Render Worker only)
        pub(crate) render_buffer: Vec<SabSlot>,
        pub(crate) asset_registry: assets::AssetRegistry,

        // Input noise reduction
        last_input_target: Option<NetworkId>,
        last_input_actions: Vec<PlayerInputKind>,

        pending_clear: bool,
        last_clear_tick: u64,

        // Fixed-Timestep Simulation (M10105/M1020)
        last_process_time: f64,
        tick_accumulator: f64,

        // Playground Input Buffering
        playground_move_x: f32,
        playground_move_y: f32,
        playground_actions: u32,
        last_fraction: f32,
        last_actions_mask: u32,
    }

    #[wasm_bindgen]
    impl AetherisClient {
        /// Creates a new AetherisClient instance.
        /// If a pointer is provided, it will use it as the backing storage (shared memory).
        #[wasm_bindgen(constructor)]
        pub fn new(shared_world_ptr: Option<u32>) -> Result<AetherisClient, JsValue> {
            console_error_panic_hook::set_once();

            // tracing_wasm doesn't have a clean try_init for global default.
            // We use a static atomic to ensure only the first worker sets the global default.
            use std::sync::atomic::{AtomicBool, Ordering};
            static LOGGER_INITIALIZED: AtomicBool = AtomicBool::new(false);
            if !LOGGER_INITIALIZED.swap(true, Ordering::SeqCst) {
                let config = tracing_wasm::WASMLayerConfigBuilder::new()
                    .set_max_level(tracing::Level::INFO)
                    .build();
                tracing_wasm::set_as_global_default_with_config(config);
            }

            let shared_world = if let Some(ptr_val) = shared_world_ptr {
                let ptr = ptr_val as *mut u8;

                // Security: Validate the incoming pointer before use
                if ptr_val == 0 || !ptr_val.is_multiple_of(8) {
                    return Err(JsValue::from_str(
                        "Invalid shared_world_ptr: null or unaligned",
                    ));
                }

                // JS-allocated SharedArrayBuffer pointers are not in the Rust registry
                // (only Rust-owned allocations are registered). The null/alignment checks
                // above are the only feasible boundary validation for externally-provided
                // pointers; trusting the caller is required by the SAB contract.
                unsafe { SharedWorld::from_ptr(ptr) }
            } else {
                SharedWorld::new()
            };

            let global = js_sys::global();
            let (ua, lang) =
                if let Ok(worker) = global.clone().dyn_into::<web_sys::WorkerGlobalScope>() {
                    let n = worker.navigator();
                    (n.user_agent().ok(), n.language())
                } else if let Ok(window) = global.dyn_into::<web_sys::Window>() {
                    let n = window.navigator();
                    (n.user_agent().ok(), n.language())
                } else {
                    (None, None)
                };

            tracing::info!(
                "Aetheris Client: Environment [UA: {}, Lang: {}]",
                ua.as_deref().unwrap_or("Unknown"),
                lang.as_deref().unwrap_or("Unknown")
            );

            tracing::info!(
                "AetherisClient initialized on worker {}",
                crate::get_worker_id()
            );

            // M10105 — emit wasm_init lifecycle span
            with_collector(|c| {
                c.push_event(
                    1,
                    "wasm_client",
                    "AetherisClient initialized",
                    "wasm_init",
                    None,
                );
            });

            let mut world_state = ClientWorld::new();
            world_state.shared_world_ref = Some(shared_world.as_ptr() as usize);

            Ok(Self {
                shared_world,
                world_state,
                render_state: None,
                transport: None,
                worker_id: crate::get_worker_id(),
                session_token: None,
                snapshots: std::collections::VecDeque::with_capacity(8),
                last_rtt_ms: 0.0,
                ping_counter: 0,
                reassembler: aetheris_protocol::Reassembler::new(),
                connection_state: ConnectionState::Disconnected,
                reconnect_attempts: 0,
                playground_rotation_enabled: false,
                playground_next_network_id: 1,
                first_playground_tick: true,
                render_buffer: Vec::with_capacity(crate::shared_world::MAX_ENTITIES),
                asset_registry: assets::AssetRegistry::new(),
                last_input_target: None,
                last_input_actions: Vec::new(),
                pending_clear: false,
                last_clear_tick: 0,
                last_process_time: crate::performance_now(),
                tick_accumulator: 0.0,
                playground_move_x: 0.0,
                playground_move_y: 0.0,
                playground_actions: 0,
                last_fraction: 0.0,
                last_actions_mask: 0,
            })
        }

        #[wasm_bindgen]
        pub fn set_view_state(&mut self, state: u32) {
            use crate::render::ViewState;
            let state = match state {
                0 => ViewState::Logo,
                1 => ViewState::Roaming,
                2 => ViewState::Entering,
                3 => ViewState::Playing,
                _ => return,
            };

            if let Some(rs) = &mut self.render_state {
                rs.set_view_state(state);
            } else {
                tracing::warn!("set_view_state called but render_state is None");
            }
        }

        #[wasm_bindgen]
        pub async fn request_otp(base_url: String, email: String) -> Result<String, String> {
            crate::auth::request_otp(base_url, email).await
        }

        #[wasm_bindgen]
        pub async fn login_with_otp(
            base_url: String,
            request_id: String,
            code: String,
        ) -> Result<String, String> {
            crate::auth::login_with_otp(base_url, request_id, code).await
        }

        #[wasm_bindgen]
        pub async fn logout(base_url: String, session_token: String) -> Result<(), String> {
            crate::auth::logout(base_url, session_token).await
        }

        #[wasm_bindgen(getter)]
        pub fn connection_state(&self) -> ConnectionState {
            self.connection_state
        }

        fn check_worker(&self) {
            debug_assert_eq!(
                self.worker_id,
                crate::get_worker_id(),
                "AetherisClient accessed from wrong worker! It is pin-bound to its creating thread."
            );
        }

        /// Returns the raw pointer to the shared world buffer.
        pub fn shared_world_ptr(&self) -> u32 {
            self.shared_world.as_ptr() as u32
        }

        pub async fn connect(
            &mut self,
            url: String,
            cert_hash: Option<Vec<u8>>,
        ) -> Result<(), JsValue> {
            self.check_worker();

            if self.connection_state == ConnectionState::Connecting
                || self.connection_state == ConnectionState::InGame
                || self.connection_state == ConnectionState::Reconnecting
            {
                return Ok(());
            }

            // M10105 — emit reconnect_attempt if it looks like one
            if self.connection_state == ConnectionState::Failed && self.reconnect_attempts > 0 {
                with_collector(|c| {
                    c.push_event(
                        2,
                        "transport",
                        "Triggering reconnection",
                        "reconnect_attempt",
                        None,
                    );
                });
            }

            self.connection_state = ConnectionState::Connecting;
            tracing::info!(url = %url, "Connecting to server...");

            let transport_result = WebTransportBridge::connect(&url, cert_hash.as_deref()).await;

            match transport_result {
                Ok(transport) => {
                    // Security: Send Auth message immediately after connection
                    if let Some(token) = &self.session_token {
                        let encoder = SerdeEncoder::new();
                        let auth_event = NetworkEvent::Auth {
                            session_token: token.clone(),
                        };

                        match encoder.encode_event(&auth_event) {
                            Ok(data) => {
                                if let Err(e) = transport.send_reliable(ClientId(0), &data).await {
                                    self.connection_state = ConnectionState::Failed;
                                    tracing::error!(error = ?e, "Handshake failed: could not send auth packet");
                                    return Err(JsValue::from_str(&format!(
                                        "Failed to send auth packet: {:?}",
                                        e
                                    )));
                                }
                                tracing::info!("Auth packet sent to server");
                            }
                            Err(e) => {
                                self.connection_state = ConnectionState::Failed;
                                tracing::error!(error = ?e, "Handshake failed: could not encode auth packet");
                                return Err(JsValue::from_str("Failed to encode auth packet"));
                            }
                        }
                    } else {
                        tracing::warn!(
                            "Connecting without session token! Server will likely discard data."
                        );
                    }

                    self.transport = Some(Box::new(transport));
                    self.connection_state = ConnectionState::InGame;
                    self.reconnect_attempts = 0;
                    tracing::info!("WebTransport connection established");
                    // M10105 — connect_handshake lifecycle span
                    with_collector(|c| {
                        c.push_event(
                            1,
                            "transport",
                            &format!("WebTransport connected: {url}"),
                            "connect_handshake",
                            None,
                        );
                    });
                    Ok(())
                }
                Err(e) => {
                    self.connection_state = ConnectionState::Failed;
                    tracing::error!(error = ?e, "Failed to establish WebTransport connection");
                    // M10105 — connect_handshake_failed lifecycle span (ERROR level)
                    with_collector(|c| {
                        c.push_event(
                            3,
                            "transport",
                            &format!("WebTransport failed: {url} — {e:?}"),
                            "connect_handshake_failed",
                            None,
                        );
                    });
                    Err(JsValue::from_str(&format!("failed to connect: {e:?}")))
                }
            }
        }

        #[wasm_bindgen]
        pub async fn reconnect(
            &mut self,
            url: String,
            cert_hash: Option<Vec<u8>>,
        ) -> Result<(), JsValue> {
            self.check_worker();
            self.connection_state = ConnectionState::Reconnecting;
            self.reconnect_attempts += 1;

            tracing::info!(
                "Attempting reconnection... (attempt {})",
                self.reconnect_attempts
            );

            self.connect(url, cert_hash).await
        }

        #[wasm_bindgen]
        pub async fn wasm_load_asset(
            &mut self,
            handle: assets::AssetHandle,
            url: String,
        ) -> Result<(), JsValue> {
            self.asset_registry.load_asset(handle, &url).await
        }

        /// Sets the session token to be used for authentication upon connection.
        pub fn set_session_token(&mut self, token: String) {
            self.session_token = Some(token);
        }

        /// Initializes rendering with a canvas element.
        /// Accepts either web_sys::HtmlCanvasElement or web_sys::OffscreenCanvas.
        pub async fn init_renderer(&mut self, canvas: JsValue) -> Result<(), JsValue> {
            self.check_worker();
            use wasm_bindgen::JsCast;

            let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
                backends: wgpu::Backends::BROWSER_WEBGPU | wgpu::Backends::GL,
                flags: wgpu::InstanceFlags::default(),
                ..wgpu::InstanceDescriptor::new_without_display_handle()
            });

            // Handle both HtmlCanvasElement and OffscreenCanvas for Worker support
            let (surface_target, width, height) =
                if let Ok(html_canvas) = canvas.clone().dyn_into::<web_sys::HtmlCanvasElement>() {
                    let width = html_canvas.width();
                    let height = html_canvas.height();
                    tracing::info!(
                        "Initializing renderer on HTMLCanvasElement ({}x{})",
                        width,
                        height
                    );
                    (wgpu::SurfaceTarget::Canvas(html_canvas), width, height)
                } else if let Ok(offscreen_canvas) =
                    canvas.clone().dyn_into::<web_sys::OffscreenCanvas>()
                {
                    let width = offscreen_canvas.width();
                    let height = offscreen_canvas.height();
                    tracing::info!(
                        "Initializing renderer on OffscreenCanvas ({}x{})",
                        width,
                        height
                    );

                    // Critical fix for wgpu 0.20+ on WASM workers:
                    // Ensure the context is initialized with the 'webgpu' id before creating the surface.
                    let _ = offscreen_canvas.get_context("webgpu").map_err(|e| {
                        JsValue::from_str(&format!("Failed to get webgpu context: {:?}", e))
                    })?;

                    (
                        wgpu::SurfaceTarget::OffscreenCanvas(offscreen_canvas),
                        width,
                        height,
                    )
                } else {
                    return Err(JsValue::from_str(
                        "Aetheris: Provided object is not a valid Canvas or OffscreenCanvas",
                    ));
                };

            let surface = instance
                .create_surface(surface_target)
                .map_err(|e| JsValue::from_str(&format!("Failed to create surface: {:?}", e)))?;

            let render_state = RenderState::new(&instance, surface, width, height)
                .await
                .map_err(|e| JsValue::from_str(&format!("Failed to init renderer: {:?}", e)))?;

            self.render_state = Some(render_state);

            // M10105 — emit render_pipeline_setup lifecycle span
            with_collector(|c| {
                c.push_event(
                    1,
                    "render_worker",
                    &format!("Renderer initialized ({}x{})", width, height),
                    "render_pipeline_setup",
                    None,
                );
            });

            Ok(())
        }

        #[wasm_bindgen]
        pub fn resize(&mut self, width: u32, height: u32) {
            if let Some(state) = &mut self.render_state {
                state.resize(width, height);
            }
        }

        #[cfg(debug_assertions)]
        #[wasm_bindgen]
        pub fn set_debug_mode(&mut self, mode: u32) {
            self.check_worker();
            if let Some(state) = &mut self.render_state {
                state.set_debug_mode(match mode {
                    0 => crate::render::DebugRenderMode::Off,
                    1 => crate::render::DebugRenderMode::Wireframe,
                    2 => crate::render::DebugRenderMode::Components,
                    _ => crate::render::DebugRenderMode::Full,
                });
            }
        }

        #[wasm_bindgen]
        pub fn set_theme_colors(&mut self, bg_base: &str, text_primary: &str) {
            self.check_worker();
            let clear = crate::render::parse_css_color(bg_base);
            let label = crate::render::parse_css_color(text_primary);

            tracing::info!(
                "Aetheris Client: Applying theme colors [bg: {} -> {:?}, text: {} -> {:?}]",
                bg_base,
                clear,
                text_primary,
                label
            );

            if let Some(state) = &mut self.render_state {
                state.set_clear_color(clear);
                #[cfg(debug_assertions)]
                state.set_label_color([
                    label.r as f32,
                    label.g as f32,
                    label.b as f32,
                    label.a as f32,
                ]);
            }
        }

        #[cfg(debug_assertions)]
        #[wasm_bindgen]
        pub fn cycle_debug_mode(&mut self) {
            if let Some(state) = &mut self.render_state {
                state.cycle_debug_mode();
            }
        }

        #[cfg(debug_assertions)]
        #[wasm_bindgen]
        pub fn toggle_grid(&mut self) {
            if let Some(state) = &mut self.render_state {
                state.toggle_grid();
            }
        }

        #[wasm_bindgen]
        pub fn latest_tick(&self) -> u64 {
            self.world_state.latest_tick
        }

        #[wasm_bindgen]
        pub fn playground_apply_input(&mut self, move_x: f32, move_y: f32, actions_mask: u32) {
            self.check_worker();
            self.playground_move_x = move_x;
            self.playground_move_y = move_y;
            self.playground_actions = actions_mask;
        }

        /// Simulation tick called by the Network Worker at a fixed rate (e.g. 20Hz).
        pub async fn tick(&mut self) {
            self.check_worker();
            use aetheris_protocol::traits::{Encoder, WorldState};

            let encoder = SerdeEncoder::new();

            // 0. Reconnection Logic
            // TODO: poll transport.closed() promise and trigger reconnection state machine
            if let Some(_transport) = &self.transport {}

            // 0.1 Periodic Ping (approx. every 1 second at 60Hz)
            if let Some(transport) = &mut self.transport {
                self.ping_counter = self.ping_counter.wrapping_add(1);
                if self.ping_counter % 60 == 0 {
                    // Use current time as timestamp (ms)
                    let now = performance_now();
                    let tick_u64 = now as u64;

                    if let Ok(data) = encoder.encode_event(&NetworkEvent::Ping {
                        client_id: ClientId(0), // Client doesn't know its ID yet usually
                        tick: tick_u64,
                    }) {
                        tracing::trace!(tick = tick_u64, "Sending Ping");
                        let _ = transport.send_unreliable(ClientId(0), &data).await;
                    }
                }
            }

            // 1. Poll Network
            if let Some(transport) = &mut self.transport {
                let events = match transport.poll_events().await {
                    Ok(e) => e,
                    Err(e) => {
                        tracing::error!("Transport poll failure: {:?}", e);
                        return;
                    }
                };
                let mut updates: Vec<(ClientId, aetheris_protocol::events::ComponentUpdate)> =
                    Vec::new();

                for event in events {
                    match event {
                        NetworkEvent::UnreliableMessage { data, client_id }
                        | NetworkEvent::ReliableMessage { data, client_id } => {
                            match encoder.decode(&data) {
                                Ok(update) => {
                                    // M10105 — Always filter by epoch tick so stale datagrams are
                                    // rejected even after the reliable ClearWorld ack has lowered
                                    // pending_clear (unreliable datagrams may overtake the ack).
                                    if self.last_clear_tick == 0
                                        || update.tick > self.last_clear_tick
                                    {
                                        updates.push((client_id, update));
                                    } else {
                                        tracing::debug!(
                                            network_id = update.network_id.0,
                                            tick = update.tick,
                                            last_clear_tick = self.last_clear_tick,
                                            "Discarding stale update (tick <= last_clear_tick)"
                                        );
                                    }
                                }
                                Err(_) => {
                                    // Try to decode as a protocol/wire event instead
                                    if let Ok(event) = encoder.decode_event(&data) {
                                        match event {
                                            aetheris_protocol::events::NetworkEvent::GameEvent {
                                                event: game_event,
                                                ..
                                            } => match &game_event {
                                                aetheris_protocol::events::GameEvent::AsteroidDepleted {
                                                    network_id,
                                                } => {
                                                    tracing::info!(?network_id, "Asteroid depleted");
                                                    self.world_state.entities.remove(&network_id);

                                                    for slot in self.world_state.entities.values_mut() {
                                                        if (slot.flags & 0x04) != 0
                                                            && slot.mining_target_id == (network_id.0 as u16)
                                                        {
                                                            slot.mining_active = 0;
                                                            slot.mining_target_id = 0;
                                                            tracing::info!("Cleared local mining target due to depletion");
                                                        }
                                                    }
                                                }
                                                aetheris_protocol::events::GameEvent::Possession {
                                                    network_id: _,
                                                }
                                                | aetheris_protocol::events::GameEvent::DamageEvent { .. }
                                                | aetheris_protocol::events::GameEvent::DeathEvent { .. }
                                                | aetheris_protocol::events::GameEvent::RespawnEvent { .. }
                                                | aetheris_protocol::events::GameEvent::CargoCollected { .. } => {
                                                    self.world_state.handle_game_event(&game_event);
                                                }
                                                aetheris_protocol::events::GameEvent::SystemManifest {
                                                    manifest,
                                                } => {
                                                    tracing::debug!(
                                                        count = manifest.len(),
                                                        "Received SystemManifest from server"
                                                    );
                                                    self.world_state.system_manifest = manifest.clone();
                                                }
                                            },
                                            aetheris_protocol::events::NetworkEvent::ClearWorld {
                                                ..
                                            } => {
                                                tracing::info!(
                                                    "Server ClearWorld ack received (via ReliableMessage) — gate lowered"
                                                );
                                                self.pending_clear = false;
                                            }
                                            _ => {}
                                        }
                                    } else {
                                        tracing::warn!(
                                            "Failed to decode server message as update or wire event"
                                        );
                                    }
                                }
                            }
                        }
                        NetworkEvent::ClientConnected(id) => {
                            tracing::info!(?id, "Server connected");
                        }
                        NetworkEvent::ClientDisconnected(id) => {
                            tracing::warn!(?id, "Server disconnected");
                        }
                        NetworkEvent::Disconnected(_id) => {
                            tracing::error!("Transport disconnected locally");
                            self.connection_state = ConnectionState::Disconnected;
                        }
                        NetworkEvent::Ping { client_id: _, tick } => {
                            // Immediately reflect the ping as a pong with same tick
                            let pong = NetworkEvent::Pong { tick };
                            if let Ok(data) = encoder.encode_event(&pong) {
                                let _ = transport.send_reliable(ClientId(0), &data).await;
                            }
                        }
                        NetworkEvent::Pong { tick } => {
                            // Calculate RTT from our own outgoing pings
                            let now = performance_now();
                            let rtt = now - (tick as f64);
                            self.last_rtt_ms = rtt;

                            with_collector(|c| {
                                c.update_rtt(rtt);
                            });

                            #[cfg(feature = "metrics")]
                            metrics::gauge!("aetheris_client_rtt_ms").set(rtt);

                            tracing::trace!(rtt_ms = rtt, tick, "Received Pong / RTT update");
                        }
                        NetworkEvent::Auth { .. } => {
                            // Client initiated event usually, ignore if received from server
                            tracing::debug!("Received Auth event from server (unexpected)");
                        }
                        NetworkEvent::SessionClosed(id) => {
                            tracing::warn!(?id, "WebTransport session closed");
                        }
                        NetworkEvent::StreamReset(id) => {
                            tracing::error!(?id, "WebTransport stream reset");
                        }
                        NetworkEvent::ReplicationBatch { events, client_id } => {
                            for event in events {
                                if self.last_clear_tick == 0 || event.tick > self.last_clear_tick {
                                    updates.push((
                                        client_id,
                                        aetheris_protocol::events::ComponentUpdate {
                                            network_id: event.network_id,
                                            component_kind: event.component_kind,
                                            payload: event.payload,
                                            tick: event.tick,
                                        },
                                    ));
                                }
                            }
                        }
                        NetworkEvent::Fragment {
                            client_id,
                            fragment,
                        } => {
                            if let Some(data) = self.reassembler.ingest(client_id, fragment) {
                                if let Ok(update) = encoder.decode(&data) {
                                    if self.last_clear_tick == 0
                                        || update.tick > self.last_clear_tick
                                    {
                                        updates.push((client_id, update));
                                    }
                                }
                            }
                        }
                        NetworkEvent::StressTest { .. } => {
                            // Client-side, we don't handle incoming stress test events usually,
                            // they are processed by the server.
                        }
                        NetworkEvent::Spawn { .. } => {
                            // Handled by GameWorker via p_spawn
                        }
                        NetworkEvent::ClearWorld { .. } => {
                            // Reliable ack: guaranteed to arrive after all unreliable
                            // datagrams sent before it (QUIC ordering).  Lower the gate
                            // and do a final flush — from this point forward, no stale
                            // entity updates can arrive.
                            tracing::info!("Server ClearWorld ack received — gate lowered");
                            self.pending_clear = false;
                        }
                        NetworkEvent::GameEvent {
                            event: game_event, ..
                        } => {
                            // Forward to inner GameEvent logic if needed,
                            // or just handle the depletion here if it's the only one.
                            match &game_event {
                                aetheris_protocol::events::GameEvent::AsteroidDepleted {
                                    network_id,
                                } => {
                                    tracing::info!(
                                        ?network_id,
                                        "Asteroid depleted (via GameEvent)"
                                    );
                                    // Instant local despawn to hide latency
                                    self.world_state.entities.remove(&network_id);

                                    // Clear local mining target if it matches the depleted asteroid
                                    for slot in self.world_state.entities.values_mut() {
                                        // flags & 0x04 is local player
                                        if (slot.flags & 0x04) != 0
                                            && slot.mining_target_id == (network_id.0 as u16)
                                        {
                                            slot.mining_active = 0;
                                            slot.mining_target_id = 0;
                                            tracing::info!(
                                                "Cleared local mining target due to depletion"
                                            );
                                        }
                                    }
                                }
                                aetheris_protocol::events::GameEvent::SystemManifest {
                                    manifest,
                                } => {
                                    tracing::info!(
                                        count = manifest.len(),
                                        "Received SystemManifest from server (via GameEvent)"
                                    );
                                    self.world_state.system_manifest = manifest.clone();
                                }
                                aetheris_protocol::events::GameEvent::Possession {
                                    network_id: _,
                                }
                                | aetheris_protocol::events::GameEvent::DamageEvent { .. }
                                | aetheris_protocol::events::GameEvent::DeathEvent { .. }
                                | aetheris_protocol::events::GameEvent::RespawnEvent { .. }
                                | aetheris_protocol::events::GameEvent::CargoCollected { .. } => {
                                    self.world_state.handle_game_event(&game_event);
                                }
                            }
                        }
                        #[allow(unreachable_patterns)]
                        _ => {
                            tracing::debug!("Unhandled outer NetworkEvent variant");
                        }
                    }
                }

                // 2. Apply updates to the Simulation World
                // Skip while a ClearWorld ack is pending: any updates arriving
                // now are stale datagrams from before the clear command.
                if self.pending_clear {
                    if !updates.is_empty() {
                        tracing::debug!(
                            count = updates.len(),
                            "Discarding updates — pending_clear gate is raised"
                        );
                    }
                } else {
                    if !updates.is_empty() {
                        let max_tick = updates.iter().map(|(_, u)| u.tick).max().unwrap_or(0);

                        // M1020 — Continuous Clock Sync to prevent 1-2s rubber-banding
                        if max_tick > 0 {
                            let drift =
                                (self.world_state.latest_tick as i32 - max_tick as i32).abs();
                            if self.first_playground_tick || drift > 20 {
                                tracing::info!(
                                    latest = self.world_state.latest_tick,
                                    server = max_tick,
                                    drift,
                                    "Syncing client latest_tick to server heartbeat"
                                );
                                self.world_state.latest_tick = max_tick;
                                self.first_playground_tick = false;
                            }
                        }

                        tracing::debug!(count = updates.len(), "Applying server updates to world");
                        self.world_state.apply_updates(&updates);
                    }
                }
            }

            // 2.5. Fixed-Timestep Simulation Loop (M1020)
            // The JS side (game.worker.ts) already calls tick() at ~60Hz via setTimeout.
            // Using `if` instead of `while` prevents double-stepping when the JS timer fires
            // slightly late (e.g. 17ms instead of 16.67ms): accumulated drift of ~0.33ms/frame
            // would otherwise cause a second physics step every ~50 frames, causing ship lurches.
            let now = crate::performance_now();
            let delta_ms = now - self.last_process_time;
            self.last_process_time = now;

            // Limit delta to prevent "spiral of death" after long freezes (max 5 frames)
            let delta_ms = delta_ms.min(100.0);
            self.tick_accumulator += delta_ms;

            const DT_MS: f64 = 1000.0 / 60.0;
            while self.tick_accumulator >= DT_MS {
                // 1. Apply buffered playground input locally (Prediction)
                // We keep this enabled in the playground to maintain responsiveness (M1020).
                // Reconciliation jitter is now mitigated by wrap-aware interpolation.
                let applied = self.world_state.playground_apply_input(
                    self.playground_move_x,
                    self.playground_move_y,
                    self.playground_actions,
                );

                if !applied && self.world_state.latest_tick % 120 == 0 {
                    tracing::warn!(
                        tick = self.world_state.latest_tick,
                        "Simulation loop running but no LocalPlayer (0x04) entity found to apply input to"
                    );
                }

                // 2. Advance global tick
                self.world_state.latest_tick += 1;
                self.world_state.simulate();
                self.tick_accumulator -= DT_MS;
            }

            // 2.5.5. Publish sub-tick fraction for smooth rendering (M10105)
            // Use EMA smoothing to prevent jitter from browser timer noise
            let fraction = (self.tick_accumulator as f32 / DT_MS as f32).clamp(0.0, 1.0);
            let alpha = 0.8;
            self.last_fraction = self.last_fraction * (1.0 - alpha) + fraction * alpha;
            self.shared_world.set_sub_tick_fraction(self.last_fraction);
            tracing::trace!(fraction, "Updated sub-tick fraction");

            // 2.6. Client-side rotation animation (local, not replicated by server)

            // M10105 — measure simulation time
            let sim_start = crate::performance_now();

            // 3. Write Authoritative Snapshot to Shared World for the Render Worker
            self.flush_to_shared_world(self.world_state.latest_tick);

            let sim_time_ms = crate::performance_now() - sim_start;
            let count = self.world_state.entities.len() as u32;

            // VS-02 — Update real-time cargo metrics for UI
            let (cargo_ore, cargo_cap) = self
                .world_state
                .player_network_id
                .and_then(|id| self.world_state.entities.get(&id))
                .map_or((0, 0), |s| (s.cargo_ore as u32, s.cargo_capacity as u32));

            with_collector(|c| {
                c.record_sim(sim_time_ms);
                c.update_entity_count(count);
                c.update_cargo(cargo_ore, cargo_cap);
            });
        }

        fn flush_to_shared_world(&mut self, tick: u64) {
            let entities = &self.world_state.entities;
            let write_buffer = self.shared_world.get_write_buffer();

            let mut count = 0;
            for (i, slot) in entities.values().enumerate() {
                if i >= MAX_ENTITIES {
                    tracing::warn!("Max entities reached in shared world! Overflow suppressed.");
                    break;
                }
                write_buffer[i] = *slot;
                count += 1;
            }

            tracing::debug!(entity_count = count, tick, "Flushed world to SAB");
            self.shared_world.commit_write(count as u32, tick);
        }

        #[wasm_bindgen]
        pub async fn request_system_manifest(&mut self) -> Result<(), JsValue> {
            self.check_worker();

            if let Some(transport) = &self.transport {
                let encoder = SerdeEncoder::new();
                let event = NetworkEvent::RequestSystemManifest {
                    client_id: ClientId(0),
                };

                if let Ok(data) = encoder.encode_event(&event) {
                    transport
                        .send_reliable(ClientId(0), &data)
                        .await
                        .map_err(|e| JsValue::from_str(&format!("{e:?}")))?;
                    tracing::info!("Sent RequestSystemManifest command to server");
                }
            }
            Ok(())
        }

        #[wasm_bindgen]
        pub fn get_system_info(&self) -> Result<JsValue, JsValue> {
            serde_wasm_bindgen::to_value(&self.world_state.system_manifest)
                .map_err(|e| JsValue::from_str(&e.to_string()))
        }

        #[wasm_bindgen]
        pub fn wasm_get_entity_statuses(&self) -> JsValue {
            #[derive(serde::Serialize)]
            struct EntityStatus {
                network_id: String,
                hp: u16,
                shield: u16,
                entity_type: u16,
                is_player: bool,
            }

            let mut entities: Vec<&SabSlot> = self.world_state.entities.values().collect();
            entities.sort_by_key(|slot| slot.network_id);

            let statuses: Vec<EntityStatus> = entities
                .into_iter()
                .map(|slot| EntityStatus {
                    network_id: slot.network_id.to_string(),
                    hp: slot.hp,
                    shield: slot.shield,
                    entity_type: slot.entity_type,
                    is_player: (slot.flags & 0x04) != 0,
                })
                .collect();

            match serde_wasm_bindgen::to_value(&statuses) {
                Ok(val) => val,
                Err(e) => {
                    web_sys::console::warn_1(&wasm_bindgen::JsValue::from_str(&format!(
                        "wasm_get_entity_statuses: serde_wasm_bindgen::to_value failed: {e}"
                    )));
                    wasm_bindgen::JsValue::NULL
                }
            }
        }

        #[wasm_bindgen]
        pub fn playground_spawn(&mut self, entity_type: u16, x: f32, y: f32, rotation: f32) {
            // Security: Prevent overflow in playground mode
            if self.world_state.entities.len() >= MAX_ENTITIES {
                tracing::warn!("playground_spawn: MAX_ENTITIES reached, spawn ignored.");
                return;
            }

            // Sync ID generator if it's currently at default but world is seeded
            if self.playground_next_network_id == 1 && !self.world_state.entities.is_empty() {
                self.playground_next_network_id = self
                    .world_state
                    .entities
                    .keys()
                    .map(|k| k.0)
                    .max()
                    .unwrap_or(0)
                    + 1;
            }

            let id = aetheris_protocol::types::NetworkId(self.playground_next_network_id);
            self.playground_next_network_id += 1;
            let slot = SabSlot {
                network_id: id.0,
                x,
                y,
                z: 0.0,
                rotation,
                dx: 0.0,
                dy: 0.0,
                dz: 0.0,
                hp: 100,
                shield: 100,
                entity_type,
                flags: 0x01, // ALIVE
                mining_active: 0,
                cargo_ore: 0,
                cargo_capacity: 0,
                mining_target_id: 0,
                combat_target_id: 0,
                combat_flash_ticks: 0,
                padding: [0; 3],
            };
            self.world_state.entities.insert(id, slot);
        }

        #[wasm_bindgen]
        pub async fn playground_spawn_net(
            &mut self,
            entity_type: u16,
            x: f32,
            y: f32,
            rot: f32,
        ) -> Result<(), JsValue> {
            self.check_worker();

            if let Some(transport) = &self.transport {
                let encoder = SerdeEncoder::new();
                let event = NetworkEvent::Spawn {
                    client_id: ClientId(0),
                    entity_type,
                    x,
                    y,
                    rot,
                };

                if let Ok(data) = encoder.encode_event(&event) {
                    transport
                        .send_reliable(ClientId(0), &data)
                        .await
                        .map_err(|e| JsValue::from_str(&format!("{e:?}")))?;
                    tracing::info!(entity_type, x, y, "Sent Spawn command to server");
                }
            } else {
                // Local fallback
                self.playground_spawn(entity_type, x, y, rot);
            }
            Ok(())
        }

        #[wasm_bindgen]
        pub fn playground_clear(&mut self) {
            self.world_state.entities.clear();
        }

        /// Sends a StartSession command to the server.
        /// The server will spawn the session Interceptor and send back a Possession event.
        /// Only valid when connected; does nothing in local sandbox mode.
        #[wasm_bindgen]
        pub async fn start_session_net(&mut self) -> Result<(), JsValue> {
            self.check_worker();

            if let Some(transport) = &self.transport {
                let encoder = SerdeEncoder::new();
                let event = NetworkEvent::StartSession {
                    client_id: ClientId(0),
                };
                if let Ok(data) = encoder.encode_event(&event) {
                    transport
                        .send_reliable(ClientId(0), &data)
                        .await
                        .map_err(|e| JsValue::from_str(&format!("{e:?}")))?;
                    tracing::info!("Sent StartSession command to server");
                }
            }
            Ok(())
        }

        /// Sends a movement/action input command to the server.
        ///
        /// The input is encoded as an unreliable component update (Kind 128)
        /// and sent to the server for processing in the next tick.
        #[wasm_bindgen]
        pub async fn send_input(
            &mut self,
            tick: u64,
            move_x: f32,
            move_y: f32,
            actions_mask: u32,
            target_id_arg: Option<u64>,
        ) -> Result<(), JsValue> {
            self.check_worker();

            // 1. Identify the controlled player entity to target the command correctly
            let target_id = if let Some(owned_id) = self.world_state.player_network_id {
                // If we have an explicit possession ID from the server, use it.
                // This is the most reliable method (M1038).
                tracing::trace!(
                    network_id = owned_id.0,
                    "[send_input] Using player_network_id for input target"
                );
                Some(owned_id)
            } else {
                // Fallback: Identify via replication flags if possession event hasn't arrived yet
                let fallback = self
                    .world_state
                    .entities
                    .iter()
                    .find(|(_, slot)| (slot.flags & 0x04) != 0)
                    .map(|(id, _)| *id);
                tracing::trace!(
                    fallback_id = ?fallback,
                    "[send_input] No player_network_id set - using 0x04 flag fallback"
                );
                fallback
            };

            let Some(target_id) = target_id else {
                tracing::trace!("[send_input] Input dropped: no controlled entity found");
                return Ok(());
            };

            tracing::trace!(
                target_id = target_id.0,
                move_x,
                move_y,
                "[send_input] Sending input for entity"
            );

            // 2. Prepare actions vector
            let mut actions = Vec::new();

            // Movement action
            if move_x.abs() > f32::EPSILON || move_y.abs() > f32::EPSILON {
                actions.push(PlayerInputKind::Move {
                    x: move_x,
                    y: move_y,
                });
            }

            // Bitmask actions (M1020 mapping)
            // Bit 2: FirePrimary (Space) - ACTION_FIRE_WEAPON
            if (actions_mask & 0x04) != 0 {
                actions.push(PlayerInputKind::FirePrimary);
            }
            // Bit 1: ToggleMining (Edge-triggered)
            if (actions_mask & 0x02) != 0 && (self.last_actions_mask & 0x02) == 0 {
                let target = if let Some(id) = target_id_arg {
                    Some(NetworkId(id))
                } else {
                    // VS-02 Auto-target: find nearest asteroid
                    if let Some(player_slot) = self.world_state.entities.get(&target_id) {
                        let player_pos = (player_slot.x, player_slot.y);
                        self.world_state
                            .entities
                            .iter()
                            .filter(|(_, slot)| slot.entity_type == 5) // Asteroid (kind 5)
                            .map(|(id, slot)| {
                                let dx = slot.x - player_pos.0;
                                let dy = slot.y - player_pos.1;
                                (id, dx * dx + dy * dy)
                            })
                            .min_by(|a, b| {
                                a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal)
                            })
                            .map(|(id, _)| *id)
                    } else {
                        None
                    }
                };

                if let Some(id) = target {
                    actions.push(PlayerInputKind::ToggleMining { target: id });
                } else {
                    tracing::warn!(
                        "ToggleMining requested without target_id and no asteroid nearby; dropping action"
                    );
                }
            }

            self.last_actions_mask = actions_mask;

            // 3. Noise reduction check
            let is_repeated = self.last_input_actions.len() == actions.len()
                && self
                    .last_input_actions
                    .iter()
                    .zip(actions.iter())
                    .all(|(a, b)| a == b)
                && self.last_input_target == Some(target_id);

            if move_x.abs() > f32::EPSILON || move_y.abs() > f32::EPSILON || actions_mask != 0 {
                if is_repeated {
                    tracing::trace!(
                        tick,
                        move_x,
                        move_y,
                        actions_mask,
                        "Client sending input (repeated)"
                    );
                } else {
                    tracing::trace!(tick, move_x, move_y, actions_mask, "Client sending input");
                }
            }

            let transport = self.transport.as_ref().ok_or_else(|| {
                JsValue::from_str("Cannot send input: transport not initialized or closed")
            })?;

            if is_repeated {
                tracing::trace!(
                    ?target_id,
                    x = move_x,
                    y = move_y,
                    "Sending InputCommand (repeated)"
                );
            } else {
                tracing::trace!(?target_id, x = move_x, y = move_y, "Sending InputCommand");
            }

            // Update last input state
            self.last_input_target = Some(target_id);
            self.last_input_actions = actions.clone();

            let cmd = InputCommand {
                tick,
                actions,
                actions_mask,
                last_seen_input_tick: None,
            }
            .clamped();

            // 4. Encode as a ComponentUpdate-compatible packet
            // We use ComponentKind(128) as the convention for InputCommands.
            // The server's TickScheduler will decode this as a standard game update.
            let payload = rmp_serde::to_vec(&cmd)
                .map_err(|e| JsValue::from_str(&format!("Failed to encode InputCommand: {e:?}")))?;

            let update = ReplicationEvent {
                network_id: target_id,
                component_kind: ComponentKind(128),
                payload,
                tick,
            };

            let mut buffer = [0u8; 1024];
            let encoder = SerdeEncoder::new();
            let len = encoder.encode(&update, &mut buffer).map_err(|e| {
                JsValue::from_str(&format!("Failed to encode input replication event: {e:?}"))
            })?;

            // 3. Send via unreliable datagram
            transport
                .send_unreliable(ClientId(0), &buffer[..len])
                .await
                .map_err(|e| {
                    JsValue::from_str(&format!("Transport error during send_input: {e:?}"))
                })?;

            Ok(())
        }

        #[wasm_bindgen]
        pub async fn playground_clear_server(&mut self) -> Result<(), JsValue> {
            self.check_worker();

            if let Some(transport) = &self.transport {
                let encoder = SerdeEncoder::new();
                let event = NetworkEvent::ClearWorld {
                    client_id: ClientId(0),
                };
                if let Ok(data) = encoder.encode_event(&event) {
                    transport
                        .send_reliable(ClientId(0), &data)
                        .await
                        .map_err(|e| JsValue::from_str(&format!("{e:?}")))?;
                    tracing::info!(
                        "Sent ClearWorld command to server — suppressing updates until ack"
                    );
                    // Immediately clear local state and raise the gate.  All incoming
                    // entity updates are suppressed until the server's reliable ClearWorld
                    // ack arrives, preventing stale in-flight datagrams from re-adding
                    // entities that were just despawned on the server.
                    self.world_state.entities.clear();
                    self.world_state.player_network_id = None;
                    self.pending_clear = true;
                    self.last_clear_tick = self.world_state.latest_tick;
                }
            } else {
                // No transport, clear immediately (no in-flight datagrams to worry about)
                self.world_state.entities.clear();
                self.world_state.player_network_id = None;
            }
            Ok(())
        }

        #[wasm_bindgen]
        pub fn playground_set_rotation_enabled(&mut self, enabled: bool) {
            self.playground_rotation_enabled = enabled;
            // Note: Rotation toggle is currently local-authoritative in playground_tick,
            // but for server-side replication it would need a network event.
        }

        #[wasm_bindgen]
        pub async fn playground_stress_test(
            &mut self,
            count: u16,
            rotate: bool,
        ) -> Result<(), JsValue> {
            self.check_worker();

            if let Some(transport) = &self.transport {
                let encoder = SerdeEncoder::new();
                let event = NetworkEvent::StressTest {
                    client_id: ClientId(0),
                    count,
                    rotate,
                };

                if let Ok(data) = encoder.encode_event(&event) {
                    transport
                        .send_reliable(ClientId(0), &data)
                        .await
                        .map_err(|e| JsValue::from_str(&format!("{e:?}")))?;
                    tracing::info!(count, rotate, "Sent StressTest command to server");
                }
                self.playground_set_rotation_enabled(rotate);
            } else {
                // Fallback to local behavior if not connected
                self.playground_set_rotation_enabled(rotate);
                self.playground_clear();
                for _ in 0..count {
                    self.playground_spawn(1, 0.0, 0.0, 0.0); // Simple spawn
                }
            }

            Ok(())
        }

        #[wasm_bindgen]
        pub fn tick_playground(&mut self) {
            self.check_worker();

            // M10105 — measure simulation time
            let sim_start = crate::performance_now();

            let now = crate::performance_now();
            let delta_ms = now - self.last_process_time;
            self.last_process_time = now;

            // Limit delta to prevent "spiral of death" (max 5 frames)
            let delta_ms = delta_ms.min(100.0);
            self.tick_accumulator += delta_ms;

            const DT_MS: f64 = 1000.0 / 60.0;
            let mut steps = 0;
            while self.tick_accumulator >= DT_MS {
                self.world_state.latest_tick += 1;

                // 1. Apply playground input (respected by prediction_enabled flag internally)
                self.world_state.playground_apply_input(
                    self.playground_move_x,
                    self.playground_move_y,
                    self.playground_actions,
                );

                // 2. Local physics simulation
                self.world_state.simulate();

                self.tick_accumulator -= DT_MS;
                steps += 1;
            }

            // Sync to shared world if we simulated at least one step
            if steps > 0 {
                // Publish sub-tick fraction for smooth rendering (M10105)
                let fraction = (self.tick_accumulator as f32 / DT_MS as f32).clamp(0.0, 1.0);
                let alpha = 0.8;
                self.last_fraction = self.last_fraction * (1.0 - alpha) + fraction * alpha;
                self.shared_world.set_sub_tick_fraction(self.last_fraction);

                let count = self.world_state.entities.len() as u32;
                self.flush_to_shared_world(self.world_state.latest_tick);

                let sim_time_ms = crate::performance_now() - sim_start;
                with_collector(|c| {
                    c.record_sim(sim_time_ms);
                    c.update_entity_count(count);
                });
            }
        }

        /// Render frame called by the Render Worker.
        pub fn render(&mut self) -> f64 {
            self.check_worker();

            let tick = self.shared_world.tick();
            let entities = self.shared_world.get_read_buffer();
            let bounds = self.shared_world.get_room_bounds();
            if let Some(state) = &mut self.render_state {
                state.set_room_bounds(bounds);
            }

            // Periodic diagnostic log for render worker
            thread_local! {
                static FRAME_COUNT: core::cell::Cell<u64> = core::cell::Cell::new(0);
            }
            FRAME_COUNT.with(|count| {
                let current = count.get();
                if current % 300 == 0 {
                    tracing::debug!(
                        "Aetheris Render Stats: Tick={}, Entities={}, Snapshots={}",
                        tick,
                        entities.len(),
                        self.snapshots.len(),
                    );
                }
                count.set(current + 1);
            });

            // 1. Buffer new snapshots — only push when tick advances
            let back_tick = self.snapshots.back().map(|s| s.tick).unwrap_or(0);
            if tick < back_tick && tick != 0 {
                tracing::warn!(
                    tick,
                    back_tick,
                    "Simulation time went backwards! Clearing snapshot buffer."
                );
                self.snapshots.clear();
            }

            if self.snapshots.is_empty() || tick > back_tick {
                tracing::trace!(tick, "Pushing new snapshot to buffer");
                self.snapshots.push_back(SimulationSnapshot {
                    tick,
                    entities: entities.to_vec(),
                });
            } else if tick == back_tick && tick != 0 {
                // Diagnostic for stagnant tick
                thread_local! {
                    static STAGNANT_COUNT: core::cell::Cell<u64> = core::cell::Cell::new(0);
                }
                STAGNANT_COUNT.with(|count| {
                    let cur = count.get() + 1;
                    if cur % 300 == 0 {
                        tracing::warn!(tick, "Render loop stalled on same tick for 300 frames");
                    }
                    count.set(cur);
                });
            }

            // 2. Calculate target playback tick with high-precision sub-tick fraction.
            // Stay 2 ticks behind latest so we always have an (s1, s2) interpolation pair.
            // We use the shared_world's sub_tick_fraction to smoothly transition between
            // simulation steps at the monitor's full refresh rate (e.g. 144Hz).
            let latest_tick = self.snapshots.back().map(|s| s.tick as f32).unwrap_or(0.0);
            let fraction = self.shared_world.sub_tick_fraction();
            let mut target_tick = latest_tick - 1.0 + fraction;

            // Ensure target_tick is within available snapshot range if possible
            if !self.snapshots.is_empty() {
                let oldest_tick = self.snapshots[0].tick as f32;
                if target_tick < oldest_tick {
                    target_tick = oldest_tick;
                }
            }

            let ent_count = entities.len();
            let frame_time_ms = self.render_at_tick(target_tick);

            // M10105 — record accurate frame time (from WGPU) + snapshot depth.
            let snap_count = self.snapshots.len() as u32;
            if tick % 60 == 0 {
                tracing::trace!(
                    tick,
                    ent_count,
                    snap_count,
                    target_tick,
                    "Render Loop Active"
                );
            }
            with_collector(|c| {
                // FPS is computed in the worker; we only report duration here.
                c.record_frame(frame_time_ms, 0.0);
                c.update_snapshot_count(snap_count);
            });

            frame_time_ms
        }

        fn render_at_tick(&mut self, target_tick: f32) -> f64 {
            if self.snapshots.len() < 2 {
                // If we don't have enough snapshots for interpolation,
                // we still want to render the background or at least one frame.
                if let Some(state) = &mut self.render_state {
                    let entities = if !self.snapshots.is_empty() {
                        self.snapshots[0].entities.clone()
                    } else {
                        Vec::new()
                    };
                    return state.render_frame_with_compact_slots(&entities);
                }
                return 0.0;
            }

            // Find snapshots S1, S2 such that S1.tick <= target_tick < S2.tick
            let mut s1_idx = 0;
            let mut found = false;

            for i in 0..self.snapshots.len() - 1 {
                if (self.snapshots[i].tick as f32) <= target_tick
                    && (self.snapshots[i + 1].tick as f32) > target_tick
                {
                    s1_idx = i;
                    found = true;
                    break;
                }
            }

            if !found {
                // If we are outside the buffer range, clamp to the nearest edge
                if target_tick < self.snapshots[0].tick as f32 {
                    s1_idx = 0;
                } else {
                    s1_idx = self.snapshots.len() - 2;
                }
            }

            let s1 = self.snapshots.get(s1_idx).unwrap();
            let s2 = self.snapshots.get(s1_idx + 1).unwrap();

            let tick_range = (s2.tick - s1.tick) as f32;
            let alpha = if tick_range > 0.0 {
                (target_tick - s1.tick as f32) / tick_range
            } else {
                1.0
            }
            .clamp(0.0, 1.0);

            // Interpolate entities into a reusable buffer to avoid per-frame heap allocations
            self.render_buffer.clear();
            self.render_buffer.extend_from_slice(&s2.entities);

            // Build a lookup map from the previous snapshot for O(1) access per entity.
            let prev_map: std::collections::HashMap<u64, &SabSlot> =
                s1.entities.iter().map(|e| (e.network_id, e)).collect();

            for ent in &mut self.render_buffer {
                if let Some(prev) = prev_map.get(&ent.network_id).copied() {
                    if let Some(bounds) = &self.world_state.room_bounds {
                        ent.x = lerp_wrapped(prev.x, ent.x, alpha, bounds.min_x, bounds.max_x);
                        ent.y = lerp_wrapped(prev.y, ent.y, alpha, bounds.min_y, bounds.max_y);
                    } else {
                        ent.x = lerp(prev.x, ent.x, alpha);
                        ent.y = lerp(prev.y, ent.y, alpha);
                    }
                    ent.z = lerp(prev.z, ent.z, alpha);
                    ent.rotation = lerp_rotation(prev.rotation, ent.rotation, alpha);
                } else {
                    // M1013/M1020 — Extrapolate backwards for newly spawned entities.
                    // This prevents the "blink" where an entity appears to stand still for
                    // one tick before starting to move.
                    let dt = 1.0 / 60.0;
                    let remaining = 1.0 - alpha;

                    if let Some(bounds) = &self.world_state.room_bounds {
                        // Use wrapped logic for backward extrapolation to handle spawns near bounds
                        ent.x = lerp_wrapped(
                            ent.x,
                            ent.x - ent.dx * dt * remaining,
                            1.0,
                            bounds.min_x,
                            bounds.max_x,
                        );
                        ent.y = lerp_wrapped(
                            ent.y,
                            ent.y - ent.dy * dt * remaining,
                            1.0,
                            bounds.min_y,
                            bounds.max_y,
                        );
                    } else {
                        ent.x -= ent.dx * dt * remaining;
                        ent.y -= ent.dy * dt * remaining;
                    }
                    ent.z -= ent.dz * dt * remaining;
                }
            }

            let mut frame_time = 0.0;
            if let Some(state) = &mut self.render_state {
                frame_time = state.render_frame_with_compact_slots(&self.render_buffer);
            }

            // 3. Prune old snapshots.
            // We keep the oldest one that is still relevant for interpolation (index 0)
            // and everything newer. We prune snapshots that are entirely behind our window.
            while self.snapshots.len() > 2 && (self.snapshots[0].tick as f32) < target_tick - 1.0 {
                self.snapshots.pop_front();
            }

            // Safety cap: prevent unbounded growth if simulation stops but render continues
            while self.snapshots.len() > 16 {
                self.snapshots.pop_front();
            }

            frame_time
        }
    }

    fn lerp(a: f32, b: f32, alpha: f32) -> f32 {
        a + (b - a) * alpha
    }

    fn lerp_wrapped(a: f32, b: f32, alpha: f32, min: f32, max: f32) -> f32 {
        let size = max - min;
        if size <= 0.0 {
            return a + (b - a) * alpha;
        }

        // Ensure inputs are within [min, max) before calculating diff
        let a_norm = (a - min).rem_euclid(size) + min;
        let b_norm = (b - min).rem_euclid(size) + min;

        let mut diff = b_norm - a_norm;
        if diff.abs() > size * 0.5 {
            if diff > 0.0 {
                diff -= size;
            } else {
                diff += size;
            }
        }
        let res = a_norm + diff * alpha;
        // Final wrap to keep result strictly in [min, max)
        (res - min).rem_euclid(size) + min
    }

    fn lerp_rotation(a: f32, b: f32, alpha: f32) -> f32 {
        // Simple rotation lerp for Phase 1.
        // Handles 2pi wraparound for smooth visuals.
        let mut diff = b - a;
        while diff < -std::f32::consts::PI {
            diff += std::f32::consts::TAU;
        }
        while diff > std::f32::consts::PI {
            diff -= std::f32::consts::TAU;
        }
        a + diff * alpha
    }
}