//! HTTP Debug Server for Azul

//!

//! This module provides an HTTP debug server that integrates with Azul's timer system

//! for cross-platform automated testing and debugging.

//!

//! ## Architecture

//!

//! The debug server is started in `App::create()` and runs on a background thread.

//! It accepts JSON commands on "/" and forwards them to the timer callback for

//! cross-platform processing via CallbackInfo.

//!

//! ## Usage

//!

//! ```bash

//! # Start app with debug server

//! AZ_DEBUG=8765 cargo run --bin my_app

//!

//! # Send events (blocks until processed)

//! curl -X POST http://localhost:8765/ -d '{"type":"get_state"}'

//! ```

use crate::solver3::layout_tree::LayoutNodeId;

use alloc::collections::BTreeMap;

use alloc::collections::VecDeque;

use alloc::string::String;

use alloc::vec::Vec;

use core::sync::atomic::{AtomicBool, AtomicU64, Ordering};

// Import the NativeScreenshotExt trait for native screenshots

#[cfg(feature = "std")]

use std::sync::{mpsc, Arc, Mutex, OnceLock};

const ROOT_DOM_ID: azul_core::dom::DomId = azul_core::dom::DomId { inner: 0 };

/// Wall-clock `wall_clock_now()` for the E2E runner's own bookkeeping

/// (per-step durations and the `wait` op's resume deadline).

///

/// Every such read in this module funnels through here so that the WASM-compat

/// CI gate ("no ungated `wall_clock_now()` in azul-css / azul-core /

/// azul-layout", `rust.yml` -> Lint & Static Checks) has exactly ONE site to

/// look at instead of a call scattered through a 12k-line dispatcher.

///

/// It is sound to read the real clock here: the whole `e2e` module is

/// `#[cfg(feature = "e2e-server")]`, a desktop-test-only feature that is not in

/// `default` and is never enabled for a wasm build — which is the target where

/// `Instant::now()` panics. This is deliberately NOT the injectable test clock

/// (`azul_core::task::Instant::now`): step durations and the `wait` deadline

/// must measure real elapsed time, or `tick_ms` would let a scenario "wait"

/// without the event loop ever making progress.

// The `not(target_family = "wasm")` states in code what the comment above

// claims: `e2e-server` is not in `default` and is never enabled for a wasm

// build. A feature gate is not a target exclusion, so without this the guard

// was an assertion in prose only.

#[cfg(all(feature = "std", not(target_family = "wasm")))]

// ==================== Types ====================

/// Request from HTTP thread to timer callback

#[cfg(feature = "std")]

pub struct DebugRequest {

    pub request_id: u64,

    pub event: DebugEvent,

    pub window_id: Option<String>,

    pub wait_for_render: bool,

    pub response_tx: mpsc::Sender<DebugResponseData>,

}

/// Response data from timer callback to HTTP thread (internal)

#[cfg(feature = "std")]

#[derive(Debug, Clone)]

pub enum DebugResponseData {

    /// Successful response with optional data

    Ok {

        window_state: Option<WindowStateSnapshot>,

        data: Option<ResponseData>,

    },

    /// Error response

    Err(String),

}

/// Typed response data variants

#[cfg(feature = "std")]

/// Which profile a `GetProfileReport` op wants.

#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]

#[serde(rename_all = "snake_case")]

pub enum ProfileKind {

    Memory,

    Cpu,

}

/// A profile snapshot, in the SAME units the engine's own report prints:

/// **KiB** (which is also what `/proc` reports, despite its "kB" label).

/// Mixing that with a decimal-MB source is a 4.9% error and has produced

/// wrong conclusions in this project's own analysis, so the unit is in every

/// field name.

#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]

pub struct ProfileResponse {

    /// Resident set size — the number an assertion like "under 50 MB" means.

    pub rss_kib: u64,

    pub heap_kib: u64,

    pub anon_kib: u64,

    pub binary_kib: u64,

    pub shared_libs_kib: u64,

    pub font_files_kib: u64,

    pub framebuffer_kib: u64,

    /// Live allocations per the allocator. `None` where `mallinfo2` is

    /// unavailable (musl, glibc < 2.33, macOS) — **null, never 0**, because a

    /// zero here reads as "no memory held", the worst available wrong answer.

    pub allocator_live_kib: Option<u64>,

    /// Freed by the program but still held by the allocator. Churn, not data.

    pub allocator_free_in_arena_kib: Option<u64>,

    /// Log messages evicted by the debug queue cap. **Non-zero invalidates a

    /// memory assertion taken under `AZ_E2E`**: the logger allocates per

    /// message, and an unbounded version of this queue once cost 41 MB and

    /// was briefly misreported as a resize leak.

