lingxia-lxapp 0.18.0

pub(crate) mod config;
pub(crate) mod definition;
pub(crate) mod runtime;

pub use definition::{register_page_resolver, resolve_page_path};

use crate::bridge::PageBridge;
use crate::lifecycle::PageLifecycleEvent;
use crate::lxapp::{self, LxAppSessionStatus, navbar::NavigationBarState};
use crate::page::config::{OrientationOverride, PageConfig};
use crate::plugin;
use crate::startup::parse_query_string;
use crate::{LxApp, LxAppError, debug, error, info, warn};
use base64::Engine;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use lingxia_log::{LogBuilder, LogLevel as LxLogLevel, LogTag};
use lingxia_platform::traits::app_runtime::{
    AnimationType, AppRuntime, OpenUrlRequest, OpenUrlTarget,
};
use lingxia_webview::runtime::destroy_webview_if_matches;
use lingxia_webview::{
    IncomingWebMessage, LoadDataRequest, LogLevel, NativeWebViewId, NavigationOutcome,
    NavigationPolicy, NewWindowPolicy, WebTag, WebView, WebViewBuilder, WebViewController,
    WebViewDelegate,
};
use ring::rand::{SecureRandom, SystemRandom};

use std::future::Future;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use tokio::sync::watch;

/// How long an isolated page's setup waits for its opener to create the
/// PageSvc. The opener does that in the same turn it awaits this page, so
/// exceeding this means nobody is coming — an isolated instance created
/// outside `lx.surface`. Fail loudly instead of leaving the page parked at
/// `about:blank` with no diagnostic.
const PAGE_SVC_READY_TIMEOUT: Duration = Duration::from_secs(10);

/// Fired at most once per process: the home lxapp delivered its first
/// `OnReady` (first render finished). Hosts dismiss the startup splash
/// overlay on this signal.
static HOME_FIRST_READY: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

fn notify_home_first_ready_once(appid: &str) {
    if lingxia_app_context::home_app_id() != Some(appid) {
        return;
    }
    if HOME_FIRST_READY.swap(true, std::sync::atomic::Ordering::Relaxed) {
        return;
    }

    // Hold the signal until the launch face has been up long enough. A page
    // that renders in 200ms would otherwise flash the splash, which reads
    // worse than not having one. The platform-side timeout still caps the
    // wait.
    //
    // Measured from process start: the OS launch frame already carries the
    // same art, so runtime boot is time the user has genuinely spent looking
    // at this face. Android cannot put full-bleed art in its system frame, so
    // its overlay separately enforces the visible hold from its own first
    // draw. A process that never marked a launch face — desktop, where this
    // signal reveals the first window — has nothing to hold for, and waiting
    // would only delay real content.
    let remaining = lingxia_app_context::splash_visible_for()
        .map(|visible| lingxia_app_context::splash_min_duration().saturating_sub(visible))
        .unwrap_or_default();
    if remaining.is_zero() {
        signal_home_first_ready();
        return;
    }
    std::mem::drop(crate::executor::spawn(async move {
        tokio::time::sleep(remaining).await;
        signal_home_first_ready();
    }));
}

fn signal_home_first_ready() {
    let Some(platform) = lxapp::runtime_registry::get_platform() else {
        return;
    };
    use lingxia_platform::traits::ui::UIUpdate;
    // The launch face has done its job. If the host resolved a campaign in
    // time, it takes over the same layer with its own countdown; otherwise the
    // face lifts straight into the app. A campaign that is not ready by this
    // moment is dropped, never shown late over real content.
    match lingxia_app_context::take_pending_campaign() {
        Some((image_path, duration_ms)) => platform.show_splash_campaign(image_path, duration_ms),
        None => platform.notify_home_first_ready(),
    }
}

type WebviewReadyReceiver = Arc<Mutex<watch::Receiver<Option<Result<(), String>>>>>;

const DEFAULT_VIEW_CALL_TIMEOUT: Duration = Duration::from_secs(15);

/// Inner state of a page that can be shared across threads
pub(crate) struct PageInstanceInner {
    id: PageInstanceId,
    appid: String,
    path: String,
    webtag: WebTag,
    /// Surface-owned instance with a per-instance webtag; never resolves by
    /// bare path.
    isolated: bool,

    // Reference to the WebView (optional, set when WebView is ready)
    webview: Arc<Mutex<Option<Arc<WebView>>>>,

    // Time when this page was last active
    last_active_time: Arc<Mutex<Instant>>,

    // state of PageInstance
    state: Arc<Mutex<PageState>>,

    // Per-page bridge nonce (used to validate the View<->Logic wiring)
    bridge_nonce: Arc<Mutex<Option<String>>>,
    bridge: PageBridge,

    // notify when WebView wiring is ready (delegate set & setup ran)
    webview_ready_tx: watch::Sender<Option<Result<(), String>>>,
    webview_ready_rx: WebviewReadyReceiver,

    // Isolated surface pages: the opener creates PageSvc on the JS worker
    // before awaiting this page. Setup must not post CreatePage onto that
    // same worker or openPage deadlocks.
    page_svc_ready_tx: watch::Sender<bool>,
    page_svc_ready_rx: Arc<Mutex<watch::Receiver<bool>>>,

    // Runtime-owned scripts installed at the earliest page-start callback.
    document_start_scripts: Vec<Arc<str>>,

    // Scripts injected on every page load (global + app-level, snapshotted at creation).
    page_scripts: Vec<Arc<str>>,

    // Async notification: bumped on every handle_loaded().
    loaded_tx: watch::Sender<u64>,

    // Canonical attempt-correlation fold over typed navigation events.
    navigation_progress: Arc<std::sync::Mutex<lingxia_webview::NavigationProgress>>,

    // Serializes teardown/rebuild transitions of the owed reset, so the timer
    // and an entry racing each other cannot interleave terminate/create sends.
    reset_transition: Arc<std::sync::Mutex<()>>,

    /// Native WebView was reclaimed to free memory. Logic, `data`, and the
    /// instance stay; [`PageInstance::ensure_live_webview`] recreates the view.
    discarded: AtomicBool,
    webview_create_in_flight: AtomicBool,
}

/// A page runs on three independent clocks, and conflating them is what let
/// `onReady` fire against a document that had not re-rendered: a logical entry
/// owes one `onLoad`, the container's visibility owes `onShow`/`onHide`, and
/// each rendered document owes one `onReady`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum EntryPhase {
    /// No entry is pending — nothing has been navigated to since the last unload.
    Idle,
    /// An entry is pending; `onLoad` fires once render has started and, for
    /// Logic-enabled pages, the bridge is up.
    LoadOwed,
    /// `onLoad` was delivered for the current entry.
    Loaded,
}

/// Where a page is in the reset it owes after leaving the stack.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum PageReset {
    /// Nothing owed — the ordinary state of a live page.
    None,
    /// The instance ended; its service and document are still the old ones.
    Pending,
    /// Torn down: the service is gone and the document is parked blank. The
    /// entry that lands on this page owes it a rebuild, and any handshake
    /// arriving before that entry must not boot a lifecycle of its own.
    AwaitingEntry,
}

/// What the container wants, and whether `onShow` has caught up with it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Visibility {
    Hidden,
    /// Visible to the container, but `onShow` waits for `onLoad` first.
    ShowOwed,
    Shown,
}

#[derive(Clone, Debug)]
pub struct PageState {
    // PageInstance(webview) render status
    render_status: PageRenderStatus,
    // page lifecycle event
    event: Option<PageLifecycleEvent>,
    /// How far the current logical entry has got.
    entry: EntryPhase,
    /// What the container wants, and whether `onShow` has caught up with it.
    visibility: Visibility,
    /// Tracks whether the current WebView document has completed its bridge handshake.
    bridge_ready: bool,
    /// Logic-enabled pages must wait for AppService bridge readiness before onLoad.
    requires_bridge_ready: bool,
    /// Whether the current document has had its `onReady`.
    ready_dispatched: bool,
    /// The reset this page owes after leaving the stack.
    reset: PageReset,
    /// A parked page holds an inert blank document while nobody is on it;
    /// its navigation events must not run the render pipeline.
    parked: bool,
    renderer_recovery_pending: bool,
    // Navigation bar state
    pub(crate) navbar_state: NavigationBarState,
    // A malformed page config owns this page's load outcome; it must not
    // silently fall back to chrome defaults.
    config_load_error: Option<String>,
    // Pull-to-refresh enabled flag
    pub(crate) enable_pull_down_refresh: bool,
    // PageInstance orientation overrides
    pub(crate) orientation_override: OrientationOverride,
    // Query parameters
    pub(crate) query: serde_json::Value,
}

impl PageState {
    fn document_is_departing(&self) -> bool {
        self.parked
            || self.reset != PageReset::None
            || self.event == Some(PageLifecycleEvent::OnUnload)
    }

    fn accepts_view_state_patches(&self) -> bool {
        self.bridge_ready && !self.document_is_departing()
    }
}

/// Automation-facing readiness snapshot for a page instance.
#[derive(Clone, Debug, Serialize)]
pub struct PageAutomationState {
    pub webview_attached: bool,
    pub webview_ready: bool,
    pub webview_error: Option<String>,
    pub bridge_ready: bool,
    pub render_state: &'static str,
    pub lifecycle: &'static str,
    pub ready: bool,
    pub query: Value,
}

#[derive(Copy, Clone, PartialEq, Debug)]
enum PageRenderStatus {
    Unstarted,
    Started,
    Finished,
}

/// Navigation type for page navigation within LxApp
/// This enum defines the different types of navigation actions that can be performed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NavigationType {
    /// Launch navigation - open entry page (clear stack)
    Launch = 0,
    /// Forward navigation - push new page
    Forward = 1,
    /// Backward navigation - pop to previous page
    Backward = 2,
    /// Replace navigation - replace current page
    Replace = 3,
    /// Switch tab navigation - switch between tab pages
    SwitchTab = 4,
}

impl NavigationType {
    /// Convert navigation type to an appropriate animation type for platform runtimes
    pub fn to_animation(self) -> AnimationType {
        match self {
            NavigationType::Forward => AnimationType::Forward,
            NavigationType::Backward => AnimationType::Backward,
            _ => AnimationType::None,
        }
    }
}

/// Represents a single page in a mini app
#[derive(Clone)]
pub struct PageInstance {
    // Use Arc to share the inner state across threads
    inner: Arc<PageInstanceInner>,
}

#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct PageInstanceId(String);

impl PageInstanceId {
    pub fn new() -> Self {
        Self(uuid::Uuid::new_v4().to_string())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }

    pub fn parse(raw: impl Into<String>) -> Option<Self> {
        let value = raw.into();
        let trimmed = value.trim();
        if trimmed.is_empty() {
            return None;
        }
        uuid::Uuid::parse_str(trimmed)
            .ok()
            .map(|id| Self(id.hyphenated().to_string()))
    }
}

impl Default for PageInstanceId {
    fn default() -> Self {
        Self::new()
    }
}

impl std::fmt::Display for PageInstanceId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

/// Options for Rust-side calls into `window.LingXiaBridge`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ViewCallOptions {
    timeout: Duration,
}

impl Default for ViewCallOptions {
    fn default() -> Self {
        Self {
            timeout: DEFAULT_VIEW_CALL_TIMEOUT,
        }
    }
}

impl ViewCallOptions {
    /// Create default call options.
    pub fn new() -> Self {
        Self::default()
    }

    /// Override the response timeout for this call.
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// Return the configured timeout.
    pub fn timeout(self) -> Duration {
        self.timeout
    }
}

fn serialize_view_call_params<P>(params: &P) -> Result<Option<Value>, LxAppError>
where
    P: Serialize + ?Sized,
{
    let value = serde_json::to_value(params)?;
    if value.is_null() {
        return Ok(None);
    }
    Ok(Some(value))
}

fn decode_view_call_result<R>(method: &str, value: Value) -> Result<R, LxAppError>
where
    R: DeserializeOwned,
{
    serde_json::from_value(value).map_err(|err| {
        LxAppError::Bridge(format!(
            "Failed to decode view response for '{}': {}",
            method, err
        ))
    })
}

