ps-blitz-script 0.5.5

//! JavaScript DOM API bindings backed by `blitz-dom`.
//!
//! The bindings are implemented as prototype objects built with Boa's native object
//! APIs. Each DOM node is represented by a single cached JS wrapper object (see
//! [`node_wrapper`]) whose native data is a [`NodeRef`] holding the `blitz-dom`
//! node id. Native functions look the document up via the [`DomCtx`] stored as
//! host-defined data on the Boa [`Context`].

mod collections;
pub(crate) mod custom_elements;
pub(crate) mod document;
pub(crate) mod doma;
pub(crate) mod element;
pub(crate) mod event;
pub(crate) mod event_interfaces;
mod event_target;
mod geometry;
mod html_element;
pub(crate) mod inline_handlers;
pub(crate) mod interfaces;
pub(crate) mod node;
mod parsing;
pub(crate) mod range;
#[cfg(feature = "shadow-dom")]
pub(crate) mod shadow;
#[cfg(feature = "shadow-dom")]
pub(crate) mod shadow_event;
#[cfg(feature = "shadow-dom")]
pub(crate) mod sheets;
pub(crate) mod style;

use blitz_dom::NodeId;
use blitz_dom::node::NodeData;
use blitz_dom::{LocalName, Namespace, QualName};
use boa_engine::object::{FunctionObjectBuilder, JsObject, WeakJsObject};
use boa_engine::property::{PropertyDescriptor, PropertyKey};
use boa_engine::value::JsValue;
use boa_engine::{
    Context, Finalize, JsData, JsNativeError, JsResult, JsString, NativeFunction, Trace,
};

use crate::state::{DomCtx, DomProtos};

/// Native data attached to DOM node wrapper objects
#[derive(Trace, Finalize, JsData)]
pub(crate) struct NodeRef {
    #[unsafe_ignore_trace]
    pub node_id: NodeId,
}

/// Fetch the [`DomCtx`] from the Boa context's host-defined data
pub(crate) fn dom_ctx(context: &mut Context) -> JsResult<DomCtx> {
    context.get_data::<DomCtx>().cloned().ok_or_else(|| {
        JsNativeError::typ()
            .with_message("DOM context missing")
            .into()
    })
}

/// Extract the node id from a JS DOM node wrapper
pub(crate) fn node_id_of_value(value: &JsValue) -> Option<NodeId> {
    value.as_object().and_then(|obj| {
        obj.downcast_ref::<NodeRef>()
            .map(|node_ref| node_ref.node_id)
    })
}

/// Extract the node id from the `this` value of a native function
pub(crate) fn this_node_id(this: &JsValue) -> JsResult<NodeId> {
    node_id_of_value(this).ok_or_else(|| {
        JsNativeError::typ()
            .with_message("`this` is not a DOM node")
            .into()
    })
}

/// Get (or create) the unique JS wrapper object for a DOM node.
///
/// Wrappers are cached in [`RuntimeState::node_wrappers`](crate::state::RuntimeState::node_wrappers)
/// so that object identity (`===`) and expando properties behave as scripts expect.
pub(crate) fn node_wrapper(ctx: &DomCtx, node_id: NodeId, context: &mut Context) -> JsObject {
    // Upgraded rather than cloned: the cache holds weak handles, so an entry
    // whose wrapper nothing else kept has been collected and a fresh one is
    // built below. Identity still holds for every wrapper something is actually
    // holding, which is the only case identity can be observed in a program.
    let cached = ctx
        .state
        .borrow()
        .node_wrappers
        .get(&node_id)
        .and_then(WeakJsObject::upgrade);
    if let Some(wrapper) = cached {
        pin_detached_document(ctx, node_id, &wrapper, context);
        return wrapper;
    }

    let custom_prototype = custom_elements::element_prototype(ctx, node_id, context);
    let proto = {
        let doc = ctx.doc.borrow();
        let state = ctx.state.borrow();
        let node = doc.get_node(node_id);
        let data = node.map(|node| &node.data);
        let is_element = matches!(
            data,
            Some(NodeData::Element(_)) | Some(NodeData::AnonymousBlock(_))
        );
        match node.and_then(|node| node.markup.as_deref()) {
            Some(blitz_dom::node::MarkupNode::Doctype { .. }) => {
                interfaces::prototype("DocumentType", context)
            }
            Some(blitz_dom::node::MarkupNode::ProcessingInstruction { .. }) => {
                interfaces::prototype("ProcessingInstruction", context)
            }
            None => match custom_prototype {
                // A defined custom element takes its class's prototype.
                Some(custom) if is_element => custom,
                #[cfg(feature = "shadow-dom")]
                _ if matches!(data, Some(NodeData::ShadowRoot(_))) => shadow::root_proto(context),
                _ if matches!(data, Some(NodeData::Document(data)) if data.content_type != "text/html") => {
                    interfaces::prototype("XMLDocument", context)
                }
                _ => interfaces::node_prototype(data, state.protos(), context),
            },
        }
    };

    let wrapper = JsObject::from_proto_and_data(Some(proto), NodeRef { node_id });
    let connected = ctx
        .doc
        .borrow()
        .get_node(node_id)
        .is_some_and(|node| node.flags.is_in_document());
    let mut state = ctx.state.borrow_mut();
    state.node_wrappers.insert(node_id, wrapper.downgrade());
    if connected {
        state.connected_wrappers.insert(node_id, wrapper.clone());
    }
    drop(state);
    inline_handlers::seed(ctx, node_id, &wrapper, context);
    pin_detached_document(ctx, node_id, &wrapper, context);
    wrapper
}

