Skip to content

armgit / moli

Public Imported from GitHub
0

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

52.8 KB
Raw Blame
use super::document_runtime::DomHandle;
use super::native_bridge::JsContextHost;
pub use moli_v8_util::{
    array_contains_strict, array_push_value, call_object_method, callback_data_index_value,
    callback_data_item, constructor_object, constructor_prototype, constructor_prototype_object,
    define_non_enumerable_static_bool_property, define_non_enumerable_static_number_property,
    define_non_enumerable_static_property, define_non_enumerable_static_string_property,
    ecmascript_promise_resolve, get_own_static_property, get_private_object, get_private_value,
    get_property, global_constructor_object, global_constructor_prototype,
    initialize_ecmascript_intrinsic_registry, new_null_prototype_object, object_bool_property,
    object_chain_contains, object_defined_string_property, object_non_empty_string_property,
    object_number_property, object_own_static_bool_property, object_own_static_property_as_array,
    object_own_static_string_property, object_property_as_array, object_property_as_object,
    object_string_property, private_key, register_ecmascript_intrinsic,
    registered_ecmascript_constructor, registered_ecmascript_prototype, set_null_prototype,
    set_private_value, throw_range_error, throw_type_error, v8_json_parse, v8_string, v8str,
    walk_object_chain,
};
use moli_webapi_declare::WebApiValue;
pub(crate) use moli_webapi_declare::define_array_data_property as define_v8_array_data_property;
use std::{
    cell::{Cell, RefCell},
    ptr::NonNull,
    rc::Rc,
};
use url::Url;
use widestring::U16String;

const SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER: &str = "moli-script-base-url-v1";

// Access-check callbacks cannot inspect the global object to rediscover the host:
// that property lookup would recursively invoke the same V8 access check. This
// slot starts non-owning during fallible bootstrap, then a successfully
// published Document realm promotes it to a Context-owned host reference. That
// mirrors ScriptState/Oilpan's retained-realm edge closely enough for Moli's
// non-tracing Rust heap: a retained function or DOM wrapper keeps its native
// Document backing alive, while temporary WindowProxy facades remain
// non-owning and fail closed as soon as the host detaches.
struct ContextHostPointerSlot {
    host_ptr: NonNull<JsContextHost>,
    host_lifecycle: Rc<Cell<ContextHostLifecycle>>,
    retained_realm_owner: RefCell<Option<RetainedDocumentRealmHostOwner>>,
}

struct RetainedDocumentRealmHostOwner {
    host: Option<Rc<RefCell<JsContextHost>>>,
    deferred_release_queue: crate::script_vm::RendererDeferredContextHostReleaseQueue,
    retained_v8_handle_state: Vec<Box<dyn std::any::Any>>,
}

impl Drop for RetainedDocumentRealmHostOwner {
    fn drop(&mut self) {
        if let Some(host) = self.host.take() {
            self.deferred_release_queue
                .defer(host, std::mem::take(&mut self.retained_v8_handle_state));
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum ContextHostLifecycle {
    Active,
    Detached,
    Destroyed,
}

/// Marks a V8 Context whose native Document host has been retired.
///
/// Navigation can keep the stable WindowProxy while replacing its Context and
/// `JsContextHost`; final Page close also parks that proxy on a host-free
/// facade. In both cases retained functions and wrappers can outlive the Rust
/// host, so every raw-pointer entry point must fail closed before inspecting
/// embedder data.
#[derive(Debug)]
struct DisconnectedPageContext;

/// Marks a real Document realm whose browsing-context execution authority has
/// ended while its ordinary JS and DOM objects remain usable if author code
/// still retains them.
#[derive(Debug)]
struct DetachedDocumentPageContext;

/// Identifies a main default Window realm after its active registrations retire.
pub(crate) struct MainDefaultWindowContext;

/// Active native registries root their objects until teardown. A detached
/// realm instead keeps those objects in its own V8-traced graph, so retaining
/// a Document preserves wrapper identity without a Rust -> V8 -> Rust cycle.
#[derive(Debug)]
pub(crate) enum RealmObjectHandle {
    Strong(v8::Global<v8::Object>),
    Traced(v8::Weak<v8::Object>),
}

impl RealmObjectHandle {
    /// Completed native state keeps identity without rooting the object's JS graph.
    pub(crate) fn weak(
        scope: &mut v8::PinScope<'_, '_>,
        object: v8::Local<'_, v8::Object>,
    ) -> Self {
        Self::Traced(v8::Weak::new(scope, object))
    }

    pub(crate) fn new(scope: &mut v8::PinScope<'_, '_>, object: v8::Local<'_, v8::Object>) -> Self {
        if page_context_is_detached_document(scope.get_current_context()) {
            Self::traced(scope, object)
        } else {
            Self::Strong(v8::Global::new(scope, object))
        }
    }

    fn traced(scope: &mut v8::PinScope<'_, '_>, object: v8::Local<'_, v8::Object>) -> Self {
        const ROOTS: &str = "__moliRetainedRealmObjects";
        let context = object
            .get_creation_context(scope)
            .unwrap_or_else(|| scope.get_current_context());
        let anchor = context.get_extras_binding_object(scope);
        let roots = get_private_value(scope, anchor, ROOTS)
            .and_then(|value| v8::Local::<v8::Array>::try_from(value).ok())
            .unwrap_or_else(|| {
                let roots = v8::Array::new(scope, 0);
                roots.set_prototype(scope, v8::null(scope).into());
                set_private_value(scope, anchor, ROOTS, roots.into());
                roots
            });
        roots.set_index(scope, roots.length(), object.into());
        Self::Traced(v8::Weak::new(scope, object))
    }

    pub(crate) fn to_local<'s>(
        &self,
        scope: &mut v8::PinScope<'s, '_>,
    ) -> Option<v8::Local<'s, v8::Object>> {
        match self {
            Self::Strong(object) => Some(v8::Local::new(scope, object)),
            Self::Traced(object) => object.to_local(scope),
        }
    }

    pub(crate) fn retain_in_realm(&mut self, scope: &mut v8::PinScope<'_, '_>) {
        if let Self::Strong(object) = self {
            let object = v8::Local::new(scope, &*object);
            *self = Self::traced(scope, object);
        }
    }

    pub(crate) fn is_strong(&self) -> bool {
        matches!(self, Self::Strong(_))
    }
}

/// A uniquely owned pending resolver needs a realm root only until its native
/// operation ends. Identity caches use `RealmObjectHandle` instead, since their
/// roots intentionally last as long as the realm.
pub(crate) enum PendingPromiseResolver {
    Strong(v8::Global<v8::PromiseResolver>),
    Traced(v8::Weak<v8::PromiseResolver>),
}

impl PendingPromiseResolver {
    const ROOTS: &str = "__moliPendingRealmResolvers";

