//! Headless driver for E2E JSON scenarios.

//!

//! [`run_e2e_test`] runs an [`E2eTest`] end-to-end through the REAL server

//! op-dispatch (`super::full::process_debug_event` + the scenario runner

//! `resume_e2e_continuation`, pumped via `super::full::e2e_pump_continuation`) —

//! no HTTP, no timer, no DLL. It emulates the slice of the platform event loop

//! the E2E path needs, and it emulates it by PORTING the DLL, not by

//! approximating it:

//!

//! * [`Runner::apply_user_change`] is a port of `PlatformWindow::apply_user_change`

//!   (`dll/src/desktop/shell2/common/event.rs`) for the `CallbackChange`

//!   variants the E2E op set can produce — DOM mutation included.

//! * [`Runner::regenerate_layout`] / [`Runner::relayout_only`] port

//!   `regenerate_layout` / `incremental_relayout`

//!   (`dll/src/desktop/shell2/common/layout.rs`) plus the render + damage tail

//!   of the headless backend (`dll/src/desktop/shell2/headless/mod.rs`).

//! * [`super::cpu_backend::CpuBackend`] is the port of that backend's CPU

//!   renderer, which is what fills `LayoutWindow::frame_report` — without it

//!   every damage assertion reports "nothing was repainted (stale screen)".

//! * The font pipeline mirrors `AppInternal::create` + the font-snapshot block

//!   at the top of `regenerate_layout`, because font RESOLUTION differs between

//!   "one `FcFontCache::build()` for the whole process" and "an async registry

//!   snapshot re-installed on every DOM regeneration" — and the corpus contains

//!   a scenario (`mock_font_exact_metrics`) whose verdict depends on exactly

//!   that difference.

//!

//! The window/callback scaffolding mirrors the pattern in

//! `tests/contenteditable_e2e.rs` (LayoutWindow + `RendererResources::default()`

//! + `ExternalSystemCallbacks::rust_internal()` + `FullWindowState`).

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

use std::collections::BTreeMap;

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

use std::time::Instant;

use azul_core::{

    dom::{DomId, DomNodeId, NodeId},

    events::ProcessEventResult,

    gl::OptionGlContextPtr,

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    hit_test::ScrollPosition,

    refany::{OptionRefAny, RefAny},

    resources::RendererResources,

    styled_dom::{NodeHierarchyItemId, StyledDom},

    window::{MonitorVec, RawWindowHandle},

    xml::ComponentMap,

};

use azul_css::system::SystemStyle;

use rust_fontconfig::FcFontCache;

use azul_layout::{

    callbacks::{CallbackChange, CallbackInfo, CallbackInfoRefData, ExternalSystemCallbacks},

    window::{LayoutWindow, MAX_EVENT_RECURSION_DEPTH},

    window_state::FullWindowState,

};

use super::cpu_backend::CpuBackend;

use super::full::{

    process_debug_event, e2e_pump_continuation, DebugEvent, DebugRequest, DebugResponseData,

    E2eSession, E2eStepResult, E2eTest, E2eTestResult, ResponseData,

};

// ── Headless window scaffolding ──────────────────────────────────────────────

struct Runner {

    layout_window: LayoutWindow,

    renderer_resources: RendererResources,

    system_callbacks: ExternalSystemCallbacks,

    window_state: FullWindowState,

    /// The sync baseline the state-diff pass reads, i.e.

    /// `CommonWindowState::previous_window_state`. `determine_all_events`

    /// derives EVERY synthetic event (MouseDown/Up, KeyDown/Up, WindowFocusIn/

    /// Out, WindowMove/Resize) from `current` vs `previous`, so without this

    /// field the diff is always empty and no pointer or key event exists at

    /// all. Advanced by `ModifyWindowState` / `QueueWindowStateSequence`

    /// exactly where the DLL calls `set_previous_window_state`.

    previous_window_state: Option<FullWindowState>,

    /// Pointer→node resolution, i.e. `CommonWindowState::cpu_hit_tester`.

    ///

    /// The runner has no WebRender, so this is the same `CpuHitTester` the

    /// headless / CPU-mode desktop backends use, rebuilt from the layout