    pub logs_dropped: u64,

    /// Wall-clock of recorded phases, `Cpu` kind only.

    #[serde(skip_serializing_if = "Vec::is_empty", default)]

    pub phases_us: Vec<(String, u64)>,

}

/// What the application's handler returned for a `CustomOp`.

#[derive(Debug, Clone, Default, serde::Serialize)]

pub struct CustomOpResponse {

    /// The op name, echoed so an async consumer can match responses.

    pub op: String,

    /// The handler's JSON result, verbatim. `null` if it returned nothing

    /// parseable — the raw string is still in `raw`.

    pub result: Option<serde_json::Value>,

    /// The handler's result before parsing. Kept because a handler returning

    /// malformed JSON is a bug worth SEEING rather than silently flattening

    /// to null.

    pub raw: String,

}

#[derive(Debug, Clone, serde::Serialize)]

#[serde(tag = "type", content = "value", rename_all = "snake_case")]

pub enum ResponseData {

    /// A memory or CPU profile snapshot, see `DebugEvent::GetProfileReport`.

    Profile(ProfileResponse),

    /// Result of an application-handled `CustomOp`.

    CustomOp(CustomOpResponse),

    /// Screenshot data (base64 encoded PNG)

    Screenshot(ScreenshotData),

    /// Node CSS properties

    NodeCssProperties(NodeCssPropertiesResponse),

    /// Node layout

    NodeLayout(NodeLayoutResponse),

    /// In-flight layout animations

    Animations(AnimationsResponse),

    /// Result of stepping layout animations

    TickAnimations(TickAnimationsResponse),

    /// All nodes layout

    AllNodesLayout(AllNodesLayoutResponse),

    /// The current DOM (nested tree + HTML), see `DebugEvent::GetDom`

    Dom(DomResponse),

    /// DOM tree

    DomTree(DomTreeResponse),

    /// Node hierarchy

    NodeHierarchy(NodeHierarchyResponse),

    /// Layout tree

    LayoutTree(LayoutTreeResponse),

    /// Display list

    DisplayList(DisplayListResponse),

    /// Scroll states

    ScrollStates(ScrollStatesResponse),

    /// Scrollable nodes

    ScrollableNodes(ScrollableNodesResponse),

    /// Scroll node by delta result

    ScrollNodeBy(ScrollNodeByResponse),

    /// Scroll node to position result

    ScrollNodeTo(ScrollNodeToResponse),

    /// Scroll node into view result

    ScrollIntoView(ScrollIntoViewResponse),

    /// Hit test result

    HitTest(HitTestResponse),

    /// HTML string

    HtmlString(HtmlStringResponse),

    /// Log messages

    Logs(LogsResponse),

    /// Health check

    Health(HealthResponse),

    /// Find node result

    FindNode(FindNodeResponse),

    /// Click node result

    ClickNode(ClickNodeResponse),

    /// Scrollbar info result

    ScrollbarInfo(ScrollbarInfoResponse),

    /// VirtualView states (all tracked VirtualViews and their internal state)

    VirtualViewStates(VirtualViewStatesResponse),

    /// VirtualView layout (nodes inside a specific VirtualView DOM)

    VirtualViewLayout(VirtualViewLayoutResponse),

    /// Selection state result

    SelectionState(SelectionStateResponse),

    /// Full selection manager dump

    SelectionManagerDump(SelectionManagerDump),

    /// App state as JSON

    AppState(AppStateResponse),

    /// App state set result

    AppStateSet(AppStateSetResponse),

    /// Drag state from unified drag system

    DragState(DragStateResponse),

    /// Detailed drag context

    DragContext(DragContextResponse),

    /// Focus state (which node has keyboard focus)

    FocusState(FocusStateResponse),

    /// `focus_node` result — which node the op actually focused

    FocusNode(FocusNodeResponse),

    /// Cursor state (cursor position and blink state)

    CursorState(CursorStateResponse),

    /// E2E test results

    E2eResults(E2eResultsResponse),

    /// Per-frame damage + frame-work counters (`get_frame_report`)

    FrameReport(FrameReportResponse),

    /// Node inserted result (returns new node_id)

    NodeInserted(NodeInsertedResponse),

    /// Node deleted result

    NodeDeleted(NodeDeletedResponse),

    /// Node text set result

    NodeTextSet(NodeTextSetResponse),

    /// Node classes set result

    NodeClassesSet(NodeClassesSetResponse),

    /// Node CSS override result

    NodeCssOverrideSet(NodeCssOverrideSetResponse),

    /// Resolved function pointer names

    FunctionPointers(FunctionPointersResponse),

    /// Component registry (available tags and their attributes)