    pub(crate) fn new(
        scope: &mut v8::PinScope<'_, '_>,
        resolver: v8::Local<'_, v8::PromiseResolver>,
    ) -> Self {
        if page_context_is_detached_document(scope.get_current_context()) {
            Self::traced(scope, resolver)
        } else {
            Self::Strong(v8::Global::new(scope, resolver))
        }
    }

    fn traced(
        scope: &mut v8::PinScope<'_, '_>,
        resolver: v8::Local<'_, v8::PromiseResolver>,
    ) -> Self {
        let context = resolver
            .get_creation_context(scope)
            .unwrap_or_else(|| scope.get_current_context());
        // Create the collection in its owning realm even when main-document
        // teardown visits a resolver belonging to a shared child world.
        let scope = &mut v8::ContextScope::new(scope, context);
        let anchor = context.get_extras_binding_object(scope);
        let roots = get_private_value(scope, anchor, Self::ROOTS)
            .and_then(|value| v8::Local::<v8::Set>::try_from(value).ok())
            .unwrap_or_else(|| {
                let roots = v8::Set::new(scope);
                set_private_value(scope, anchor, Self::ROOTS, roots.into());
                roots
            });
        let _ = roots.add(scope, resolver.into());
        Self::Traced(v8::Weak::new(scope, resolver))
    }

    pub(crate) fn to_local<'s>(
        &self,
        scope: &mut v8::PinScope<'s, '_>,
    ) -> Option<v8::Local<'s, v8::PromiseResolver>> {
        match self {
            Self::Strong(resolver) => Some(v8::Local::new(scope, resolver)),
            Self::Traced(resolver) => resolver.to_local(scope),
        }
    }

    pub(crate) fn retain_in_realm(&mut self, scope: &mut v8::PinScope<'_, '_>) {
        if let Self::Strong(resolver) = self {
            let resolver = v8::Local::new(scope, &*resolver);
            *self = Self::traced(scope, resolver);
        }
    }

    /// Release the realm edge before settling or cancelling the operation.
    /// The returned Local keeps the resolver alive for the rest of this scope.
    pub(crate) fn into_local<'s>(
        self,
        scope: &mut v8::PinScope<'s, '_>,
    ) -> Option<v8::Local<'s, v8::PromiseResolver>> {
        let resolver = self.to_local(scope)?;
        if matches!(self, Self::Traced(_)) {
            let context = resolver
                .get_creation_context(scope)
                .unwrap_or_else(|| scope.get_current_context());
            let scope = &mut v8::ContextScope::new(scope, context);
            let anchor = context.get_extras_binding_object(scope);
            if let Some(roots) = get_private_value(scope, anchor, Self::ROOTS)
                .and_then(|value| v8::Local::<v8::Set>::try_from(value).ok())
            {
                let _ = roots.delete(scope, resolver.into());
            }
        }
        Some(resolver)
    }
}

/// Value edges owned by native state become ordinary V8 edges when a realm
/// retires. A private holder supports primitives as well as objects and keeps
/// cross-realm values attached to the realm that owns the native state.
pub(crate) enum RealmValueHandle {
    Strong(v8::Global<v8::Value>),
    Traced(RealmObjectHandle),
}

impl RealmValueHandle {
    const VALUE: &str = "__moliRetainedRealmValue";

    pub(crate) fn new(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<'_, v8::Value>) -> Self {
        if page_context_is_detached_document(scope.get_current_context()) {
            Self::traced(scope, value)
        } else {
            Self::Strong(v8::Global::new(scope, value))
        }
    }

    fn traced(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<'_, v8::Value>) -> Self {
        let holder = v8::Object::new(scope);
        set_private_value(scope, holder, Self::VALUE, value);
        Self::Traced(RealmObjectHandle::traced(scope, holder))
    }

    pub(crate) fn to_local<'s>(
        &self,
        scope: &mut v8::PinScope<'s, '_>,
    ) -> v8::Local<'s, v8::Value> {
        match self {
            Self::Strong(value) => v8::Local::new(scope, value),
            Self::Traced(holder) => holder
                .to_local(scope)
                .and_then(|holder| get_private_value(scope, holder, Self::VALUE))
                .unwrap_or_else(|| v8::undefined(scope).into()),
        }
    }

    pub(crate) fn retain_in_realm(&mut self, scope: &mut v8::PinScope<'_, '_>) {
        if let Self::Strong(value) = self {
            let value = v8::Local::new(scope, &*value);
            *self = Self::traced(scope, value);
        }
    }
}

/// Materializes the unexposed prototype described by a WebIDL iterator
/// FunctionTemplate. The temporary constructor is an implementation detail, so
/// its back-reference must not leak onto the iterator prototype.
pub(crate) fn materialize_hidden_function_template_prototype<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    template: v8::Local<'s, v8::FunctionTemplate>,
) -> Option<v8::Local<'s, v8::Object>> {
    let constructor = template.get_function(scope)?;
    let prototype = constructor
        .get(scope, v8str(scope, "prototype").into())
        .and_then(|value| v8::Local::<v8::Object>::try_from(value).ok())?;
    let constructor_key = v8str(scope, "constructor");
    let _ = prototype.delete(scope, constructor_key.into());
    Some(prototype)
}