    /// results (see [`Runner::rebuild_hit_tester`]).

    cpu_hit_tester: azul_layout::headless::CpuHitTester,

    /// CPU renderer + retained damage state (port of the headless backend).

    cpu_backend: CpuBackend,

    /// The app-level font cache, i.e. `AppInternal::fc_cache`. Re-installed on

    /// the layout window's font manager at the top of every `regenerate_layout`,

    /// exactly like the DLL does.

    app_fc_cache: FcFontCache,

    /// The async font registry, i.e. `AppInternal::font_registry`.

    #[cfg(feature = "font_async_registry")]

    font_registry: Option<Arc<azul_layout::FcFontRegistry>>,

    /// Set by a `ModifyWindowState` whose size changed. Consumed by

    /// [`Runner::service`], which then runs the SAME resize decision the

    /// shells run (`LayoutWindow::resize_needs_full_regeneration`): full DOM

    /// regeneration only when a recorded window-size query answer flips or a

    /// CSS breakpoint / orientation is crossed; otherwise a relayout of the

    /// existing `StyledDom` at the new size. This is what lets the corpus

    /// assert `dom_regenerations == 0` across a plain resize.

    resize_pending: bool,

    /// Set by a `ModifyWindowState` whose DPI changed. Always a full

    /// regeneration: a scale change invalidates every cached rasterisation

    /// and every shaped run measured at the old scale.

    dpi_pending: bool,

    /// `CallbackChange`s this host could not apply faithfully (see

    /// [`Runner::unsupported`]). Non-empty ⇒ the scenario FAILS: it asked the

    /// engine to do something the headless runner cannot do, so whatever it

    /// asserted afterwards was asserted against a window where that something

    /// never happened.

    unsupported_changes: Vec<String>,

    /// The redraw a rendered frame asked for, i.e. the platform loop's

    /// `request_redraw()`.

    ///

    /// PORT of the tail of every DLL present path (x11 `mod.rs:4031`, wayland

    /// `mod.rs:4761`, windows `mod.rs:1062`/`1297`, macos `mod.rs:6334`):

    ///

    /// ```ignore

    /// // If any scrollbar is actively fading (0 < opacity < 1), schedule

    /// // another frame so the fade-out animation runs to completion.

    /// if lw.gpu_state_manager.scrollbar_fade_active { self.request_redraw(); }

    /// ```

    ///

    /// This host had no such re-arm, so the frame driven by `tick_ms` /

    /// `wait_frame` was the LAST one: a `wait` yields with a resume deadline,

    /// the pump sleeps, and `service()` then finds no pending change and

    /// renders nothing. Every state that settles on ELAPSED TIME — and the

    /// scrollbar fade, at `fade_delay` 500 ms + `fade_duration` 200 ms, is the

    /// one the corpus exercises — stayed frozen at whatever the last explicit

    /// frame left behind, so `scrollbar_fade_active` was still true when the

    /// scenario asked whether the window had settled.

    pending_redraw: bool,

}

impl Runner {

        // Port of `AppInternal::create`'s font setup: the app starts with an

        // async registry and an EMPTY `FcFontCache` (or a disk-cache snapshot);

        // the cache is populated from the registry at the first layout. This is

        // NOT the same as handing the window one eagerly-built `FcFontCache`:

        // the registry snapshot replaces the window's cache handle, which is

        // what makes in-memory (`register_named_font`) families behave the way

        // they do in a real app.

        #[cfg(feature = "font_async_registry")]

            // `FcFontRegistry::new()` already returns an `Arc<Self>`.

            // DETERMINISM: block until the scout has published the font set

            // (no-op when a disk cache was loaded; 5 s cap inside).

            //

            // Without this the fonts a DOM resolves depend on HOW FAR the

            // background builders happened to get before that particular

            // layout ran — so the same scenario resolves a 1-font fallback

            // chain when a step services a mount immediately and a 7-font one

            // when a `wait` delays it, and any assertion over font resources

            // silently measures thread scheduling. A verdict that moves with

            // background-thread progress is exactly the flake class this suite