    ComponentRegistry(ComponentRegistryResponse),

    /// Library list (lightweight summary)

    Libraries(LibraryListResponse),

    /// Components within a specific library

    LibraryComponents(LibraryComponentsResponse),

    /// Exported code (compiled project files)

    ExportedCode(ExportedCodeResponse),

    /// Component library imported successfully

    ImportedLibrary(ImportedLibraryResponse),

    /// Component library exported as JSON

    ExportedLibrary(ExportedLibraryResponse),

    /// Component preview image (CPU-rendered)

    ComponentPreview(ComponentPreviewResponse),

    /// Node dataset (RefAny serialized to JSON)

    NodeDataset(NodeDatasetResponse),

    /// Generic JSON data (for endpoints that return arbitrary JSON)

    Json(serde_json::Value),

}

/// Response for GetComponentPreview — CPU-rendered component image.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentPreviewResponse {

    /// Base64-encoded PNG data URI ("data:image/png;base64,...")

    pub data: String,

    /// Actual content width in logical pixels

    pub width: f32,

    /// Actual content height in logical pixels

    pub height: f32,

}

/// Response for GetNodeDataset — serialized RefAny dataset of a DOM node.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeDatasetResponse {

    /// The node ID queried

    pub node_id: u64,

    /// Metadata about the RefAny type

    pub metadata: RefAnyMetadata,

    /// The serialized dataset JSON (null if not serializable)

    pub dataset: serde_json::Value,

    /// Error message if serialization failed

    #[serde(skip_serializing_if = "Option::is_none")]

    pub error: Option<RefAnyError>,

}

/// Wrapper for E2E test results

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct E2eResultsResponse {

    pub results: Vec<E2eTestResult>,

}

/// Response for InsertNode: returns the new node's ID

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeInsertedResponse {

    pub new_node_id: u64,

    pub parent_id: u64,

    pub node_type: String,

}

/// Response for DeleteNode

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct NodeDeletedResponse {

    pub node_id: u64,

    pub success: bool,

}

/// Response for SetNodeText

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeTextSetResponse {

    pub node_id: u64,

    pub new_text: String,

}

/// Response for `FocusNode`: the node DOM focus was moved to.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct FocusNodeResponse {

    pub node_id: u64,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub selector: Option<String>,

}

/// Response for SetNodeClasses

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeClassesSetResponse {

    pub node_id: u64,

    pub classes: Vec<String>,

    pub id: Option<String>,

}

/// One damage rect, in logical px.

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct DamageRectJson {

    pub x: f32,

    pub y: f32,

    pub width: f32,

    pub height: f32,

}

/// Response for `get_frame_report` — the whole `FrameReport`, queryable from the

/// E2E API (and from `POST /` in the inspector).

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct FrameReportResponse {

    /// Full display-list builds since the last reset — 0 across a paint-only

    /// transition tick proves the DL was PATCHED, not rebuilt.

    pub dl_rebuilds: u32,

    /// Whether the last display-list build was the per-IFC PATCH (splice +

    /// re-emit) — true after a text edit, false after a structural change.

    pub last_dl_build_patched: bool,

    pub frame_index: u64,

    /// `"none"`, `"rects"` or `"full"`.

    pub paint_damage_kind: String,

    pub paint_damage_rects: Vec<DamageRectJson>,

    pub paint_damage_area_ratio: f32,

    pub present_damage_kind: String,

    pub present_damage_rects: Vec<DamageRectJson>,

    pub present_damage_area_ratio: f32,

    /// Damage accumulated since the last `reset_frame_counters` (what the

    /// `assert_damage*` ops look at by default).

    pub accumulated_paint_damage_kind: String,

    pub accumulated_paint_damage_rects: Vec<DamageRectJson>,

    pub accumulated_present_damage_kind: String,

    pub frames_since_reset: u32,

    /// EVENT passes (`process_window_events` depth), not layout passes.

    pub relayout_iterations: u32,

    pub dom_regenerations: u32,

    /// Times layout ACTUALLY ran (`layout_and_generate_display_list`).

    pub layout_passes: u32,

    pub hit_depth_cap: bool,

    /// Terminal `ProcessEventResult` discriminant (0 = DoNothing … 6 = RegenerateDomAllWindows).

    pub terminal_result: u8,

    /// Injectable test-clock offset in ms (advanced by `tick_ms`).

    pub test_clock_offset_ms: u64,

}

/// Response for SetNodeCssOverride

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeCssOverrideSetResponse {

    pub node_id: u64,

    pub property: String,

    pub value: String,

}

/// Response for ResolveFunctionPointers

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct FunctionPointersResponse {

    pub resolved: Vec<ResolvedFunctionPointer>,

}