// # Why V8 callbacks use `RefCell::as_ptr()` instead of `borrow_mut()`
//
// `JsContextHost` is stored as `Rc<RefCell<JsContextHost>>`. Every V8 callback
// needs a `*mut` pointer to call methods on it.
//
// The obvious approach — `hrc.borrow_mut()` — panics at runtime because **V8
// callbacks are inherently re-entrant**: any V8 API call (property access, object
// creation, function invocation, scope operations, etc.) can synchronously execute
// JavaScript, which can trigger *other* V8 callbacks that also need the host.
// If the outer callback holds a `RefMut` guard (or even a `Ref` guard), the inner
// callback's attempt to `borrow_mut()` (or `borrow()`) causes a `RefCell` panic.
//
// Example call chain that panics with `borrow_mut()`:
//   1. `event_target_add_event_listener_callback` — holds `borrow_mut()` guard
//   2. calls `host.add_event_listener(scope, ...)` which touches V8 scope
//   3. V8 evaluates a getter → `window_document_getter` fires
//   4. `window_document_getter` calls `hrc.borrow()` → panics (already mutably borrowed)
//
// `RefCell::as_ptr()` returns a `*mut T` without acquiring any borrow guard, so
// nested callbacks can freely access the host. This is safe because:
// - The `Rc` guarantees the underlying allocation is alive for the callback's duration.
// - All V8 callbacks run on a single thread (V8 isolates are single-threaded).
// - No `&mut` reference alias is observable across a V8 re-entry boundary, since the
//   outer callback does not hold a Rust reference while V8 is executing JavaScript.
//
// `borrow_mut()` is still used in `script_vm.rs` top-level entry points (e.g.
// `replace_document_resource_runtime`, `take_network_output`) which are called from Rust code
// outside V8 callback context, where re-entrancy cannot occur.

pub(crate) fn serialize_v8_array<'s, T>(
    scope: &mut v8::PinScope<'s, '_>,
    value: T,
) -> Option<v8::Local<'s, v8::Array>>
where
    T: WebApiValue<'s>,
{
    let value = value.to_v8_value(scope)?;
    v8::Local::<v8::Array>::try_from(value).ok()
}

pub(crate) fn serialize_v8_iter_array<'s, I, T>(
    scope: &mut v8::PinScope<'s, '_>,
    values: I,
) -> Option<v8::Local<'s, v8::Array>>
where
    I: IntoIterator<Item = T>,
    T: WebApiValue<'s>,
{
    let values = values.into_iter().collect::<Vec<_>>();
    serialize_v8_array(scope, values.as_slice())
}

pub(crate) fn callable_relevant_context<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    mut callable: v8::Local<'s, v8::Value>,
) -> Option<v8::Local<'s, v8::Context>> {
    // V8's GetFunctionRealm unwraps Proxy chains. Bound functions are created
    // in their target function's context, so their creation context already
    // identifies the target realm through the public embedding API.
    while callable.is_proxy() {
        let proxy = v8::Local::<v8::Proxy>::try_from(callable).ok()?;
        callable = proxy.get_target(scope);
    }
    v8::Local::<v8::Object>::try_from(callable)
        .ok()?
        .get_creation_context(scope)
}

pub(crate) fn new_target_realm_constructor_prototype<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    new_target: v8::Local<'s, v8::Value>,
    constructor_name: &str,
) -> Option<v8::Local<'s, v8::Object>> {
    let context = callable_relevant_context(scope, new_target)?;
    let prototype = {
        let context_scope = &mut v8::ContextScope::new(scope, context);
        let prototype = global_constructor_prototype(context_scope, constructor_name)?;
        v8::Global::new(context_scope, prototype)
    };
    Some(v8::Local::new(scope, &prototype))
}

pub(crate) fn receiver_uses_new_target_realm_object_fallback<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    receiver: v8::Local<'s, v8::Object>,
    new_target: v8::Local<'s, v8::Value>,
) -> bool {
    let Some(receiver_prototype) = receiver.get_prototype(scope) else {
        return false;
    };
    let Some(object_prototype) =
        new_target_realm_constructor_prototype(scope, new_target, "Object")
    else {
        return false;
    };
    receiver_prototype.strict_equals(object_prototype.into())
}

pub(crate) fn apply_webidl_constructor_prototype_fallback<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    receiver: v8::Local<'s, v8::Object>,
    new_target: v8::Local<'s, v8::Value>,
    default_constructor_name: &str,
) {
    // V8 has already read `NewTarget.prototype` while preparing the native
    // constructor receiver. Do not read it again: a Proxy getter must run only
    // once. V8 represents a non-object result with NewTarget's realm-local
    // Object prototype, which lets us replace precisely that fallback with
    // the WebIDL interface's default prototype from the same realm.
    if !receiver_uses_new_target_realm_object_fallback(scope, receiver, new_target) {
        return;
    }
    let Some(prototype) =
        new_target_realm_constructor_prototype(scope, new_target, default_constructor_name)
    else {
        return;
    };
    let _ = receiver.set_prototype(scope, prototype.into());
}

pub(super) fn create_script_origin_with_base_url<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    resource_name: &str,
    line_offset: i32,
    base_url: Option<&Url>,
) -> v8::ScriptOrigin<'s> {
    create_script_origin_with_base_url_and_nonce(scope, resource_name, line_offset, base_url, None)
}

pub(super) fn create_script_origin_with_base_url_and_nonce<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    resource_name: &str,
    line_offset: i32,
    base_url: Option<&Url>,
    nonce: Option<&str>,
) -> v8::ScriptOrigin<'s> {
    let name = v8::String::new(scope, resource_name).expect("v8 string allocation");
    let host_defined_options = base_url.and_then(|base_url| {
        script_host_defined_options_with_base_url_and_nonce(scope, base_url, nonce)
    });
    v8::ScriptOrigin::new(
        scope,
        name.into(),
        line_offset,
        0,
        false,
        -1,
        None,
        false,
        false,
        false,
        host_defined_options,
    )
}

pub(crate) fn script_base_url_from_host_defined_options(
    scope: &mut v8::PinScope<'_, '_>,
    host_defined_options: v8::Local<'_, v8::Data>,
) -> Option<Url> {
    let options = script_host_defined_options_as_fixed_array(host_defined_options)?;
    if options.length() < 2 {
        return None;
    }
    let marker = options.get(scope, 0)?;
    let marker = v8::Local::<v8::String>::try_from(marker).ok()?;
    if marker.to_rust_string_lossy(scope) != SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER {
        return None;
    }
    let base_url = options.get(scope, 1)?;
    let base_url = v8::Local::<v8::String>::try_from(base_url).ok()?;
    Url::parse(&base_url.to_rust_string_lossy(scope)).ok()
}