/// Only wrappers touched by script participate in these traced links. A
/// detached document and its node wrappers can be collected together.
fn pin_detached_document(ctx: &DomCtx, node_id: NodeId, wrapper: &JsObject, context: &mut Context) {
    const OWNER_KEY: &str = "__blitz_internal_owner_document__";
    let owner = {
        let doc = ctx.doc.borrow();
        doc.get_node(node_id)
            .and_then(|node| node.owner_document)
            .filter(|owner| *owner != doc.root_node().id)
    };
    let previous = wrapper
        .get(JsString::from(OWNER_KEY), context)
        .ok()
        .and_then(|value| value.as_object());
    let previous_id = previous
        .as_ref()
        .and_then(|object| object.downcast_ref::<NodeRef>().map(|node| node.node_id));
    let owned_key = format!("__blitz_internal_owned_node_{}", node_id.as_u64());
    if previous_id != owner {
        if let Some(previous) = previous {
            let _ = previous.delete_property_or_throw(JsString::from(owned_key.as_str()), context);
        }
        define_value(wrapper, OWNER_KEY, JsValue::null(), context);
    }
    if let Some(owner) = owner {
        let document = node_wrapper(ctx, owner, context);
        define_value(wrapper, OWNER_KEY, document.clone().into(), context);
        define_value(&document, &owned_key, wrapper.clone().into(), context);
    }
}

/// Detach a node, and free it when script can no longer reach it.
///
/// `remove_node` keeps a removed node alive so a wrapper still holding it stays
/// usable, which is the right contract - `removeChild` returns the node and a
/// browser keeps it working. Applying that to *every* removed node is what grew
/// the document without bound, because the overwhelming majority are rows a
/// framework built and dropped and no script will mention again.
///
/// The wrapper cache is weak now, so it answers this honestly: an entry that
/// upgrades means something is still holding the wrapper, and one that does not
/// means the collector has taken it and the node is unreachable.
pub(crate) fn remove_and_free_node(ctx: &DomCtx, node_id: NodeId, context: &mut Context) {
    node::unroot_detached_listener_subtree(ctx, node_id, context);
    ctx.mutate_doc().mutate().remove_node(node_id);
    // Parked rather than judged. Asking "can script still reach this" right now
    // always answers yes: the wrapper was alive a moment ago, because the call
    // that removed the node went through it. `sweep_detached_nodes` asks later,
    // once the collector has had a chance to disagree.
    ctx.state.borrow_mut().detached_nodes.push(node_id);
}

/// Stop treating a node as detached when script inserts it again before the
/// collector judged it. DOM move operations commonly remove and append in one
/// turn, and a later sweep must not drop the newly connected subtree.
pub(crate) fn mark_node_reattached(ctx: &DomCtx, node_id: NodeId) {
    let ids = {
        let doc = ctx.doc.borrow();
        let mut ids = Vec::new();
        let mut stack = vec![node_id];
        while let Some(id) = stack.pop() {
            if let Some(node) = doc.get_node(id) {
                if node.flags.is_in_document() {
                    ids.push(id);
                }
                stack.extend(node.children.iter().copied());
                if let Some(contents) = node
                    .element_data()
                    .and_then(|element| element.template_contents)
                {
                    stack.push(contents);
                }
                #[cfg(feature = "shadow-dom")]
                if let Some(root_id) = node.shadow_root_id() {
                    stack.push(root_id);
                }
            }
        }
        ids
    };
    let mut state = ctx.state.borrow_mut();
    state
        .detached_nodes
        .retain(|candidate| *candidate != node_id);
    for id in ids {
        if let Some(wrapper) = state
            .node_wrappers
            .get(&id)
            .and_then(|wrapper| wrapper.upgrade())
        {
            state.connected_wrappers.insert(id, wrapper);
        }
    }
}