/// A resolved function pointer

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ResolvedFunctionPointer {

    pub address: String,

    pub symbol_name: Option<String>,

    /// The shared library / binary file that contains this symbol

    pub file_name: Option<String>,

    /// Source file path (if resolved via backtrace or heuristic)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub source_file: Option<String>,

    /// Source line number (if resolved via backtrace)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub source_line: Option<u32>,

    /// Human-readable hint about resolution quality

    #[serde(skip_serializing_if = "Option::is_none")]

    pub hint: Option<String>,

    /// Whether the resolved info is approximate (heuristic-based)

    #[serde(default)]

    pub approximate: bool,

}

/// Response for ExportCode: compiled project as a base64-encoded ZIP

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ExportedCodeResponse {

    /// Target language used

    pub language: String,

    /// Map of filename → file content (source code)

    pub files: std::collections::HashMap<String, String>,

    /// Any warnings or notes from compilation

    pub warnings: Vec<String>,

}

/// Response for GetComponentRegistry

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentRegistryResponse {

    /// Libraries of components, grouped by collection name

    pub libraries: Vec<ComponentLibraryInfo>,

}

/// A library / collection of components

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentLibraryInfo {

    /// Library name (e.g., "builtin", "shadcn", "myproject")

    pub name: String,

    /// Library version

    pub version: String,

    /// Human-readable description

    pub description: String,

    /// Whether this library can be exported

    pub exportable: bool,

    /// Whether this library can be modified (add/remove/edit components)

    pub modifiable: bool,

    /// Named data model types defined by this library

    pub data_models: Vec<DataModelInfo>,

    /// Named enum types defined by this library

    pub enum_models: Vec<EnumModelInfo>,

    /// Components in this library

    pub components: Vec<ComponentInfo>,

}

/// Information about a registered component/tag

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentInfo {

    /// The tag name (e.g., "div", "a", "button")

    pub tag: String,

    /// The qualified name (e.g., "builtin:div", "shadcn:avatar")

    pub qualified_name: String,

    /// Display name for the GUI (e.g., "Link" for "a", "Avatar")

    pub display_name: String,

    /// Description / documentation

    pub description: String,

    /// Source: "builtin", "compiled", "user_defined"

    pub source: String,

    /// Component-specific data model fields (the component's own attributes,

    /// e.g., href/target/rel for <a>). These ARE the component's main data model.

    pub data_model: Vec<ComponentDataFieldInfo>,

    /// Universal HTML attributes (id, class, style, etc.)

    /// Shown in a collapsed section in the debugger.

    pub universal_attributes: Vec<ComponentAttributeInfo>,

    /// Callback slots this component exposes

    pub callback_slots: Vec<ComponentCallbackSlotInfo>,

    /// CSS

    pub css: String,

}

/// Info about an attribute a component accepts

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentAttributeInfo {

    /// Attribute name (e.g., "href", "src", "alt")

    pub name: String,

    /// Attribute type hint (e.g., "String", "bool", "i32")

    pub attr_type: String,

    /// Default value, if any

    pub default: Option<String>,

    /// Description

    pub description: String,

}

/// Info about a callback slot

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentCallbackSlotInfo {

    /// Slot name (e.g., "on_click", "on_value_change")

    pub name: String,

    /// Callback type name (e.g., "ButtonOnClickCallbackType")

    pub callback_type: String,

    /// Description

    pub description: String,

}

/// Info about a data model field

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentDataFieldInfo {

    /// Field name

    pub name: String,

    /// Flat type string (for backwards compat / display)

    pub field_type: String,

    /// Structured type descriptor

    pub field_type_structured: StructuredFieldType,

    /// Default value

    pub default: Option<String>,

    /// Whether this field is required (must be provided by the parent)

    pub required: bool,

    /// Description

    pub description: String,

}

/// Structured type descriptor for component field types.

/// Replaces flat string matching with typed JSON.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

#[serde(tag = "kind")]

pub enum StructuredFieldType {

    #[serde(rename = "primitive")]

    Primitive { name: String },

    #[serde(rename = "callback")]

    Callback { args: Vec<CallbackArgInfo>, return_type: String },

    #[serde(rename = "ref_any")]

    RefAny { type_hint: String },

    #[serde(rename = "option")]

    OptionType { inner: Box<StructuredFieldType> },

    #[serde(rename = "vec")]

    VecType { inner: Box<StructuredFieldType> },

    #[serde(rename = "struct_ref")]

    StructRef { name: String },

    #[serde(rename = "enum_ref")]

    EnumRef { name: String },

}

/// Info about a callback argument

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct CallbackArgInfo {

    pub name: String,

    #[serde(rename = "type")]

    pub arg_type: String,

}