pub(crate) fn script_nonce_from_host_defined_options(
    scope: &mut v8::PinScope<'_, '_>,
    host_defined_options: v8::Local<'_, v8::Data>,
) -> Option<String> {
    let options = script_host_defined_options_as_fixed_array(host_defined_options)?;
    if options.length() < 3 {
        return None;
    }
    let marker = options.get(scope, 0)?;
    let marker = v8::Local::<v8::String>::try_from(marker).ok()?;
    if marker.to_rust_string_lossy(scope) != SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER {
        return None;
    }
    let nonce = options.get(scope, 2)?;
    let nonce = v8::Local::<v8::String>::try_from(nonce).ok()?;
    let nonce = nonce.to_rust_string_lossy(scope);
    (!nonce.is_empty()).then_some(nonce)
}

pub(crate) fn script_parser_inserted_from_host_defined_options(
    scope: &mut v8::PinScope<'_, '_>,
    host_defined_options: v8::Local<'_, v8::Data>,
) -> Option<bool> {
    let options = script_host_defined_options_as_fixed_array(host_defined_options)?;
    if options.length() < 4 {
        return None;
    }
    let marker = options.get(scope, 0)?;
    let marker = v8::Local::<v8::String>::try_from(marker).ok()?;
    if marker.to_rust_string_lossy(scope) != SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER {
        return None;
    }
    let parser_metadata = options.get(scope, 3)?;
    let parser_metadata = v8::Local::<v8::String>::try_from(parser_metadata).ok()?;
    match parser_metadata.to_rust_string_lossy(scope).as_str() {
        "parser-inserted" => Some(true),
        "not-parser-inserted" => Some(false),
        _ => None,
    }
}

fn script_host_defined_options_as_fixed_array<'s>(
    host_defined_options: v8::Local<'s, v8::Data>,
) -> Option<v8::Local<'s, v8::FixedArray>> {
    // V8 passes ScriptOrigin host-defined options back to dynamic import
    // callbacks. The public Rust binding does not expose a PrimitiveArray
    // predicate or TryFrom<Data>, but PrimitiveArray is readable through the
    // FixedArray view and the binding has a safe Data -> FixedArray predicate.
    // Use that read-only view for both our PrimitiveArray payload and V8's
    // default empty FixedArray; the marker below decides whether it is ours.
    v8::Local::<v8::FixedArray>::try_from(host_defined_options).ok()
}

pub(crate) fn script_base_url_from_continuation_data(
    scope: &mut v8::PinScope<'_, '_>,
) -> Option<Url> {
    let value = scope.get_continuation_preserved_embedder_data();
    let value = v8::Local::<v8::String>::try_from(value).ok()?;
    Url::parse(&value.to_rust_string_lossy(scope)).ok()
}

pub(crate) fn script_base_url_continuation_data<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    base_url: &Url,
) -> Option<v8::Local<'s, v8::Value>> {
    v8_string(scope, base_url.as_str()).map(Into::into)
}

pub(crate) fn script_host_defined_options_with_base_url_and_nonce<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    base_url: &Url,
    nonce: Option<&str>,
) -> Option<v8::Local<'s, v8::Data>> {
    script_host_defined_options_with_fetch_metadata(scope, base_url, nonce, false)
}

pub(crate) fn script_host_defined_options_with_fetch_metadata<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    base_url: &Url,
    nonce: Option<&str>,
    parser_inserted: bool,
) -> Option<v8::Local<'s, v8::Data>> {
    let marker = v8_string(scope, SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER)?;
    let value = v8_string(scope, base_url.as_str())?;
    let nonce = v8_string(scope, nonce.unwrap_or_default())?;
    let parser_metadata = v8_string(
        scope,
        if parser_inserted {
            "parser-inserted"
        } else {
            "not-parser-inserted"
        },
    )?;
    let options = v8::PrimitiveArray::new(scope, 4);
    options.set(scope, 0, marker.into());
    options.set(scope, 1, value.into());
    options.set(scope, 2, nonce.into());
    options.set(scope, 3, parser_metadata.into());
    Some(options.into())
}

pub(super) fn enqueue_host_microtask(
    scope: &mut v8::PinScope<'_, '_>,
    callback: v8::Local<'_, v8::Function>,
) {
    scope.enqueue_microtask(callback);
}

pub(super) fn global_bridge_object<'s>(
    scope: &mut v8::PinScope<'s, '_>,
) -> Option<v8::Local<'s, v8::Object>> {
    let global = scope.get_current_context().global(scope);
    get_own_static_property(scope, global, "__moliNativeBridge")
        .and_then(|value| v8::Local::<v8::Object>::try_from(value).ok())
}

pub(super) fn call_global_bridge_method<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    name: &str,
    args: &[v8::Local<'s, v8::Value>],
) -> Option<v8::Local<'s, v8::Value>> {
    let bridge = global_bridge_object(scope)?;
    let method = bridge.get(scope, v8_string(scope, name)?.into())?;
    let method = v8::Local::<v8::Function>::try_from(method).ok()?;
    crate::script_execution::call_function(scope, method, bridge.into(), args)
}

/// Obtain a raw `*mut JsContextHost` pointer from the V8 global bridge.
///
/// This is the standard way to access the host inside **V8 callbacks**. It reads
/// the pointer stored in bridge internal field 0 (set during `install_into_bridge`).
///
/// We return a raw pointer instead of a `&mut` reference because V8 callbacks are
/// inherently re-entrant: any V8 API call (property access, object creation, scope
/// operations…) can synchronously execute JavaScript, which fires *other* V8
/// callbacks that also need the host. If we used `RefCell::borrow_mut()`, the
/// inner callback's `borrow_mut()` would panic ("already mutably borrowed").
///
/// See the module-level comment at the top of this file for a detailed example.
///
/// # Safety contract for callers
///
/// The returned pointer is valid for the duration of the V8 callback because the
/// owning ScriptVm page state keeps a Rust-side `Rc`, and each live V8 context
/// owns an additional bridge-ref token for the ref-count stored in the native
/// bridge object. All document V8 callbacks run on the render
/// owner thread, so there is no data race. Callers must not hold a Rust `&mut`
/// reference across a V8 API call that could trigger re-entrant JavaScript
/// execution.
pub(super) fn context_host_ptr_from_global_bridge(
    scope: &mut v8::PinScope<'_, '_>,
) -> Option<*mut JsContextHost> {
    let context = scope.get_current_context();
    if page_context_is_disconnected(context) {
        return None;
    }
    if let Some(host_ptr) = context_host_ptr_from_context_slot(context) {
        return Some(host_ptr);
    }
    // Read directly from bridge internal field 0 — no Rc ref-count overhead.
    let global = context.global(scope);
    context_host_ptr_from_window_object(scope, global)
}

