use blitz_dom::Document as _;
use blitz_script::ScriptDocument;
use blitz_traits::events::{
BlitzImeEvent, BlitzInputEvent, BlitzWheelDelta, BlitzWheelEvent, BlitzWheelPhase, DomEvent,
DomEventData, MouseEventButton, MouseEventButtons, Point, UiEvent,
};
use keyboard_types::{Code, Key};
use crate::document::{
activate_agent_node, control_error, debug_error, element_attr, hover_agent_node,
inspect_document, key_event, keyboard_modifiers, resolve_agent_node,
};
use crate::{
AgentAction, AgentControlRequest, DebugError, DebugResponse, InputCommand, KeyPhase,
PointerPhase, WheelPhase,
};
pub(crate) const MAX_SETTLE_POLLS: usize = 100;
#[derive(Default)]
pub struct DocumentControl {
revision: u64,
pointer: (f32, f32),
buttons: MouseEventButtons,
#[cfg(feature = "capture")]
capture: crate::document::DocumentCapture,
}
impl DocumentControl {
pub fn new() -> Self {
Self::default()
}
pub fn revision(&self) -> u64 {
self.revision
}
pub fn next_revision(&mut self) -> u64 {
self.revision += 1;
self.revision
}
pub fn pointer(&self) -> (f32, f32) {
self.pointer
}
pub fn agent(
&mut self,
document: &mut ScriptDocument,
request: AgentControlRequest,
) -> DebugResponse {
match request {
AgentControlRequest::Inspect { root, max_depth } => {
self.revision += 1;
inspect_document(document, root, max_depth, self.revision)
}
AgentControlRequest::Act(action) => match self.act(document, action) {
Ok(()) => match settle(document) {
Ok(()) => {
self.revision += 1;
DebugResponse::Ack
}
Err(error) => DebugResponse::Error(error),
},
Err(error) => DebugResponse::Error(error),
},
AgentControlRequest::Condense { level, options } => {
self.revision += 1;
match inspect_document(document, None, 0, self.revision) {
DebugResponse::AgentSnapshot(snapshot) => {
let page = crate::condense::condense(&snapshot.nodes, options);
DebugResponse::Condensation(level.select(page))
}
_ => control_error(
"unsupportedRequest",
"the document has no semantic tree to condense",
),
}
}
AgentControlRequest::ListTargets
| AgentControlRequest::Navigate { .. }
| AgentControlRequest::Relaunch
| AgentControlRequest::Quit => control_error(
"unsupportedRequest",
"navigation and process lifecycle belong to the embedder, not to the document",
),
}
}
pub fn act(
&mut self,
document: &mut ScriptDocument,
action: AgentAction,
) -> Result<(), DebugError> {
match action {
AgentAction::Focus { node_id } => {
crate::document::focus_agent_node(document, blitz_dom::NodeId::from_u64(node_id))?;
}
AgentAction::Click { node_id } => {
self.pointer = activate_agent_node(document, node_id, 1)?;
}
AgentAction::DoubleClick { node_id } => {
self.pointer = activate_agent_node(document, node_id, 2)?;
}
AgentAction::Hover { node_id } => {
self.pointer = resolve_agent_node(document, node_id)?.1;
hover_agent_node(document, node_id)?;
}
AgentAction::SetValue { node_id, value } => {
set_node_value(document, blitz_dom::NodeId::from_u64(node_id), value)?;
}
AgentAction::ScrollIntoView { node_id } => {
let node_id = blitz_dom::NodeId::from_u64(node_id);
if document.inner().get_node(node_id).is_none() {
return Err(debug_error("unknownNode", "node does not exist"));
}
let mut events = Vec::new();
document
.inner_mut()
.scroll_to_node_centered_with_events(node_id, |event| events.push(event));
for event in events {
document.dispatch_dom_event(event);
}
}
AgentAction::ScrollBy {
node_id,
delta_x,
delta_y,
} => {
let node_id = blitz_dom::NodeId::from_u64(node_id);
if document.inner().get_node(node_id).is_none() {
return Err(debug_error("unknownNode", "node does not exist"));
}
let mut events = Vec::new();
document
.inner_mut()
.scroll_nearest_container_by_with_events(node_id, delta_x, delta_y, |event| {
events.push(event)
});
for event in events {
document.dispatch_dom_event(event);
}
}
AgentAction::Input(input) => self.input(document, input)?,
}
Ok(())
}
fn input(
&mut self,
document: &mut ScriptDocument,
input: InputCommand,
) -> Result<(), DebugError> {
match input {
InputCommand::Key {
phase,
key,
code,
modifiers,
} => {
let parsed_key = key.parse::<Key>().unwrap_or(Key::Character(key));
let parsed_code = code.parse::<Code>().unwrap_or(Code::Unidentified);
let event = key_event(
phase,
parsed_key,
parsed_code,
keyboard_modifiers(modifiers),
);
document.handle_ui_event(match phase {
KeyPhase::Down => UiEvent::KeyDown(event),
KeyPhase::Up => UiEvent::KeyUp(event),
});
}
InputCommand::Pointer {
phase,
x,
y,
button,
modifiers,
} => {
let button = mouse_button(button)?;
self.pointer = (x as f32, y as f32);
match phase {
PointerPhase::Down => self.buttons.insert(button.into()),
PointerPhase::Up | PointerPhase::Cancel => self.buttons.remove(button.into()),
PointerPhase::Move => {}
}
let event = crate::document::pointer_event_for_document(
document,
self.pointer,
button,
self.buttons,
keyboard_modifiers(modifiers),
);
document.handle_ui_event(match phase {
PointerPhase::Move => UiEvent::PointerMove(event),
PointerPhase::Down => UiEvent::PointerDown(event),
PointerPhase::Up => UiEvent::PointerUp(event),
PointerPhase::Cancel => UiEvent::PointerCancel(event),
});
}
InputCommand::Wheel {
delta_x,
delta_y,
phase,
modifiers,
} => {
let event = BlitzWheelEvent {
delta: BlitzWheelDelta::Pixels(delta_x, delta_y),
phase: match phase {
WheelPhase::Started => BlitzWheelPhase::Started,
WheelPhase::Moved => BlitzWheelPhase::Moved,
WheelPhase::Ended => BlitzWheelPhase::Ended,
},
coords: crate::document::pointer_coords_for_document(document, self.pointer),
buttons: self.buttons,
mods: keyboard_modifiers(modifiers),
element: Point::default(),
};
document
.inner_mut()
.set_hover_to(self.pointer.0, self.pointer.1);
document.handle_ui_event(UiEvent::Wheel(event));
}
}
Ok(())
}
#[cfg(feature = "capture")]
pub fn capture(
&mut self,
document: &mut ScriptDocument,
request: crate::CaptureRequest,
) -> Result<crate::CapturedImage, DebugError> {
request.validate().map_err(|why| DebugError {
code: "invalidArgument".into(),
message: why.into(),
})?;
self.capture.capture(document, request)
}
}
pub fn settle(document: &mut ScriptDocument) -> Result<(), DebugError> {
for _ in 0..MAX_SETTLE_POLLS {
if !document.poll(None) {
document.inner_mut().resolve(0.0);
return Ok(());
}
}
document.inner_mut().resolve(0.0);
Err(debug_error(
"actionDidNotSettle",
"the action kept synchronous script work runnable past the settlement budget",
))
}
pub(crate) fn set_node_value(
document: &mut ScriptDocument,
node_id: blitz_dom::NodeId,
value: String,
) -> Result<(), DebugError> {
let current = document
.inner()
.get_node(node_id)
.and_then(|node| node.element_data())
.and_then(|element| element.text_input_data())
.map(|input| input.editor.text().to_string());
let Some(current) = current else {
let is_select = document
.inner()
.get_node(node_id)
.and_then(|node| node.element_data())
.is_some_and(|element| element.name.local.as_ref() == "select");
if is_select {
let index = {
let doc = document.inner();
let options = doc.select_options(node_id);
options
.iter()
.position(|option| doc.option_value(*option) == value)
.or_else(|| {
options
.iter()
.position(|option| doc.option_label(*option).trim() == value.trim())
})
};
let Some(index) = index else {
return Err(debug_error(
"noSuchOption",
"the select has no option with that value",
));
};
document.inner_mut().set_focus_to(node_id);
let changed = document
.inner_mut()
.set_select_selected_index(node_id, index);
if changed {
document.inner_mut().snapshot_node(node_id);
let value = document.inner().select_value(node_id);
document.dispatch_dom_event(DomEvent::new(
node_id,
DomEventData::Input(BlitzInputEvent { value }),
));
}
return Ok(());
}
let is_value_input = document
.inner()
.get_node(node_id)
.and_then(|node| node.element_data())
.is_some_and(|element| {
element.name.local.as_ref() == "input"
&& matches!(
element_attr(element, "type").unwrap_or("text"),
"date" | "datetime-local" | "month" | "time" | "week" | "color"
)
});
if !is_value_input {
return Err(debug_error("notEditable", "node is not a text input"));
}
document.inner_mut().set_focus_to(node_id);
document.inner_mut().mutate().set_attribute(
node_id,
blitz_dom::qual_name!("value"),
&value,
);
document.dispatch_dom_event(DomEvent::new(
node_id,
DomEventData::Input(BlitzInputEvent { value }),
));
return Ok(());
};
document.inner_mut().set_focus_to(node_id);
if let Some(len) = std::num::NonZeroUsize::new(current.len()) {
document.inner_mut().with_text_input(node_id, |mut editor| {
editor.delete_bytes_before_selection(len);
editor.delete_bytes_after_selection(len);
});
}
document.handle_ui_event(UiEvent::Ime(BlitzImeEvent::Commit(value)));
Ok(())
}
fn mouse_button(button: u16) -> Result<MouseEventButton, DebugError> {
match button {
0 => Ok(MouseEventButton::Main),
1 => Ok(MouseEventButton::Auxiliary),
2 => Ok(MouseEventButton::Secondary),
3 => Ok(MouseEventButton::Fourth),
4 => Ok(MouseEventButton::Fifth),
_ => Err(debug_error(
"unsupportedButton",
"pointer button must be 0 through 4",
)),
}
}
#[cfg(test)]
mod tests {
use blitz_dom::DocumentConfig;
use super::*;
use crate::{AgentSnapshot, Modifiers};
fn document() -> ScriptDocument {
let mut document = ScriptDocument::from_html(
r#"<style>
#scroller { height: 40px; overflow: auto; }
#tall { height: 400px; }
</style>
<button id="press">Press me</button>
<input id="field" value="before">
<input id="date" type="date" value="2025-01-01">
<div id="scroller"><div id="tall">tall</div></div>
<output id="log"></output>
<output id="date-log"></output>
<script>
document.getElementById('press').addEventListener('click', () => {
document.getElementById('log').textContent = 'pressed';
});
document.getElementById('date').addEventListener('input', event => {
document.getElementById('date-log').textContent = event.target.value;
});
</script>"#,
DocumentConfig::default(),
);
document
.inner_mut()
.set_viewport(blitz_traits::shell::Viewport::new(
800,
600,
1.0,
blitz_traits::shell::ColorScheme::Light,
));
document.inner_mut().resolve(0.0);
settle(&mut document).expect("the fixture settles");
document
}
fn node(control: &mut DocumentControl, document: &mut ScriptDocument, dom_id: &str) -> u64 {
let DebugResponse::AgentSnapshot(AgentSnapshot { nodes, .. }) = control.agent(
document,
AgentControlRequest::Inspect {
root: None,
max_depth: 0,
},
) else {
panic!("inspection did not answer with a tree")
};
nodes
.iter()
.find(|node| node.dom_id.as_deref() == Some(dom_id))
.unwrap_or_else(|| panic!("the fixture has no #{dom_id}"))
.id
}
fn text(document: &ScriptDocument, selector: &str) -> String {
let id = document
.inner()
.query_selector(selector)
.unwrap()
.unwrap_or_else(|| panic!("the fixture has no {selector}"));
document.inner().get_node(id).unwrap().text_content()
}
#[test]
fn an_embedder_drives_a_document_with_no_socket() {
let mut document = document();
let mut control = DocumentControl::new();
let press = node(&mut control, &mut document, "press");
let response = control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::Click { node_id: press }),
);
assert_eq!(response, DebugResponse::Ack);
assert_eq!(text(&document, "#log"), "pressed");
}
#[test]
fn a_revision_advances_with_every_answer() {
let mut document = document();
let mut control = DocumentControl::new();
let before = control.revision();
let press = node(&mut control, &mut document, "press");
control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::Click { node_id: press }),
);
assert!(
control.revision() > before,
"a client watching the revision must see that something happened"
);
}
#[test]
fn setting_a_value_replaces_what_was_there_with_no_fonts_installed() {
let mut document = document();
let mut control = DocumentControl::new();
let field = node(&mut control, &mut document, "field");
assert_eq!(
control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::SetValue {
node_id: field,
value: "after".into(),
}),
),
DebugResponse::Ack
);
let value = document
.inner()
.get_node(blitz_dom::NodeId::from_u64(field))
.and_then(|node| node.element_data())
.and_then(|element| element.text_input_data())
.map(|input| input.editor.text().to_string())
.expect("the field is a text input");
assert_eq!(
value, "after",
"the old contents were appended to rather than replaced"
);
}
#[test]
fn setting_a_date_value_updates_the_dom_and_dispatches_input() {
let mut document = document();
let mut control = DocumentControl::new();
let date = node(&mut control, &mut document, "date");
assert_eq!(
control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::SetValue {
node_id: date,
value: "2025-06-24".into(),
}),
),
DebugResponse::Ack
);
let value = document
.inner()
.get_node(blitz_dom::NodeId::from_u64(date))
.and_then(|node| node.element_data())
.and_then(|element| element_attr(element, "value").map(str::to_owned));
assert_eq!(value.as_deref(), Some("2025-06-24"));
assert_eq!(text(&document, "#date-log"), "2025-06-24");
}
#[test]
fn focus_moves_the_focused_node_without_activating_it() {
let mut document = document();
let mut control = DocumentControl::new();
let field = node(&mut control, &mut document, "field");
assert_eq!(
control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::Focus { node_id: field }),
),
DebugResponse::Ack
);
let DebugResponse::AgentSnapshot(snapshot) = control.agent(
&mut document,
AgentControlRequest::Inspect {
root: None,
max_depth: 0,
},
) else {
panic!("inspection did not answer with a tree")
};
assert_eq!(snapshot.focused_node, Some(field));
assert_eq!(
text(&document, "#log"),
"",
"focusing a control must not activate it"
);
}
#[test]
fn the_process_lifecycle_is_refused_rather_than_acknowledged() {
let mut document = document();
let mut control = DocumentControl::new();
for request in [
AgentControlRequest::Navigate {
url: "https://example.com/".into(),
},
AgentControlRequest::Relaunch,
AgentControlRequest::Quit,
] {
let DebugResponse::Error(error) = control.agent(&mut document, request) else {
panic!("a document cannot restart its own process or fetch a URL")
};
assert_eq!(error.code, "unsupportedRequest");
}
}
#[test]
fn an_unknown_node_is_an_error_and_not_a_panic() {
let mut document = document();
let mut control = DocumentControl::new();
let DebugResponse::Error(error) = control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::ScrollIntoView {
node_id: u64::MAX - 1,
}),
) else {
panic!("a node that is not there cannot be scrolled to")
};
assert_eq!(error.code, "unknownNode");
}
#[test]
fn a_pointer_button_outside_the_range_is_refused() {
let mut document = document();
let mut control = DocumentControl::new();
let DebugResponse::Error(error) = control.agent(
&mut document,
AgentControlRequest::Act(AgentAction::Input(InputCommand::Pointer {
phase: PointerPhase::Down,
x: 1.0,
y: 1.0,
button: 9,
modifiers: Modifiers::default(),
})),
) else {
panic!("button 9 does not exist")
};
assert_eq!(error.code, "unsupportedButton");
}
}