/// Free detached nodes whose wrappers the collector has taken.
///
/// This is the half that could not be written before wrappers were weak. A node
/// is removed while script may still hold its wrapper, and that cannot be judged
/// at the moment of removal; it can be judged later, and "later" is any point
/// after a collection. An entry that still upgrades is a node something is
/// holding on to, so it stays detached exactly as before.
///
/// Called from the poll loop, so the cost is bounded by how much was removed
/// rather than by the size of the document.
pub(crate) fn sweep_detached_nodes(ctx: &DomCtx) {
    // Boa's automatic collector is allocation-driven, so a large application
    // can repeatedly remount DOM trees without crossing its collection
    // threshold soon enough. Weak wrappers only become observably dead after a
    // collection; without this bound, detached nodes and their listener-owned
    // Solid closures grow linearly while the visible tree remains flat.
    //
    // Do not collect on every removal. Small detached sets are normal DOM
    // behavior and Boa may collect them naturally. Crossing this threshold is
    // the signal that delayed collection is now more expensive than one GC.
    //
    // Count only nodes detached since the last sweep. Nodes the last sweep kept
    // are still held by script; a forced collection cannot free them, and
    // counting them made a page holding 256 detached wrappers run a full GC on
    // every poll.
    const DETACHED_NODE_GC_THRESHOLD: usize = 256;
    let fresh = {
        let state = ctx.state.borrow();
        state
            .detached_nodes
            .len()
            .saturating_sub(state.detached_kept)
    };
    if fresh >= DETACHED_NODE_GC_THRESHOLD {
        boa_gc::force_collect();
    }

    let candidates = std::mem::take(&mut ctx.state.borrow_mut().detached_nodes);
    if candidates.is_empty() {
        return;
    }

    let mut keep = Vec::new();
    let mut freed = Vec::new();

    for node_id in candidates {
        let held = {
            let state = ctx.state.borrow();
            let doc = ctx.doc.borrow();
            // Gone already, through a parent that was freed first.
            if doc.get_node(node_id).is_none() {
                continue;
            }
            let mut stack = vec![node_id];
            let mut held = false;
            while let Some(id) = stack.pop() {
                let wrapper_alive = state
                    .node_wrappers
                    .get(&id)
                    .and_then(WeakJsObject::upgrade)
                    .is_some();
                // A listener belongs to its node; it is not an external root.
                // Treating the listener table itself as reachability keeps
                // every removed interactive subtree forever, because buttons
                // necessarily have listeners. A live wrapper is the evidence
                // that script outside the node still owns it. If no wrapper
                // survives, the listeners are dropped with the node below.
                if wrapper_alive {
                    held = true;
                    break;
                }
                if let Some(node) = doc.get_node(id) {
                    stack.extend(node.children.iter().copied());
                    if let Some(contents) = node
                        .element_data()
                        .and_then(|element| element.template_contents)
                    {
                        stack.push(contents);
                    }
                    #[cfg(feature = "shadow-dom")]
                    if let Some(root_id) = node.shadow_root_id() {
                        stack.push(root_id);
                    }
                }
            }
            held
        };

        if held {
            // Still reachable. Look again after the next collection: a
            // framework often holds a row for a tick and then lets go.
            keep.push(node_id);
            continue;
        }

        ctx.mutate_doc()
            .mutate()
            .remove_and_drop_node_with(node_id, &mut |id| freed.push(id));
    }

    // The caches are keyed by id, so a freed id has to leave them: the slot can
    // be reused, and a stale entry would hand out a wrapper for a different
    // node entirely.
    let mut state = ctx.state.borrow_mut();
    state.detached_kept = keep.len();
    state.detached_nodes = keep;
    for id in freed {
        state.node_wrappers.remove(&id);
        state.dataset_wrappers.remove(&id);
        state.class_list_wrappers.remove(&id);
        state.node_listeners.remove(&id);
        state.connected_wrappers.remove(&id);
    }
}