pub(super) fn install_context_host_pointer_slot(
    context: v8::Local<'_, v8::Context>,
    host_ptr: *mut JsContextHost,
    host_lifecycle: Rc<Cell<ContextHostLifecycle>>,
) {
    let host_ptr =
        NonNull::new(host_ptr).expect("V8 context JsContextHost pointer should not be null");
    assert!(
        host_lifecycle.get() == ContextHostLifecycle::Active,
        "a retired JsContextHost must not be installed into a V8 context"
    );
    let common = Rc::clone(&unsafe { &*host_ptr.as_ptr() }.common);
    crate::common_runtime::CommonRuntimeBinding::install_window(
        context,
        &common,
        host_ptr.as_ptr(),
        &host_lifecycle,
    );
    if let Some(existing) = context.get_slot::<ContextHostPointerSlot>() {
        assert!(
            existing.host_ptr == host_ptr && Rc::ptr_eq(&existing.host_lifecycle, &host_lifecycle),
            "V8 context JsContextHost pointer must not be rebound"
        );
        return;
    }
    let previous = context.set_slot(Rc::new(ContextHostPointerSlot {
        host_ptr,
        host_lifecycle: host_lifecycle.clone(),
        retained_realm_owner: RefCell::new(None),
    }));
    debug_assert!(previous.is_none());
}

pub(super) fn context_host_ptr_from_context_slot(
    context: v8::Local<'_, v8::Context>,
) -> Option<*mut JsContextHost> {
    if page_context_is_disconnected(context) {
        return None;
    }
    context
        .get_slot::<ContextHostPointerSlot>()
        .map(|slot| slot.host_ptr.as_ptr())
}

pub(crate) fn retain_context_host_for_document_realm(
    context: v8::Local<'_, v8::Context>,
    host: Rc<RefCell<JsContextHost>>,
    deferred_release_queue: crate::script_vm::RendererDeferredContextHostReleaseQueue,
) {
    let slot = context
        .get_slot::<ContextHostPointerSlot>()
        .expect("published Document realm must have a JsContextHost pointer slot");
    let host_ptr = NonNull::new(host.as_ptr())
        .expect("published Document realm JsContextHost pointer should not be null");
    assert_eq!(
        slot.host_ptr, host_ptr,
        "published Document realm must retain its installed JsContextHost"
    );
    assert!(
        slot.host_lifecycle.get() != ContextHostLifecycle::Destroyed,
        "destroyed JsContextHost must not gain a retained realm owner"
    );
    let mut retained = slot.retained_realm_owner.borrow_mut();
    if let Some(existing) = retained.as_ref() {
        assert!(
            existing
                .host
                .as_ref()
                .is_some_and(|existing| Rc::ptr_eq(existing, &host)),
            "Document realm JsContextHost owner must not be rebound"
        );
        return;
    }
    *retained = Some(RetainedDocumentRealmHostOwner {
        host: Some(host),
        deferred_release_queue,
        retained_v8_handle_state: Vec::new(),
    });
}

pub(crate) fn retain_context_v8_handle_state_for_safe_release<T: 'static>(
    context: v8::Local<'_, v8::Context>,
    state: Rc<T>,
) {
    let slot = context
        .get_slot::<ContextHostPointerSlot>()
        .expect("retained Context embedder state requires a Document host slot");
    let mut retained_owner = slot.retained_realm_owner.borrow_mut();
    let retained_owner = retained_owner
        .as_mut()
        .expect("retained Context embedder state requires a published real realm");
    retained_owner
        .retained_v8_handle_state
        .push(Box::new(state));
}

pub(crate) fn page_context_is_disconnected(context: v8::Local<'_, v8::Context>) -> bool {
    context.get_slot::<DisconnectedPageContext>().is_some()
        || context
            .get_slot::<ContextHostPointerSlot>()
            .is_some_and(|slot| match slot.host_lifecycle.get() {
                ContextHostLifecycle::Active => false,
                ContextHostLifecycle::Detached => slot.retained_realm_owner.borrow().is_none(),
                ContextHostLifecycle::Destroyed => true,
            })
}

pub(crate) fn page_context_is_detached_document(context: v8::Local<'_, v8::Context>) -> bool {
    context.get_slot::<DetachedDocumentPageContext>().is_some()
        || context
            .get_slot::<ContextHostPointerSlot>()
            .is_some_and(|slot| slot.host_lifecycle.get() == ContextHostLifecycle::Detached)
}

pub(crate) fn detach_document_page_context(context: v8::Local<'_, v8::Context>) {
    if page_context_is_disconnected(context) || page_context_is_detached_document(context) {
        return;
    }
    let slot = context
        .get_slot::<ContextHostPointerSlot>()
        .expect("detached Document realm must have a JsContextHost pointer slot");
    assert!(
        slot.retained_realm_owner.borrow().is_some(),
        "only a retained real Document realm may enter detached state"
    );
    let previous = context.set_slot(Rc::new(DetachedDocumentPageContext));
    debug_assert!(previous.is_none());
}

/// Convenience wrapper for callbacks that immediately need the host value.
///
/// This has the same re-entrancy caveat as `context_host_ptr_from_global_bridge`:
/// do not keep the returned `&mut JsContextHost` across V8 calls that can
/// synchronously enter JavaScript and re-enter native callbacks.
pub(super) fn context_host_from_global_bridge<'host>(
    scope: &mut v8::PinScope<'_, '_>,
) -> Option<&'host mut JsContextHost> {
    let host_ptr = context_host_ptr_from_global_bridge(scope)?;
    Some(unsafe { &mut *host_ptr })
}

pub(crate) fn debug_assert_script_visible_callback_outside_structural_mutation(
    scope: &mut v8::PinScope<'_, '_>,
    action: &str,
) {
    #[cfg(debug_assertions)]
    if let Some(host_ptr) = context_host_ptr_from_global_bridge(scope) {
        unsafe { &*host_ptr }.debug_assert_not_in_structural_mutation(action);
    }
    #[cfg(not(debug_assertions))]
    {
        let _ = (scope, action);
    }
}