/// Response for GetLibraries — list of registered component libraries (without component details)

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LibraryListResponse {

    pub libraries: Vec<LibrarySummary>,

}

/// Summary info for a library (no component details)

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LibrarySummary {

    pub name: String,

    pub version: String,

    pub description: String,

    pub exportable: bool,

    pub modifiable: bool,

    pub component_count: usize,

}

/// A named data model (struct definition) in a library

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DataModelInfo {

    /// Type name, e.g. "UserProfile"

    pub name: String,

    /// Human-readable description

    pub description: String,

    /// Fields in this struct

    pub fields: Vec<ComponentDataFieldInfo>,

}

/// A named enum model in a library

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct EnumModelInfo {

    /// Enum name, e.g. "UserRole"

    pub name: String,

    /// Human-readable description

    pub description: String,

    /// Variants

    pub variants: Vec<EnumVariantInfo>,

}

/// A single enum variant

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct EnumVariantInfo {

    /// Variant name

    pub name: String,

    /// Human-readable description

    pub description: String,

    /// Associated fields (empty for unit variants)

    pub fields: Vec<ComponentDataFieldInfo>,

}

/// Response for GetLibraryComponents — components within a specific library

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LibraryComponentsResponse {

    pub library: String,

    pub components: Vec<ComponentInfo>,

}

/// Response for ImportComponentLibrary

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ImportedLibraryResponse {

    /// Name of the imported library

    pub library_name: String,

    /// Number of components imported

    pub component_count: usize,

    /// Whether this was an update (true) or new addition (false)

    pub was_update: bool,

}

/// Response for ExportComponentLibrary — JSON-serializable library definition

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedLibraryResponse {

    /// Library name

    pub name: String,

    /// Library version

    pub version: String,

    /// Library description

    pub description: String,

    /// Named data model types (struct definitions)

    #[serde(default)]

    pub data_models: Vec<ExportedDataModelDef>,

    /// Named enum model types

    #[serde(default)]

    pub enum_models: Vec<ExportedEnumModelDef>,

    /// Component definitions (JSON-serializable subset)

    pub components: Vec<ExportedComponentDef>,

}

/// A named data model (struct) for export/import

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedDataModelDef {

    pub name: String,

    #[serde(default)]

    pub description: String,

    pub fields: Vec<ExportedDataField>,

}

/// A named enum model for export/import

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedEnumModelDef {

    pub name: String,

    #[serde(default)]

    pub description: String,

    pub variants: Vec<ExportedEnumVariantDef>,

}

/// A single enum variant for export/import

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedEnumVariantDef {

    pub name: String,

    #[serde(default)]

    pub description: String,

    #[serde(default)]

    pub fields: Vec<ExportedDataField>,

}

/// A component definition in JSON-serializable form (for import/export).

/// Uses a unified `fields` list instead of separate parameters/data_fields/callback_slots.

/// Callbacks are fields with type "Callback(...)", struct refs use "struct:Name", etc.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedComponentDef {

    /// Component name (without collection prefix)

    pub name: String,

    /// Human-readable display name

    pub display_name: String,

    /// Markdown description

    #[serde(default)]

    pub description: String,

    /// Unified data model fields (data fields, callbacks, parameters — all in one list).

    /// Callbacks have type "Callback(...)", regular fields have type "String", "bool", etc.

    #[serde(default)]

    pub fields: Vec<ExportedDataField>,

    /// CSS for the component

    #[serde(default)]

    pub css: String,

}

#[cfg(feature = "std")]

/// A data model field in JSON form (unified: data fields, callbacks, parameters).

/// For callbacks, set `type` to "Callback(...)" or "Callback".

/// For struct/enum references, use "struct:TypeName" or "enum:TypeName".

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

pub struct ExportedDataField {

    /// Field name (must be a valid identifier)

    pub name: String,

    /// Field type string: "String", "bool", "i32", "Callback(...)", "Option<i32>", etc.

    #[serde(rename = "type", default = "default_param_type")]

    pub field_type: String,

    /// Default value as string (parsed according to field type)

    #[serde(default)]

    pub default: Option<String>,

    /// Human-readable description

    #[serde(default)]

    pub description: String,

}

/// Metadata about a RefAny's type

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct RefAnyMetadata {

    /// The compiler-generated type ID

    pub type_id: u64,

    /// Human-readable type name (e.g., "app::MyStruct")

    pub type_name: String,

    /// Whether this RefAny supports JSON serialization

    pub can_serialize: bool,

    /// Whether this RefAny type supports JSON deserialization

    pub can_deserialize: bool,

    /// Number of active references to this data

    pub ref_count: usize,

}