            // exists to eliminate.

            } else {

            };

        };

        #[cfg(not(feature = "font_async_registry"))]

        let app_fc_cache = FcFontCache::build();

        Self {

            layout_window: {

                // Tweens OFF unless the scenario asked for them (`setup.animations`).

                // The default stays off so a scenario that never drives the clock

                // cannot screenshot geometry mid-glide — but "off, always, with no

                // flag" is what left the animated caret and the selection tween

                // with ZERO e2e coverage. Turning them on is deterministic here:

                // `run_e2e_test` freezes this thread's clock and only `tick_ms` /

                // `wait` advance it, so a tween's progress is a pure function of

                // the ops the scenario ran.

                } else {

                });

            },

            #[cfg(feature = "font_async_registry")]

            resize_pending: false,

            dpi_pending: false,

            pending_redraw: false,

        }

    /// Build a `CallbackInfo` over the current window/state and run `f` with it.

    /// `ref_data` and the transient locals it borrows are dropped when `f`

    /// returns, releasing the borrow so the caller can relayout.

        );

    /// Run the full layout pipeline for `styled_dom` and re-register scroll nodes.

            )

        // Same CRITICAL sync as the DLL paths (regenerate_layout's tail /

        // incremental_relayout): the cached state is the "old size" the resize

        // decision diffs against. Without it, every resize after the first

        // compared against the size of the last FULL layout — conservative

        // (extra full regenerations), but wrong.

    /// Rebuild [`Runner::cpu_hit_tester`] from the current layout results.

    ///

    /// Port of the headless backend's post-`regenerate_layout` rebuild

    /// (`dll/.../shell2/headless/mod.rs`), which carries this comment: *without

    /// this rebuild that tester stays empty, so every click hit-tests to

    /// nothing and widget callbacks never fire*.

    ///

    /// Called from exactly two places, and both are load-bearing:

    ///

    /// * [`Runner::layout`] — the single funnel every layout pass goes through

    ///   (`regenerate_layout` for mount / remount / resize / DPI, and

    ///   `relayout_only` for an in-place DOM or style mutation). Rebuilding

    ///   here is what keeps a `click` after a `set_node_text` from testing the

    ///   pre-mutation geometry.

    /// * the tail of [`Runner::service`] — the paths that produce a new frame

    ///   WITHOUT running layout (`ShouldReRenderCurrentWindow`,

    ///   `ShouldUpdateDisplayListCurrentWindow`,

    ///   `UpdateHitTesterAndProcessAgain` — the last one names it outright) all

    ///   land there, and a display-list rebuild can move the `VirtualView`

    ///   placements this tester translates child DOMs by. It also guarantees

    ///   the invariant that actually matters: at the START of every op the

    ///   tester agrees with the frame on screen. A stale tester does not fail

    ///   loudly — it silently answers with the WRONG node, which is worse than

    ///   the `unsupported` refusal this replaced.

            );

    /// Port of `PlatformWindow::update_hit_test_at`

    /// (`dll/src/desktop/shell2/common/event.rs`): resolve the pointer position

    /// to nodes and publish the result on the hover manager, which is where

    /// `determine_all_events` reads the mouse target from and where

    /// `CallbackInfo::get_hit_node` / text selection look it up.

    ///

    /// The CPU→`FullHitTest` conversion is the SAME function the desktop

    /// shells' `perform_hit_test` uses

    /// ([`azul_layout::headless::convert_cpu_hit_test_to_full`]) — not a

    /// re-derivation.

        use azul_layout::managers::hover::InputPointId;

            )

        };

    /// Publish one hit test per live touch point and drive the gesture

    /// manager's per-finger sessions.

    ///

    /// This is the port of the X11 XI2 touch handler

    /// (`dll/src/desktop/shell2/linux/x11/mod.rs`), which does exactly these

    /// two things next to writing `touch_state`: it feeds

    /// `gesture_drag_manager.touch_down/touch_move/touch_up` (what

    /// `detect_pinch` / `detect_rotation` / `detect_swipe_direction` consume)

    /// and lets the state-diff pass derive the touch events.

    ///

    /// DELIBERATE DEVIATION: the shells pass the pointer's SCREEN position as

    /// the second coordinate; a headless window has no screen, so the window

    /// position is reused. Only multi-window gesture bookkeeping reads it.

        use azul_layout::managers::hover::InputPointId;

                )

            };

                ),

            }

        }

        }

    /// Drop the hover history of every touch point that is no longer down.

    ///

    /// Runs at the END of [`Runner::service`], not inside

    /// [`Runner::sync_touch_points`]: `determine_all_events` resolves the

    /// TARGET of a `TouchEnd` through that history, so purging before the pass

    /// would send every touch-up to the mouse target instead of to the node the

    /// finger was actually on. Purging afterwards keeps

    /// `HoverManager::hover_histories` from growing one entry per touch id

    /// forever, which is exactly the kind of per-interaction growth the

    /// `[idle/growth]` family exists to catch.

        use azul_layout::managers::hover::InputPointId;

    /// Apply the `CallbackChange`s the runner pushed this pump, then finish the

    /// frame the way the platform event loop does.

    ///

    /// `needs_update` is the debug-op `needs_update` flag: the DLL's debug timer

    /// returns `Update::RefreshDom` for it, which the event loop turns into a

    /// full `regenerate_layout()`.

        // Each change is applied IN ORDER, as it is drained — NOT collapsed into

        // "the last one wins". The real shell runs `apply_user_change` once per

        // change and takes the MAX of the results; collapsing loses transient

        // states (a `key_down`+`key_up` pair that lands in a single continuation

        // slice would leave only the key-RELEASED state, and Tab-to-focus-next

        // would silently do nothing).

        // The redraw the PREVIOUS frame asked for (see `pending_redraw`). The

        // platform loops service `request_redraw()` on the next turn of the

        // loop, which is exactly here — and it is the only thing that lets a

        // time-driven animation advance across a step that pushes no change of

        // its own (`wait`).

        } else {

        };

        // Timers, AFTER this pass's changes: an op that ARMS a timer (focusing a

        // contenteditable arms the caret blink) has to have armed it before the

        // pump looks, or the timer would always be one op late.

        // A pending mount/unmount always needs the DOM rebuilt, even if the op

        // that produced it somehow did not set `needs_update`. (`RemountDom`

        // already returns `ShouldRegenerateDomCurrentWindow` from

        // `apply_user_change`; this covers a mount left dirty by an earlier

        // pass that never got to regenerate.)

        // RESIZE POLICY (user ruling 2026-08-08) — the same decision every

        // desktop shell makes, through the same LayoutWindow fn, so the corpus

        // tests exactly what the shells run. A DPI change is always a full

        // regeneration; a size change re-invokes layout() only when a recorded

        // window-size query answer flips or a CSS breakpoint / orientation is

        // crossed. Everything else re-flows the existing StyledDom.

            );

            } else {

            });

            ProcessEventResult::ShouldRegenerateDomCurrentWindow

            // The name IS the contract. A paint-only restyle (`:hover` /

            // `:focus` changing a colour) mutates the styled DOM's property

            // cache and asks for exactly this — but the DISPLAY LIST still

            // carries the old paint, so rendering without rebuilding it shows

            // the pre-restyle pixels and reports zero damage.

            //

            // This was invisible while every pointer op set `needs_update`: the

            // forced `regenerate_layout()` rebuilt the display list as a side

            // effect, so `:hover` appeared to work for the wrong reason. With

            // the op no longer fabricating that rebuild, the arm has to do the

            // work its own name promises.

            //

            // `UpdateHitTesterAndProcessAgain` is grouped here because it ranks

            // ABOVE `ShouldUpdateDisplayListCurrentWindow` in

            // `ProcessEventResult`'s order — it may never do less work than the

            // result it dominates. (The real shells map it to a full

            // regeneration; a display-list rebuild is the floor, not the cap.)

            ProcessEventResult::ShouldUpdateDisplayListCurrentWindow

        }

        // Keep servicing the redraws the frames themselves ask for, until the

        // window stops changing. The platform loops do this across turns of the

        // event loop; here it has to happen INSIDE one `service()`, because the

        // next thing the pump runs is the scenario's next step — and if that

        // step is an idleness assertion, it reads whatever this call left

        // behind. The scrollbar fade is 700 ms of WALL CLOCK (`fade_delay` 500 +

        // `fade_duration` 200) and each headless frame costs about a

        // millisecond, so this is a real-time-paced loop, exactly like a shell

        // redrawing at the display's rate — not a spin that fabricates time.

        // The frame is now final for this op. Re-derive the pointer→node map

        // from it so the NEXT op's hit test cannot read geometry that a

        // display-list-only path (the render-only arms above) just moved. See

        // [`Runner::rebuild_hit_tester`].

    /// Arm the caret / selection tween driver if the display-list pass this

    /// frame ran left a tween in flight — port of the shared site at the tail

    /// of the DLL's `process_window_events`

    /// (`dll/src/desktop/shell2/common/event.rs`). The timer self-terminates

    /// via its `RefAny`'d flag when the tween finishes, so there is no matching

    /// stop call.

    ///

    /// PLACEMENT DIFFERS FROM THE DLL ON PURPOSE. The DLL arms inside the event

    /// pass because a shell's frame ends there; this host's frame ends in

    /// [`Runner::service`], and the ops that move a caret (`text_input`,

    /// `move_cursor`, `set_text_selection`) reach `apply_user_change` straight

    /// from `service` without a state-diff pass. Arming inside

    /// `process_window_events` alone would leave every op-driven tween

    /// un-driven — which is indistinguishable, from a scenario, from the tween

    /// not existing.

        use azul_core::task::CARET_TWEEN_TIMER_ID;

        {

    /// Run every timer that is due, i.e. the timer half of the DLL's

    /// `PlatformWindow::process_timers_and_threads` +

    /// `PlatformWindow::invoke_expired_timers`

    /// (`dll/src/desktop/shell2/common/event.rs`).

    ///

    /// WHY IT EXISTS: `AddTimer` / `RemoveTimer` / `StartCursorBlinkTimer` /

    /// `StopCursorBlinkTimer` were all declared `unsupported("no timer driver")`

    /// — every one of `LayoutWindow`'s pieces (`tick_timers`, `run_single_timer`,

    /// `time_until_next_timer_ms`) existed, but nothing in this host ever drove

    /// them. Caret blink was therefore untestable and any behaviour that only

    /// happens on a timer expiry could not be expressed as a scenario.

    ///

    /// TIME. `Instant::now()` honours the thread-scoped test clock that the

    /// `tick_ms` op advances (`azul_core::task::advance_test_clock_ms`), so a

    /// scenario drives timers by *asserting* time rather than by sleeping

    /// through it: `tick_ms 600` expires a 530 ms blink, deterministically, in

    /// microseconds.

    ///

    /// READINESS is decided by `Timer::invoke`, not here — `tick_timers`

    /// deliberately returns every registered timer and `invoke` returns

    /// `DoNothing`/`Continue` for one whose delay or interval has not elapsed.

    /// That is why pumping on every `service()` is cheap and correct rather

    /// than a spin.

    ///

    /// The `Update` a timer callback returns is NOT the only way a rebuild gets

    /// requested (465060f5b): `apply_user_change` runs a whole event pass for

    /// `ModifyWindowState` / `CreateTextInput`, and a user callback dispatched

    /// inside it can itself return `Update::RefreshDom`, which surfaces as a

    /// `ShouldRegenerateDom*` RESULT. Folding both into one `max` is what keeps

    /// a requested DOM rebuild from being downgraded to a relayout of the DOM it

    /// was supposed to replace — the bug just fixed on the DLL side.

        use azul_core::callbacks::Update;

        use azul_core::task::TimerId;

            // Applied IMMEDIATELY, before the next timer runs, so inter-timer

            // visibility works: a timer that removes another timer must actually

            // have removed it by the time that one is reached. (A `Timer` that

            // asked to terminate arrives here as a `RemoveTimer` change appended

            // by `run_single_timer` itself.)

        }

    /// Service the redraws a rendered frame asked for (`pending_redraw`), until

    /// the window stops changing.

    ///

    /// The cap is a SAFETY NET for a flag that never clears, not the expected

    /// exit: the scrollbar fade is driven by a monotonic clock, so it always

    /// terminates on its own. Hitting the cap deliberately leaves the state

    /// machine visibly un-settled rather than hanging the run — which is the

    /// outcome `assert_state_machines_idle` exists to report.

        const MAX_REDRAW_FRAMES: usize = 4096;

    /// Port of `PlatformWindow::process_window_events`

    /// (`dll/src/desktop/shell2/common/event.rs`) — the state-diff pass, and the

    /// thing `FrameReport::relayout_iterations` counts.

    ///

    /// The DLL records `max(depth + 1)` in an observability wrapper around this

    /// function and sets `hit_depth_cap` when the recursion is broken off at

    /// `MAX_EVENT_RECURSION_DEPTH`. Both are ported here VERBATIM, because the

    /// number an assertion reads has to mean the same thing in both hosts:

    ///

    /// * `0` — no event pass ran at all. That is what an idle frame looks like:

    ///   a clock tick with no state delta produces a repaint and nothing else.

    /// * `1` — one pass, converged.

    /// * `>1` — the pass had to be re-entered (a callback changed state that

    ///   raised new events); this is the invalidation-loop signal.

    ///

    /// Before this existed the runner hard-coded `1` inside the

    /// `ModifyWindowState` arm, so an idle frame reported the same number as a

    /// converged event pass and `assert_work_bounded` could not tell "no work"

    /// from "one pass of work".

    ///

    /// The pass itself mirrors the DLL's ordering: determine events → `:hover`

    /// restyle → user callbacks → click-to-focus → keyboard default action →

    /// focus events → re-entry. It used to run ONLY the keyboard branch, which

    /// is why no pointer op could focus a node headlessly.

        #[allow(clippy::cast_possible_truncation)]

            // The DLL log_warn's here and returns; the flag is what turns that

            // silent cap into a red assertion.

        // ── 1. EVENT DETERMINATION ───────────────────────────────────────

        //

        // `determine_all_events` is the ONLY thing that turns a window-state

        // delta into events. It reads the pointer target off the hover

        // manager, which the callers of this pass (`ModifyWindowState`,

        // `QueueWindowStateSequence`, `RequestHitTestUpdate`) fill in via

        // `update_hit_test_at` — exactly as the DLL's platform layer does

        // before calling `process_window_events`.

            ];

            )

        };

        // Clear the one-shot pending-event flags now that this pass has

        // collected them — one event per change, not one per frame (the DLL

        // does this at the same point, right after determination).

        // ── 2. INCREMENTAL `:hover` RESTYLE ──────────────────────────────

        // Enter/leave targets of THIS pass, restyled now so pure-CSS `:hover`

        // rules take effect without a DOM regeneration.

        {

                };

            }

        }

        // The hit test the callbacks (and the click-to-focus pass below) see.

        // ── 3. USER CALLBACK DISPATCH (W3C capture → target → bubble) ────

        // The wheel delta has now been delivered; clear it so no later pass

        // re-fires a stale Scroll event.

            azul_core::callbacks::Update::RefreshDom

                | azul_core::callbacks::Update::RefreshDomAllWindows

        // ── 3b. POST-CALLBACK TEXT INPUT ─────────────────────────────────

        //

        // Port of the DLL's `post_callback_filter_system_changes` →

        // `SystemChange::ApplyPendingTextInput` → `ApplyTextChangeset` tail.

        // The DECISION is not re-derived here: the same `azul_core` function

        // both hosts call answers it.

        //

        // THIS STAGE DID NOT EXIST. Text recorded but not yet applied — which

        // is what a native shell has at this point in the pass, because it

        // calls `record_text_input` BEFORE running the pass — was never landed

        // by this host, and a callback's `prevent_default()` never killed a

        // recorded edit either. The e2e corpus could reach text only through

        // `CallbackChange::CreateTextInput`, whose own arm records, dispatches

        // and applies in one go; a KeyDown handler's veto is structurally

        // invisible to that shape, so no scenario could express the thing every

        // shell does on every keystroke.

        {

            use azul_core::events::SystemChange;

            );

            {

                    } else {

                    });

                    );

        }

        // ── 4. MOUSE CLICK-TO-FOCUS (W3C default action) ─────────────────

        // The deepest focusable ancestor of the deepest hit node takes focus

        // on MouseDown. This is the default action that makes `click` able to

        // focus anything at all — before the hit tester was wired, the ONLY

        // way to move focus headlessly was Tab.

        {

                    };

                    }

                }

        // ── 5. KEYBOARD DEFAULT ACTIONS (Tab / Shift+Tab / Escape) ───────

        // Gated on a KeyDown in THIS pass, like the DLL. Before that gate

        // existed the runner re-ran the action on every recursion level, so a

        // single Tab walked the focus ring MAX_EVENT_RECURSION_DEPTH times and

        // set `hit_depth_cap` on every key press (it only produced the right

        // answer because 7 steps over 3 focusables is a net +1).

        // ── 6. FOCUS EVENTS + RE-ENTRY ───────────────────────────────────

        {

            // Collapse any selection: standard UI behaviour on focus change.

                    azul_core::callbacks::Update::RefreshDom

                        | azul_core::callbacks::Update::RefreshDomAllWindows

            // CRITICAL (verbatim from the DLL): advance the sync baseline

            // BEFORE recursing, or the SAME MouseDown / Tab is re-detected at

            // depth+1 and its default action fires again on every level.

        // TEXT-EDIT NOTIFICATIONS (port of the DLL's drain): edits committed

        // outside the text-input record pipeline dispatch their Input event

        // here, so `On::Input` observes deletions and line breaks too.

        {

                        )

        }

        // Finalize pending focus changes (caret init for contenteditable) —

        // the DLL's end-of-pass `SystemChange::FinalizePendingFocusChanges`.

        // DELIBERATE DEVIATION, floored not faithful: the DLL returns `result`

        // as-is, so a pass whose events changed nothing observable returns

        // DoNothing and the shell skips the frame. This host's damage

        // machinery is fed by `render_and_record` (see `Runner::service`), and

        // an event pass that produced no frame at all leaves the frame report

        // describing the PREVIOUS op. Flooring at "repaint" costs an extra

        // no-damage render and never hides one.

    /// Port of the DLL's `apply_system_change(SystemChange::SetFocus { .. })`:

    /// move focus, scroll the new node into view, and apply the `:focus`

    /// restyle so focus styling lands on THIS frame instead of the next resize.

        use azul_layout::managers::scroll_into_view::ScrollIntoViewOptions;

    /// Port of `PlatformWindow::dispatch_events_propagated`

    /// (`dll/src/desktop/shell2/common/event.rs`): plan the callback

    /// invocations for a batch of `SyntheticEvent`s using the W3C

    /// capture→target→bubble model, invoke them, then apply every

    /// `CallbackChange` they produced through [`Runner::apply_user_change`].

    ///

    /// Returns `(max ProcessEventResult, merged Update, any preventDefault)`.

    /// `preventDefault` is what suppresses the click-to-focus and keyboard

    /// default actions above, so this cannot be short-circuited to "no

    /// callbacks exist in an XML mount" — a scenario that mounts a component

    /// carrying callbacks would then silently take the default action anyway.

    #[allow(clippy::too_many_lines)]

        use azul_core::{

            callbacks::{CoreCallbackData, Update},

            events::EventFilter,

            id::NodeId as CoreNodeId,

        };

        struct PlannedInvocation {

            dom_id: DomId,

            node_id: NodeId,

            callback_data: CoreCallbackData,

        }

        // Phase 1 — build the dispatch plan (read-only over the layout window).

                        EventFilter::Hover(_) => {

                            };

                            };

                            }

                            );

                                };

                                }

                            }

                        }

                        EventFilter::Focus(_) => {

                            // Focus events fire on the focused node only.

                            };

                            };

                            }

                        }

                        EventFilter::Window(_) | EventFilter::Application(_) => {

                            // Window / Application events fire on EVERY node

                            // carrying a matching callback.

                                    }

                                }

                            }

                        }

                        EventFilter::Component(_) => {

                            // Lifecycle events carry their target node; no

                            // propagation.

                            };

                            };

                            }

                        }

                    }

                }

            }

        };

        // Phase 2 — invoke.

            // W3C stopPropagation: remaining handlers on the SAME node still

            // run; the first handler on a different node ends the dispatch.

            {