pub(crate) fn call_script_visible_function<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    function: v8::Local<'s, v8::Function>,
    receiver: v8::Local<'s, v8::Value>,
    args: &[v8::Local<'s, v8::Value>],
    action: &str,
) -> Option<v8::Local<'s, v8::Value>> {
    debug_assert_script_visible_callback_outside_structural_mutation(scope, action);
    crate::script_execution::call_function(scope, function, receiver, args)
}

pub(super) fn context_host_ptr_from_window_object(
    scope: &mut v8::PinScope<'_, '_>,
    object: v8::Local<'_, v8::Object>,
) -> Option<*mut JsContextHost> {
    if page_context_is_disconnected(scope.get_current_context())
        || object
            .get_creation_context(scope)
            .is_some_and(page_context_is_disconnected)
    {
        return None;
    }
    if let Some(value) = object.get_internal_field(scope, 0)
        && let Ok(external) = v8::Local::<v8::External>::try_from(value)
    {
        let ptr = external.value() as *mut JsContextHost;
        if !ptr.is_null() {
            return Some(ptr);
        }
    }

    let bridge = get_own_static_property(scope, object, "__moliNativeBridge")
        .and_then(|value| v8::Local::<v8::Object>::try_from(value).ok())?;
    let value = bridge.get_internal_field(scope, 0)?;
    let external = v8::Local::<v8::External>::try_from(value).ok()?;
    let ptr = external.value() as *mut JsContextHost;
    if ptr.is_null() { None } else { Some(ptr) }
}

pub(super) fn node_wrapper_from_handle<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    handle: DomHandle,
) -> Option<v8::Local<'s, v8::Object>> {
    // V8 callback helper — wrap_handle triggers V8 operations (property
    // interceptors, instantiate_wrapper) that re-enter other callbacks.
    let host_ptr = context_host_ptr_from_global_bridge(scope)?;
    unsafe { &mut *host_ptr }
        .native_bridge_mut()
        .wrap_handle(scope, host_ptr, handle)
}

/// Update an existing node wrapper in its creation realm. Native lifecycle work
/// can run before that realm exists, so it must not allocate a wrapper in the
/// caller's context just to synchronize a JavaScript view of native state.
pub(crate) fn with_cached_node_wrapper_realm<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    host: &JsContextHost,
    handle: DomHandle,
    operation: impl FnOnce(&mut v8::PinScope<'s, '_>, v8::Local<'s, v8::Object>),
) {
    let Some(wrapper) = host.native_bridge().cached_handle_wrapper(scope, handle) else {
        return;
    };
    let Some(context) = wrapper.get_creation_context(scope) else {
        return;
    };
    let scope = &mut v8::ContextScope::new(scope, context);
    operation(scope, wrapper);
}

pub(super) fn global_bridge_method<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    name: &str,
) -> Option<(v8::Local<'s, v8::Object>, v8::Local<'s, v8::Function>)> {
    let bridge = global_bridge_object(scope)?;
    let method = bridge.get(scope, v8_string(scope, name)?.into())?;
    let method = v8::Local::<v8::Function>::try_from(method).ok()?;
    Some((bridge, method))
}

pub(super) fn callback_arg_string(
    scope: &mut v8::PinScope<'_, '_>,
    args: &v8::FunctionCallbackArguments<'_>,
    index: i32,
) -> Option<String> {
    args.get(index)
        .to_string(scope)
        .map(|value| value.to_rust_string_lossy(scope))
}

pub(crate) fn v8_string_to_u16_string(
    scope: &mut v8::PinScope<'_, '_>,
    value: v8::Local<'_, v8::String>,
) -> U16String {
    let mut units = vec![0; value.length()];
    // The vendored V8 binding for String::write_v2 returns `()`. The buffer is
    // sized from the same V8 string length and the binding writes at most that
    // many UTF-16 code units.
    value.write_v2(scope, 0, &mut units, v8::WriteFlags::empty());
    U16String::from_vec(units)
}

pub(crate) fn v8_value_to_dom_string_u16<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    value: v8::Local<'s, v8::Value>,
    treat_null_as_empty_string: bool,
) -> Option<U16String> {
    if value.is_null() && treat_null_as_empty_string {
        return Some(U16String::new());
    }
    if value.is_symbol() {
        throw_type_error(scope, "Failed to convert value to DOMString.");
        return None;
    }

    let converted = {
        let try_catch = std::pin::pin!(v8::TryCatch::new(scope));
        let mut scope = try_catch.init();
        match value.to_string(&scope) {
            Some(value) => Some(v8_string_to_u16_string(&mut scope, value)),
            None if scope.has_caught() => {
                let _ = scope.rethrow();
                return None;
            }
            None => None,
        }
    };
    if converted.is_none() {
        throw_type_error(scope, "Failed to convert value to DOMString.");
    }
    converted
}

pub(crate) fn v8_string_from_utf16_units<'s>(
    scope: &mut v8::PinScope<'s, '_>,
    units: &[u16],
) -> Option<v8::Local<'s, v8::String>> {
    v8::String::new_from_two_byte(scope, units, v8::NewStringType::Normal)
}

pub(crate) fn utf16_units(value: &str) -> Vec<u16> {
    value.encode_utf16().collect()
}

pub(crate) fn utf16_len(value: &str) -> usize {
    value.encode_utf16().count()
}

pub(crate) fn string_from_utf16_units_lossy(units: &[u16]) -> String {
    String::from_utf16_lossy(units)
}

pub(crate) fn utf16_slice_units_lossy(units: &[u16], start: usize, end: usize) -> String {
    let start = start.min(units.len());
    let end = end.min(units.len()).max(start);
    string_from_utf16_units_lossy(&units[start..end])
}

pub(crate) fn utf16_slice_lossy(value: &str, start: usize, end: usize) -> String {
    let units = utf16_units(value);
    utf16_slice_units_lossy(&units, start, end)
}

pub(crate) fn utf16_split_units_lossy(units: &[u16], offset: usize) -> (String, String) {
    let offset = offset.min(units.len());
    (
        string_from_utf16_units_lossy(&units[..offset]),
        string_from_utf16_units_lossy(&units[offset..]),
    )
}

pub(crate) fn utf16_replace_units_range_lossy(
    units: &[u16],
    start: usize,
    count: usize,
    replacement: &[u16],
) -> String {
    let start = start.min(units.len());
    let end = start.saturating_add(count).min(units.len());
    let mut next = Vec::with_capacity(
        units
            .len()
            .saturating_sub(end.saturating_sub(start))
            .saturating_add(replacement.len()),
    );
    next.extend_from_slice(&units[..start]);
    next.extend_from_slice(replacement);
    next.extend_from_slice(&units[end..]);
    string_from_utf16_units_lossy(&next)
}