impl PageInstance {
    /// Reconstruct a PageInstance from a shared inner (used by scheme handler closures).
    pub(crate) fn from_inner(inner: Arc<PageInstanceInner>) -> Self {
        Self { inner }
    }

    fn generate_bridge_nonce() -> String {
        let rng = SystemRandom::new();
        let mut bytes = [0u8; 16];
        // If entropy fails (unlikely), fall back to a time-based token.
        if rng.fill(&mut bytes).is_err() {
            let nanos = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap_or_default()
                .as_nanos()
                .to_le_bytes();
            bytes.copy_from_slice(&nanos[..16]);
        }
        base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes)
    }

    /// Build PageState from JSON config
    /// PageConfig is the single source of truth for configuration.
    fn build_page_state(lxapp: &lxapp::LxApp, path: &str) -> PageState {
        // Page JSON describes native page presentation, not just PageSvc
        // behavior. Shape C Views still need custom navigation chrome,
        // orientation, and pull-to-refresh even though they have no Logic
        // runtime. Only the service lifecycle is conditional on `logic`.
        let (page_config, config_load_error) = match PageConfig::from_json(lxapp, path) {
            Ok(config) => (config, None),
            Err(error) => {
                error!("Page config load failed for {}: {}", path, error)
                    .with_appid(lxapp.appid.clone())
                    .with_path(path.to_string());
                (PageConfig::default(), Some(error.to_string()))
            }
        };
        PageState {
            event: None,
            render_status: PageRenderStatus::Unstarted,
            entry: EntryPhase::Idle,
            visibility: Visibility::Hidden,
            bridge_ready: false,
            requires_bridge_ready: lxapp.logic_enabled(),
            ready_dispatched: false,
            reset: PageReset::None,
            parked: false,
            renderer_recovery_pending: false,
            navbar_state: page_config.create_navbar_state(),
            config_load_error,
            enable_pull_down_refresh: page_config.is_pull_down_refresh_enabled(),
            orientation_override: page_config.get_orientation_override(),
            query: serde_json::json!({}),
        }
    }

    /// Create a new page in pending state (WebView creation in progress)
    pub(crate) fn new<F, Fut>(appid: String, path: String, lxapp: &LxApp, setup_callback: F) -> Self
    where
        F: Fn(&PageInstance) -> Fut + Send + 'static,
        Fut: std::future::Future<Output = Result<(), String>> + Send + 'static,
    {
        Self::new_with_isolation(appid, path, lxapp, false, setup_callback)
    }

    /// `isolated` marks surface-owned pages: they never resolve by bare path
    /// and their dispose lifecycle belongs to the owning surface.
    pub(crate) fn new_with_isolation<F, Fut>(
        appid: String,
        path: String,
        lxapp: &LxApp,
        isolated: bool,
        setup_callback: F,
    ) -> Self
    where
        F: Fn(&PageInstance) -> Fut + Send + 'static,
        Fut: std::future::Future<Output = Result<(), String>> + Send + 'static,
    {
        // Build page state from LxApp configuration
        let page_state = Self::build_page_state(lxapp, &path);
        let id = PageInstanceId::new();
        // Every WebView-owning page gets a per-instance tag: two instances of
        // one route never share registry keys, and platform-side state bound
        // to the tag string dies with its instance.
        let webtag = WebTag::new(
            &appid,
            &format!("{path}#{}", id.as_str()),
            Some(lxapp.session.id),
        );
        let bridge_nonce = Self::generate_bridge_nonce();
        let lxapp_arc = lxapp.clone_arc();
        let (ready_tx, ready_rx) = watch::channel(None);
        let (page_svc_ready_tx, page_svc_ready_rx) = watch::channel(false);
        let (loaded_tx, _) = watch::channel(0u64);
        let inner = Arc::new(PageInstanceInner {
            navigation_progress: Arc::new(std::sync::Mutex::new(Default::default())),
            reset_transition: Arc::new(std::sync::Mutex::new(())),
            id,
            appid: appid.clone(),
            path: path.clone(),
            webtag: webtag.clone(),
            isolated,
            last_active_time: Arc::new(Mutex::new(Instant::now())),
            state: Arc::new(Mutex::new(page_state)),
            webview: Arc::new(Mutex::new(None)),
            bridge_nonce: Arc::new(Mutex::new(Some(bridge_nonce))),
            bridge: PageBridge::new(lxapp_arc.clone(), lxapp_arc.executor.clone()),
            webview_ready_tx: ready_tx,
            webview_ready_rx: Arc::new(Mutex::new(ready_rx)),
            page_svc_ready_tx,
            page_svc_ready_rx: Arc::new(Mutex::new(page_svc_ready_rx)),
            document_start_scripts: lxapp.document_start_scripts_snapshot(),
            page_scripts: lxapp.page_scripts_snapshot(),
            loaded_tx,
            discarded: AtomicBool::new(false),
            webview_create_in_flight: AtomicBool::new(true),
        });

        let page = Self { inner };
        page.spawn_strict_webview(setup_callback);
        page
    }

    /// Create a headless page (nonce allocated, no WebView created).
    ///
    /// Used for a shared logical page that can be attached to externally
    /// managed WebViews one at a time.
    pub(crate) fn new_headless(appid: String, path: String, lxapp: &LxApp) -> Self {
        let page_state = Self::build_page_state(lxapp, &path);
        let id = PageInstanceId::new();
        let bridge_nonce = Self::generate_bridge_nonce();
        let webtag = WebTag::new(&appid, &path, Some(lxapp.session.id));
        let lxapp_arc = lxapp.clone_arc();
        let (ready_tx, ready_rx) = watch::channel(None);
        let (page_svc_ready_tx, page_svc_ready_rx) = watch::channel(false);
        let (loaded_tx, _) = watch::channel(0u64);
        let inner = Arc::new(PageInstanceInner {
            navigation_progress: Arc::new(std::sync::Mutex::new(Default::default())),
            reset_transition: Arc::new(std::sync::Mutex::new(())),
            id,
            appid,
            path,
            webtag,
            isolated: false,
            last_active_time: Arc::new(Mutex::new(Instant::now())),
            state: Arc::new(Mutex::new(page_state)),
            webview: Arc::new(Mutex::new(None)),
            bridge_nonce: Arc::new(Mutex::new(Some(bridge_nonce))),
            bridge: PageBridge::new(lxapp_arc.clone(), lxapp_arc.executor.clone()),
            webview_ready_tx: ready_tx,
            webview_ready_rx: Arc::new(Mutex::new(ready_rx)),
            page_svc_ready_tx,
            page_svc_ready_rx: Arc::new(Mutex::new(page_svc_ready_rx)),
            document_start_scripts: lxapp.document_start_scripts_snapshot(),
            page_scripts: lxapp.page_scripts_snapshot(),
            loaded_tx,
            discarded: AtomicBool::new(false),
            webview_create_in_flight: AtomicBool::new(false),
        });
        Self { inner }
    }

    pub fn bridge_nonce(&self) -> Option<String> {
        self.inner.bridge_nonce.lock().ok().and_then(|v| v.clone())
    }

    pub fn instance_id(&self) -> PageInstanceId {
        self.inner.id.clone()
    }

    pub fn instance_id_string(&self) -> String {
        self.inner.id.to_string()
    }

    /// Surface-owned instance with a per-instance webtag; never resolves by
    /// bare path.
    pub(crate) fn is_isolated(&self) -> bool {
        self.inner.isolated
    }

    pub(crate) fn is_discarded(&self) -> bool {
        self.inner.discarded.load(Ordering::SeqCst)
    }

    pub(crate) fn has_live_webview(&self) -> bool {
        self.webview().is_some() && !self.is_discarded()
    }

    /// Destroy the native WebView without unloading the page. Logic, `data`,
    /// query, and the instance stay; the next show recreates the document.
    pub(crate) fn discard_webview(&self) -> Result<(), LxAppError> {
        if self.inner.isolated {
            return Ok(());
        }
        if self.inner.webview_create_in_flight.load(Ordering::SeqCst) {
            return Ok(());
        }
        // The budget works from a snapshot; the app may have been shown, or
        // this tab entered, since it was taken.
        let lxapp = self.owning_lxapp();
        if lxapp.is_shown() || lxapp.get_page_stack().contains(&self.instance_id_string()) {
            return Ok(());
        }
        let Some(webview) = self.webview() else {
            self.inner.discarded.store(true, Ordering::SeqCst);
            return Ok(());
        };
        self.cancel_bridge_work();
        if let Ok(mut webview_guard) = self.inner.webview.lock() {
            let _ = webview_guard.take();
        }
        destroy_webview_if_matches(&self.webtag(), &webview);
        if let Ok(mut state) = self.inner.state.lock() {
            Self::invalidate_document_state(&mut state);
        }
        let _ = self.inner.webview_ready_tx.send(None);
        self.inner.discarded.store(true, Ordering::SeqCst);
        Ok(())
    }

    /// Recreate a discarded page WebView. No-op when the view is already live
    /// or a create is already in flight.
    pub(crate) fn ensure_live_webview(&self) {
        if self.has_live_webview() {
            return;
        }
        if !self.is_discarded() {
            return;
        }
        if self
            .inner
            .webview_create_in_flight
            .swap(true, Ordering::SeqCst)
        {
            return;
        }
        self.inner.discarded.store(false, Ordering::SeqCst);
        let _ = self.inner.webview_ready_tx.send(None);
        self.spawn_strict_webview(|page| {
            let page = page.clone();
            async move {
                let result = page.load_html().map_err(|err| err.to_string());
                if let Err(ref err) = result {
                    // Same-tag creates refuse a registered view, so a kept
                    // one would fail every later reload.
                    let attached = page.inner.webview.lock().ok().and_then(|mut v| v.take());
                    if let Some(webview) = attached {
                        destroy_webview_if_matches(&page.webtag(), &webview);
                    }
                    page.inner.discarded.store(true, Ordering::SeqCst);
                    crate::warn!("failed to reload discarded page WebView: {err}")
                        .with_appid(page.appid())
                        .with_path(page.path());
                }
                result
            }
        });
    }

    fn spawn_strict_webview<F, Fut>(&self, setup_callback: F)
    where
        F: Fn(&PageInstance) -> Fut + Send + 'static,
        Fut: Future<Output = Result<(), String>> + Send + 'static,
    {
        let page_weak_for_lx = Arc::downgrade(&self.inner);
        let lxapp = self.owning_lxapp();
        let runtime_for_nav = lxapp.runtime.clone();
        let appid_for_nav = self.appid();
        let session_id_for_nav = lxapp.session_id();
        let runtime_for_new_window = lxapp.runtime.clone();
        let appid_for_new_window = self.appid();
        let session_id_for_new_window = lxapp.session_id();
        let isolated = self.inner.isolated;
        let webtag = self.webtag();

        let session = WebViewBuilder::strict(webtag)
            .surface_owned(isolated)
            .delegate(Arc::new(self.clone()))
            .on_scheme("lx", move |req| {
                let page_weak_for_lx = page_weak_for_lx.clone();
                async move {
                    let Some(inner) = page_weak_for_lx.upgrade() else {
                        return None.into();
                    };
                    let page = PageInstance::from_inner(inner);
                    let lxapp = page.owning_lxapp();
                    if lxapp.status() == LxAppSessionStatus::Closed {
                        return None.into();
                    }
                    lxapp.handle_lingxia_request(&page, req).into()
                }
            })
            .on_navigation(move |request| {
                let url = request.url.as_str();
                let scheme = url.split(':').next().unwrap_or("");
                match scheme {
                    "lx" | "data" | "blob" => NavigationPolicy::Allow,
                    _ => {
                        if scheme != "about" {
                            let _ = runtime_for_nav.open_url(OpenUrlRequest {
                                owner_appid: appid_for_nav.clone(),
                                owner_session_id: session_id_for_nav,
                                url: url.to_string(),
                                target: OpenUrlTarget::External,
                                want_tab_id: false,
                            });
                        }
                        NavigationPolicy::Cancel
                    }
                }
            })
            .on_new_window(move |url| {
                let _ = runtime_for_new_window.open_url(OpenUrlRequest {
                    owner_appid: appid_for_new_window.clone(),
                    owner_session_id: session_id_for_new_window,
                    url: url.to_string(),
                    target: OpenUrlTarget::SelfTarget,
                    want_tab_id: false,
                });
                NewWindowPolicy::Cancel
            })
            .create();

        let page_for_task = self.clone();
        let appid_clone = self.appid();
        let path_clone = self.path();
        crate::executor::spawn(async move {
            let result = match session.wait_ready().await {
                Ok(webview_controller) => {
                    page_for_task.attach_webview(webview_controller.clone());
                    setup_callback(&page_for_task).await
                }
                Err(e) => {
                    let still_registered = page_for_task
                        .owning_lxapp()
                        .get_page_by_instance_id(&page_for_task.instance_id())
                        .is_some();
                    if page_for_task.document_is_departing() || !still_registered {
                        debug!("Cancelled WebView creation for departed page: {}", e)
                            .with_appid(appid_clone)
                            .with_path(path_clone);
                    } else {
                        error!("Failed to create WebView: {}", e)
                            .with_appid(appid_clone)
                            .with_path(path_clone);
                    }
                    Err(e.to_string())
                }
            };
            page_for_task
                .inner
                .webview_create_in_flight
                .store(false, Ordering::SeqCst);
            if result.is_err() {
                page_for_task.inner.discarded.store(true, Ordering::SeqCst);
            }
            page_for_task.mark_webview_ready(result);
        });
    }

    /// The webview tag identifying this page instance's view (also the
    /// page key passed to [`crate::NativeComponentHost::on_page_destroyed`]).
    pub fn webtag(&self) -> WebTag {
        self.inner.webtag.clone()
    }

    pub(crate) fn bridge(&self) -> PageBridge {
        self.inner.bridge.clone()
    }

    /// Host-TCB entrypoint for an admitted browser control document. The
    /// opaque pending lease owns the exact native/context check; callers never
    /// receive V3 credentials or construct a bridge protocol directly.
    #[doc(hidden)]
    pub fn bind_required_v3_document(
        &self,
        native_authority: &crate::NativeControlPlaneAuthority,
        context: &lingxia_webview::WebMessageContext,
        pending: &dyn crate::RequiredV3DocumentGate,
    ) -> Result<(), LxAppError> {
        self.inner
            .bridge
            .bind_required_v3_document(native_authority, self, context, pending)
    }

    /// Host-TCB installer for use inside BrowserDocumentSessions' held
    /// BootstrapPending closure. Unlike [`Self::bind_required_v3_document`],
    /// it does not re-enter the browser registry through a lease.
    #[doc(hidden)]
    pub fn bind_required_v3_authority(
        &self,
        native_authority: &crate::NativeControlPlaneAuthority,
        context: &lingxia_webview::WebMessageContext,
        authority: crate::ControlDocumentAuthority,
        outbound_gate: std::sync::Arc<dyn lingxia_webview::DocumentOutboundGate>,
    ) -> Result<crate::DeferredRequiredV3Cancellation, LxAppError> {
        self.inner.bridge.bind_required_v3_authority(
            native_authority,
            self,
            context,
            authority,
            outbound_gate,
        )
    }

    #[doc(hidden)]
    pub fn promote_active_browser_document(
        &self,
        native_authority: &crate::NativeControlPlaneAuthority,
        authority: crate::ControlDocumentAuthority,
    ) -> bool {
        self.inner
            .bridge
            .promote_active_browser_document(native_authority, authority)
    }

    /// Remove only the active required-V3 bridge work for this authority.
    #[doc(hidden)]
    pub fn revoke_required_v3_document(
        &self,
        native_authority: &crate::NativeControlPlaneAuthority,
        authority: crate::ControlDocumentAuthority,
    ) -> bool {
        self.inner
            .bridge
            .revoke_required_v3_document(native_authority, self, authority)
    }

    pub(crate) fn owning_lxapp(&self) -> Arc<LxApp> {
        self.inner.bridge.lxapp()
    }

    pub(crate) fn cancel_bridge_work(&self) {
        self.inner.bridge.cancel_page_work(self);
    }

    /// Records that this instance ended and owes a reset.
    pub(crate) fn mark_reset_pending(&self) {
        if let Ok(mut state) = self.inner.state.lock() {
            state.reset = PageReset::Pending;
        }
    }

    /// Claims the owed teardown, if this page still owes one.
    pub(crate) fn take_reset_pending(&self) -> bool {
        let Ok(mut state) = self.inner.state.lock() else {
            return false;
        };
        if state.reset == PageReset::Pending {
            state.reset = PageReset::AwaitingEntry;
            return true;
        }
        false
    }

    /// Claims the owed rebuild, if this page was torn down and none ran yet.
    pub(crate) fn take_reset_awaiting_entry(&self) -> bool {
        let Ok(mut state) = self.inner.state.lock() else {
            return false;
        };
        if state.reset == PageReset::AwaitingEntry {
            state.reset = PageReset::None;
            return true;
        }
        false
    }

    /// Serializes teardown/rebuild transitions across the timer and an entry.
    pub(crate) fn reset_transition_guard(&self) -> std::sync::MutexGuard<'_, ()> {
        self.inner
            .reset_transition
            .lock()
            .unwrap_or_else(|e| e.into_inner())
    }

    /// Parks the retained WebView while nobody is on the page: the document
    /// is replaced with an inert blank one, so no stale DOM (or open popup)
    /// survives to the next entry and no page code runs off-screen.
    /// Whether Logic may still push `setData` into this document.
    ///
    /// Handshake `ready` is kept across a warm-webview restart, so it cannot
    /// answer this. Same-route relaunch parks and rebuilds the document
    /// while the old service is still flushing a 16ms debounce — that is the
    /// setData / teardown race. Drop the patch: `this.data` already has it
    /// and the next snapshot reserializes live state.
    pub(crate) fn accepts_view_state_patches(&self) -> bool {
        self.inner
            .state
            .lock()
            .is_ok_and(|state| state.accepts_view_state_patches())
    }

    pub(crate) fn document_is_departing(&self) -> bool {
        self.inner
            .state
            .lock()
            .is_ok_and(|state| state.document_is_departing())
    }

    pub(crate) fn park_view(&self) {
        if let Ok(mut state) = self.inner.state.lock() {
            state.parked = true;
        }
        // Transparent so the host-owned page background shows through.
        const PARKED_DOCUMENT: &str = "<!DOCTYPE html><html><head><meta charset=\"utf-8\">\
             <style>html,body{background:transparent}</style></head><body></body></html>";
        if let Some(controller) = self.webview_controller()
            && let Err(err) =
                controller.load_data(LoadDataRequest::new(PARKED_DOCUMENT, &self.base_url()))
        {
            warn!("Failed to park document for {}: {}", self.path(), err)
                .with_appid(self.appid())
                .with_path(self.path());
        }
    }

    /// Prepare a retained WebView for a freshly-created PageSvc.
    ///
    /// An in-place app-service restart keeps the native page instance, so the
    /// normal attach path cannot clear the old worker's bridge/lifecycle state.
    pub(crate) fn prepare_for_service_restart(&self) {
        self.cancel_bridge_work();
        if let Ok(mut state) = self.inner.state.lock() {
            // reset_webview_lifecycle_state clears the flag, but a parked view
            // stays parked across the restart.
            let parked = state.parked;
            Self::reset_webview_lifecycle_state(&mut state);
            state.parked = parked;
        }
    }

    pub(crate) fn needs_renderer_recovery(&self) -> bool {
        self.inner
            .state
            .lock()
            .is_ok_and(|state| state.renderer_recovery_pending)
    }

    /// WKWebView survives renderer loss; only its document must be rebuilt.
    #[cfg(target_vendor = "apple")]
    pub(crate) fn recover_renderer(&self) -> Result<(), LxAppError> {
        let _transition = self.reset_transition_guard();
        {
            let mut state = self.inner.state.lock().unwrap();
            if !std::mem::take(&mut state.renderer_recovery_pending) {
                return Ok(());
            }
            // A departed page already owes a fresh document on its next entry.
            if state.document_is_departing() {
                return Ok(());
            }
        }
        if self.webview().is_none() {
            return Ok(());
        }
        if let Err(error) = self.load_html() {
            self.inner.state.lock().unwrap().renderer_recovery_pending = true;
            return Err(error);
        }
        Ok(())
    }

    fn invalidate_document_state(state: &mut PageState) {
        // Logic and the entry/query survive. Replaying onLoad would reset
        // forms and duplicate subscriptions; only onReady belongs to the new DOM.
        state.bridge_ready = false;
        state.ready_dispatched = false;
        state.render_status = PageRenderStatus::Unstarted;
    }

    fn invalidate_renderer_state(state: &mut PageState) {
        Self::invalidate_document_state(state);
        state.renderer_recovery_pending = true;
    }

    /// Apply a re-read page JSON to a retained instance. Dev reload uses this
    /// so `navigationStyle` and the rest of the native chrome follow the file.
    pub(crate) fn apply_reloaded_page_json(&self, lxapp: &LxApp) {
        let (page_config, config_load_error) = match PageConfig::from_json(lxapp, &self.path()) {
            Ok(config) => (config, None),
            Err(error) => {
                error!("Page config load failed for {}: {}", self.path(), error)
                    .with_appid(lxapp.appid.clone())
                    .with_path(self.path().to_string());
                (PageConfig::default(), Some(error.to_string()))
            }
        };
        if let Ok(mut state) = self.inner.state.lock() {
            state.navbar_state = page_config.create_navbar_state();
            state.config_load_error = config_load_error;
            state.enable_pull_down_refresh = page_config.is_pull_down_refresh_enabled();
            state.orientation_override = page_config.get_orientation_override();
        }
    }

    /// Attach WebView to this page (called when WebView is ready)
    pub fn attach_webview(&self, webview: Arc<WebView>) {
        let mut should_reset_lifecycle = false;
        if let Ok(mut webview_guard) = self.inner.webview.lock() {
            let current_webview_is_same = webview_guard
                .as_ref()
                .map(|current| Arc::ptr_eq(current, &webview));
            should_reset_lifecycle =
                Self::should_reset_lifecycle_on_attach(current_webview_is_same);
            *webview_guard = Some(webview);
        }
        if should_reset_lifecycle && let Ok(mut state) = self.inner.state.lock() {
            Self::reset_webview_lifecycle_state(&mut state);
        }
    }

    /// Admit a platform-attested WebView message into this page's bridge.
    ///
    /// The message context remains attached through protocol decode and host
    /// route dispatch so authorization can be installed at one admission seam.
    pub fn handle_incoming_web_message(
        &self,
        message: IncomingWebMessage,
    ) -> Result<(), LxAppError> {
        self.inner.bridge.handle_incoming(self, message)
    }

    /// Registry-held phase of browser control ingress. It prepares an opaque
    /// frame without invoking host code or synchronously posting to WebView.
    #[doc(hidden)]
    pub fn prepare_required_v3_incoming(
        &self,
        native_authority: &crate::NativeControlPlaneAuthority,
        message: IncomingWebMessage,
        authority: crate::ControlDocumentAuthority,
        execution_gate: crate::RequiredV3ExecutionGate,
    ) -> Result<crate::PreparedRequiredV3Incoming, LxAppError> {
        self.inner.bridge.prepare_required_v3_incoming(
            native_authority,
            self,
            message,
            authority,
            execution_gate,
        )
    }

    /// Post-registry-lock phase of browser control ingress.
    #[doc(hidden)]
    pub fn execute_prepared_required_v3_incoming(
        &self,
        prepared: crate::PreparedRequiredV3Incoming,
    ) -> Result<(), LxAppError> {
        self.inner
            .bridge
            .execute_prepared_required_v3_incoming(self, prepared)
    }

    /// Get complete page state
    pub fn get_page_state(&self) -> Option<PageState> {
        self.inner.state.lock().ok().map(|state| state.clone())
    }

    // Only the entry clock rewinds here. `onReady` belongs to the rendered
    // document, so a cached instance that re-enters without a document reload
    // has nothing new to be ready about.
    fn request_on_load(state: &mut PageState) {
        state.entry = EntryPhase::LoadOwed;
        state.reset = PageReset::None;
        if state.visibility == Visibility::Shown {
            state.visibility = Visibility::ShowOwed;
        }
    }

    /// Handshake auto-boots `onLoad` only for a page that is already supposed
    /// to be on screen, or an isolated surface. A Hidden Idle page is a warm
    /// instance waiting for an entry — preloaded tabs — and must not run
    /// `onLoad` until switchTab / launch / navigate requests it.
    fn handshake_should_request_on_load(state: &PageState, isolated: bool) -> bool {
        state.entry == EntryPhase::Idle
            && state.reset == PageReset::None
            && (isolated || state.visibility != Visibility::Hidden)
    }

    /// `switchTab` onto a warm tab is a visibility flip, not a new entry.
    fn switch_tab_should_request_on_load(entry: EntryPhase) -> bool {
        entry == EntryPhase::Idle
    }

    pub(crate) fn switch_tab_owes_on_load(&self) -> bool {
        self.inner
            .state
            .lock()
            .map(|state| Self::switch_tab_should_request_on_load(state.entry))
            .unwrap_or(true)
    }

    fn should_reset_lifecycle_on_attach(current_webview_is_same: Option<bool>) -> bool {
        matches!(current_webview_is_same, Some(false))
    }

    fn reset_webview_lifecycle_state(state: &mut PageState) {
        let is_currently_visible = state.event == Some(PageLifecycleEvent::OnShow);
        state.event = None;
        state.parked = false;
        state.render_status = PageRenderStatus::Unstarted;
        state.visibility = if is_currently_visible {
            Visibility::ShowOwed
        } else {
            Visibility::Hidden
        };
        state.entry = EntryPhase::Idle;
        state.bridge_ready = false;
        state.ready_dispatched = false;
    }

    fn collect_ready_lifecycle_events(
        state: &mut PageState,
        events_to_fire: &mut Vec<(PageLifecycleEvent, Option<String>)>,
    ) {
        if state.entry == EntryPhase::LoadOwed
            && (!state.requires_bridge_ready || state.bridge_ready)
            && !matches!(state.render_status, PageRenderStatus::Unstarted)
        {
            let query = serde_json::to_string(&state.query).ok();
            events_to_fire.push((PageLifecycleEvent::OnLoad, query));
            state.entry = EntryPhase::Loaded;
        }

        // Weixin ordering for the first visible load is Load -> Show -> Ready.
        if state.entry == EntryPhase::Loaded && state.visibility == Visibility::ShowOwed {
            events_to_fire.push((PageLifecycleEvent::OnShow, None));
            state.visibility = Visibility::Shown;
            state.event = Some(PageLifecycleEvent::OnShow);
        }

        // `onReady` is the first-paint hook of a visible entry. A document
        // that finished off-screen (preloaded tab) waits until Show.
        if state.entry == EntryPhase::Loaded
            && (!state.requires_bridge_ready || state.bridge_ready)
            && state.render_status == PageRenderStatus::Finished
            && !state.ready_dispatched
            && state.visibility == Visibility::Shown
        {
            events_to_fire.push((PageLifecycleEvent::OnReady, None));
            state.ready_dispatched = true;
        }
    }

    fn collect_hidden_or_unloaded_lifecycle_event(
        state: &mut PageState,
        event: PageLifecycleEvent,
        events_to_fire: &mut Vec<(PageLifecycleEvent, Option<String>)>,
    ) {
        debug_assert!(matches!(
            event,
            PageLifecycleEvent::OnHide | PageLifecycleEvent::OnUnload
        ));

        state.visibility = Visibility::Hidden;
        if event == PageLifecycleEvent::OnUnload && state.entry == EntryPhase::LoadOwed {
            // Cancel an entry that never got its `onLoad`. One already
            // delivered stays delivered: the PageInstance can be reused after
            // `onUnload` without a fresh bridge handshake, and only real
            // document teardown rewinds the entry through reset.
            state.entry = EntryPhase::Idle;
        }
        if state.event != Some(event) {
            events_to_fire.push((event, None));
            state.event = Some(event);
        }
    }

    fn lifecycle_cancels_bridge_work(event: PageLifecycleEvent) -> bool {
        event == PageLifecycleEvent::OnUnload
    }

    fn fire_lifecycle_events(&self, events_to_fire: Vec<(PageLifecycleEvent, Option<String>)>) {
        if events_to_fire.is_empty() {
            return;
        }

        let lxapp = self.owning_lxapp();
        let appid = self.appid();
        let path = self.path();

        if events_to_fire
            .iter()
            .any(|(event, _)| *event == PageLifecycleEvent::OnReady)
        {
            notify_home_first_ready_once(&appid);
        }

        for (event, query) in events_to_fire {
            // Keep the in-process native-component host in sync with
            // the page lifecycle: hidden AND unloaded pages hide their
            // overlays and pause playback (an unloaded page's webview
            // may stay cached and be revived by a later navigation, so
            // its components only pause here — they are torn down with
            // the page instance through `on_page_destroyed` when it is
            // disposed). Mirrors the platform managers' inactive/
            // active/destroyed handling.
            match event {
                PageLifecycleEvent::OnShow => {
                    crate::native_component::notify_page_visibility(self.webtag().key(), true);
                }
                PageLifecycleEvent::OnHide | PageLifecycleEvent::OnUnload => {
                    crate::native_component::notify_page_visibility(self.webtag().key(), false);
                }
                _ => {}
            }

            if let Err(e) = lxapp.executor.call_page_service_event(
                lxapp.clone(),
                path.clone(),
                Some(self.instance_id_string()),
                event,
                query,
            ) {
                error!("Failed to call {}: {}", String::from(event), e)
                    .with_appid(appid.clone())
                    .with_path(path.clone());
            }
        }
    }

    pub(crate) fn notify_bridge_ready(&self) {
        let mut events_to_fire: Vec<(PageLifecycleEvent, Option<String>)> = Vec::new();
        {
            let mut state = self.inner.state.lock().unwrap();
            if state.bridge_ready {
                return;
            }

            state.bridge_ready = true;
            // A page whose document was rebuilt for a future entry has no
            // entry to serve: booting here would deliver `onLoad` (with the
            // previous entry's query) and `onReady` to nobody, and leave the
            // real entry with a second `onLoad` and no `onReady`. Pages that
            // handshake while already supposed to be shown — surfaces, an
            // app-service restart — still boot from here. Hidden Idle pages
            // are warm instances, not entries.
            if Self::handshake_should_request_on_load(&state, self.inner.isolated) {
                Self::request_on_load(&mut state);
            }
            Self::collect_ready_lifecycle_events(&mut state, &mut events_to_fire);
        }
        self.fire_lifecycle_events(events_to_fire);
    }

    fn notify_render_started_inner(&self) {
        let mut events_to_fire: Vec<(PageLifecycleEvent, Option<String>)> = Vec::new();
        {
            let mut state = self.inner.state.lock().unwrap();
            state.render_status = PageRenderStatus::Started;
            Self::collect_ready_lifecycle_events(&mut state, &mut events_to_fire);
        }
        self.fire_lifecycle_events(events_to_fire);
    }

    fn notify_render_finished_after_scripts(&self) {
        let mut events_to_fire: Vec<(PageLifecycleEvent, Option<String>)> = Vec::new();
        {
            let mut state = self.inner.state.lock().unwrap();
            state.render_status = PageRenderStatus::Finished;
            Self::collect_ready_lifecycle_events(&mut state, &mut events_to_fire);
        }
        self.fire_lifecycle_events(events_to_fire);
    }

    pub(crate) fn dispatch_lifecycle_event(&self, event: PageLifecycleEvent) {
        // Central lifecycle state machine for a single WebView-backed PageInstance.
        // Sources of events:
        // - First-time entry: open / navigate / first switchTab requests onLoad
        // - Handshake auto-boots onLoad only when the page is already supposed
        //   to be shown (surfaces, app-service restart), never a Hidden warm-up
        // - Re-navigation with new query (navigateTo / redirectTo): native
        //   requests onLoad again
        // - Render completion: WebView delegate triggers onReady after page
        //   scripts are injected, gated on the page having been shown
        // - Visibility changes: native triggers onShow/onHide
        // Goals (Weixin semantics adapted to a single WebView instance):
        // - onLoad carries query and may occur multiple times across logical
        //   navigations (first-time + each navigateTo with new params). switchTab
        //   onto a warm tab is not a new entry.
        // - onReady fires once per rendered document, after the first Show
        // - onShow fires each time the page becomes visible (after a hide), without query

        // Serialize the departure marker with Logic-to-View patch delivery.
        // Once this guard is acquired, an old service can no longer pass its
        // final acceptance check while this document is being retired.
        let _reset_transition =
            (event == PageLifecycleEvent::OnUnload).then(|| self.reset_transition_guard());

        if Self::lifecycle_cancels_bridge_work(event) {
            self.cancel_bridge_work();
        }

        // An entry never inherits the instance that left: if this page was
        // popped and its deferred reset has not run yet, complete it here,
        // before the entry's own onLoad is queued against the fresh state.
        if event == PageLifecycleEvent::OnLoad {
            self.owning_lxapp().flush_page_reset(self);
        }

        // A collection of events to fire after the lock is released.
        let mut events_to_fire: Vec<(PageLifecycleEvent, Option<String>)> = Vec::new();

        // acquire lock, update state, determine events to fire
        // The lock must be released before calling the executor to avoid deadlocks,
        // in case the JS code calls back into Rust and needs to access page state.
        {
            let mut state = self.inner.state.lock().unwrap();

            // OnPullDownRefresh is a simple event that fires immediately without state tracking
            if event == PageLifecycleEvent::OnPullDownRefresh {
                events_to_fire.push((event, None));
            }
            // OnHide and OnUnload are handled exclusively and do not trigger the main event cascade.
            else if event == PageLifecycleEvent::OnHide || event == PageLifecycleEvent::OnUnload {
                Self::collect_hidden_or_unloaded_lifecycle_event(
                    &mut state,
                    event,
                    &mut events_to_fire,
                );
            } else {
                // This logic handles the Load -> Show -> Ready cascade.

                // Update raw status based on the incoming event.
                if event == PageLifecycleEvent::OnShow && state.visibility != Visibility::Shown {
                    state.visibility = Visibility::ShowOwed;
                }

                if event == PageLifecycleEvent::OnLoad {
                    Self::request_on_load(&mut state);
                }

                Self::collect_ready_lifecycle_events(&mut state, &mut events_to_fire);
            }
        }

        //  Fire the collected events outside of the lock to prevent deadlocks.
        self.fire_lifecycle_events(events_to_fire);
    }

    /// Get navbar state (read-only)
    pub fn get_navbar_state(&self) -> Option<NavigationBarState> {
        self.inner
            .state
            .lock()
            .ok()
            .map(|state| state.navbar_state.clone())
    }

    /// Get navbar state with mutable access (internal use)
    pub fn get_navbar_state_mut<F, R>(&self, f: F) -> Option<R>
    where
        F: FnOnce(&mut NavigationBarState) -> R,
    {
        self.inner
            .state
            .lock()
            .ok()
            .map(|mut state| f(&mut state.navbar_state))
    }

    /// Get page orientation overrides from state
    pub fn get_orientation_override(&self) -> Option<OrientationOverride> {
        self.inner
            .state
            .lock()
            .ok()
            .map(|state| state.orientation_override)
    }

    /// Get WebView if available
    pub fn webview(&self) -> Option<Arc<WebView>> {
        if let Ok(webview_guard) = self.inner.webview.lock() {
            webview_guard.clone()
        } else {
            None
        }
    }

    /// Return a non-blocking readiness snapshot suitable for devtools.
    pub fn automation_state(&self) -> PageAutomationState {
        let webview_attached = self.webview().is_some();
        let webview_result = self
            .inner
            .webview_ready_rx
            .lock()
            .ok()
            .and_then(|rx| rx.borrow().clone());
        let (webview_ready, webview_error) = match webview_result {
            Some(Ok(())) => (true, None),
            Some(Err(error)) => (false, Some(error)),
            None => (false, None),
        };
        let state = self.inner.state.lock().ok();
        let bridge_ready = state.as_ref().is_some_and(|state| state.bridge_ready);
        let render_state = match state.as_ref().map(|state| state.render_status) {
            Some(PageRenderStatus::Started) => "loading",
            Some(PageRenderStatus::Finished) => "finished",
            _ => "unstarted",
        };
        let lifecycle = state
            .as_ref()
            .and_then(|state| state.event.map(|event| event.as_str()))
            .unwrap_or("unknown");
        let ready = state.as_ref().is_some_and(|state| state.ready_dispatched);
        let query = state
            .as_ref()
            .map(|state| state.query.clone())
            .unwrap_or_else(|| serde_json::json!({}));
        PageAutomationState {
            webview_attached,
            webview_ready,
            webview_error,
            bridge_ready,
            render_state,
            lifecycle,
            ready,
            query,
        }
    }

    pub(crate) fn mark_webview_ready(&self, result: Result<(), String>) {
        let ok = result.is_ok();
        // Ignore errors; receiver will handle missing updates.
        let _ = self.inner.webview_ready_tx.send(Some(result));
        if ok {
            crate::lxapp::page_discard::enforce_page_webview_budget();
        }
    }

    pub(crate) fn mark_page_svc_ready(&self) {
        let _ = self.inner.page_svc_ready_tx.send(true);
    }

    pub(crate) async fn wait_page_svc_ready(&self) -> Result<(), String> {
        let rx = self
            .inner
            .page_svc_ready_rx
            .lock()
            .map(|r| r.clone())
            .map_err(|_| "page svc ready receiver poisoned".to_string())?;
        if *rx.borrow() {
            return Ok(());
        }
        let mut rx = rx;
        let marked = async {
            while rx.changed().await.is_ok() {
                if *rx.borrow() {
                    return Ok(());
                }
            }
            Err("page svc ready channel closed before the opener created it".to_string())
        };
        tokio::time::timeout(PAGE_SVC_READY_TIMEOUT, marked)
            .await
            .unwrap_or_else(|_| {
                Err(format!(
                    "no opener created this isolated page's Logic service within {}s; \
                     an isolated instance must be opened through lx.surface",
                    PAGE_SVC_READY_TIMEOUT.as_secs()
                ))
            })
    }

    /// Notify that the page's WebView started loading (mirrors WebViewDelegate::on_page_started).
    /// Used by external delegates to forward events to a shared page.
    pub fn notify_page_started(&self) {
        if !self.inner.document_start_scripts.is_empty()
            && let Some(webview) = self.webview()
        {
            for js in &self.inner.document_start_scripts {
                if let Err(error) = webview.exec_js(js) {
                    crate::error!("document-start script injection failed: {}", error)
                        .with_appid(self.inner.appid.clone())
                        .with_path(self.inner.path.clone());
                }
            }
            // The page-chrome bootstrap was captured when the app first loaded
            // and carries that moment's scheme; stamp the live one onto this
            // new document so a later Appearance change is not undone.
            self.owning_lxapp().republish_page_scheme(self);
        }
        self.notify_render_started_inner();
    }

    pub async fn wait_webview_ready(&self) -> Result<(), String> {
        if self.is_discarded() {
            self.ensure_live_webview();
        }
        let rx = {
            // Clone receiver so concurrent waiters don't block each other.
            self.inner
                .webview_ready_rx
                .lock()
                .map(|r| r.clone())
                .map_err(|_| "webview ready receiver poisoned".to_string())?
        };

        // Fast-path: already has a value.
        if let Some(res) = rx.borrow().clone() {
            return res;
        }

        let mut rx = rx;
        while rx.changed().await.is_ok() {
            if let Some(res) = rx.borrow().clone() {
                return res;
            }
        }

        Err("webview ready channel closed before result".to_string())
    }

    async fn handle_loaded_async(&self) {
        if !self.inner.page_scripts.is_empty()
            && let Some(webview) = self.webview()
        {
            for js in &self.inner.page_scripts {
                if let Err(e) = webview.exec_js(js) {
                    crate::error!("page script injection failed: {}", e)
                        .with_appid(self.inner.appid.clone())
                        .with_path(self.inner.path.clone());
                }
            }
        }

        if self.inner.isolated {
            let lxapp = self.owning_lxapp();
            let revision = lxapp.next_page_chrome_revision();
            let appearance = lxapp.appearance_state().resolved;
            if let Err(err) = lxapp
                .publish_realized_page_chrome(self, revision, appearance)
                .await
            {
                crate::warn!("Failed to publish isolated page chrome: {}", err)
                    .with_appid(self.inner.appid.clone())
                    .with_path(self.inner.path.clone());
            }
        }

        self.notify_render_finished_after_scripts();
        self.inner.loaded_tx.send_modify(|v| *v = v.wrapping_add(1));
    }

    /// Unified page-loaded handler. Call from any delegate (lxapp or external)
    /// when the WebView finishes a navigation.
    ///
    /// Script injection is awaited before `OnReady` and loaded notifications.
    pub fn handle_loaded(&self) {
        let page = self.clone();
        std::mem::drop(crate::executor::spawn(async move {
            page.handle_loaded_async().await;
        }));
    }

    /// Subscribe to page-loaded events.
    ///
    /// The receiver is notified each time `handle_loaded` completes
    /// (scripts are already injected at that point).
    pub fn subscribe_loaded(&self) -> watch::Receiver<u64> {
        self.inner.loaded_tx.subscribe()
    }

    /// Detach and drop the WebView held by this page.
    /// This breaks PageInstance -> WebView strong reference and triggers platform Drop when
    /// combined with registry removal.
    pub fn detach_webview(&self) {
        self.cancel_bridge_work();
        if let Ok(mut webview_guard) = self.inner.webview.lock() {
            // Drop the Arc by taking it out
            let _ = webview_guard.take();
        }
        if let Ok(mut state) = self.inner.state.lock() {
            Self::reset_webview_lifecycle_state(&mut state);
        }
    }

    /// Get the WebView controller for this page (returns None if not ready)
    pub(crate) fn webview_controller(&self) -> Option<Arc<dyn WebViewController>> {
        if let Some(webview) = self.webview() {
            Some(webview as Arc<dyn WebViewController>)
        } else {
            None
        }
    }

    /// Load HTML content into this page's WebView.
    ///
    /// Does not wait on the permission snapshot: an empty WebView is torn down
    /// before the grant arrives. Fetches stay denied until it is ready.
    pub(crate) fn load_html(&self) -> Result<(), LxAppError> {
        // A real document is coming: its navigation events drive the render
        // pipeline again.
        if let Ok(mut state) = self.inner.state.lock() {
            state.parked = false;
            // A normal rebuild may have repaired the document before the
            // deferred foreground recovery gets to it.
            #[cfg(target_vendor = "apple")]
            {
                state.renderer_recovery_pending = false;
            }
        }
        let lxapp = self.owning_lxapp();
        let path = self.path();
        let config_load_error = self
            .inner
            .state
            .lock()
            .ok()
            .and_then(|state| state.config_load_error.clone());
        let html_string = if let Some(message) = config_load_error {
            lingxia_webview::render_load_error_page(lingxia_webview::LoadErrorPage {
                title: "Page configuration error",
                message: &message,
                retry_label: "Retry",
                retry_url: &self.base_url(),
            })
        } else {
            String::from_utf8_lossy(
                &lxapp.generate_page_html(&path, self.bridge_nonce().as_deref()),
            )
            .into_owned()
        };
        let base_url = self.base_url();

        if let Some(controller) = self.webview_controller() {
            controller
                .load_data(LoadDataRequest::new(&html_string, &base_url))
                .map_err(LxAppError::from)
        } else {
            Err(LxAppError::WebView("WebView not ready".to_string()))
        }
    }

    /// Returns the appid of this page
    pub fn path(&self) -> String {
        self.inner.path.clone()
    }

    /// Returns the appid of this page
    pub fn appid(&self) -> String {
        self.inner.appid.clone()
    }

    /// Returns the base URL used when loading this page's HTML.
    pub fn base_url(&self) -> String {
        if let Some((plugin_name, page_path)) = plugin::parse_plugin_page_path(&self.path()) {
            if page_path.is_empty() {
                return format!("lx://plugin/{}", plugin_name);
            }
            return format!("lx://plugin/{}/{}", plugin_name, page_path);
        }
        format!("lx://lxapp/{}/{}", self.appid(), self.path())
    }

    /// Update the last active time to now
    pub(crate) fn mark_active(&self) {
        if let Ok(mut time) = self.inner.last_active_time.lock() {
            *time = Instant::now();
        }
    }

    /// Get the last active time for LRU eviction
    pub(crate) fn get_last_active_time(&self) -> Option<Instant> {
        self.inner.last_active_time.lock().ok().map(|time| *time)
    }

    /// Check if pull-to-refresh is enabled for this page
    pub fn is_pull_down_refresh_enabled(&self) -> bool {
        self.inner
            .state
            .lock()
            .ok()
            .map(|state| state.enable_pull_down_refresh)
            .unwrap_or(false)
    }

    /// Check if this page is a TabBar page
    pub fn is_tabbar_page(&self) -> bool {
        let lxapp = self.owning_lxapp();
        match lxapp.get_tabbar() {
            Some(tab_bar) => tab_bar.is_tabbar_page(&self.inner.path),
            None => false,
        }
    }

    pub fn navigate_to(
        &self,
        target_page: PageInstance,
        nav_type: NavigationType,
    ) -> Result<PageInstance, LxAppError> {
        // Normalize through LxApp to ensure consistent canonical paths (e.g. plugin routes).
        let target_url =
            crate::append_page_query(target_page.path(), &target_page.automation_state().query)
                .map_err(LxAppError::InvalidParameter)?;
        self.navigate_to_url(&target_url, nav_type)
    }

    /// Navigate from this page to a target URL. This is the entry point that
    /// decides which instance the navigation lands on.
    pub fn navigate_to_url(
        &self,
        target_url: &str,
        nav_type: NavigationType,
    ) -> Result<PageInstance, LxAppError> {
        let lxapp = self.owning_lxapp();
        lxapp.validate_navigation_entry(target_url, nav_type)?;
        let target_page = if nav_type == NavigationType::Replace
            && lxapp.resolve_entry_path(target_url) == self.path()
        {
            // Redirecting a page to itself keeps the instance and document;
            // the entry re-runs onLoad against the updated query.
            lxapp.get_or_create_page(target_url)
        } else {
            lxapp.create_page_for_entry(target_url)
        };
        self.navigate_to_internal(target_page, nav_type, &lxapp)
    }

    /// Internal navigation logic shared by regular and plugin navigation
    fn navigate_to_internal(
        &self,
        target_page: PageInstance,
        nav_type: NavigationType,
        lxapp: &Arc<LxApp>,
    ) -> Result<PageInstance, LxAppError> {
        let path = target_page.path();
        let target_url =
            crate::append_page_query(path.clone(), &target_page.automation_state().query)
                .map_err(LxAppError::InvalidParameter)?;
        let mut target_page = target_page;
        // Public entry points run this before resolving PageSvc/query state;
        // keep the same preflight here as a backstop for direct native calls.
        lxapp.validate_navigation_entry(&target_url, nav_type)?;
        if target_page.is_discarded() {
            target_page.ensure_live_webview();
        }
        let is_tabbar_page = lxapp
            .get_tabbar()
            .is_some_and(|tabbar| tabbar.is_tabbar_page(&path));
        let is_tab_switch = nav_type == NavigationType::SwitchTab
            || (nav_type == NavigationType::Launch && is_tabbar_page);
        let is_initial_route = path == lxapp.config().get_initial_route();

        // 2. Handle page stack modifications
        match nav_type {
            NavigationType::Launch | NavigationType::SwitchTab => {
                if nav_type == NavigationType::Launch {
                    let stack_pages = lxapp.get_page_stack_pages();
                    for page in &stack_pages {
                        page.dispatch_lifecycle_event(PageLifecycleEvent::OnUnload);
                        let webview = page.webview();
                        page.detach_webview();
                        if let Some(webview) = webview {
                            destroy_webview_if_matches(&page.webtag(), &webview);
                        }
                    }
                    let stack_ids: Vec<String> = stack_pages
                        .iter()
                        .map(|page| page.instance_id_string())
                        .collect();
                    lxapp.remove_pages(&stack_ids);
                    target_page = lxapp.get_or_create_page(&target_url);
                }
                if nav_type == NavigationType::SwitchTab {
                    // switchTab only hides the tab pages it leaves, but any
                    // pushed page leaves the stack for good here and must end
                    // its instance like every other departure.
                    for page in lxapp.get_page_stack_pages() {
                        if page.is_tabbar_page() {
                            continue;
                        }
                        page.dispatch_lifecycle_event(PageLifecycleEvent::OnUnload);
                        lxapp.schedule_page_reset(&page);
                    }
                }
                lxapp.clear_page_stack()?;
            }
            NavigationType::Replace => {
                lxapp.pop_from_page_stack();
            }
            NavigationType::Forward => {
                // Backstop for the preflight: only a path-pinned singleton
                // (tab page) can resolve to an instance already on the stack,
                // and two slots must never share one instance.
                if lxapp
                    .get_page_stack()
                    .iter()
                    .any(|id| id == &target_page.instance_id_string())
                {
                    return Err(LxAppError::InvalidParameter(format!(
                        "navigateTo target '{path}' is already on the page stack; \
                         use lx.switchTab or lx.navigateBack to return to it."
                    )));
                }
            }
            NavigationType::Backward => {
                return Err(LxAppError::UnsupportedOperation(
                    "should use navigate_back".to_string(),
                ));
            }
        }

        // 3. Handle UI state based on navigation type (TabBar, NavBar)
        lxapp.with_tabbar_mut(|t| t.set_visible(is_tab_switch));
        if is_tab_switch
            && let Some(Some(index)) = lxapp.with_tabbar_mut(|t| t.find_index_by_path(&path))
        {
            lxapp.with_tabbar_mut(|t| {
                t.set_selected_index(index);
            });
        } else if !is_tabbar_page {
            // Navigating to a non-tab page: no tabbar item may stay
            // highlighted (the lxapp tab itself still is).
            lxapp.with_tabbar_mut(|t| {
                t.clear_selected_index();
            });
        }
        lxapp.push_to_page_stack(&target_page)?;

        // Set navbar state AFTER page creation to avoid being overwritten
        let stack_size = lxapp.get_page_stack_size();
        let show_back_button = stack_size > 1;
        let show_home_button = stack_size <= 1 && !is_tabbar_page && !is_initial_route;
        target_page.get_navbar_state_mut(|navbar| {
            let allow_buttons = navbar.show_navbar;
            navbar.set_back_button_visibility(show_back_button && allow_buttons);
            navbar.set_home_button_visibility(show_home_button && allow_buttons);
        });

        lxapp.sync_host_ui();

        // 5. Dispatch lifecycle events for current and target pages
        match nav_type {
            NavigationType::Replace => {
                // Replacing a page with itself never takes it off screen, so
                // unloading or resetting would retire the live document and
                // make its next `onLoad` unable to patch the view. The entry
                // re-runs `onLoad` with the new query against that document.
                if !Self::replace_reuses_document(&self.inner.id, &target_page.inner.id) {
                    self.dispatch_lifecycle_event(PageLifecycleEvent::OnUnload);
                    lxapp.schedule_page_reset(self);
                }
            }
            NavigationType::Launch => {}
            _ => {
                // A non-tab page leaving on a switchTab was already unloaded
                // with the rest of the stack; hiding it now would be a second
                // goodbye to an instance that ended.
                let unloaded_by_tab_switch = nav_type == NavigationType::SwitchTab
                    && !lxapp
                        .get_tabbar()
                        .is_some_and(|tabbar| tabbar.is_tabbar_page(&self.path()));
                if !unloaded_by_tab_switch {
                    self.dispatch_lifecycle_event(PageLifecycleEvent::OnHide);
                }
            }
        }

        // Request onLoad for a new entry. switchTab onto a tab that already
        // ran onLoad is only a visibility flip — onShow comes from the
        // platform container, the same way navigateBack reveals a page.
        if nav_type != NavigationType::SwitchTab || target_page.switch_tab_owes_on_load() {
            target_page.dispatch_lifecycle_event(PageLifecycleEvent::OnLoad);
        }

        // 6. Perform the native navigation
        (*lxapp.runtime)
            .navigate(
                self.appid(),
                path,
                target_page.webtag().key().to_string(),
                nav_type.to_animation(),
            )
            .map_err(LxAppError::from)?;

        lxapp.sync_host_ui();

        // Do not dispatch OnReady here. WebViewDelegate::on_page_finished() will do it.

        Ok(target_page)
    }

    fn replace_reuses_document(source: &PageInstanceId, target: &PageInstanceId) -> bool {
        source == target
    }

    pub fn navigate_back(&self, delta: u32) -> Result<(), LxAppError> {
        let lxapp = self.owning_lxapp();
        let stack_size = lxapp.get_page_stack_size();

        // Ensure at least one page remains
        if stack_size <= 1 {
            return Ok(());
        }

        let mut pages_to_pop = delta;
        // Prevent popping all pages
        if pages_to_pop as usize >= stack_size {
            pages_to_pop = (stack_size - 1) as u32;
        }

        if pages_to_pop == 0 {
            return Ok(());
        }

        for _ in 0..pages_to_pop {
            if let Some(page) = lxapp.pop_from_page_stack() {
                page.dispatch_lifecycle_event(PageLifecycleEvent::OnUnload);
                // `onUnload` means the instance ended. The WebView is retained
                // for a warm re-entry, so reset the service and the document
                // behind it — otherwise the next entry inherits this one's
                // `data` and its DOM, popups included.
                lxapp.schedule_page_reset(&page);
            }
        }

        if let Ok(dest) = lxapp.current_page() {
            if dest.is_discarded() {
                dest.ensure_live_webview();
            }
            let path = dest.path();
            // Forward navigation clears selected_index on detail pages, so
            // Back must restore selection as well as visibility.
            let is_tabbar_page = lxapp
                .with_tabbar_mut(|tabbar| restore_tabbar_after_back(tabbar, &path))
                .unwrap_or(false);

            // Update NavBar back button visibility based on the new stack size
            let new_stack_size = lxapp.get_page_stack_size();
            {
                let dest_page = dest.clone();
                let is_initial_route = path == lxapp.config().get_initial_route();
                let show_home_button = new_stack_size <= 1 && !is_tabbar_page && !is_initial_route;
                dest_page.get_navbar_state_mut(|navbar| {
                    let allow_buttons = navbar.show_navbar;
                    navbar.set_back_button_visibility(new_stack_size > 1 && allow_buttons);
                    navbar.set_home_button_visibility(show_home_button && allow_buttons);
                });
            }

            (*lxapp.runtime).navigate(
                self.appid(),
                path.clone(),
                dest.webtag().key().to_string(),
                NavigationType::Backward.to_animation(),
            )?;
            // Reveal lifecycle for the destination. Platforms with native
            // page containers (iOS/Android/Harmony) call `on_page_show`
            // from the container when the page surfaces; the windowed
            // runtime has no such callback, and `dispatch_lifecycle_event`
            // de-dupes when both paths fire.
            dest.dispatch_lifecycle_event(PageLifecycleEvent::OnShow);
            dest.mark_active();
            lxapp.sync_host_ui();
            Ok(())
        } else {
            Err(LxAppError::UnsupportedOperation(
                "PageInstance stack is empty after pop".to_string(),
            ))
        }
    }

    pub(crate) fn set_query(&self, query_str: String) {
        if let Ok(query_value) = parse_query_string(&query_str) {
            self.inner.state.lock().unwrap().query = query_value;
        }
    }

    /// Call a JavaScript function in the page's logic service
    ///
    /// # Arguments
    /// * `name` - Function name to call
    /// * `arg` - JSON string containing function arguments
    ///
    /// # Returns
    /// `Ok(())` if successful, `Err(LxAppError)` if execution fails
    pub fn call_js(&self, name: String, arg: String) -> Result<(), LxAppError> {
        let lxapp = self.owning_lxapp();
        lxapp.executor.call_page_service(
            lxapp.clone(),
            self.path(),
            Some(self.instance_id_string()),
            name,
            Some(arg),
        )
    }

    /// Call a View method on this page without a payload and deserialize the response.
    pub async fn call_view<R>(&self, method: &str) -> Result<R, LxAppError>
    where
        R: DeserializeOwned,
    {
        self.call_view_in(method, ViewCallOptions::default()).await
    }

    /// Call a View method on this page without a payload using explicit call options.
    pub async fn call_view_in<R>(
        &self,
        method: &str,
        options: ViewCallOptions,
    ) -> Result<R, LxAppError>
    where
        R: DeserializeOwned,
    {
        let value = self.call_view_json_in(method, options).await?;
        decode_view_call_result(method, value)
    }

    /// Call a View method on this page with a typed payload and deserialize the response.
    pub async fn call_view_with<P, R>(&self, method: &str, params: &P) -> Result<R, LxAppError>
    where
        P: Serialize + ?Sized,
        R: DeserializeOwned,
    {
        self.call_view_with_in(method, params, ViewCallOptions::default())
            .await
    }

    /// Call a View method on this page with a typed payload using explicit call options.
    pub async fn call_view_with_in<P, R>(
        &self,
        method: &str,
        params: &P,
        options: ViewCallOptions,
    ) -> Result<R, LxAppError>
    where
        P: Serialize + ?Sized,
        R: DeserializeOwned,
    {
        let value = self.call_view_json_with_in(method, params, options).await?;
        decode_view_call_result(method, value)
    }

    /// Call a View method on this page and return the raw JSON response.
    pub async fn call_view_json(&self, method: &str) -> Result<Value, LxAppError> {
        self.call_view_json_in(method, ViewCallOptions::default())
            .await
    }

    /// Call a View method on this page and return the raw JSON response using explicit options.
    pub async fn call_view_json_in(
        &self,
        method: &str,
        options: ViewCallOptions,
    ) -> Result<Value, LxAppError> {
        self.call_view_json_value(method, None, options).await
    }

    /// Call a View method on this page with a typed payload and return the raw JSON response.
    pub async fn call_view_json_with<P>(
        &self,
        method: &str,
        params: &P,
    ) -> Result<Value, LxAppError>
    where
        P: Serialize + ?Sized,
    {
        self.call_view_json_with_in(method, params, ViewCallOptions::default())
            .await
    }

    /// Call a View method on this page with a typed payload and return the raw JSON response.
    pub async fn call_view_json_with_in<P>(
        &self,
        method: &str,
        params: &P,
        options: ViewCallOptions,
    ) -> Result<Value, LxAppError>
    where
        P: Serialize + ?Sized,
    {
        self.call_view_json_value(method, serialize_view_call_params(params)?, options)
            .await
    }

    async fn call_view_json_value(
        &self,
        method: &str,
        params: Option<Value>,
        options: ViewCallOptions,
    ) -> Result<Value, LxAppError> {
        let pending = crate::view_call::call_view(self, method, params)?;
        crate::view_call::await_pending_view_call(pending, options.timeout()).await
    }
}