/// Convert an optional node id to a JS value (wrapper object or `null`)
pub(crate) fn node_or_null(
    ctx: &DomCtx,
    node_id: Option<NodeId>,
    context: &mut Context,
) -> JsValue {
    match node_id {
        Some(node_id) => node_wrapper(ctx, node_id, context).into(),
        None => JsValue::null(),
    }
}

/// Construct an HTML `QualName` from a string
pub(crate) fn qual_name(local: &str) -> QualName {
    QualName::new(None, markup5ever::ns!(html), LocalName::from(local))
}

/// Construct a `QualName` in the given namespace from a string
pub(crate) fn qual_name_ns(local: &str, ns: &str) -> QualName {
    QualName::new(None, Namespace::from(ns), LocalName::from(local))
}

pub(crate) fn js_str(s: &str) -> JsValue {
    JsString::from(s).into()
}

/// Convert a JS value to a Rust `String` (via ECMAScript `ToString`)
///
/// This is the single point at which a string crosses from the JavaScript heap
/// into the host, so it is also where that traffic is counted. See
/// [`crate::script_stats::BoundaryCounters`]: the count is off unless deep
/// profiling is on, and it exists because bytes across the boundary is the
/// quantity a binding design changes, while a wall-clock number folds it
/// together with everything else the call did.
pub(crate) fn to_rust_string(value: &JsValue, context: &mut Context) -> JsResult<String> {
    let string = value.to_string(context)?.to_std_string_lossy();
    crate::script_stats::record_boundary_string(string.len());
    Ok(string)
}

type NativeFnPtr = fn(&JsValue, &[JsValue], &mut Context) -> JsResult<JsValue>;

/// Define a method on a prototype object
pub(crate) fn define_method(
    obj: &JsObject,
    name: &str,
    length: usize,
    body: NativeFnPtr,
    context: &mut Context,
) {
    let function = FunctionObjectBuilder::new(
        context.realm(),
        NativeFunction::from_copy_closure(move |this, args, context| {
            custom_elements::native_scope(this, args, context, body)
        }),
    )
    .name(JsString::from(name))
    .length(length)
    .build();
    obj.define_property_or_throw(
        PropertyKey::from(JsString::from(name)),
        PropertyDescriptor::builder()
            .value(function)
            .writable(true)
            .enumerable(false)
            .configurable(true)
            .build(),
        context,
    )
    .expect("failed to define DOM method");
}

/// Define an accessor (getter/setter pair) on a prototype object
pub(crate) fn define_accessor(
    obj: &JsObject,
    name: &str,
    getter: Option<NativeFnPtr>,
    setter: Option<NativeFnPtr>,
    context: &mut Context,
) {
    let getter = getter.map(|g| {
        FunctionObjectBuilder::new(context.realm(), NativeFunction::from_fn_ptr(g))
            .name(JsString::from(format!("get {name}")))
            .length(0)
            .build()
    });
    let setter = setter.map(|s| {
        FunctionObjectBuilder::new(
            context.realm(),
            NativeFunction::from_copy_closure(move |this, args, context| {
                custom_elements::native_scope(this, args, context, s)
            }),
        )
        .name(JsString::from(format!("set {name}")))
        .length(1)
        .build()
    });
    let mut builder = PropertyDescriptor::builder()
        .enumerable(false)
        .configurable(true);
    if let Some(getter) = getter {
        builder = builder.get(getter);
    }
    if let Some(setter) = setter {
        builder = builder.set(setter);
    }
    obj.define_property_or_throw(
        PropertyKey::from(JsString::from(name)),
        builder.build(),
        context,
    )
    .expect("failed to define DOM accessor");
}

/// Define a plain data property
pub(crate) fn define_value(obj: &JsObject, name: &str, value: JsValue, context: &mut Context) {
    if event::set_event_field(obj, name, &value) {
        return;
    }
    obj.define_property_or_throw(
        PropertyKey::from(JsString::from(name)),
        PropertyDescriptor::builder()
            .value(value)
            .writable(true)
            .enumerable(false)
            .configurable(true)
            .build(),
        context,
    )
    .expect("failed to define DOM property");
}