pub(crate) fn utf16_scalar_boundary_at_or_after(units: &[u16], offset: usize) -> usize {
    let offset = offset.min(units.len());
    if offset > 0
        && offset < units.len()
        && (0xD800..=0xDBFF).contains(&units[offset - 1])
        && (0xDC00..=0xDFFF).contains(&units[offset])
    {
        offset + 1
    } else {
        offset
    }
}

pub(crate) fn utf16_previous_scalar_boundary(units: &[u16], offset: usize) -> usize {
    let mut previous = offset.min(units.len()).saturating_sub(1);
    if previous > 0
        && (0xDC00..=0xDFFF).contains(&units[previous])
        && (0xD800..=0xDBFF).contains(&units[previous - 1])
    {
        previous -= 1;
    }
    previous
}

pub(crate) fn utf16_next_scalar_boundary(units: &[u16], offset: usize) -> usize {
    let offset = offset.min(units.len());
    if offset == units.len() {
        return offset;
    }
    let mut next = offset + 1;
    if next < units.len()
        && (0xD800..=0xDBFF).contains(&units[offset])
        && (0xDC00..=0xDFFF).contains(&units[next])
    {
        next += 1;
    }
    next
}

pub(crate) fn utf16_units_contain_unpaired_surrogate(units: &[u16]) -> bool {
    let mut index = 0;
    while index < units.len() {
        let unit = units[index];
        if (0xD800..=0xDBFF).contains(&unit) {
            if units
                .get(index + 1)
                .is_some_and(|next| (0xDC00..=0xDFFF).contains(next))
            {
                index += 2;
                continue;
            }
            return true;
        }
        if (0xDC00..=0xDFFF).contains(&unit) {
            return true;
        }
        index += 1;
    }
    false
}

#[cfg(test)]
mod tests {
    use std::pin::pin;

    use super::{
        SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER, object_chain_contains,
        script_base_url_from_host_defined_options,
        script_host_defined_options_with_base_url_and_nonce,
        script_host_defined_options_with_fetch_metadata, script_nonce_from_host_defined_options,
        script_parser_inserted_from_host_defined_options, utf16_replace_units_range_lossy,
        utf16_slice_lossy, utf16_split_units_lossy, utf16_units, walk_object_chain,
    };
    use crate::ensure_v8_for_test as ensure_v8;
    use moli_v8_util::walk_object_chain_last;
    use moli_webapi_declare::WebApiObject;
    use url::Url;