/// Error information for RefAny operations

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

#[serde(tag = "error_type", content = "message", rename_all = "snake_case")]

pub enum RefAnyError {

    /// Type does not support JSON serialization

    NotSerializable,

    /// Type does not support JSON deserialization

    NotDeserializable,

    /// Serde serialization/deserialization failed

    SerdeError(String),

    /// Valid JSON but cannot construct RefAny (type mismatch, missing fields, etc.)

    TypeConstructionError(String),

}

/// App state response (JSON serialized) with full metadata

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct AppStateResponse {

    /// Metadata about the RefAny type

    pub metadata: RefAnyMetadata,

    /// The serialized JSON data (null if serialization failed or not supported)

    pub state: serde_json::Value,

    /// Error message if serialization failed

    #[serde(skip_serializing_if = "Option::is_none")]

    pub error: Option<RefAnyError>,

}

/// App state set result

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct AppStateSetResponse {

    /// Whether the operation succeeded

    pub success: bool,

    /// Optional error details

    #[serde(skip_serializing_if = "Option::is_none")]

    pub error: Option<RefAnyError>,

}

/// Screenshot response data

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ScreenshotData {

    /// Base64 encoded PNG with data URI prefix

    pub data: String,

}

/// Hit test response

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct HitTestResponse {

    pub x: f32,

    pub y: f32,

    pub node_id: Option<u64>,

    pub node_tag: Option<String>,

}

/// Find node response - returns location and size of found node

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct FindNodeResponse {

    pub found: bool,

    pub node_id: Option<u64>,

    pub x: Option<f32>,

    pub y: Option<f32>,

    pub width: Option<f32>,

    pub height: Option<f32>,

    pub tag: Option<String>,

    pub classes: Option<Vec<String>>,

}

/// Click node response

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ClickNodeResponse {

    pub success: bool,

    pub message: String,

}

/// HTML string response

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct HtmlStringResponse {

    pub html: String,

}

/// Logs response

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LogsResponse {

    pub logs: Vec<LogMessage>,

}

/// Health check response

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct HealthResponse {

    pub port: u16,

    pub pending_logs: usize,

    pub logs: Vec<LogMessageJson>,

}

/// JSON-friendly log message

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LogMessageJson {

    pub timestamp_us: u64,

    pub level: String,

    pub category: String,

    pub message: String,

}

/// HTTP response wrapper for serialization

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

#[serde(tag = "status")]

pub enum DebugHttpResponse {

    #[serde(rename = "ok")]

    Ok(DebugHttpResponseOk),

    #[serde(rename = "error")]

    Error(DebugHttpResponseError),

}

/// Successful HTTP response body

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DebugHttpResponseOk {

    pub request_id: u64,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub window_state: Option<WindowStateSnapshot>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub data: Option<ResponseData>,

}

/// Error HTTP response body

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DebugHttpResponseError {

    #[serde(skip_serializing_if = "Option::is_none")]

    pub request_id: Option<u64>,

    pub message: String,

}

/// A log message

#[derive(Debug, Clone)]

pub struct LogMessage {

    pub timestamp_us: u64,

    pub level: LogLevel,

    pub category: LogCategory,

    pub message: String,

    pub location: String,

    pub window_id: Option<String>,

}

#[cfg(feature = "std")]

impl serde::Serialize for LogMessage {

    {

        use serde::ser::SerializeStruct;

}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]

pub enum LogLevel {

    Trace,

    Debug,

    Info,

    Warn,

    Error,

}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum LogCategory {

    General,

    Window,

    EventLoop,

    Input,

    Layout,

    Text,

    DisplayList,

    Rendering,

    Resources,

    Callbacks,

    Timer,

    DebugServer,

    Platform,

}

/// Snapshot of window state for response

#[derive(Debug, Clone)]

pub struct WindowStateSnapshot {

    pub window_id: String,

    pub logical_width: f32,

    pub logical_height: f32,

    pub physical_width: u32,

    pub physical_height: u32,

    pub dpi: u32,

    pub hidpi_factor: f32,

    pub focused: bool,

    pub dom_node_count: usize,

    pub focused_node: Option<u64>,

}

#[cfg(feature = "std")]

impl serde::Serialize for WindowStateSnapshot {

    {