/// Owned form of a `NavigationOutcome`, so the progress lock is released
/// before the handlers run.
enum ClassifiedNavigation {
    Started,
    Loaded,
    Failed { description: String, kind: String },
    Superseded,
}

impl WebViewDelegate for PageInstance {
    fn on_web_content_process_terminated(&self, native_view: NativeWebViewId) {
        if self
            .webview()
            .is_none_or(|view| view.native_view_id() != native_view)
        {
            return;
        }
        {
            let _transition = self.reset_transition_guard();
            Self::invalidate_renderer_state(&mut self.inner.state.lock().unwrap());
            self.cancel_bridge_work();
        }
        warn!("Page renderer terminated; scheduling recovery")
            .with_appid(self.appid())
            .with_path(self.path());
        self.owning_lxapp().recover_terminated_renderers();
    }

    fn on_navigation_event(&self, event: lingxia_webview::NavigationEvent) {
        // A parked document's navigation is bookkeeping, not a page render:
        // it must not inject scripts or advance the render clock.
        if self.inner.state.lock().is_ok_and(|state| state.parked) {
            return;
        }
        let outcome = {
            let mut progress = self
                .inner
                .navigation_progress
                .lock()
                .unwrap_or_else(|e| e.into_inner());
            // Borrowing the event out of the guard would hold the lock across
            // the handlers below, which re-enter page state.
            match progress.classify(&event) {
                NavigationOutcome::Started { .. } => ClassifiedNavigation::Started,
                NavigationOutcome::Loaded { .. } => ClassifiedNavigation::Loaded,
                NavigationOutcome::Failed { error } => ClassifiedNavigation::Failed {
                    description: error.description.clone(),
                    kind: format!("{:?}", error.kind),
                },
                NavigationOutcome::Superseded => ClassifiedNavigation::Superseded,
            }
        };
        match outcome {
            ClassifiedNavigation::Started => self.notify_page_started(),
            ClassifiedNavigation::Loaded => self.handle_loaded(),
            ClassifiedNavigation::Failed { description, kind } => {
                error!("page load failed: {} ({})", description, kind)
                    .with_appid(self.inner.appid.clone())
                    .with_path(self.inner.path.clone());
            }
            ClassifiedNavigation::Superseded => {}
        }
    }