    #[derive(WebApiObject)]
    #[webapi(plain, data_properties)]
    struct TestParentObjectDeclaration<'scope> {
        parent_node: v8::Local<'scope, v8::Object>,
    }

    #[derive(WebApiObject)]
    #[webapi(plain, data_properties)]
    struct TestParentValueDeclaration<'scope> {
        parent_node: v8::Local<'scope, v8::Value>,
    }

    #[derive(WebApiObject)]
    #[webapi(plain)]
    struct TestIdentityObjectDeclaration {}

    fn primitive_host_defined_options<'s>(
        scope: &mut v8::PinScope<'s, '_>,
        fields: &[&str],
    ) -> v8::Local<'s, v8::Data> {
        let options = v8::PrimitiveArray::new(scope, fields.len());
        for (index, field) in fields.iter().enumerate() {
            let value = v8::String::new(scope, field).expect("test option field");
            options.set(scope, index, value.into());
        }
        options.into()
    }

    #[test]
    fn utf16_string_helpers_use_code_unit_offsets() {
        let value = "a\u{1f306}b";
        assert_eq!(utf16_slice_lossy(value, 1, 3), "\u{1f306}");
        assert_eq!(utf16_slice_lossy(value, 2, 3), "\u{fffd}");
        let units = utf16_units(value);
        assert_eq!(
            utf16_split_units_lossy(&units, 3),
            ("\u{61}\u{1f306}".to_owned(), "b".to_owned())
        );
        assert_eq!(utf16_replace_units_range_lossy(&units, 1, 2, &[]), "ab");
        assert_eq!(
            utf16_replace_units_range_lossy(&units, 1, 2, &[b'x' as u16]),
            "axb"
        );
    }

    #[test]
    fn script_host_defined_options_read_moli_primitive_array_payload() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let base_url = Url::parse("https://example.test/scripts/entry.js").unwrap();
        let options =
            script_host_defined_options_with_base_url_and_nonce(scope, &base_url, Some("abc123"))
                .expect("script host-defined options should allocate");

        assert_eq!(
            script_base_url_from_host_defined_options(scope, options),
            Some(base_url.clone())
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, options),
            Some("abc123".to_owned())
        );
        assert_eq!(
            script_parser_inserted_from_host_defined_options(scope, options),
            Some(false)
        );

        let parser_options =
            script_host_defined_options_with_fetch_metadata(scope, &base_url, Some("abc123"), true)
                .expect("parser-inserted host-defined options should allocate");
        assert_eq!(
            script_parser_inserted_from_host_defined_options(scope, parser_options),
            Some(true)
        );
    }

    #[test]
    fn script_host_defined_options_ignore_non_fixed_array_data() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let value: v8::Local<'_, v8::Value> = v8::String::new(scope, "not-moli-options")
            .expect("test string")
            .into();
        let data: v8::Local<'_, v8::Data> = value.into();

        assert_eq!(script_base_url_from_host_defined_options(scope, data), None);
        assert_eq!(script_nonce_from_host_defined_options(scope, data), None);
        assert_eq!(
            script_parser_inserted_from_host_defined_options(scope, data),
            None
        );
    }

    #[test]
    fn script_host_defined_options_ignore_malformed_payloads() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let empty = primitive_host_defined_options(scope, &[]);
        assert_eq!(
            script_base_url_from_host_defined_options(scope, empty),
            None
        );
        assert_eq!(script_nonce_from_host_defined_options(scope, empty), None);
        assert_eq!(
            script_parser_inserted_from_host_defined_options(scope, empty),
            None
        );

        let marker_only =
            primitive_host_defined_options(scope, &[SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER]);
        assert_eq!(
            script_base_url_from_host_defined_options(scope, marker_only),
            None
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, marker_only),
            None
        );

        let wrong_marker = primitive_host_defined_options(
            scope,
            &["not-moli-options", "https://example.test/entry.js"],
        );
        assert_eq!(
            script_base_url_from_host_defined_options(scope, wrong_marker),
            None
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, wrong_marker),
            None
        );

        let invalid_base = primitive_host_defined_options(
            scope,
            &[SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER, "http://[::1"],
        );
        assert_eq!(
            script_base_url_from_host_defined_options(scope, invalid_base),
            None
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, invalid_base),
            None
        );
    }

    #[test]
    fn script_host_defined_options_treat_missing_or_empty_nonce_as_absent() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let base_url = Url::parse("https://example.test/no-nonce.js").unwrap();
        let missing_nonce = primitive_host_defined_options(
            scope,
            &[
                SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER,
                "https://example.test/no-nonce.js",
            ],
        );
        assert_eq!(
            script_base_url_from_host_defined_options(scope, missing_nonce),
            Some(base_url)
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, missing_nonce),
            None
        );

        let empty_nonce = primitive_host_defined_options(
            scope,
            &[
                SCRIPT_BASE_URL_HOST_DEFINED_OPTIONS_MARKER,
                "https://example.test/empty-nonce.js",
                "",
            ],
        );
        assert_eq!(
            script_base_url_from_host_defined_options(scope, empty_nonce),
            Some(Url::parse("https://example.test/empty-nonce.js").unwrap())
        );
        assert_eq!(
            script_nonce_from_host_defined_options(scope, empty_nonce),
            None
        );
    }

    #[test]
    fn script_host_defined_options_ignore_v8_native_fixed_array_payload() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let source = v8::String::new(scope, "export default 1;").expect("module source");
        let name = v8::String::new(scope, "https://example.test/native-fixed-array.js")
            .expect("module source name");
        let origin = v8::ScriptOrigin::new(
            scope,
            name.into(),
            0,
            0,
            false,
            -1,
            None,
            false,
            false,
            true,
            None,
        );
        let mut source = v8::script_compiler::Source::new(source, Some(&origin));
        let module =
            v8::script_compiler::compile_module(scope, &mut source).expect("module should compile");
        let requests = module.get_module_requests();
        assert_eq!(requests.length(), 0);

        let data: v8::Local<'_, v8::Data> = requests.into();
        assert_eq!(script_base_url_from_host_defined_options(scope, data), None);
        assert_eq!(script_nonce_from_host_defined_options(scope, data), None);
    }

    fn object_with_parent<'s>(
        scope: &mut v8::PinScope<'s, '_>,
        parent_node: v8::Local<'s, v8::Object>,
    ) -> v8::Local<'s, v8::Object> {
        TestParentObjectDeclaration::new(parent_node)
            .bind(scope)
            .expect("test parent object declaration should bind")
    }

    fn object_with_parent_value<'s>(
        scope: &mut v8::PinScope<'s, '_>,
        parent_node: v8::Local<'s, v8::Value>,
    ) -> v8::Local<'s, v8::Object> {
        TestParentValueDeclaration::new(parent_node)
            .bind(scope)
            .expect("test parent value declaration should bind")
    }

    fn test_identity_object<'s>(scope: &mut v8::PinScope<'s, '_>) -> v8::Local<'s, v8::Object> {
        TestIdentityObjectDeclaration::new()
            .bind(scope)
            .expect("test identity object declaration should bind")
    }

    #[test]
    fn walk_object_chain_follows_property_until_missing() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let root = test_identity_object(scope);
        let middle = object_with_parent(scope, root);
        let leaf = object_with_parent(scope, middle);

        let chain = walk_object_chain(scope, leaf, "parentNode");
        assert_eq!(chain.len(), 3, "expected leaf->middle->root chain");
        assert!(chain[0].strict_equals(leaf.into()));
        assert!(chain[1].strict_equals(middle.into()));
        assert!(chain[2].strict_equals(root.into()));

        // A node with no parent property is its own one-element chain.
        let solo = test_identity_object(scope);
        let solo_chain = walk_object_chain(scope, solo, "parentNode");
        assert_eq!(solo_chain.len(), 1);
        assert!(solo_chain[0].strict_equals(solo.into()));
    }

    #[test]
    fn walk_object_chain_stops_on_non_object_property() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        // parentNode set to v8::null/undefined/Number — walk must NOT consume
        // these as objects, even though they are present on the object.
        let null = v8::null(scope);
        let leaf = object_with_parent_value(scope, null.into());
        assert_eq!(walk_object_chain(scope, leaf, "parentNode").len(), 1);

        let number = v8::Number::new(scope, 42.0);
        let leaf2 = object_with_parent_value(scope, number.into());
        assert_eq!(walk_object_chain(scope, leaf2, "parentNode").len(), 1);
    }

    #[test]
    fn walk_object_chain_last_returns_root_of_chain() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let root = test_identity_object(scope);
        let mid = object_with_parent(scope, root);
        let leaf = object_with_parent(scope, mid);

        let last = walk_object_chain_last(scope, leaf, "parentNode");
        assert!(
            last.strict_equals(root.into()),
            "expected last() to land on root"
        );

        // Single-node chain — its last is itself.
        let solo = test_identity_object(scope);
        let solo_last = walk_object_chain_last(scope, solo, "parentNode");
        assert!(solo_last.strict_equals(solo.into()));
    }

    #[test]
    fn object_chain_contains_uses_strict_equality_not_property_equality() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = pin!(v8::HandleScope::new(&mut isolate));
        let scope = &mut scope.init();
        let context = v8::Context::new(scope, Default::default());
        let scope = &mut v8::ContextScope::new(scope, context);

        let a = test_identity_object(scope);
        let b = test_identity_object(scope);
        let c = test_identity_object(scope);
        let chain = [a, b];

        assert!(object_chain_contains(&chain, a));
        assert!(object_chain_contains(&chain, b));
        assert!(!object_chain_contains(&chain, c));

        // Two fresh-but-equivalent empty objects must not be considered the
        // same node — strict equality on object handles is identity.
        let look_alike = test_identity_object(scope);
        assert!(!object_chain_contains(&chain, look_alike));

        // An empty chain trivially contains nothing.
        let empty: [v8::Local<v8::Object>; 0] = [];
        assert!(!object_chain_contains(&empty, a));
    }
}