        use serde::ser::SerializeStruct;

}

// ==================== Response Data Structures ====================

/// Response for GetNodeCssProperties

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeCssPropertiesResponse {

    pub node_id: u64,

    pub property_count: usize,

    pub properties: Vec<String>,

}

/// One in-flight layout animation, as `get_animations` reports it.

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct AnimationNodeJson {

    pub node_id: u64,

    pub translate_x: f32,

    pub translate_y: f32,

    pub scale_x: f32,

    pub scale_y: f32,

    pub opacity: f32,

    pub finished: bool,

    /// Whether the value reached `css_current_transform_values` — the map the

    /// rasteriser and hit-tester read. Proves the animation is on screen and

    /// not merely bookkept.

    pub published: bool,

}

/// Response for `GetAnimations`.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct AnimationsResponse {

    /// How many animations are in flight.

    pub active: usize,

    /// Retained departing subtrees still on screen. Must return to 0 once the

    /// exits settle — a zombie that outlives its animation is a leak, and one

    /// that vanishes early took its state with it mid-flight.

    pub zombies: usize,

    /// Diff-triggered `animation` transitions in flight. Same lifecycle law

    /// as `zombies`: must return to 0 once every override settles.

    pub transitions: usize,

    /// Cumulative retained-tree re-solves driven by zombie width/height

    /// channels. A pure slide leaves this at 0 (the frozen path); a

    /// shrinking exit re-solves per changed frame.

    pub zombie_relayouts: u64,

    /// Keyframed tracks currently driving LIVE nodes (`-azul-animation-in`

    /// and caught-mid-exit reversals).

    pub live_tracks: usize,

    pub nodes: Vec<AnimationNodeJson>,

}

/// Response for `TickAnimations`.

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct TickAnimationsResponse {

    pub dt_micros: u32,

    pub steps: u32,

    /// Animations still in flight AFTER the steps were applied.

    pub active: usize,

}

/// Response for GetNodeLayout

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct NodeLayoutResponse {

    pub node_id: u64,

    pub size: Option<LogicalSizeJson>,

    pub position: Option<LogicalPositionJson>,

    pub rect: Option<LogicalRectJson>,

}

/// Response for GetAllNodesLayout

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct AllNodesLayoutResponse {

    pub dom_id: u32,

    pub node_count: usize,

    pub nodes: Vec<NodeLayoutInfo>,

}

/// Layout info for a single node

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeLayoutInfo {

    pub node_id: usize,

    pub tag: Option<String>,

    pub id: Option<String>,

    pub classes: Vec<String>,

    pub rect: Option<LogicalRectJson>,

}

/// Response for GetDomTree

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct DomTreeResponse {

    pub dom_id: u32,

    pub node_count: usize,

    pub dpi: u32,

    pub hidpi_factor: f32,

    pub logical_width: f32,

    pub logical_height: f32,

}

/// Response for GetNodeHierarchy

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeHierarchyResponse {

    pub root: i64,

    pub node_count: usize,

    pub nodes: Vec<HierarchyNodeInfo>,

}

/// Response for `GetDom` — the current DOM as a NESTED tree plus its HTML.

///

/// Distinct from its two siblings: `GetDomTree` returns only counters (no

/// nodes at all) and `GetNodeHierarchy` returns a FLAT array keyed by index.

/// `GetDom` returns the DOM the way a consumer actually wants to read it —

/// nested, one call, with the serialized HTML alongside it.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DomResponse {

    pub dom_id: usize,

    pub node_count: usize,

    /// The same string `GetHtmlString` returns, so a caller needs one round-trip.

    pub html: String,

    /// The root node, with all children nested under it.

    pub root: DomNodeJson,

}

/// One node of the nested `GetDom` tree.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DomNodeJson {

    pub index: usize,

    #[serde(rename = "type")]

    pub node_type: String,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub id: Option<String>,

    #[serde(skip_serializing_if = "Vec::is_empty")]

    pub classes: Vec<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub text: Option<String>,

    #[serde(skip_serializing_if = "Vec::is_empty")]

    pub children: Vec<DomNodeJson>,

}

/// Hierarchy info for a single node

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct HierarchyNodeInfo {

    pub index: usize,

    #[serde(rename = "type")]

    pub node_type: String,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub tag: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub id: Option<String>,

    #[serde(skip_serializing_if = "Vec::is_empty")]

    pub classes: Vec<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub text: Option<String>,

    pub parent: i64,

    pub children: Vec<usize>,

    #[serde(skip_serializing_if = "Vec::is_empty")]

    pub events: Vec<NodeEventInfo>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub rect: Option<LogicalRectJson>,

    pub tab_index: Option<i32>,

    pub contenteditable: bool,

    /// Which component rendered this DOM node (if any).

    /// Enables the debugger to show a Component Tree alongside the DOM tree.

    #[serde(skip_serializing_if = "Option::is_none")]

    pub component: Option<ComponentOriginJson>,

    /// Whether this node has a dataset (opaque RefAny data).

    /// True if `NodeData.dataset` is `Some(...)`. The actual data is opaque

    /// but knowing it exists helps visualize component state.

    #[serde(skip_serializing_if = "Option::is_none")]

    pub has_dataset: Option<bool>,

}

