Skip to content

armgit / moli

Public Imported from GitHub
0

Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust

37.8 KB
Raw Blame
use anyhow::{Context, Result, anyhow};
use std::pin::pin;
use std::time::{Duration, Instant};

use super::ScriptVm;
use crate::context_bootstrap::{
    construct_original_event, construct_original_page_transition_event,
    record_performance_dom_content_loaded_event_end,
    record_performance_dom_content_loaded_event_start, record_performance_load_event_end,
    record_performance_load_event_start,
};
use crate::document_runtime::{
    DeferredPageTask, DeferredPageTaskLane, DocumentRuntime, FollowupPageTaskDisposition,
};
use crate::frame_owner_model::MainDocumentScriptLoadDelayLease;
use crate::host::{EventTargetHandle, HostTimeoutRunResult};
use crate::native_bridge::{JsContextHost, element::queue_revealed_lazy_media_loads};
use crate::page_task_queue::{PostParseLifecycleWork, PostParsePageOwnedWork};
use crate::planning::PreparedScript;
use crate::script_vm::ImmediateRuntimeScriptWorkSignal;
use crate::util::v8str;
use crate::v8_execution_watchdog::{
    V8ExecutionWatchdog, V8ExecutionWatchdogKind, V8ExecutionWatchdogOutcome,
};

const LIFECYCLE_EVENT_WATCHDOG_TIMEOUT: Duration = Duration::from_secs(8);

