#[cfg(feature = "client")]
pub mod client;
pub mod condense;
#[cfg(feature = "engine")]
pub mod document;
#[cfg(feature = "engine")]
pub mod in_process;
#[cfg(any(feature = "server", feature = "client"))]
pub mod latest;
pub mod lifecycle;
pub mod webgpu;
pub use webgpu::*;
#[cfg(all(feature = "server", unix))]
pub mod server;
use endpoint_libs::libs::ws::mcp_wire::{INVALID_PARAMS, INVALID_REQUEST, parse};
pub use endpoint_libs::libs::ws::{
MessageStream, WireMessage,
mcp_wire::{
JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcRequest, JsonRpcResponse,
MCP_PROTOCOL_VERSION,
},
transport::{FramedError, Transport, TransportStream, framed_json_neutral},
};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
pub const DEBUG_PROTOCOL_VERSION: u32 = 1;
pub const MAX_DEBUG_FRAME_BYTES: usize = 16 * 1024 * 1024;
pub const MCP_INITIALIZE: &str = "initialize";
pub const MCP_INITIALIZED_NOTIFICATION: &str = "notifications/initialized";
pub const MCP_TOOLS_LIST: &str = "tools/list";
pub const MCP_TOOLS_CALL: &str = "tools/call";
pub const AGENT_CONTROL_TOOL: &str = "blitz.agent.control";
pub const AGENT_EVENT_NOTIFICATION: &str = "notifications/blitz/agent";
pub const DIAGNOSTICS_TOOL: &str = "blitz.diagnostics";
pub const DIAGNOSTICS_EVENT_NOTIFICATION: &str = "notifications/blitz/diagnostics";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct DebugDescriptor {
pub protocol_version: u32,
pub pid: u32,
pub instance_id: String,
pub address: String,
pub renderer: String,
pub renderer_revision: String,
}
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum IncomingRequest {
Initialize {
id: JsonRpcId,
},
Initialized,
ToolsList {
id: JsonRpcId,
},
Agent {
id: JsonRpcId,
request: AgentControlRequest,
},
Diagnostics {
id: JsonRpcId,
request: DiagnosticsRequest,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "command", content = "params", rename_all = "camelCase")]
#[non_exhaustive]
pub enum AgentControlRequest {
Inspect {
root: Option<u64>,
max_depth: u32,
},
Act(AgentAction),
Navigate {
url: String,
},
Condense {
#[serde(default)]
level: condense::Level,
#[serde(default)]
options: condense::CondenseOptions,
},
Relaunch,
Quit,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "command", content = "params", rename_all = "camelCase")]
#[non_exhaustive]
pub enum DiagnosticsRequest {
Observe {
streams: Vec<DebugStream>,
},
Snapshot(SnapshotRequest),
Metrics,
WaitForIdle,
WindowComposition,
Capture(CaptureRequest),
WebGpuInspect,
WebGpuCapture {
target: String,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct CaptureRequest {
pub node_id: Option<u64>,
pub scale: f32,
}
impl Default for CaptureRequest {
fn default() -> Self {
Self {
node_id: None,
scale: 1.0,
}
}
}
impl CaptureRequest {
pub fn validate(&self) -> Result<(), &'static str> {
if !self.scale.is_finite() || !(0.25..=8.0).contains(&self.scale) {
return Err("capture scale must be finite and between 0.25 and 8");
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct CapturedImage {
pub width: u32,
pub height: u32,
pub rgba_base64: String,
pub node_id: Option<u64>,
}
#[cfg(feature = "capture")]
impl CapturedImage {
pub fn from_rgba(width: u32, height: u32, rgba: &[u8]) -> Result<Self, DebugError> {
let expected = u64::from(width)
.saturating_mul(u64::from(height))
.saturating_mul(4);
if width == 0 || height == 0 || expected != rgba.len() as u64 {
return Err(DebugError {
code: "invalidArgument".to_owned(),
message: format!(
"RGBA8 capture is {width}x{height} but holds {} bytes",
rgba.len()
),
});
}
const FRAME_ENVELOPE_RESERVE: usize = 64 * 1024;
const MAX_BASE64_BYTES: usize = MAX_DEBUG_FRAME_BYTES - FRAME_ENVELOPE_RESERVE;
const MAX_RAW_BYTES: usize = (MAX_BASE64_BYTES / 4) * 3;
if rgba.len() > MAX_RAW_BYTES {
return Err(DebugError {
code: "captureTooLarge".to_owned(),
message: format!(
"{width}x{height} cannot fit in one diagnostic frame; capture a smaller texture"
),
});
}
Ok(Self {
width,
height,
rgba_base64: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, rgba),
node_id: None,
})
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "result", content = "value", rename_all = "camelCase")]
#[allow(clippy::large_enum_variant)] #[non_exhaustive]
pub enum DebugResponse {
Ack,
AgentSnapshot(AgentSnapshot),
Snapshot(DebugSnapshot),
Metrics(RendererMetrics),
Idle(RevisionSet),
WindowComposition(WindowComposition),
Captured(CapturedImage),
WebGpu(WebGpuReport),
Condensation(condense::Condensation),
Error(DebugError),
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct WindowComposition {
pub supported: bool,
pub surface_transparent: bool,
pub glass_enabled: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub glass_backend: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tint_rgba: Option<[u8; 4]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub radius: Option<f64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "event", content = "value", rename_all = "camelCase")]
#[allow(clippy::large_enum_variant)] #[non_exhaustive]
pub enum DebugEvent {
Snapshot(DebugSnapshot),
Metrics(RendererMetrics),
Console(ConsoleEntry),
RuntimeError(RuntimeErrorEntry),
PaintCommitted {
revision: u64,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "event", content = "value", rename_all = "camelCase")]
#[non_exhaustive]
pub enum AgentControlEvent {
Ready(DebugDescriptor),
TreeChanged { revision: u64 },
Lifecycle(LifecycleEvent),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum DebugStream {
Snapshots,
Metrics,
Console,
RuntimeErrors,
Paint,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotRequest {
pub include_dom: bool,
pub include_layout: bool,
pub include_computed_style: bool,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub node_ids: Vec<u64>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(from = "[f64; 4]", into = "[f64; 4]")]
pub struct LayoutBounds {
pub x: f64,
pub y: f64,
pub width: f64,
pub height: f64,
}
impl From<[f64; 4]> for LayoutBounds {
fn from([x, y, width, height]: [f64; 4]) -> Self {
Self {
x,
y,
width,
height,
}
}
}
impl From<LayoutBounds> for [f64; 4] {
fn from(bounds: LayoutBounds) -> Self {
[bounds.x, bounds.y, bounds.width, bounds.height]
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(from = "[f64; 2]", into = "[f64; 2]")]
pub struct LayoutSize {
pub width: f64,
pub height: f64,
}
impl From<[f64; 2]> for LayoutSize {
fn from([width, height]: [f64; 2]) -> Self {
Self { width, height }
}
}
impl From<LayoutSize> for [f64; 2] {
fn from(size: LayoutSize) -> Self {
[size.width, size.height]
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(from = "[f64; 2]", into = "[f64; 2]")]
pub struct LayoutOffset {
pub x: f64,
pub y: f64,
}
impl From<[f64; 2]> for LayoutOffset {
fn from([x, y]: [f64; 2]) -> Self {
Self { x, y }
}
}
impl From<LayoutOffset> for [f64; 2] {
fn from(offset: LayoutOffset) -> Self {
[offset.x, offset.y]
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(from = "[f64; 4]", into = "[f64; 4]")]
pub struct LayoutEdges {
pub top: f64,
pub right: f64,
pub bottom: f64,
pub left: f64,
}
impl From<[f64; 4]> for LayoutEdges {
fn from([top, right, bottom, left]: [f64; 4]) -> Self {
Self {
top,
right,
bottom,
left,
}
}
}
impl From<LayoutEdges> for [f64; 4] {
fn from(edges: LayoutEdges) -> Self {
[edges.top, edges.right, edges.bottom, edges.left]
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct LayoutDiagnosticRow {
pub node_id: u64,
pub bounds: LayoutBounds,
pub scroll_offset: LayoutOffset,
pub client_size: LayoutSize,
pub scroll_size: LayoutSize,
pub scroll_range: LayoutSize,
pub border: LayoutEdges,
pub padding: LayoutEdges,
pub content_size: LayoutSize,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "action", content = "params", rename_all = "camelCase")]
#[non_exhaustive]
pub enum AgentAction {
Focus {
node_id: u64,
},
Click {
node_id: u64,
},
DoubleClick {
node_id: u64,
},
Hover {
node_id: u64,
},
SetValue {
node_id: u64,
value: String,
},
ScrollIntoView {
node_id: u64,
},
ScrollBy {
node_id: u64,
delta_x: f64,
delta_y: f64,
},
Input(InputCommand),
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "input", rename_all = "camelCase")]
#[non_exhaustive]
pub enum InputCommand {
Key {
phase: KeyPhase,
key: String,
code: String,
modifiers: Modifiers,
},
Pointer {
phase: PointerPhase,
x: f64,
y: f64,
button: u16,
modifiers: Modifiers,
},
Wheel {
delta_x: f64,
delta_y: f64,
phase: WheelPhase,
modifiers: Modifiers,
},
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct Modifiers {
pub shift: bool,
pub control: bool,
pub alt: bool,
pub meta: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum KeyPhase {
Down,
Up,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum PointerPhase {
Move,
Down,
Up,
Cancel,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum WheelPhase {
Started,
Moved,
Ended,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RevisionSet {
pub document: u64,
pub style: u64,
pub layout: u64,
pub paint: u64,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct DebugSnapshot {
pub revisions: RevisionSet,
pub active_window: Option<String>,
pub active_element: Option<u64>,
pub dom: Option<serde_json::Value>,
pub layout: Option<Vec<LayoutDiagnosticRow>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub computed_style: Option<serde_json::Value>,
pub metrics: RendererMetrics,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct AgentSnapshot {
pub revision: u64,
pub active_window: Option<String>,
pub focused_node: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub viewport: Option<[f64; 4]>,
pub nodes: Vec<SemanticNode>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct SemanticNode {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub dom_id: Option<String>,
pub id: u64,
pub parent: Option<u64>,
pub role: String,
pub name: String,
pub value: Option<String>,
pub enabled: bool,
#[serde(default)]
pub focusable: bool,
#[serde(default)]
pub viewport_fixed: bool,
pub visible: bool,
pub selected: bool,
pub bounds: Option<[f64; 4]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub slot: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RendererMetrics {
pub revisions: RevisionSet,
pub queue_depth: Option<u64>,
pub invalidations_coalesced: u64,
pub frame: Option<FrameMetrics>,
pub frame_window: Option<FrameWindowMetrics>,
pub snapshot: Option<SnapshotCost>,
pub script: Option<ScriptMetrics>,
pub resident_bytes: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ScriptMetrics {
pub mean_ms: f64,
pub p95_ms: f64,
pub max_ms: f64,
pub window_polls: u64,
pub total_polls: u64,
pub productive_polls: u64,
pub spent_ms: f64,
pub breakdown: Vec<ScriptSource>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ScriptSource {
pub label: String,
pub calls: u64,
pub total_ms: f64,
pub worst_ms: f64,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct FrameMetrics {
pub input_to_present_ms: Option<f64>,
pub style_ms: Option<f64>,
pub layout_ms: Option<f64>,
pub resolve_ms: f64,
pub scene_ms: f64,
pub submit_ms: Option<f64>,
pub present_ms: Option<f64>,
pub renderer_ms: f64,
pub total_ms: f64,
pub age_ms: f64,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct TimingStats {
pub mean_ms: f64,
pub p95_ms: f64,
pub max_ms: f64,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct FrameWindowMetrics {
pub frames_total: u64,
pub window_frames: u64,
pub resolve: TimingStats,
pub scene: TimingStats,
pub renderer: TimingStats,
pub total: TimingStats,
pub interval: TimingStats,
pub active_fps: f64,
pub missed_refreshes: u64,
pub display_refresh_hz: Option<f64>,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotCost {
pub poll_ms: f64,
pub resolve_ms: f64,
pub total_ms: f64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ConsoleEntry {
pub sequence: u64,
pub level: String,
pub message: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeErrorEntry {
pub sequence: u64,
pub message: String,
pub stack: String,
pub revisions: RevisionSet,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "state", rename_all = "camelCase")]
#[non_exhaustive]
pub enum LifecycleEvent {
Relaunching { replacement_instance_id: String },
Ready { instance_id: String },
Quitting,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct DebugError {
pub code: String,
pub message: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
struct ToolCallParams {
name: String,
arguments: serde_json::Value,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
struct ToolCallResult {
content: Vec<TextContent>,
structured_content: serde_json::Value,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
is_error: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
struct TextContent {
#[serde(rename = "type")]
content_type: String,
text: String,
}
#[derive(Debug)]
#[non_exhaustive]
pub enum DebugProtocolError {
Json(serde_json::Error),
Rpc(JsonRpcError),
NonTextFrame,
RequestIdRequired,
UnexpectedMessage,
UnexpectedMethod(String),
UnexpectedTool(String),
PayloadTooLarge(usize),
}
impl std::fmt::Display for DebugProtocolError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Json(error) => write!(formatter, "invalid debug frame: {error}"),
Self::Rpc(error) => write!(
formatter,
"JSON-RPC error {}: {}",
error.code, error.message
),
Self::NonTextFrame => formatter.write_str("debug protocol requires a text frame"),
Self::RequestIdRequired => formatter.write_str("tools/call requires a request id"),
Self::UnexpectedMessage => formatter.write_str("unexpected JSON-RPC message"),
Self::UnexpectedMethod(method) => write!(formatter, "unexpected method {method}"),
Self::UnexpectedTool(tool) => write!(formatter, "unexpected tool {tool}"),
Self::PayloadTooLarge(bytes) => write!(
formatter,
"debug response is {bytes} bytes, exceeding the {MAX_DEBUG_FRAME_BYTES}-byte frame limit"
),
}
}
}
impl std::error::Error for DebugProtocolError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Json(error) => Some(error),
_ => None,
}
}
}
impl From<serde_json::Error> for DebugProtocolError {
fn from(error: serde_json::Error) -> Self {
Self::Json(error)
}
}
pub fn encode_agent_request(
id: JsonRpcId,
request: &AgentControlRequest,
) -> Result<WireMessage, DebugProtocolError> {
encode_tool_request(id, AGENT_CONTROL_TOOL, request)
}
pub fn decode_incoming(message: WireMessage) -> Result<IncomingRequest, DebugProtocolError> {
decode_incoming_value(decode_wire_value(message)?)
}
pub fn decode_incoming_value(
value: serde_json::Value,
) -> Result<IncomingRequest, DebugProtocolError> {
let JsonRpcMessage::Request(request) = decode_rpc_value(value)? else {
return Err(DebugProtocolError::UnexpectedMessage);
};
match request.method.as_str() {
MCP_INITIALIZE => Ok(IncomingRequest::Initialize {
id: request.id.ok_or(DebugProtocolError::RequestIdRequired)?,
}),
MCP_INITIALIZED_NOTIFICATION if request.is_notification() => {
Ok(IncomingRequest::Initialized)
}
MCP_TOOLS_LIST => Ok(IncomingRequest::ToolsList {
id: request.id.ok_or(DebugProtocolError::RequestIdRequired)?,
}),
MCP_TOOLS_CALL => decode_incoming_tool_call(request),
_ => Err(DebugProtocolError::UnexpectedMethod(request.method)),
}
}
pub fn encode_initialize_response(
id: JsonRpcId,
server_name: &str,
server_version: &str,
) -> Result<WireMessage, DebugProtocolError> {
encode_rpc(JsonRpcMessage::Response(JsonRpcResponse::result(
Some(id),
serde_json::json!({
"protocolVersion": MCP_PROTOCOL_VERSION,
"capabilities": {"tools": {"listChanged": false}},
"serverInfo": {"name": server_name, "version": server_version}
}),
)))
}
pub fn encode_tools_list_response(
id: JsonRpcId,
include_diagnostics: bool,
) -> Result<WireMessage, DebugProtocolError> {
let mut tools = vec![serde_json::json!({
"name": AGENT_CONTROL_TOOL,
"description": "Inspect and operate the native Blitz semantic UI tree",
"inputSchema": schema_for::<AgentControlRequest>()?
})];
if include_diagnostics {
tools.push(serde_json::json!({
"name": DIAGNOSTICS_TOOL,
"description": "Observe Blitz DOM, layout, errors, and renderer metrics",
"inputSchema": schema_for::<DiagnosticsRequest>()?
}));
}
encode_rpc(JsonRpcMessage::Response(JsonRpcResponse::result(
Some(id),
serde_json::json!({"tools": tools}),
)))
}
fn schema_for<T: JsonSchema>() -> Result<serde_json::Value, DebugProtocolError> {
serde_json::to_value(schemars::schema_for!(T)).map_err(DebugProtocolError::from)
}
pub fn encode_rpc_error(
id: Option<JsonRpcId>,
error: JsonRpcError,
) -> Result<WireMessage, DebugProtocolError> {
encode_rpc(JsonRpcMessage::Response(JsonRpcResponse::error(id, error)))
}
pub fn decode_agent_request(
message: WireMessage,
) -> Result<(JsonRpcId, AgentControlRequest), DebugProtocolError> {
decode_tool_request(message, AGENT_CONTROL_TOOL)
}
pub fn encode_diagnostics_request(
id: JsonRpcId,
request: &DiagnosticsRequest,
) -> Result<WireMessage, DebugProtocolError> {
encode_tool_request(id, DIAGNOSTICS_TOOL, request)
}
pub fn decode_diagnostics_request(
message: WireMessage,
) -> Result<(JsonRpcId, DiagnosticsRequest), DebugProtocolError> {
decode_tool_request(message, DIAGNOSTICS_TOOL)
}
pub fn encode_response(
id: JsonRpcId,
response: &DebugResponse,
) -> Result<WireMessage, DebugProtocolError> {
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct BorrowedToolCallResult<'a> {
content: [TextContent; 1],
structured_content: &'a DebugResponse,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
is_error: bool,
}
#[derive(Serialize)]
struct RpcResponse<'a> {
jsonrpc: &'static str,
id: JsonRpcId,
result: BorrowedToolCallResult<'a>,
}
let message = WireMessage::text(serde_json::to_string(&RpcResponse {
jsonrpc: "2.0",
id,
result: BorrowedToolCallResult {
content: [TextContent {
content_type: "text".into(),
text: response_summary(response),
}],
structured_content: response,
is_error: matches!(response, DebugResponse::Error(_)),
},
})?);
if matches!(&message, WireMessage::Text(text) if text.len() > MAX_DEBUG_FRAME_BYTES) {
let WireMessage::Text(text) = &message else {
unreachable!("text encoding checked above")
};
return Err(DebugProtocolError::PayloadTooLarge(text.len()));
}
Ok(message)
}
fn response_summary(response: &DebugResponse) -> String {
match response {
DebugResponse::Ack => "ok".into(),
DebugResponse::AgentSnapshot(snapshot) => {
format!("semantic snapshot with {} nodes", snapshot.nodes.len())
}
DebugResponse::Snapshot(_) => "diagnostic snapshot".into(),
DebugResponse::Metrics(_) => "renderer metrics".into(),
DebugResponse::Idle(_) => "renderer idle".into(),
DebugResponse::WindowComposition(_) => "native window composition".into(),
DebugResponse::Captured(image) => {
format!("captured {}x{} image", image.width, image.height)
}
DebugResponse::Condensation(condensation) => {
format!("condensed page, {} level", condensation.level_name())
}
DebugResponse::WebGpu(_) => "WebGPU report".into(),
DebugResponse::Error(error) => error.message.clone(),
}
}
pub fn decode_response(
message: WireMessage,
) -> Result<(JsonRpcId, DebugResponse), DebugProtocolError> {
decode_response_value(decode_wire_value(message)?)
}
pub fn decode_response_value(
value: serde_json::Value,
) -> Result<(JsonRpcId, DebugResponse), DebugProtocolError> {
let JsonRpcMessage::Response(response) = decode_rpc_value(value)? else {
return Err(DebugProtocolError::UnexpectedMessage);
};
let id = response.id.ok_or(DebugProtocolError::RequestIdRequired)?;
if let Some(error) = response.error {
return Err(DebugProtocolError::Rpc(error));
}
let result: ToolCallResult = serde_json::from_value(
response
.result
.ok_or(DebugProtocolError::UnexpectedMessage)?,
)?;
Ok((id, serde_json::from_value(result.structured_content)?))
}
pub fn encode_agent_event(event: &AgentControlEvent) -> Result<WireMessage, DebugProtocolError> {
encode_notification(AGENT_EVENT_NOTIFICATION, event)
}
pub fn decode_agent_event(message: WireMessage) -> Result<AgentControlEvent, DebugProtocolError> {
decode_notification(message, AGENT_EVENT_NOTIFICATION)
}
pub fn encode_diagnostics_event(event: &DebugEvent) -> Result<WireMessage, DebugProtocolError> {
encode_notification(DIAGNOSTICS_EVENT_NOTIFICATION, event)
}
pub fn decode_diagnostics_event(message: WireMessage) -> Result<DebugEvent, DebugProtocolError> {
decode_notification(message, DIAGNOSTICS_EVENT_NOTIFICATION)
}
pub fn decode_diagnostics_event_value(
value: serde_json::Value,
) -> Result<DebugEvent, DebugProtocolError> {
decode_notification_value(value, DIAGNOSTICS_EVENT_NOTIFICATION)
}
fn encode_tool_request<T: Serialize>(
id: JsonRpcId,
tool: &str,
request: &T,
) -> Result<WireMessage, DebugProtocolError> {
let params = ToolCallParams {
name: tool.into(),
arguments: serde_json::to_value(request)?,
};
encode_rpc(JsonRpcMessage::Request(JsonRpcRequest::call(
id,
MCP_TOOLS_CALL,
serde_json::to_value(params)?,
)))
}
fn decode_tool_request<T: DeserializeOwned>(
message: WireMessage,
expected_tool: &str,
) -> Result<(JsonRpcId, T), DebugProtocolError> {
let JsonRpcMessage::Request(request) = decode_rpc(message)? else {
return Err(DebugProtocolError::UnexpectedMessage);
};
if request.method != MCP_TOOLS_CALL {
return Err(DebugProtocolError::UnexpectedMethod(request.method));
}
let id = request.id.ok_or(DebugProtocolError::RequestIdRequired)?;
let params: ToolCallParams = serde_json::from_value(request.params.ok_or_else(|| {
DebugProtocolError::Rpc(JsonRpcError::new(
INVALID_PARAMS,
"missing tools/call params",
))
})?)?;
if params.name != expected_tool {
return Err(DebugProtocolError::UnexpectedTool(params.name));
}
Ok((id, serde_json::from_value(params.arguments)?))
}
fn decode_incoming_tool_call(
request: JsonRpcRequest,
) -> Result<IncomingRequest, DebugProtocolError> {
let id = request.id.ok_or(DebugProtocolError::RequestIdRequired)?;
let params: ToolCallParams = serde_json::from_value(request.params.ok_or_else(|| {
DebugProtocolError::Rpc(JsonRpcError::new(
INVALID_PARAMS,
"missing tools/call params",
))
})?)?;
match params.name.as_str() {
AGENT_CONTROL_TOOL => Ok(IncomingRequest::Agent {
id,
request: serde_json::from_value(params.arguments)?,
}),
DIAGNOSTICS_TOOL => Ok(IncomingRequest::Diagnostics {
id,
request: serde_json::from_value(params.arguments)?,
}),
_ => Err(DebugProtocolError::UnexpectedTool(params.name)),
}
}
fn encode_notification<T: Serialize>(
method: &str,
value: &T,
) -> Result<WireMessage, DebugProtocolError> {
encode_rpc(JsonRpcMessage::Request(JsonRpcRequest::notification(
method,
serde_json::to_value(value)?,
)))
}
fn decode_notification<T: DeserializeOwned>(
message: WireMessage,
expected_method: &str,
) -> Result<T, DebugProtocolError> {
decode_notification_value(decode_wire_value(message)?, expected_method)
}
fn decode_notification_value<T: DeserializeOwned>(
value: serde_json::Value,
expected_method: &str,
) -> Result<T, DebugProtocolError> {
let JsonRpcMessage::Request(request) = decode_rpc_value(value)? else {
return Err(DebugProtocolError::UnexpectedMessage);
};
if !request.is_notification() {
return Err(DebugProtocolError::Rpc(JsonRpcError::new(
INVALID_REQUEST,
"notification must not contain an id",
)));
}
if request.method != expected_method {
return Err(DebugProtocolError::UnexpectedMethod(request.method));
}
serde_json::from_value(request.params.ok_or_else(|| {
DebugProtocolError::Rpc(JsonRpcError::new(
INVALID_PARAMS,
"missing notification params",
))
})?)
.map_err(Into::into)
}
pub fn encode_rpc(message: JsonRpcMessage) -> Result<WireMessage, DebugProtocolError> {
Ok(WireMessage::text(serde_json::to_string(&message)?))
}
pub fn peek_request_id(message: &WireMessage) -> Option<JsonRpcId> {
let WireMessage::Text(text) = message else {
return None;
};
match parse(text) {
Ok(JsonRpcMessage::Request(request)) => request.id,
_ => None,
}
}
pub fn peek_value_request_id(value: &serde_json::Value) -> Option<JsonRpcId> {
serde_json::from_value(value.get("id")?.clone()).ok()
}
pub fn decode_wire_value(message: WireMessage) -> Result<serde_json::Value, DebugProtocolError> {
let WireMessage::Text(text) = message else {
return Err(DebugProtocolError::NonTextFrame);
};
serde_json::from_str(&text).map_err(Into::into)
}
pub fn decode_rpc_value(value: serde_json::Value) -> Result<JsonRpcMessage, DebugProtocolError> {
serde_json::from_value(value).map_err(Into::into)
}
pub fn decode_rpc(message: WireMessage) -> Result<JsonRpcMessage, DebugProtocolError> {
let WireMessage::Text(text) = message else {
return Err(DebugProtocolError::NonTextFrame);
};
parse(&text).map_err(DebugProtocolError::Rpc)
}
#[cfg(any(feature = "server", feature = "client"))]
pub use endpoint_libs::libs::ws::transport::nagoya::NagoyaStream;
#[cfg(test)]
mod tests {
use super::*;
fn key_request() -> AgentControlRequest {
AgentControlRequest::Act(AgentAction::Input(InputCommand::Key {
phase: KeyPhase::Down,
key: "2".into(),
code: "Digit2".into(),
modifiers: Modifiers {
meta: true,
..Default::default()
},
}))
}
#[test]
fn typed_modifier_input_round_trips_mcp_tools_call() {
let request = key_request();
let id = JsonRpcId::Number(7);
assert_eq!(
decode_agent_request(encode_agent_request(id.clone(), &request).unwrap()).unwrap(),
(id, request)
);
}
#[test]
fn node_addressed_actions_round_trip() {
for action in [
AgentAction::Focus { node_id: 8 },
AgentAction::Click { node_id: 9 },
AgentAction::DoubleClick { node_id: 10 },
AgentAction::Hover { node_id: 11 },
AgentAction::SetValue {
node_id: 12,
value: "fixture".into(),
},
AgentAction::ScrollIntoView { node_id: 13 },
AgentAction::ScrollBy {
node_id: 14,
delta_x: 1.0,
delta_y: -2.0,
},
AgentAction::Input(InputCommand::Pointer {
phase: PointerPhase::Move,
x: 3.0,
y: 4.0,
button: 0,
modifiers: Modifiers::default(),
}),
AgentAction::Input(InputCommand::Wheel {
delta_x: 0.0,
delta_y: 5.0,
phase: WheelPhase::Moved,
modifiers: Modifiers::default(),
}),
] {
let request = AgentControlRequest::Act(action);
let id = JsonRpcId::Number(8);
assert_eq!(
decode_agent_request(encode_agent_request(id.clone(), &request).unwrap()).unwrap(),
(id, request)
);
}
for request in [
AgentControlRequest::Navigate {
url: "/second.html".into(),
},
AgentControlRequest::Relaunch,
AgentControlRequest::Quit,
] {
let id = JsonRpcId::Number(9);
assert_eq!(
decode_agent_request(encode_agent_request(id.clone(), &request).unwrap()).unwrap(),
(id, request)
);
}
}
#[test]
fn capture_scale_is_bounded_before_a_renderer_allocates() {
for scale in [f32::NAN, f32::INFINITY, -1.0, 0.0, 0.24, 8.01] {
assert!(
CaptureRequest {
node_id: None,
scale
}
.validate()
.is_err()
);
}
for scale in [0.25, 1.0, 4.0, 8.0] {
assert!(
CaptureRequest {
node_id: None,
scale
}
.validate()
.is_ok()
);
}
}
#[test]
fn oversized_capture_response_is_rejected_before_framing() {
let response = DebugResponse::Captured(CapturedImage {
width: 1,
height: 1,
rgba_base64: "A".repeat(MAX_DEBUG_FRAME_BYTES),
node_id: None,
});
assert!(matches!(
encode_response(JsonRpcId::Number(1), &response),
Err(DebugProtocolError::PayloadTooLarge(_))
));
}
#[test]
fn click_wire_shape_is_literal_and_foreign_client_readable() {
let message = encode_agent_request(
JsonRpcId::Number(3),
&AgentControlRequest::Act(AgentAction::Click { node_id: 9 }),
)
.unwrap();
let WireMessage::Text(text) = message else {
panic!("debug requests must be text frames")
};
let value: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(value["method"], MCP_TOOLS_CALL);
assert_eq!(value["params"]["name"], AGENT_CONTROL_TOOL);
assert_eq!(value["params"]["arguments"]["command"], "act");
assert_eq!(value["params"]["arguments"]["params"]["action"], "click");
assert_eq!(
value["params"]["arguments"]["params"]["params"]["node_id"],
9
);
}
#[test]
fn unrelated_mcp_tool_is_rejected_explicitly() {
let message = JsonRpcMessage::Request(JsonRpcRequest::call(
JsonRpcId::Number(1),
MCP_TOOLS_CALL,
serde_json::json!({"name": "other.tool", "arguments": {}}),
));
assert!(matches!(
decode_agent_request(encode_rpc(message).unwrap()),
Err(DebugProtocolError::UnexpectedTool(tool)) if tool == "other.tool"
));
}
#[test]
fn responses_and_notifications_round_trip() {
let id = JsonRpcId::Number(19);
let response = DebugResponse::Ack;
assert_eq!(
decode_response(encode_response(id.clone(), &response).unwrap()).unwrap(),
(id, response)
);
let event = AgentControlEvent::TreeChanged { revision: 12 };
assert_eq!(
decode_agent_event(encode_agent_event(&event).unwrap()).unwrap(),
event
);
let event = DebugEvent::PaintCommitted { revision: 13 };
assert_eq!(
decode_diagnostics_event(encode_diagnostics_event(&event).unwrap()).unwrap(),
event
);
}
#[test]
fn diagnostics_metrics_request_and_response_round_trip() {
let id = JsonRpcId::Number(23);
assert_eq!(
decode_diagnostics_request(
encode_diagnostics_request(id.clone(), &DiagnosticsRequest::Metrics).unwrap()
)
.unwrap(),
(id.clone(), DiagnosticsRequest::Metrics)
);
let response = DebugResponse::Metrics(RendererMetrics {
resident_bytes: Some(4096),
..Default::default()
});
assert_eq!(
decode_response(encode_response(id.clone(), &response).unwrap()).unwrap(),
(id, response)
);
}
#[test]
fn native_window_composition_round_trips_without_pixel_inference() {
let id = JsonRpcId::Number(24);
assert_eq!(
decode_diagnostics_request(
encode_diagnostics_request(id.clone(), &DiagnosticsRequest::WindowComposition)
.unwrap()
)
.unwrap(),
(id.clone(), DiagnosticsRequest::WindowComposition)
);
let response = DebugResponse::WindowComposition(WindowComposition {
supported: true,
surface_transparent: true,
glass_enabled: true,
glass_backend: Some("nativeGlass".into()),
tint_rgba: Some([174, 50, 112, 0]),
radius: Some(12.0),
});
assert_eq!(
decode_response(encode_response(id.clone(), &response).unwrap()).unwrap(),
(id, response)
);
}
#[test]
fn tools_list_describes_the_typed_requests() {
let message = encode_tools_list_response(JsonRpcId::Number(31), true).unwrap();
let JsonRpcMessage::Response(response) = decode_rpc(message).unwrap() else {
panic!("tools/list should be a response")
};
let tools = response.result.unwrap()["tools"]
.as_array()
.unwrap()
.to_vec();
let agent = &tools[0]["inputSchema"];
let diagnostics = &tools[1]["inputSchema"];
assert!(
agent.get("oneOf").is_some() || agent.get("$defs").is_some(),
"agent schema must describe its tagged command variants: {agent}"
);
assert!(
diagnostics.get("oneOf").is_some() || diagnostics.get("$defs").is_some(),
"diagnostics schema must describe its tagged command variants: {diagnostics}"
);
assert_ne!(agent, &serde_json::json!({"type": "object"}));
assert_ne!(diagnostics, &serde_json::json!({"type": "object"}));
let agent_text = agent.to_string();
let diagnostics_text = diagnostics.to_string();
assert!(agent_text.contains("command") && agent_text.contains("inspect"));
assert!(diagnostics_text.contains("command") && diagnostics_text.contains("metrics"));
}
#[test]
fn typed_layout_row_preserves_the_existing_wire_shape() {
let row = LayoutDiagnosticRow {
node_id: 7,
bounds: LayoutBounds {
x: 1.0,
y: 2.0,
width: 30.0,
height: 40.0,
},
scroll_offset: LayoutOffset { x: 3.0, y: 4.0 },
client_size: LayoutSize {
width: 30.0,
height: 40.0,
},
scroll_size: LayoutSize {
width: 50.0,
height: 60.0,
},
scroll_range: LayoutSize {
width: 20.0,
height: 20.0,
},
border: LayoutEdges {
top: 1.0,
right: 2.0,
bottom: 3.0,
left: 4.0,
},
padding: LayoutEdges {
top: 5.0,
right: 6.0,
bottom: 7.0,
left: 8.0,
},
content_size: LayoutSize {
width: 10.0,
height: 11.0,
},
};
let old_wire_shape = serde_json::json!({
"nodeId": 7,
"bounds": [1.0, 2.0, 30.0, 40.0],
"scrollOffset": [3.0, 4.0],
"clientSize": [30.0, 40.0],
"scrollSize": [50.0, 60.0],
"scrollRange": [20.0, 20.0],
"border": [1.0, 2.0, 3.0, 4.0],
"padding": [5.0, 6.0, 7.0, 8.0],
"contentSize": [10.0, 11.0]
});
assert_eq!(serde_json::to_value(&row).unwrap(), old_wire_shape);
assert_eq!(
serde_json::from_value::<LayoutDiagnosticRow>(old_wire_shape).unwrap(),
row
);
}
#[test]
fn semantic_node_keeps_authored_dom_identity_separate_from_node_handle() {
let node = SemanticNode {
dom_id: Some("settings-save".into()),
id: 42,
parent: None,
role: "button".into(),
name: "Save settings".into(),
value: None,
enabled: true,
focusable: true,
viewport_fixed: false,
visible: true,
selected: false,
bounds: Some([1.0, 2.0, 30.0, 20.0]),
slot: Some("button".into()),
};
let encoded = serde_json::to_value(&node).unwrap();
assert_eq!(encoded["domId"], "settings-save");
assert_eq!(encoded["id"], 42);
assert_eq!(
serde_json::from_value::<SemanticNode>(encoded).unwrap(),
node
);
}
#[test]
fn frame_metrics_round_trip_and_keep_unmeasured_fields_empty() {
let id = JsonRpcId::Number(24);
let response = DebugResponse::Metrics(RendererMetrics {
frame: Some(FrameMetrics {
resolve_ms: 1.5,
scene_ms: 2.25,
renderer_ms: 3.0,
total_ms: 6.75,
age_ms: 12.0,
..Default::default()
}),
frame_window: Some(FrameWindowMetrics {
frames_total: 900,
window_frames: 256,
total: TimingStats {
mean_ms: 6.0,
p95_ms: 11.0,
max_ms: 40.0,
},
active_fps: 59.4,
missed_refreshes: 2,
display_refresh_hz: Some(60.0),
..Default::default()
}),
snapshot: Some(SnapshotCost {
poll_ms: 0.5,
resolve_ms: 1.0,
total_ms: 4.0,
}),
..Default::default()
});
let (decoded_id, decoded) =
decode_response(encode_response(id.clone(), &response).unwrap()).unwrap();
assert_eq!(decoded_id, id);
assert_eq!(decoded, response);
let DebugResponse::Metrics(metrics) = decoded else {
panic!("expected renderer metrics")
};
let frame = metrics.frame.unwrap();
assert_eq!(frame.input_to_present_ms, None);
assert_eq!(frame.style_ms, None);
assert_eq!(frame.layout_ms, None);
assert_eq!(frame.submit_ms, None);
assert_eq!(frame.present_ms, None);
assert_eq!(metrics.queue_depth, None);
}
}