/// JSON representation of a component origin stamp.

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ComponentOriginJson {

    /// Qualified component name, e.g. "shadcn:card"

    pub component_id: String,

    /// Data model at render time as a typed JSON value (object, number, string, etc.)

    pub data_model: serde_json::Value,

}

/// Event handler info for a single callback on a node

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct NodeEventInfo {

    pub event: String,

    pub callback_ptr: String,

}

/// Response for GetLayoutTree

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LayoutTreeResponse {

    pub root: usize,

    pub node_count: usize,

    pub nodes: Vec<LayoutNodeInfo>,

}

/// Layout tree info for a single node

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct LayoutNodeInfo {

    pub layout_idx: usize,

    pub dom_idx: i64,

    #[serde(rename = "type")]

    pub node_type: String,

    pub is_anonymous: bool,

    pub anonymous_type: Option<String>,

    pub formatting_context: String,

    pub parent: i64,

    pub children: Vec<usize>,  // populated from layout_tree.children(idx)

}

/// Response for GetDisplayList

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DisplayListResponse {

    pub total_items: usize,

    pub rect_count: usize,

    pub text_count: usize,

    pub border_count: usize,

    pub image_count: usize,

    pub other_count: usize,

    pub items: Vec<DisplayListItemInfo>,

    /// Clip chain analysis - shows push/pop balance

    #[serde(skip_serializing_if = "Option::is_none")]

    pub clip_analysis: Option<ClipChainAnalysis>,

}

/// Clip chain analysis for debugging clipping issues

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ClipChainAnalysis {

    /// Final clip depth (should be 0 if balanced)

    pub final_clip_depth: i32,

    /// Final scroll depth (should be 0 if balanced)

    pub final_scroll_depth: i32,

    /// Final stacking context depth (should be 0 if balanced)

    pub final_stacking_depth: i32,

    /// Whether all push/pop pairs are balanced

    pub balanced: bool,

    /// List of clip operations in order

    pub operations: Vec<ClipOperation>,

}

/// A single clip/scroll/stacking operation

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct ClipOperation {

    /// Index in display list

    pub index: usize,

    /// Operation type

    pub op: String,

    /// Clip depth after this operation

    pub clip_depth: i32,

    /// Scroll depth after this operation

    pub scroll_depth: i32,

    /// Stacking context depth after this operation

    pub stacking_depth: i32,

    /// Bounds if applicable

    #[serde(skip_serializing_if = "Option::is_none")]

    pub bounds: Option<LogicalRectJson>,

    /// Content size (for scroll frames)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub content_size: Option<LogicalSizeJson>,

    /// Scroll ID (for scroll frames)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub scroll_id: Option<u64>,

}

/// Display list item info

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct DisplayListItemInfo {

    pub index: usize,

    #[serde(rename = "type")]

    pub item_type: String,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub x: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub y: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub width: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub height: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub color: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub font_size: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub glyph_count: Option<usize>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub z_index: Option<i32>,

    /// Current clip depth when this item is rendered

    #[serde(skip_serializing_if = "Option::is_none")]

    pub clip_depth: Option<i32>,

    /// Current scroll depth when this item is rendered

    #[serde(skip_serializing_if = "Option::is_none")]

    pub scroll_depth: Option<i32>,

    /// Content size (for scroll frames)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub content_size: Option<LogicalSizeJson>,

    /// Scroll ID (for scroll frames)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub scroll_id: Option<u64>,

    /// Debug info string (for debugging scrollbar bounds, etc.)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub debug_info: Option<String>,

    /// Border colors per side (for border items)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub border_colors: Option<BorderColorsJson>,

    /// Border widths per side (for border items)

    #[serde(skip_serializing_if = "Option::is_none")]

    pub border_widths: Option<BorderWidthsJson>,

}

/// Border colors for all four sides (JSON output)

#[cfg(feature = "std")]

#[derive(Debug, Clone, serde::Serialize)]

pub struct BorderColorsJson {

    #[serde(skip_serializing_if = "Option::is_none")]

    pub top: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub right: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub bottom: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub left: Option<String>,

}

/// Border widths for all four sides (JSON output)

#[cfg(feature = "std")]

#[derive(Debug, Clone, Copy, serde::Serialize)]

pub struct BorderWidthsJson {

    #[serde(skip_serializing_if = "Option::is_none")]

    pub top: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub right: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub bottom: Option<f32>,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub left: Option<f32>,

}