    /// Handles a postMessage from the WebView
    fn handle_post_message(&self, message: IncomingWebMessage) {
        // Native-component envelopes can mutate native state without entering
        // the JSON bridge. Admit every platform-attested message first; bridge
        // dispatch repeats this idempotent check immediately before decoding.
        if let Err(e) = self.inner.bridge.admit_incoming(self, message.context()) {
            error!("Rejected postMessage: {}", e)
                .with_appid(self.inner.appid.clone())
                .with_path(self.inner.path.clone());
            return;
        }
        let msg = message.body();
        if let Some((level, message)) = decode_console_envelope(msg) {
            self.log(level, &message);
            return;
        }
        if let Some(component_payload) = decode_native_component_envelope(msg) {
            self.handle_native_component_message(component_payload);
            return;
        }

        if let Err(e) = self.handle_incoming_web_message(message) {
            if self.document_is_departing() || self.webview().is_none() {
                debug!("Dropping view message after page unload")
                    .with_appid(self.inner.appid.clone())
                    .with_path(self.inner.path.clone());
            } else {
                error!("Invalid postMessage: {}", e)
                    .with_appid(self.inner.appid.clone())
                    .with_path(self.inner.path.clone());
            }
        }
    }

    /// Routes embedded native-component messages from the view to the
    /// registered in-process host (Windows; other platforms deliver
    /// component traffic through their own channels and never hit this).
    fn handle_native_component_message(&self, message_json: String) {
        crate::native_component::dispatch_component_message(self, &message_json);
    }