impl ScriptVm {
    fn dispatch_document_event_body(&mut self, event_type: &str) -> Result<()> {
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        let context_host = self._context_host.clone();
        let document_runtime = &mut self.document_runtime;
        self.renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                // SAFETY: as_ptr() — V8 callbacks are re-entrant; borrow_mut() panics. See util.rs.
                let host_ptr: *mut JsContextHost = (*context_host).as_ptr();
                document_runtime
                    .dispatch_document_event(scope, host_ptr, event_type)
                    .map_err(anyhow::Error::msg)
            })
    }

    pub(super) fn perform_owner_lane_task_microtask_checkpoints(&mut self) -> Result<()> {
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        self.renderer_document_isolate
            .with_entered_renderer_document_isolate(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                // SAFETY: `context_ptr` points at `self.page_default_runtime.context`, and this closure runs with
                // the document isolate entered. `ScriptVm` owns both values, so the context belongs
                // to the entered isolate for the full checkpoint scope.
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                Self::perform_microtask_checkpoints(scope, None)?;
                Ok(())
            })
            .context("owner-lane microtask checkpoint failed")
    }

    /// Execute the body of one V8 foreground continuation.
    ///
    /// The selected Page-task dispatcher owns the task-end checkpoint. Keeping
    /// this method body-only prevents a V8 helper from creating an intermediate
    /// checkpoint before the scheduler task has actually completed.
    pub(crate) fn run_v8_foreground_task_body(
        &mut self,
        task: moli_v8_platform::V8ForegroundTask,
    ) -> bool {
        self.run_v8_foreground_task(task)
    }

    /// Perform one selected Page task's agent checkpoint and turn-exit cleanup.
    ///
    /// Callers must invoke this only after a task family has removed every
    /// helper-local checkpoint from the selected task body. The runtime
    /// `page_task_checkpoint` component is the production authority deciding
    /// when this primitive runs.
    pub(crate) fn finish_selected_page_task_checkpoint(
        &mut self,
        boundary: crate::style_engine::StyleInvalidationTurnExitBoundary,
    ) -> Result<()> {
        let result = self.perform_owner_lane_task_microtask_checkpoints();
        self.finish_runtime_turn_with_style_drain(boundary, result)
    }

    /// Finish one selected callback task with its established post-checkpoint
    /// reconciliation.
    ///
    /// This sequence is intentionally distinct from
    /// `finish_selected_page_task_checkpoint()`: child browsing contexts and
    /// runtime scripts produced by Promise reactions do not exist until the
    /// checkpoint has run, while `finish_host_task_turn()` owns the final
    /// runtime/style turn-exit cleanup. No borrow or V8 scope crosses the
    /// asynchronous runtime follow-up.
    pub(crate) async fn finish_selected_page_callback_task(
        &mut self,
        loader: &crate::network::ResourceRequestClient,
    ) -> Result<()> {
        self.perform_owner_lane_task_microtask_checkpoints()?;
        self.sync_child_browsing_context_records();
        self.finish_host_task_turn(loader, false).await
    }

    /// Dispatch one Document lifecycle event body without ending its HTML task.
    ///
    /// The main-document lifecycle coordinator owns the ordinary task-end
    /// checkpoint. Keeping this primitive body-only prevents DCL and
    /// `readystatechange` helpers from silently becoming a second completion
    /// authority. Parser-finish DCL temporarily uses the explicit compatibility
    /// wrapper below until P5-A3 moves that direct successor as one unit.
    pub(super) fn dispatch_document_lifecycle_event_body(
        &mut self,
        event_type: &str,
    ) -> Result<()> {
        let watchdog = self
            .renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                V8ExecutionWatchdog::arm(
                    V8ExecutionWatchdogKind::LifecycleEvent,
                    scope.thread_safe_handle(),
                    LIFECYCLE_EVENT_WATCHDOG_TIMEOUT,
                )
            });
        let watchdog_timeout = watchdog.timeout();
        let result = {
            let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
            self.renderer_document_isolate
                .with_renderer_document_isolate_mut(|isolate| {
                    let scope = pin!(v8::HandleScope::new(isolate));
                    let scope = &mut scope.init();
                    let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                    let scope = &mut v8::ContextScope::new(scope, context);
                    if event_type == "DOMContentLoaded" {
                        record_performance_dom_content_loaded_event_start(scope);
                    }
                    Ok(())
                })
        }
        .and_then(|()| self.dispatch_document_event_body(event_type));
        let timed_out = watchdog.disarm() == V8ExecutionWatchdogOutcome::TimedOut;
        result?;
        if timed_out {
            anyhow::bail!(
                "document lifecycle event `{event_type}` exceeded {:?} and was terminated",
                watchdog_timeout
            );
        }
        Ok(())
    }

    /// Publish the event-end timing that is intentionally observable only
    /// after the owning lifecycle task's checkpoint.
    pub(super) fn record_document_lifecycle_event_end(&mut self, event_type: &str) {
        if event_type == "DOMContentLoaded" {
            let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
            self.renderer_document_isolate
                .with_renderer_document_isolate_mut(|isolate| {
                    let scope = pin!(v8::HandleScope::new(isolate));
                    let scope = &mut scope.init();
                    let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                    let scope = &mut v8::ContextScope::new(scope, context);
                    record_performance_dom_content_loaded_event_end(scope);
                });
        }
    }

    /// Compatibility boundary for direct ScriptVm fixtures. Production
    /// lifecycle work uses the body-only primitive and a typed coordinator.
    #[cfg(test)]
    pub(super) fn dispatch_document_lifecycle_event(&mut self, event_type: &str) -> Result<()> {
        self.dispatch_document_lifecycle_event_body(event_type)?;
        self.perform_owner_lane_task_microtask_checkpoints()
            .with_context(|| {
                format!("document lifecycle event `{event_type}` microtask checkpoint failed")
            })?;
        self.record_document_lifecycle_event_end(event_type);
        Ok(())
    }

    pub(super) fn dispatch_document_lifecycle_event_body_best_effort(
        &mut self,
        event_type: &str,
    ) -> super::MainDocumentLifecycleEventDispatch {
        if let Err(error) = self.dispatch_document_lifecycle_event_body(event_type) {
            self.record_runtime_warning(format_args!(
                "document lifecycle event dispatch failed for `{event_type}`: {error}"
            ));
            return super::MainDocumentLifecycleEventDispatch::FailedBestEffort;
        }
        super::MainDocumentLifecycleEventDispatch::Completed
    }

    pub(super) fn queue_current_main_document_image_load_events(&mut self) -> Result<()> {
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        let context_host = self._context_host.clone();
        let document_runtime = &mut self.document_runtime;
        self.renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                // SAFETY: as_ptr() - V8 callbacks are re-entrant; borrow_mut() panics. See util.rs.
                let host_ptr: *mut JsContextHost = (*context_host).as_ptr();
                document_runtime.queue_current_main_document_image_load_events(scope, host_ptr);
                Ok(())
            })
    }

    pub(super) fn queue_current_main_document_media_loads(&mut self) -> Result<()> {
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        let context_host = self._context_host.clone();
        let document_runtime = &mut self.document_runtime;
        self.renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                // SAFETY: as_ptr() - V8 callbacks are re-entrant; borrow_mut() panics. See util.rs.
                let host_ptr: *mut JsContextHost = (*context_host).as_ptr();
                document_runtime.queue_current_main_document_media_loads(scope, host_ptr);
                Ok(())
            })
    }

    /// Dispatch the Window `load` body without crossing the load-to-pageshow
    /// lifecycle checkpoint.
    pub(super) fn dispatch_window_load_event_body(&mut self) -> Result<()> {
        let timing_enabled = moli_trace::cdp_nav_timing_enabled();
        let task_started = timing_enabled.then(Instant::now);
        self.prune_stale_child_default_execution_contexts();
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        let context_host = self._context_host.clone();
        let document_runtime = &mut self.document_runtime;
        self.renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                // SAFETY: as_ptr() — V8 callbacks are re-entrant; borrow_mut() panics. See util.rs.
                let host_ptr: *mut JsContextHost = (*context_host).as_ptr();
                let global = scope.get_current_context().global(scope);
                let step_started = timing_enabled.then(Instant::now);
                if let Some(document_value) = global.get(scope, v8str(scope, "document").into())
                    && let Ok(document) = v8::Local::<v8::Object>::try_from(document_value)
                    && let Some(body_value) = document.get(scope, v8str(scope, "body").into())
                    && let Ok(body) = v8::Local::<v8::Object>::try_from(body_value)
                {
                    let _ = body.get(scope, v8str(scope, "onload").into());
                }
                if let Some(step_started) = step_started {
                    tracing::info!(
                        target: "moli_cdp_nav_timing",
                        stage = "window_load_event_step_completed",
                        step = "body_onload_getter",
                        step_elapsed_ms = step_started.elapsed().as_millis(),
                        total_elapsed_ms = task_started
                            .as_ref()
                            .map(|started| started.elapsed().as_millis())
                            .unwrap_or_default(),
                    );
                }

                let step_started = timing_enabled.then(Instant::now);
                let event = construct_original_event(scope, "load")
                    .ok_or_else(|| anyhow!("failed to construct window load event"))?;
                if let Some(step_started) = step_started {
                    tracing::info!(
                        target: "moli_cdp_nav_timing",
                        stage = "window_load_event_step_completed",
                        step = "construct_load_event",
                        step_elapsed_ms = step_started.elapsed().as_millis(),
                        total_elapsed_ms = task_started
                            .as_ref()
                            .map(|started| started.elapsed().as_millis())
                            .unwrap_or_default(),
                    );
                }
                let document_target = EventTargetHandle::Node(document_runtime.document_handle());
                record_performance_load_event_start(scope);
                let step_started = timing_enabled.then(Instant::now);
                document_runtime
                    .dispatch_public_event_with_original_target(
                        scope,
                        host_ptr,
                        EventTargetHandle::Window,
                        document_target,
                        event,
                    )
                    .map_err(anyhow::Error::msg)?;
                if let Some(step_started) = step_started {
                    tracing::info!(
                        target: "moli_cdp_nav_timing",
                        stage = "window_load_event_step_completed",
                        step = "dispatch_public_load_event",
                        step_elapsed_ms = step_started.elapsed().as_millis(),
                        total_elapsed_ms = task_started
                            .as_ref()
                            .map(|started| started.elapsed().as_millis())
                            .unwrap_or_default(),
                    );
                }
                let step_started = timing_enabled.then(Instant::now);
                queue_revealed_lazy_media_loads(scope, host_ptr);
                if let Some(step_started) = step_started {
                    tracing::info!(
                        target: "moli_cdp_nav_timing",
                        stage = "window_load_event_step_completed",
                        step = "queue_revealed_lazy_media_loads",
                        step_elapsed_ms = step_started.elapsed().as_millis(),
                        total_elapsed_ms = task_started
                            .as_ref()
                            .map(|started| started.elapsed().as_millis())
                            .unwrap_or_default(),
                    );
                }
                Ok(())
            })
    }

    /// Publish load event-end and dispatch the non-persisted `pageshow` body.
    ///
    /// The caller must have completed the explicit load-to-pageshow lifecycle
    /// checkpoint. This method deliberately does not perform the final task-end
    /// checkpoint after pageshow.
    pub(super) fn dispatch_window_pageshow_event_body(&mut self) -> Result<()> {
        let context_ptr: *const v8::Global<v8::Context> = &self.page_default_runtime.context;
        let context_host = self._context_host.clone();
        let document_runtime = &mut self.document_runtime;
        self.renderer_document_isolate
            .with_renderer_document_isolate_mut(|isolate| {
                let scope = pin!(v8::HandleScope::new(isolate));
                let scope = &mut scope.init();
                let context = unsafe { v8::Local::new(scope, &*context_ptr) };
                let scope = &mut v8::ContextScope::new(scope, context);
                // SAFETY: as_ptr() — V8 callbacks are re-entrant; borrow_mut() panics. See util.rs.
                let host_ptr: *mut JsContextHost = (*context_host).as_ptr();
                let document_target = EventTargetHandle::Node(document_runtime.document_handle());
                record_performance_load_event_end(scope);
                let pageshow =
                    construct_original_page_transition_event(scope, "pageshow", false)
                        .ok_or_else(|| anyhow!("failed to construct window pageshow event"))?;
                document_runtime
                    .dispatch_public_event_with_original_target(
                        scope,
                        host_ptr,
                        EventTargetHandle::Window,
                        document_target,
                        pageshow,
                    )
                    .map_err(anyhow::Error::msg)?;
                Ok(())
            })
    }

    /// Compatibility wrapper for direct ScriptVm fixtures. Production
    /// ordinary lifecycle work uses `dispatch_window_load_event_body()` and
    /// receives its final task-end from the lifecycle coordinator.
    #[cfg(test)]
    pub(super) fn dispatch_window_load_event(&mut self) -> Result<()> {
        self.dispatch_window_load_event_body()?;
        self.perform_owner_lane_task_microtask_checkpoints()?;
        self.dispatch_window_pageshow_event_body()?;
        self.perform_owner_lane_task_microtask_checkpoints()
    }

    pub(super) fn dispatch_window_load_event_body_best_effort(
        &mut self,
    ) -> super::MainDocumentLifecycleEventDispatch {
        if let Err(error) = self.dispatch_window_load_event_body() {
            self.record_runtime_warning(format_args!("window load dispatch failed: {error}"));
            return super::MainDocumentLifecycleEventDispatch::FailedBestEffort;
        }
        super::MainDocumentLifecycleEventDispatch::Completed
    }

    pub(super) fn dispatch_window_pageshow_event_body_best_effort(
        &mut self,
    ) -> super::MainDocumentLifecycleEventDispatch {
        if let Err(error) = self.dispatch_window_pageshow_event_body() {
            self.record_runtime_warning(format_args!("window pageshow dispatch failed: {error}"));
            return super::MainDocumentLifecycleEventDispatch::FailedBestEffort;
        }
        super::MainDocumentLifecycleEventDispatch::Completed
    }

    pub(super) fn merge_followup_task_disposition(
        disposition: &mut FollowupPageTaskDisposition,
        next: FollowupPageTaskDisposition,
    ) {
        match next {
            FollowupPageTaskDisposition::Skipped => {}
            FollowupPageTaskDisposition::Deferred => {
                *disposition = FollowupPageTaskDisposition::Deferred;
            }
            FollowupPageTaskDisposition::Enqueued => {
                if *disposition == FollowupPageTaskDisposition::Skipped {
                    *disposition = FollowupPageTaskDisposition::Enqueued;
                }
            }
        }
    }

    fn deferred_lifecycle_work_for_lane(
        work: PostParseLifecycleWork,
        lane: DeferredPageTaskLane,
    ) -> Result<DeferredPageTask> {
        DeferredPageTask::page_owned_work(PostParsePageOwnedWork::lifecycle_work(work), lane)
            .ok_or_else(|| anyhow!("parser-boundary lifecycle work must execute at its concrete parser task boundary"))
    }

    #[cfg(test)]
    fn deferred_page_owned_work_for_lane(
        work: PostParsePageOwnedWork,
        lane: DeferredPageTaskLane,
    ) -> Result<DeferredPageTask> {
        DeferredPageTask::page_owned_work(work, lane).ok_or_else(|| {
            anyhow!(
                "parser-boundary page-owned work must execute at its concrete parser task boundary"
            )
        })
    }

    fn enqueue_deferred_page_task(&mut self, task: DeferredPageTask) {
        let (lane, work) = task.into_parts();
        match lane {
            DeferredPageTaskLane::ParserBoundary => {
                unreachable!(
                    "DeferredPageTask constructor rejects parser-boundary work before storage"
                );
            }
            DeferredPageTaskLane::PreDomContentLoaded => {
                self.document_runtime
                    .enqueue_parser_owned_pre_domcontentloaded_page_owned_work(work);
            }
            DeferredPageTaskLane::PostDomContentLoaded => {
                self.enqueue_main_document_runtime_work(work);
            }
        }
    }

    pub(super) fn enqueue_main_document_runtime_work(&mut self, work: PostParsePageOwnedWork) {
        let Some(document_owner) = self.current_main_document_task_owner() else {
            self.record_runtime_warning(format_args!(
                "dropping post-DCL runtime work without a current main Document owner"
            ));
            return;
        };
        let producer = self
            .post_domcontentloaded_page_task_tx
            .bind_main_document_runtime_producer(document_owner);
        if producer.send_post_parse_work_when_ready(work).is_err() {
            self.record_runtime_warning(format_args!(
                "main-Document runtime work could not bind its ready-source admission"
            ));
        }
    }

    pub(crate) fn enqueue_runtime_script_work_continuation(&mut self) {
        let Some(document_owner) = self.current_main_document_task_owner() else {
            self.record_runtime_warning(format_args!(
                "dropping runtime continuation without a current main Document owner"
            ));
            return;
        };
        if self.queued_main_document_runtime_continuation_owner == Some(document_owner) {
            return;
        }
        let continuation = self
            .page_runtime_wake_tx
            .bind_main_document_runtime_continuation(document_owner);
        if continuation.send_runtime_script_continuation().is_ok() {
            self.queued_main_document_runtime_continuation_owner = Some(document_owner);
        } else {
            self.record_runtime_warning(format_args!(
                "main-Document runtime route closed before its continuation was accepted"
            ));
        }
    }

    /// Publish one durable scheduler token for the current main Document's
    /// parser-owned module queue.
    ///
    /// The underlying scheduler store may contain several ready actions. One
    /// token authorizes one action. When a ready tail remains, the body
    /// executor may publish its next token before the current selected-task
    /// checkpoint; the scheduler cannot select that token until the current
    /// dispatcher returns. The exact-owner guard prevents repeated readiness
    /// observations from duplicating the same head.
    pub(crate) fn enqueue_parser_owned_module_continuation(&mut self) -> bool {
        let Some(document_owner) = self.current_main_document_task_owner() else {
            self.record_runtime_warning(format_args!(
                "parser-owned module continuation became ready without a current main Document owner"
            ));
            return false;
        };
        if self.queued_main_document_parser_module_continuation_owner == Some(document_owner) {
            return true;
        }
        let queued = self
            .page_runtime_wake_tx
            .bind_main_document_runtime_continuation(document_owner)
            .send_parser_owned_module_continuation()
            .is_ok();
        if queued {
            self.queued_main_document_parser_module_continuation_owner = Some(document_owner);
        } else {
            self.record_runtime_warning(format_args!(
                "main-Document runtime route closed before parser module continuation admission"
            ));
        }
        queued
    }

    pub(crate) fn begin_parser_owned_module_continuation_turn(
        &mut self,
        document_owner: crate::frame_owner_model::FrameDocumentTaskOwner,
    ) {
        if self.queued_main_document_parser_module_continuation_owner == Some(document_owner) {
            self.queued_main_document_parser_module_continuation_owner = None;
        }
    }

    pub(super) fn enqueue_immediate_runtime_script_work_signal(
        &mut self,
        signal: ImmediateRuntimeScriptWorkSignal,
    ) {
        match signal {
            ImmediateRuntimeScriptWorkSignal::StablePageTurnContinuation => {
                self.enqueue_runtime_script_work_continuation();
            }
        }
    }

    pub(super) fn enqueue_runtime_script_work_continuation_if_ready(&mut self) {
        self.enqueue_immediate_runtime_script_work_signal(
            ImmediateRuntimeScriptWorkSignal::StablePageTurnContinuation,
        );
    }

    #[cfg(test)]
    pub(super) fn enqueue_page_owned_work_or_defer(
        &mut self,
        work: PostParsePageOwnedWork,
        lane: DeferredPageTaskLane,
    ) -> Result<FollowupPageTaskDisposition> {
        let mut ready_task = None;
        let deferred_task = Self::deferred_page_owned_work_for_lane(work, lane)?;
        let disposition = self
            .document_runtime
            .deferred_page_tasks_mut()
            .enqueue_or_defer(deferred_task, |task| ready_task = Some(task));
        if let Some(task) = ready_task {
            self.enqueue_deferred_page_task(task);
        }
        Ok(disposition)
    }

    pub(super) fn enqueue_lifecycle_work_or_defer(
        &mut self,
        work: PostParseLifecycleWork,
        lane: DeferredPageTaskLane,
    ) -> Result<FollowupPageTaskDisposition> {
        let mut ready_task = None;
        let deferred_task = Self::deferred_lifecycle_work_for_lane(work, lane)?;
        let disposition = self
            .document_runtime
            .deferred_page_tasks_mut()
            .enqueue_or_defer(deferred_task, |task| ready_task = Some(task));
        if let Some(task) = ready_task {
            self.enqueue_deferred_page_task(task);
        }
        Ok(disposition)
    }

    pub(super) fn enqueue_lifecycle_work_items_or_defer(
        &mut self,
        work_items: Vec<PostParseLifecycleWork>,
        lane: DeferredPageTaskLane,
    ) -> Result<FollowupPageTaskDisposition> {
        let mut disposition = FollowupPageTaskDisposition::Skipped;

        for work in work_items {
            Self::merge_followup_task_disposition(
                &mut disposition,
                self.enqueue_lifecycle_work_or_defer(work, lane)?,
            );
        }

        Ok(disposition)
    }

    pub(super) fn drain_deferred_page_tasks(&mut self) -> Result<()> {
        let mut drained = Vec::new();
        self.document_runtime
            .deferred_page_tasks_mut()
            .drain_into(|deferred| drained.push(deferred));
        for deferred in drained {
            self.enqueue_deferred_page_task(deferred);
        }
        if self
            .document_runtime
            .runtime_script_work_mut()
            .is_paused_for_deferred_page_tasks()
            && !self.document_runtime.runtime_script_work_mut().is_idle()
        {
            if self.runtime_script_work_should_signal_immediate_progress() {
                self.enqueue_runtime_script_work_continuation_if_ready();
            }
        } else {
            self.document_runtime
                .runtime_script_work_mut()
                .resume_after_deferred_page_tasks();
        }
        Ok(())
    }

    pub(super) fn refresh_script_vm_local_document_state(&mut self) {
        self.apply_pending_main_document_owner_transitions();
        self.document_runtime.accept_ready_runtime_script_events();
        self.sync_live_document_style_sources_if_pending();
    }

    pub(crate) fn drain_deferred_page_tasks_best_effort(&mut self) {
        if let Err(error) = self.drain_deferred_page_tasks() {
            self.record_runtime_warning(format_args!("deferred page-task drain failed: {error}"));
        }
    }

    pub(super) fn enqueue_script_failure_lifecycle_work_for_prepared_script(
        &mut self,
        script: &PreparedScript,
        message: &str,
        module_failure_policy: Option<crate::host::ModuleFailurePolicy>,
        error_constructor: Option<crate::types::ScriptErrorConstructorKind>,
    ) -> Result<FollowupPageTaskDisposition> {
        self.enqueue_script_failure_lifecycle_work_with_load_delay_binding(
            script,
            message,
            module_failure_policy,
            error_constructor,
            None,
        )
    }

    pub(super) fn enqueue_script_failure_lifecycle_work_with_load_delay_binding(
        &mut self,
        script: &PreparedScript,
        message: &str,
        module_failure_policy: Option<crate::host::ModuleFailurePolicy>,
        error_constructor: Option<crate::types::ScriptErrorConstructorKind>,
        load_delay_binding: Option<MainDocumentScriptLoadDelayLease>,
    ) -> Result<FollowupPageTaskDisposition> {
        let mut planned_failure_work = self.document_runtime.plan_script_failure_lifecycle_work(
            script,
            message,
            module_failure_policy,
            error_constructor,
        );
        if let Some(binding) = load_delay_binding {
            planned_failure_work.push(PostParseLifecycleWork::SettleMainDocumentScriptLoadDelay(
                binding,
            ));
        }
        self.enqueue_lifecycle_work_items_or_defer(
            planned_failure_work,
            self.prepared_script_followup_lane(script),
        )
    }

    pub(crate) fn enqueue_script_failure_lifecycle_work_best_effort(
        &mut self,
        script: &PreparedScript,
        message: &str,
        module_failure_policy: Option<crate::host::ModuleFailurePolicy>,
        error_constructor: Option<crate::types::ScriptErrorConstructorKind>,
    ) {
        match self.enqueue_script_failure_lifecycle_work_for_prepared_script(
            script,
            message,
            module_failure_policy,
            error_constructor,
        ) {
            Ok(FollowupPageTaskDisposition::Skipped) => {}
            Ok(FollowupPageTaskDisposition::Deferred | FollowupPageTaskDisposition::Enqueued) => {}
            Err(error) => {
                self.record_runtime_warning(format_args!(
                    "script failure page-task enqueue failed for `{}`: {error}",
                    script.url
                ));
            }
        }
    }

    pub(super) fn enqueue_script_load_lifecycle_work_for_prepared_script_best_effort(
        &mut self,
        script: &PreparedScript,
    ) -> FollowupPageTaskDisposition {
        self.enqueue_script_load_lifecycle_work_with_load_delay_binding_best_effort(script, None)
    }

    pub(super) fn enqueue_script_load_lifecycle_work_with_load_delay_binding_best_effort(
        &mut self,
        script: &PreparedScript,
        load_delay_binding: Option<MainDocumentScriptLoadDelayLease>,
    ) -> FollowupPageTaskDisposition {
        let mut work_items = Vec::new();
        if let Some(work) = self.plan_script_load_lifecycle_work_for_prepared_script(script) {
            work_items.push(work);
        }
        if let Some(binding) = load_delay_binding {
            work_items.push(PostParseLifecycleWork::SettleMainDocumentScriptLoadDelay(
                binding,
            ));
        }
        if work_items.is_empty() {
            return FollowupPageTaskDisposition::Skipped;
        }
        let enqueue_result = self.enqueue_lifecycle_work_items_or_defer(
            work_items,
            self.prepared_script_followup_lane(script),
        );
        enqueue_result.unwrap_or_else(|error| {
            panic!(
                "validated script terminal work failed to enter its lifecycle lane for `{}`: {error}",
                script.url
            )
        })
    }

    pub(crate) fn enqueue_main_document_script_load_delay_settlement_best_effort(
        &mut self,
        script: &PreparedScript,
        binding: MainDocumentScriptLoadDelayLease,
    ) -> FollowupPageTaskDisposition {
        let owner = binding.owner();
        let kind = binding.kind();
        let load_delay_token = binding.load_delay_token();
        match self.enqueue_lifecycle_work_or_defer(
            PostParseLifecycleWork::SettleMainDocumentScriptLoadDelay(binding),
            self.prepared_script_followup_lane(script),
        ) {
            Ok(disposition) => disposition,
            Err(error) => {
                panic!(
                    "exact script load-delay lease {owner:?}/{kind:?}/{load_delay_token:?} failed to enter its validated lifecycle lane for `{}`: {error}",
                    script.url
                )
            }
        }
    }

    pub(super) fn pause_runtime_script_work_at_followup_task_boundary(
        &mut self,
        disposition: FollowupPageTaskDisposition,
    ) -> bool {
        match disposition {
            FollowupPageTaskDisposition::Skipped => false,
            FollowupPageTaskDisposition::Deferred => {
                self.handle_runtime_script_work_at_explicit_boundary(false);
                true
            }
            FollowupPageTaskDisposition::Enqueued => {
                self.handle_runtime_script_work_at_explicit_boundary(true);
                true
            }
        }
    }

    /// Execute one due timer heap head without checkpointing or callback
    /// follow-up.
    ///
    /// Production callers must enter through the selected Page timer task,
    /// which commits the single task-end callback completion.
    pub(super) fn run_next_timeout_body(
        &mut self,
        selection: crate::page_task_queue::RendererPageTimerSelection,
    ) -> Result<HostTimeoutRunResult> {
        #[cfg(test)]
        if let Some(message) = self.test_next_timeout_failure.take() {
            return Err(anyhow!("{message}"));
        }

        let document_runtime: *mut DocumentRuntime = &mut *self.document_runtime;
        self.with_default_context_scope(|scope, _host_ptr| {
            // SAFETY: the raw pointer is derived from `self.document_runtime` immediately before
            // entering this non-escaping closure.
            // `with_default_context_scope` only
            // creates the V8 context scope and does not access or move
            // `document_runtime`; the render owner lane runs this
            // synchronously on one thread.
            Ok(unsafe { &mut *document_runtime }.run_next_timeout_body(scope, selection))
        })
    }

    /// Complete one timer in a low-level ScriptVm fixture without a Page owner
    /// slot.
    ///
    /// This preserves the body -> one checkpoint -> child-sync boundary for
    /// domain tests. PageVm behavior tests must use the production selected
    /// dispatcher so runtime follow-up and replacement reconciliation are not
    /// bypassed.
    #[cfg(test)]
    pub(crate) fn run_next_timeout_for_test(&mut self) -> Result<HostTimeoutRunResult> {
        let result = self
            .run_next_timeout_body(crate::page_task_queue::RendererPageTimerSelection::AnyReady)?;
        if result.consumed_heap_head() {
            self.perform_owner_lane_task_microtask_checkpoints()?;
            self.sync_child_browsing_context_records();
        }
        Ok(result)
    }

    #[cfg(test)]
    pub(super) fn fail_next_timeout_for_testing(&mut self, message: impl Into<String>) {
        self.test_next_timeout_failure = Some(message.into());
    }

    pub(crate) fn ms_to_next_timeout(&self) -> Option<u64> {
        self.document_runtime.ms_to_next_timeout()
    }

    #[cfg(test)]
    pub(crate) fn has_ready_timeout(&self) -> bool {
        self.document_runtime.has_ready_timeout()
    }

    pub(crate) fn next_ready_timeout_deadline(
        &self,
        selection: crate::page_task_queue::RendererPageTimerSelection,
    ) -> Option<Instant> {
        self.document_runtime.next_ready_timeout_deadline(selection)
    }

    pub(crate) fn next_timeout_deadline(&self) -> Option<Instant> {
        self.document_runtime.next_timeout_deadline()
    }

    pub(crate) fn record_runtime_warning(&mut self, message: std::fmt::Arguments<'_>) {
        let text = message.to_string();
        let execution_context_id = self.runtime_observable_default_execution_context_id();
        self.runtime_observable_source_queue
            .record_lifecycle_error(text.clone());
        // The queue above is the durable CLI/diagnostic history. Protocol
        // delivery is a separate concrete fact: bind it to the turn and realm
        // that produced the warning instead of waiting for another activity
        // to diff the cumulative queue.
        self._context_host.borrow().append_live_turn_observation(
            crate::runtime::RendererProtocolObservation::RuntimeLifecycleError {
                text,
                execution_context_id,
            },
        );
    }

    #[cfg(test)]
    pub(crate) fn runtime_observable_lifecycle_errors_for_testing(&mut self) -> Vec<String> {
        let _ = self.sync_runtime_observable_source_events();
        self.runtime_observable_source_queue
            .lifecycle_error_messages_for_testing()
    }
}