/// Event types for which `on<event>` IDL-style properties are defined on the
/// node prototype. Frameworks (e.g. Preact) use `'onclick' in dom` checks to
/// infer the correct casing of event names, so these need to be present.
pub(crate) const ON_EVENT_TYPES: &[&str] = &[
    "click",
    "dblclick",
    "contextmenu",
    "mousedown",
    "mouseup",
    "mousemove",
    "mouseenter",
    "mouseleave",
    "mouseover",
    "mouseout",
    "pointerdown",
    "pointerup",
    "pointermove",
    "pointercancel",
    "pointerenter",
    "pointerleave",
    "pointerover",
    "pointerout",
    "touchstart",
    "touchmove",
    "touchend",
    "touchcancel",
    "keydown",
    "keyup",
    "keypress",
    "input",
    "change",
    "focus",
    "blur",
    "focusin",
    "focusout",
    "submit",
    "scroll",
    "wheel",
    "error",
    "load",
    "slotchange",
];

/// Where an `on<event>` handler is actually stored on the instance.
pub(crate) const ON_HANDLER_PREFIX: &str = "__blitz_internal_on_";

/// Define `on<event>` as an accessor rather than as a plain `null` property.
///
/// The handler is kept on the instance under a hidden key, and assigning one
/// roots the wrapper for as long as the node is in the document. A data
/// property cannot do the second half: nothing observes the write, so the only
/// thing keeping the handler alive was the page's own reference to the element.
///
/// Every CDN loader has this shape: create a script, set `onload`, append it,
/// return, and wait on the promise the script resolves. Keeping its wrapper
/// alive preserves the callback until the script load is acknowledged.
pub(crate) fn define_on_event_accessor(
    proto: &JsObject,
    event_type: &'static str,
    context: &mut Context,
) {
    let getter = FunctionObjectBuilder::new(
        context.realm(),
        NativeFunction::from_copy_closure(move |this, _args, context| {
            inline_handlers::get(this, event_type, context)
        }),
    )
    .name(JsString::from(format!("get on{event_type}")))
    .length(0)
    .build();

    let setter = FunctionObjectBuilder::new(
        context.realm(),
        NativeFunction::from_copy_closure(move |this, args, context| {
            inline_handlers::set(this, args, event_type, context)
        }),
    )
    .name(JsString::from(format!("set on{event_type}")))
    .length(1)
    .build();

    proto
        .define_property_or_throw(
            PropertyKey::from(JsString::from(format!("on{event_type}"))),
            PropertyDescriptor::builder()
                .get(getter)
                .set(setter)
                .enumerable(false)
                .configurable(true)
                .build(),
            context,
        )
        .expect("failed to define an on<event> accessor");
}

/// Initialise the DOM prototype objects and store them in the runtime state
pub(crate) fn init_protos(ctx: &DomCtx, context: &mut Context) {
    let object_proto = context.intrinsics().constructors().object().prototype();

    let node_proto = JsObject::with_object_proto(context.intrinsics());
    node::init_node_proto(&node_proto, context);

    // `on<event>` IDL-style properties (default null)
    for event_type in ON_EVENT_TYPES {
        define_on_event_accessor(&node_proto, event_type, context);
    }

    let element_proto = JsObject::with_object_proto(context.intrinsics());
    element_proto.set_prototype(Some(node_proto.clone()));
    element::init_element_proto(&element_proto, context);

    let character_data_proto = JsObject::with_object_proto(context.intrinsics());
    character_data_proto.set_prototype(Some(node_proto.clone()));
    node::init_character_data_proto(&character_data_proto, context);

    let document_proto = JsObject::with_object_proto(context.intrinsics());
    document_proto.set_prototype(Some(node_proto.clone()));
    document::init_document_proto(&document_proto, context);

    let event_proto = JsObject::with_object_proto(context.intrinsics());
    event::init_event_proto(&event_proto, context);

    let style_proto = JsObject::with_object_proto(context.intrinsics());
    style::init_style_proto(&style_proto, context);

    let _ = object_proto;

    ctx.state.borrow_mut().protos = Some(DomProtos {
        node: node_proto,
        element: element_proto,
        character_data: character_data_proto.clone(),
        document: document_proto,
        event: event_proto.clone(),
        style: style_proto,
    });
    event::register_event_constructor(&event_proto, context);
    document::register_text_constructor(&character_data_proto, context);
    interfaces::init(context);
    doma::install(ctx, context);
    #[cfg(feature = "shadow-dom")]
    shadow::init(ctx, context);
    range::init(context);
    parsing::install(ctx, context);
    inline_handlers::install(context);
}