    /// Receive log from WebView
    fn log(&self, level: LogLevel, message: &str) {
        // Convert lingxia_webview::LogLevel to lingxia_log::LogLevel
        let log_level = match level {
            LogLevel::Error => LxLogLevel::Error,
            LogLevel::Warn => LxLogLevel::Warn,
            LogLevel::Info => LxLogLevel::Info,
            LogLevel::Debug => LxLogLevel::Debug,
            LogLevel::Verbose => LxLogLevel::Debug, // Map Verbose to Debug
        };

        LogBuilder::new(LogTag::WebViewConsole, message)
            .with_level(log_level)
            .with_path(&self.inner.path)
            .with_appid(self.inner.appid.clone());
    }
}

fn decode_console_envelope(msg: &str) -> Option<(LogLevel, String)> {
    let json = serde_json::from_str::<Value>(msg).ok()?;
    json.get("__lingxia_console__")
        .and_then(Value::as_bool)
        .filter(|enabled| *enabled)?;
    let level = match json.get("level").and_then(Value::as_str) {
        Some("error") => LogLevel::Error,
        Some("warn") => LogLevel::Warn,
        Some("debug") => LogLevel::Debug,
        Some("info") => LogLevel::Info,
        Some("verbose") => LogLevel::Verbose,
        _ => LogLevel::Info,
    };
    let message = json.get("message").and_then(Value::as_str)?.to_string();
    Some((level, message))
}

fn decode_native_component_envelope(msg: &str) -> Option<String> {
    let json = serde_json::from_str::<Value>(msg).ok()?;
    json.get("__lingxia_native_component__")
        .and_then(Value::as_bool)
        .filter(|enabled| *enabled)?;
    json.get("payload")
        .and_then(Value::as_str)
        .map(str::to_string)
}

impl Drop for PageInstanceInner {
    fn drop(&mut self) {
        // Native components mounted by this page (if any) go down with it.
        crate::native_component::notify_page_destroyed(self.webtag.key());

        // Destroy WebView if it exists
        if let Ok(mut webview) = self.webview.lock()
            && let Some(_webview_controller) = webview.take()
        {
            // WebView will be automatically destroyed when controller is dropped
            info!("WebView destroyed for page")
                .with_appid(self.appid.clone())
                .with_path(self.path.clone());
        }
    }
}

fn restore_tabbar_after_back(tabbar: &mut crate::lxapp::tabbar::TabBar, path: &str) -> bool {
    let index = tabbar.find_index_by_path(path);
    tabbar.set_visible(index.is_some());
    if let Some(index) = index {
        tabbar.set_selected_index(index);
        true
    } else {
        false
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[derive(Debug, serde::Deserialize)]
    struct ViewReply {
        ok: bool,
    }

    fn test_page_state() -> PageState {
        PageState {
            event: None,
            render_status: PageRenderStatus::Unstarted,
            entry: EntryPhase::Idle,
            visibility: Visibility::Hidden,
            bridge_ready: false,
            requires_bridge_ready: true,
            ready_dispatched: false,
            reset: PageReset::None,
            parked: false,
            renderer_recovery_pending: false,
            navbar_state: NavigationBarState::default(),
            config_load_error: None,
            enable_pull_down_refresh: false,
            orientation_override: OrientationOverride::default(),
            query: serde_json::json!({}),
        }
    }

    #[test]
    fn document_discard_preserves_logic_entry_query_and_visibility() {
        let mut state = test_page_state();
        state.entry = EntryPhase::Loaded;
        state.visibility = Visibility::Hidden;
        state.event = Some(PageLifecycleEvent::OnHide);
        state.query = serde_json::json!({"step": "login"});
        state.bridge_ready = true;
        state.ready_dispatched = true;
        state.render_status = PageRenderStatus::Finished;

        PageInstance::invalidate_document_state(&mut state);
        assert!(!state.renderer_recovery_pending);
        assert!(!state.accepts_view_state_patches());
        assert_eq!(state.entry, EntryPhase::Loaded);
        assert_eq!(state.visibility, Visibility::Hidden);
        assert_eq!(state.query, serde_json::json!({"step": "login"}));
        assert!(!PageInstance::handshake_should_request_on_load(
            &state, false
        ));
    }

    #[test]
    fn renderer_recovery_preserves_logic_entry_query_and_visibility() {
        let mut state = test_page_state();
        state.entry = EntryPhase::Loaded;
        state.visibility = Visibility::Shown;
        state.event = Some(PageLifecycleEvent::OnShow);
        state.query = serde_json::json!({"step": "login"});
        state.bridge_ready = true;
        state.ready_dispatched = true;
        state.render_status = PageRenderStatus::Finished;

        PageInstance::invalidate_renderer_state(&mut state);
        assert!(state.renderer_recovery_pending);
        assert!(!state.accepts_view_state_patches());
        assert_eq!(state.entry, EntryPhase::Loaded);
        assert_eq!(state.visibility, Visibility::Shown);
        assert_eq!(state.query, serde_json::json!({"step": "login"}));
        assert!(!PageInstance::handshake_should_request_on_load(
            &state, false
        ));

        let mut events = Vec::new();
        state.requires_bridge_ready = true;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);
        assert!(events.is_empty());
        state.bridge_ready = true;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);
        assert_eq!(events, vec![(PageLifecycleEvent::OnReady, None)]);
    }

    #[test]
    fn renderer_recovery_does_not_reenter_hidden_or_parked_pages() {
        for parked in [false, true] {
            let mut state = test_page_state();
            state.parked = parked;
            if parked {
                state.reset = PageReset::AwaitingEntry;
            }
            PageInstance::invalidate_renderer_state(&mut state);
            assert_eq!(state.parked, parked);
            assert!(!PageInstance::handshake_should_request_on_load(
                &state, false
            ));
            let mut events = Vec::new();
            state.bridge_ready = true;
            state.render_status = PageRenderStatus::Finished;
            PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);
            assert!(events.is_empty());
        }
    }

    #[test]
    fn view_state_patches_drop_once_the_document_is_departing() {
        let mut state = test_page_state();
        assert!(!state.accepts_view_state_patches());

        state.bridge_ready = true;
        assert!(state.accepts_view_state_patches());

        state.parked = true;
        assert!(!state.accepts_view_state_patches());
        state.parked = false;

        state.reset = PageReset::Pending;
        assert!(!state.accepts_view_state_patches());
        state.reset = PageReset::AwaitingEntry;
        assert!(!state.accepts_view_state_patches());
        state.reset = PageReset::None;

        state.event = Some(PageLifecycleEvent::OnUnload);
        assert!(!state.accepts_view_state_patches());
    }

    #[test]
    fn rebuilding_clears_the_departed_document_event() {
        let mut state = test_page_state();
        state.event = Some(PageLifecycleEvent::OnUnload);
        state.reset = PageReset::AwaitingEntry;
        state.parked = true;

        PageInstance::reset_webview_lifecycle_state(&mut state);
        state.reset = PageReset::None;

        assert_eq!(state.event, None);
        assert!(!state.document_is_departing());
    }

    #[test]
    fn same_instance_replace_keeps_the_document_live() {
        let source = PageInstanceId::new();
        let replacement = PageInstanceId::new();

        assert!(PageInstance::replace_reuses_document(&source, &source));
        assert!(!PageInstance::replace_reuses_document(
            &source,
            &replacement
        ));

        let mut state = test_page_state();
        state.bridge_ready = true;
        state.render_status = PageRenderStatus::Finished;
        state.entry = EntryPhase::Loaded;
        state.visibility = Visibility::Shown;
        state.event = Some(PageLifecycleEvent::OnShow);

        PageInstance::request_on_load(&mut state);
        let mut events = Vec::new();
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(events[0].0, PageLifecycleEvent::OnLoad);
        assert!(state.accepts_view_state_patches());
        assert!(!state.document_is_departing());
    }

    #[test]
    fn serialize_view_call_params_skips_null() {
        assert_eq!(serialize_view_call_params(&()).unwrap(), None);
        assert_eq!(
            serialize_view_call_params(&serde_json::json!({ "topic": "status" })).unwrap(),
            Some(serde_json::json!({ "topic": "status" }))
        );
    }

    #[test]
    fn decode_view_call_result_deserializes_typed_payload() {
        let reply: ViewReply =
            decode_view_call_result("example.echo", serde_json::json!({ "ok": true })).unwrap();
        assert!(reply.ok);
    }

    #[test]
    fn decode_view_call_result_reports_method_name() {
        let err = decode_view_call_result::<ViewReply>("example.echo", serde_json::json!({}))
            .unwrap_err();

        match err {
            LxAppError::Bridge(message) => {
                assert!(message.contains("example.echo"));
            }
            other => panic!("unexpected error: {other:?}"),
        }
    }

    #[test]
    fn view_call_options_default_timeout_is_positive() {
        assert!(ViewCallOptions::default().timeout() > Duration::ZERO);
    }

    #[test]
    fn back_to_tab_page_restores_the_selected_item() {
        let mut tabbar: crate::lxapp::tabbar::TabBar = serde_json::from_value(serde_json::json!({
            "items": [
                { "page": "home" },
                { "page": "api" }
            ]
        }))
        .unwrap();
        tabbar
            .validate(&[("home", "pages/home/index"), ("api", "pages/api/index")])
            .unwrap();
        tabbar.clear_selected_index();
        tabbar.set_visible(false);

        assert!(restore_tabbar_after_back(&mut tabbar, "pages/api/index"));
        assert!(tabbar.is_effectively_visible());
        assert_eq!(tabbar.get_selected_index(), 1);
    }

    #[test]
    fn lifecycle_cascade_waits_for_bridge_ready_before_on_load() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        PageInstance::request_on_load(&mut state);
        state.render_status = PageRenderStatus::Started;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert!(events.is_empty());
        assert_eq!(state.entry, EntryPhase::LoadOwed);
        assert_ne!(state.entry, EntryPhase::Loaded);

        state.bridge_ready = true;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![(PageLifecycleEvent::OnLoad, Some("{}".to_string()))]
        );
        assert_ne!(state.entry, EntryPhase::LoadOwed);
        assert_eq!(state.entry, EntryPhase::Loaded);
    }

    #[test]
    fn lifecycle_cascade_allows_on_load_without_bridge_for_native_only_pages() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.requires_bridge_ready = false;
        PageInstance::request_on_load(&mut state);
        state.render_status = PageRenderStatus::Started;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![(PageLifecycleEvent::OnLoad, Some("{}".to_string()))]
        );
        assert_ne!(state.entry, EntryPhase::LoadOwed);
        assert_eq!(state.entry, EntryPhase::Loaded);
    }

    #[test]
    fn lifecycle_cascade_orders_load_show_ready() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.entry = EntryPhase::LoadOwed;
        state.bridge_ready = true;
        state.visibility = Visibility::ShowOwed;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![
                (PageLifecycleEvent::OnLoad, Some("{}".to_string())),
                (PageLifecycleEvent::OnShow, None),
                (PageLifecycleEvent::OnReady, None),
            ]
        );
        assert_ne!(state.entry, EntryPhase::LoadOwed);
        assert_eq!(state.entry, EntryPhase::Loaded);
        assert_eq!(state.visibility, Visibility::Shown);
        assert!(state.ready_dispatched);
    }

    #[test]
    fn reentering_a_cached_page_does_not_refire_ready_without_a_reload() {
        let mut state = test_page_state();
        state.bridge_ready = true;
        state.visibility = Visibility::ShowOwed;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::request_on_load(&mut state);
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut Vec::new());
        assert!(state.ready_dispatched);

        // Re-entry without a document reload: load and show repeat, ready does not.
        let mut events = Vec::new();
        state.visibility = Visibility::ShowOwed;
        PageInstance::request_on_load(&mut state);
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![
                (PageLifecycleEvent::OnLoad, Some("{}".to_string())),
                (PageLifecycleEvent::OnShow, None),
            ]
        );
    }

    #[test]
    fn a_reset_page_fires_ready_again_for_the_new_document() {
        let mut state = test_page_state();
        state.bridge_ready = true;
        state.visibility = Visibility::ShowOwed;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::request_on_load(&mut state);
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut Vec::new());

        // A reset reloads the document, so the next render is ready-worthy.
        PageInstance::reset_webview_lifecycle_state(&mut state);
        state.bridge_ready = true;
        state.visibility = Visibility::ShowOwed;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::request_on_load(&mut state);
        let mut events = Vec::new();
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert!(events.contains(&(PageLifecycleEvent::OnReady, None)));
    }

    #[test]
    fn a_torn_down_page_does_not_boot_from_a_stray_handshake() {
        let mut state = test_page_state();
        state.reset = PageReset::AwaitingEntry;
        state.entry = EntryPhase::Idle;

        // The bridge-ready auto-request is what boots surfaces and app-service
        // restarts; a torn-down page whose rebuild is racing the entry must
        // stay put instead of firing onLoad at nobody.
        assert!(!PageInstance::handshake_should_request_on_load(
            &state, false
        ));
        assert!(!PageInstance::handshake_should_request_on_load(
            &state, true
        ));

        // The real entry clears it and takes over.
        PageInstance::request_on_load(&mut state);
        assert_eq!(state.reset, PageReset::None);
        assert_eq!(state.entry, EntryPhase::LoadOwed);
    }

    #[test]
    fn handshake_does_not_boot_a_hidden_idle_page() {
        let state = test_page_state();
        assert_eq!(state.entry, EntryPhase::Idle);
        assert_eq!(state.visibility, Visibility::Hidden);
        assert!(!PageInstance::handshake_should_request_on_load(
            &state, false
        ));
    }

    #[test]
    fn handshake_boots_a_visible_or_isolated_idle_page() {
        let mut shown = test_page_state();
        shown.visibility = Visibility::ShowOwed;
        assert!(PageInstance::handshake_should_request_on_load(
            &shown, false
        ));

        let hidden_surface = test_page_state();
        assert!(PageInstance::handshake_should_request_on_load(
            &hidden_surface,
            true
        ));
    }

    #[test]
    fn hidden_warmup_defers_ready_until_shown() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.bridge_ready = true;
        PageInstance::request_on_load(&mut state);
        state.render_status = PageRenderStatus::Finished;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![(PageLifecycleEvent::OnLoad, Some("{}".to_string()))]
        );
        assert!(!state.ready_dispatched);

        events.clear();
        state.visibility = Visibility::ShowOwed;
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);
        assert_eq!(
            events,
            vec![
                (PageLifecycleEvent::OnShow, None),
                (PageLifecycleEvent::OnReady, None),
            ]
        );
        assert!(state.ready_dispatched);
    }

    #[test]
    fn switch_tab_requests_on_load_only_for_a_fresh_entry() {
        assert!(PageInstance::switch_tab_should_request_on_load(
            EntryPhase::Idle
        ));
        assert!(!PageInstance::switch_tab_should_request_on_load(
            EntryPhase::LoadOwed
        ));
        assert!(!PageInstance::switch_tab_should_request_on_load(
            EntryPhase::Loaded
        ));
    }

    #[test]
    fn a_lifecycle_reset_unparks_the_document() {
        let mut state = test_page_state();
        state.parked = true;

        // Attaching a different WebView (or preparing for a service restart)
        // starts a fresh document story; stale parking must not swallow it.
        PageInstance::reset_webview_lifecycle_state(&mut state);
        assert!(!state.parked);
    }

    #[test]
    fn unload_cancels_a_pending_entry_but_not_a_delivered_one() {
        let mut owed = test_page_state();
        owed.entry = EntryPhase::LoadOwed;
        PageInstance::collect_hidden_or_unloaded_lifecycle_event(
            &mut owed,
            PageLifecycleEvent::OnUnload,
            &mut Vec::new(),
        );
        assert_eq!(owed.entry, EntryPhase::Idle);

        // A delivered entry stays delivered, so a reused instance does not
        // re-request `onLoad` off the back of its existing bridge.
        let mut delivered = test_page_state();
        delivered.entry = EntryPhase::Loaded;
        PageInstance::collect_hidden_or_unloaded_lifecycle_event(
            &mut delivered,
            PageLifecycleEvent::OnUnload,
            &mut Vec::new(),
        );
        assert_eq!(delivered.entry, EntryPhase::Loaded);
    }

    #[test]
    fn hiding_a_shown_page_owes_on_show_again_on_re_entry() {
        let mut state = test_page_state();
        state.bridge_ready = true;
        state.visibility = Visibility::ShowOwed;
        state.render_status = PageRenderStatus::Finished;
        PageInstance::request_on_load(&mut state);
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut Vec::new());
        assert_eq!(state.visibility, Visibility::Shown);

        let mut events = Vec::new();
        PageInstance::collect_hidden_or_unloaded_lifecycle_event(
            &mut state,
            PageLifecycleEvent::OnHide,
            &mut events,
        );
        assert_eq!(state.visibility, Visibility::Hidden);

        // Becoming visible again owes another onShow, with no second onLoad:
        // the entry never ended.
        state.visibility = Visibility::ShowOwed;
        let mut events = Vec::new();
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);
        assert_eq!(events, vec![(PageLifecycleEvent::OnShow, None)]);
    }

    #[test]
    fn reset_webview_lifecycle_state_does_not_keep_stale_hidden_show_request() {
        let mut state = test_page_state();
        state.event = Some(PageLifecycleEvent::OnHide);
        state.visibility = Visibility::ShowOwed;
        state.entry = EntryPhase::LoadOwed;
        state.bridge_ready = true;
        state.entry = EntryPhase::Loaded;
        state.visibility = Visibility::Shown;
        state.ready_dispatched = true;
        state.render_status = PageRenderStatus::Finished;

        PageInstance::reset_webview_lifecycle_state(&mut state);

        assert_eq!(state.visibility, Visibility::Hidden);
        assert_ne!(state.entry, EntryPhase::LoadOwed);
        assert!(!state.bridge_ready);
        assert_ne!(state.entry, EntryPhase::Loaded);
        assert_ne!(state.visibility, Visibility::Shown);
        assert!(!state.ready_dispatched);
        assert_eq!(state.render_status, PageRenderStatus::Unstarted);
    }

    #[test]
    fn reset_webview_lifecycle_state_preserves_current_visible_intent() {
        let mut state = test_page_state();
        state.event = Some(PageLifecycleEvent::OnShow);

        PageInstance::reset_webview_lifecycle_state(&mut state);

        assert_ne!(state.visibility, Visibility::Hidden);
    }

    #[test]
    fn on_unload_preserves_bridge_ready_for_reusable_page_instance() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.visibility = Visibility::ShowOwed;
        state.entry = EntryPhase::LoadOwed;
        state.bridge_ready = true;

        PageInstance::collect_hidden_or_unloaded_lifecycle_event(
            &mut state,
            PageLifecycleEvent::OnUnload,
            &mut events,
        );

        assert_eq!(events, vec![(PageLifecycleEvent::OnUnload, None)]);
        assert_eq!(state.visibility, Visibility::Hidden);
        assert_ne!(state.entry, EntryPhase::LoadOwed);
        assert!(state.bridge_ready);
    }

    #[test]
    fn only_on_unload_cancels_page_bridge_work() {
        assert!(!PageInstance::lifecycle_cancels_bridge_work(
            PageLifecycleEvent::OnHide
        ));
        assert!(PageInstance::lifecycle_cancels_bridge_work(
            PageLifecycleEvent::OnUnload
        ));
    }

    #[test]
    fn attach_reset_boundary_only_resets_real_replacement() {
        assert!(!PageInstance::should_reset_lifecycle_on_attach(None));
        assert!(!PageInstance::should_reset_lifecycle_on_attach(Some(true)));
        assert!(PageInstance::should_reset_lifecycle_on_attach(Some(false)));
    }

    #[test]
    fn first_attach_must_not_drop_bridge_ready_load_request() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.bridge_ready = true;
        PageInstance::request_on_load(&mut state);
        state.render_status = PageRenderStatus::Started;

        // First None -> Some attach must not reset; otherwise this state would
        // lose bridge_ready/load_requested before render-start can complete onLoad.
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![(PageLifecycleEvent::OnLoad, Some("{}".to_string()))]
        );
        assert_eq!(state.entry, EntryPhase::Loaded);
    }

    #[test]
    fn first_attach_must_not_drop_pending_show_request() {
        let mut state = test_page_state();
        let mut events = Vec::new();

        state.visibility = Visibility::ShowOwed;
        state.bridge_ready = true;
        PageInstance::request_on_load(&mut state);
        state.render_status = PageRenderStatus::Started;

        // OnShow can arrive before onLoad; first attach must preserve that
        // intent so onShow is emitted immediately after onLoad.
        PageInstance::collect_ready_lifecycle_events(&mut state, &mut events);

        assert_eq!(
            events,
            vec![
                (PageLifecycleEvent::OnLoad, Some("{}".to_string())),
                (PageLifecycleEvent::OnShow, None),
            ]
        );
        assert_eq!(state.entry, EntryPhase::Loaded);
        assert_eq!(state.visibility, Visibility::Shown);
    }
}