From 77aad83917f6a221ff3fe2db95ea3cf870c8870f Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:14:27 +0700
Subject: [PATCH 01/13] fix(agent): a header cell is a header, not a cell

`semantic_role` mapped `td` and `th` to the same `cell`, so every table in the
fleet arrived with no way to tell a column's title from a value under it. A
check that means "the Version column" had nothing to ask for.

HTML-AAM maps `<th>` to `columnheader` or `rowheader` by its `scope`, and
blitz-dom's own accessibility tree already does this in
`packages/blitz-dom/src/accessibility.rs`. The two trees over the same document
disagreed; this makes them agree, including the fallback to `columnheader` when
no `scope` is written, which is the ordinary `<thead>` case.
---
 crates/tauri-runtime-blitz/src/agent.rs | 88 ++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index 785784d..d2f6e6b 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -508,7 +508,22 @@ pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
         "li" => "listitem",
         "table" => "table",
         "tr" => "row",
-        "td" | "th" => "cell",
+        "td" => "cell",
+        // A header cell is not a cell.
+        //
+        // HTML-AAM maps `<th>` to `columnheader` or `rowheader`, and blitz-dom's
+        // own accessibility tree already does exactly this, so the two trees
+        // disagreed about the same document. What a header is for is saying
+        // which column or row the values under it belong to, and a check that
+        // wants "the Version column" has nothing to ask for while every header
+        // is spelled the same as the data beneath it.
+        //
+        // `scope` decides. Without one this is a column header, which is the
+        // common case (a `<thead>` row) and what blitz-dom falls back to.
+        "th" => match element_attr(element, "scope") {
+            Some("row") | Some("rowgroup") => "rowheader",
+            _ => "columnheader",
+        },
         "h1" | "h2" | "h3" | "h4" | "h5" | "h6" => "heading",
         "input" => match element_attr(element, "type").unwrap_or("text") {
             "checkbox" => "checkbox",
@@ -1853,3 +1868,74 @@ mod tests {
         );
     }
 }
+
+/// What the semantic tree says about one small document.
+///
+/// Every test here reads the tree through `inspect_document`, which is the
+/// entry point a headless QA host calls, rather than through the naming
+/// helpers directly. A role or a name that is right inside the crate and wrong
+/// by the time it reaches the socket is the defect these were written for.
+#[cfg(all(test, feature = "agent-control", unix))]
+mod semantic_tests {
+    use super::*;
+    use blitz_dom::DocumentConfig;
+
+    /// One document, reproducing every naming and role defect this module
+    /// covers. Kept whole rather than split per test so a fix that repairs one
+    /// case by breaking another is caught by the next assertion down.
+    const REPRO: &str = r#"<table aria-label="named table">
+  <thead><tr><th scope="col">Crate</th></tr></thead>
+  <tbody><tr><td>worktable</td></tr></tbody>
+</table>
+<section aria-label="a named section"><p>text</p></section>
+<datalist id="t"><option value="u64"></option></datalist>
+<pre>plain text in a pre</pre>
+<div role="tooltip">tooltip text</div>"#;
+
+    fn tree(html: &str) -> Vec<SemanticNode> {
+        let mut document = ScriptDocument::from_html(html, DocumentConfig::default());
+        document.inner_mut().resolve(0.0);
+        match inspect_document(&mut document, None, 0, 1) {
+            DebugResponse::AgentSnapshot(snapshot) => snapshot.nodes,
+            other => panic!("inspection did not answer with a tree: {other:?}"),
+        }
+    }
+
+    fn roles<'a>(nodes: &'a [SemanticNode], role: &str) -> Vec<&'a SemanticNode> {
+        nodes.iter().filter(|node| node.role == role).collect()
+    }
+
+    fn names(nodes: &[SemanticNode], role: &str) -> Vec<String> {
+        roles(nodes, role)
+            .into_iter()
+            .map(|node| node.name.clone())
+            .collect()
+    }
+
+    #[test]
+    fn a_header_cell_is_a_header() {
+        let nodes = tree(REPRO);
+        assert_eq!(
+            roles(&nodes, "columnheader").len(),
+            1,
+            "a `<th scope=\"col\">` is a column header, not an ordinary cell"
+        );
+        assert_eq!(
+            roles(&nodes, "cell").len(),
+            1,
+            "only the `<td>` is a cell"
+        );
+    }
+
+    #[test]
+    fn a_row_scoped_header_is_a_row_header() {
+        let nodes = tree(
+            r#"<table><tr><th scope="row">Crate</th><td>worktable</td></tr></table>"#,
+        );
+        assert_eq!(
+            roles(&nodes, "rowheader").len(),
+            1,
+            "`scope=\"row\"` makes a header describe its row, which is what blitz-dom reports"
+        );
+    }
+}

From e7f68baf9d1c547b0373d24fd984c21e735c0e74 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:16:18 +0700
Subject: [PATCH 02/13] fix(agent): name a cell, a header and a row from their
 contents

The role list in `semantic_name` said `cell` and `row` were deliberately absent
because their content is a whole subtree. That objection belongs to `generic`,
not to these: ARIA gives `cell`, `gridcell`, `columnheader`, `rowheader` and
`row` nameFrom author and contents, and a row's name being the run of its cells
is what a screen reader announces when the caret enters the row.

The cost of leaving them out was every table in the fleet. `<td>worktable</td>`,
a direct text child, came back as `cell ""`, so a table of crate names, versions
and column types was a grid of anonymous boxes. Two site suites reported their
tables as absent from the accessibility tree; the nodes were there and every one
of them was nameless, which from outside is the same thing.

The list moves to `names_from_contents` because the text walker needs the same
answer, and a role list written twice goes stale once.
---
 crates/tauri-runtime-blitz/src/agent.rs | 125 +++++++++++++++---------
 1 file changed, 80 insertions(+), 45 deletions(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index d2f6e6b..c9cd8c7 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -701,6 +701,60 @@ fn name_text(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument) -> Stri
     out
 }
 
+/// Whether a role takes its accessible name from its own subtree when the
+/// author wrote no explicit one.
+///
+/// ARIA's *nameFrom: author, contents*, and nothing else. The list is closed on
+/// purpose: a role that is not on it is named only by what the author declared,
+/// because a container's text content is its whole subtree and naming those
+/// would give every wrapper on a page a name made of the page.
+///
+/// `alert` and `status` are here because they are the roles an application uses
+/// to say something happened -- a refusal, a saved confirmation -- and what they
+/// say is their content. Without them a live region arrives anonymous, so "the
+/// reason is shown" is not a question a suite can ask, and every validation
+/// outcome has to be approximated by something else that moved.
+///
+/// `menuitem`, `tab` and `treeitem` are the menu, tab and tree equivalents of
+/// `option`. Leaving them out made every dropdown item in the fleet anonymous:
+/// a `<button role="menuitem">Platform Admin</button>` came back with an empty
+/// name, so nothing was announced and no check could name the option it meant
+/// to press.
+///
+/// The table roles are here because ARIA gives all five of them
+/// *nameFrom: contents*, and their absence is why whole tables of crate names,
+/// versions and column types were unreadable: the cells were in the tree and
+/// every one of them was anonymous, which reads from outside as a table that is
+/// not in the tree at all. A row's name being the run of its cells is not an
+/// accident of that rule, it is the rule: it is what a screen reader announces
+/// when the caret enters the row.
+///
+/// `semantic_role` returns a `role` attribute verbatim, so an author who writes
+/// one of these opts into the naming this list provides.
+#[cfg(all(feature = "agent-control", unix))]
+pub(crate) fn names_from_contents(role: &str) -> bool {
+    matches!(
+        role,
+        "button"
+            | "link"
+            | "heading"
+            | "option"
+            | "alert"
+            | "status"
+            | "menuitem"
+            | "menuitemcheckbox"
+            | "menuitemradio"
+            | "tab"
+            | "treeitem"
+            | "cell"
+            | "gridcell"
+            | "columnheader"
+            | "rowheader"
+            | "row"
+    )
+}
+
+#[cfg(all(feature = "agent-control", unix))]
 pub(crate) fn semantic_name(
     element: &blitz_dom::ElementData,
     node: &blitz_dom::Node,
@@ -722,46 +776,8 @@ pub(crate) fn semantic_name(
         .or_else(|| element_attr(element, "alt").map(std::borrow::Cow::Borrowed))
         .or_else(|| element_attr(element, "title").map(std::borrow::Cow::Borrowed))
         // Named by their own content.
-        //
-        // `alert` and `status` are here because they are the roles an
-        // application uses to say something happened -- a refusal, a saved
-        // confirmation -- and what they say is their content. Without them a
-        // live region arrives anonymous, so "the reason is shown" is not a
-        // question that can be asked, and every validation outcome in a suite
-        // has to be approximated by something else that moved.
-        //
-        // Deliberately not `generic`. A wrapper's text content is its entire
-        // subtree, so naming those would give every container on the page a
-        // name made of the whole page.
         .or_else(|| {
-            matches!(
-                role,
-                "button"
-                    | "link"
-                    | "heading"
-                    | "option"
-                    | "alert"
-                    | "status"
-                    // The menu, tab and tree equivalents of `option`. ARIA names all
-                    // of these from their own content, and leaving them out
-                    // made every dropdown item in the fleet anonymous: a
-                    // `<button role="menuitem">Platform Admin</button>` came
-                    // back with an empty name, so a screen reader announced
-                    // nothing and no check could name the option it meant to
-                    // press. `semantic_role` returns the `role` attribute
-                    // verbatim, so an author who writes one of these opts out
-                    // of the native naming this list is meant to provide.
-                    //
-                    // Still deliberately absent: `cell` and `row`. Their
-                    // content is a whole subtree, which is the same objection
-                    // the comment above raises against `generic`.
-                    | "menuitem"
-                    | "menuitemcheckbox"
-                    | "menuitemradio"
-                    | "tab"
-                    | "treeitem"
-            )
-            .then(|| std::borrow::Cow::Owned(name_text(node, document)))
+            names_from_contents(role).then(|| std::borrow::Cow::Owned(name_text(node, document)))
         })
         // A placeholder is the last resort a browser falls back to, and it is
         // the only thing naming a great many search and filter fields. Last, so
@@ -1920,18 +1936,37 @@ mod semantic_tests {
             1,
             "a `<th scope=\"col\">` is a column header, not an ordinary cell"
         );
+        assert_eq!(roles(&nodes, "cell").len(), 1, "only the `<td>` is a cell");
+    }
+
+    #[test]
+    fn a_cell_is_named_by_what_it_holds() {
+        let nodes = tree(REPRO);
         assert_eq!(
-            roles(&nodes, "cell").len(),
-            1,
-            "only the `<td>` is a cell"
+            names(&nodes, "cell"),
+            vec!["worktable".to_string()],
+            "a data cell's text is its accessible name, so a table of values is readable"
+        );
+        assert_eq!(
+            names(&nodes, "columnheader"),
+            vec!["Crate".to_string()],
+            "a header cell is named by its content too"
         );
     }
 
     #[test]
-    fn a_row_scoped_header_is_a_row_header() {
-        let nodes = tree(
-            r#"<table><tr><th scope="row">Crate</th><td>worktable</td></tr></table>"#,
+    fn a_row_is_named_by_its_cells() {
+        let nodes = tree(REPRO);
+        assert_eq!(
+            names(&nodes, "row"),
+            vec!["Crate".to_string(), "worktable".to_string()],
+            "a row is named from its contents, which is what makes a table row addressable"
         );
+    }
+
+    #[test]
+    fn a_row_scoped_header_is_a_row_header() {
+        let nodes = tree(r#"<table><tr><th scope="row">Crate</th><td>worktable</td></tr></table>"#);
         assert_eq!(
             roles(&nodes, "rowheader").len(),
             1,

From b887eb004119a2e966695f2f84c3592dfe7dcb74 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:17:06 +0700
Subject: [PATCH 03/13] fix(agent): a named section is a region

`semantic_role` had no `section` arm, so `<section aria-label="a named
section">` arrived as `generic` with a name on it. HTML-AAM maps a `<section>`
with an accessible name to `region` and one without to `generic`, and both
halves are load-bearing: the named case is how a page says which part of itself
this is, and promoting the unnamed case would put a landmark around every block
on a page that uses `<section>` as a synonym for `<div>`.

Decided from attributes rather than from the computed name, because the name is
not known at this point and computing it here would walk a section's whole
subtree once per element in the document. `aria-labelledby` counts towards the
landmark even though `semantic_name` does not yet resolve that reference, which
is a gap in naming rather than a reason to withhold the role.

blitz-dom reports `Role::Section` for every `<section>`; that is the one place
in this change where the two trees do not converge, and the HTML-AAM rule is
the one a QA suite and a screen reader both act on.
---
 crates/tauri-runtime-blitz/src/agent.rs | 44 +++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index c9cd8c7..f3efa32 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -503,6 +503,30 @@ pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
         "img" => "img",
         "nav" => "navigation",
         "main" => "main",
+        // A named section is a landmark; an unnamed one is nothing.
+        //
+        // HTML-AAM: `<section>` maps to `region` when it has an accessible
+        // name, and to `generic` otherwise. Both halves matter. A named section
+        // is how a page says "this part is the connection settings", and it
+        // arrived indistinguishable from the `<div>`s around it; an unnamed one
+        // is a wrapper, and promoting those would put a landmark around every
+        // block on a page that reaches for `<section>` as a synonym for `<div>`.
+        //
+        // Attributes only, because the name has not been computed yet at this
+        // point and computing it here would walk the section's whole subtree for
+        // every element in the document. That is the same set an accessible name
+        // can come from for a container: `aria-labelledby` is included so an
+        // author who names a section that way still gets the landmark, even
+        // though `semantic_name` does not yet resolve that reference.
+        "section"
+            if ["aria-label", "aria-labelledby", "title"]
+                .iter()
+                .any(|name| {
+                    element_attr(element, name).is_some_and(|value| !value.trim().is_empty())
+                }) =>
+        {
+            "region"
+        }
         "form" => "form",
         "ul" | "ol" => "list",
         "li" => "listitem",
@@ -1973,4 +1997,24 @@ mod semantic_tests {
             "`scope=\"row\"` makes a header describe its row, which is what blitz-dom reports"
         );
     }
+
+    #[test]
+    fn a_named_section_is_a_region() {
+        let nodes = tree(REPRO);
+        assert_eq!(
+            names(&nodes, "region"),
+            vec!["a named section".to_string()],
+            "a `<section>` with an accessible name is a landmark, not a wrapper"
+        );
+    }
+
+    #[test]
+    fn an_unnamed_section_is_not_a_region() {
+        let nodes = tree("<section><p>text</p></section>");
+        assert!(
+            roles(&nodes, "region").is_empty(),
+            "HTML-AAM gives an unnamed section no landmark role, so a page of \
+             plain sections does not grow a landmark per wrapper"
+        );
+    }
 }

From fc63a32049bedfabc671d7199d106a3640cdcd32 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:17:45 +0700
Subject: [PATCH 04/13] fix(agent): name a tooltip by what it says

`role="tooltip"` was not on the nameFrom-contents list, so a tooltip arrived as
a node saying that some explanation is on screen without saying what the
explanation is. ARIA names a tooltip from its contents, and this is the same
class of finding as the live region one: the roles whose entire purpose is to
say one thing were the roles that reported nothing.
---
 crates/tauri-runtime-blitz/src/agent.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index f3efa32..dd079e9 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -765,6 +765,11 @@ pub(crate) fn names_from_contents(role: &str) -> bool {
             | "option"
             | "alert"
             | "status"
+            // The same class as `alert` and `status`: a tooltip exists to say
+            // one thing, and what it says is its content. Anonymous, it is a
+            // node reporting that some explanation is on screen without
+            // reporting the explanation.
+            | "tooltip"
             | "menuitem"
             | "menuitemcheckbox"
             | "menuitemradio"
@@ -2008,6 +2013,16 @@ mod semantic_tests {
         );
     }
 
+    #[test]
+    fn a_tooltip_says_what_it_says() {
+        let nodes = tree(REPRO);
+        assert_eq!(
+            names(&nodes, "tooltip"),
+            vec!["tooltip text".to_string()],
+            "a tooltip is named by its contents, and its contents are the whole point of it"
+        );
+    }
+
     #[test]
     fn an_unnamed_section_is_not_a_region() {
         let nodes = tree("<section><p>text</p></section>");

From 664794849b6db35a2214db1b552e9941ba0ea707 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:18:59 +0700
Subject: [PATCH 05/13] fix(agent): an option with no text is named by its
 label, then its value

`<option value="u64">` is how a `<datalist>` is written, and naming an option
from its contents alone left every entry in one anonymous. HTML resolves an
option's label as the `label` attribute if present, then the option's text, and
browsers fall back to `value` when there is neither, which is what a person sees
in the list.

Empty contents no longer end the search either. The contents arm returned
`Some("")` for a role on the nameFrom-contents list, which stopped the chain and
made every fallback below it unreachable.
---
 crates/tauri-runtime-blitz/src/agent.rs | 47 ++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index dd079e9..b62f29d 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -804,9 +804,34 @@ pub(crate) fn semantic_name(
         })
         .or_else(|| element_attr(element, "alt").map(std::borrow::Cow::Borrowed))
         .or_else(|| element_attr(element, "title").map(std::borrow::Cow::Borrowed))
+        // An option's `label`, which HTML gives precedence over the option's
+        // own text: `<option label="Sixty four bits">u64</option>` announces the
+        // label.
+        .or_else(|| {
+            (role == "option")
+                .then(|| element_attr(element, "label"))
+                .flatten()
+                .map(std::borrow::Cow::Borrowed)
+        })
         // Named by their own content.
+        //
+        // Empty contents are not a name, and stopping here on an empty string
+        // is how the fallbacks below became unreachable for the roles on this
+        // list.
+        .or_else(|| {
+            names_from_contents(role)
+                .then(|| name_text(node, document))
+                .filter(|text| !text.trim().is_empty())
+                .map(std::borrow::Cow::Owned)
+        })
+        // What is left of an option that carries no text at all: a
+        // `<datalist>` entry is written `<option value="u64">`, and its value is
+        // what a browser announces and what a person sees in the list.
         .or_else(|| {
-            names_from_contents(role).then(|| std::borrow::Cow::Owned(name_text(node, document)))
+            (role == "option")
+                .then(|| element_attr(element, "value"))
+                .flatten()
+                .map(std::borrow::Cow::Borrowed)
         })
         // A placeholder is the last resort a browser falls back to, and it is
         // the only thing naming a great many search and filter fields. Last, so
@@ -2013,6 +2038,26 @@ mod semantic_tests {
         );
     }
 
+    #[test]
+    fn a_value_only_option_is_named_by_its_value() {
+        let nodes = tree(REPRO);
+        assert_eq!(
+            names(&nodes, "option"),
+            vec!["u64".to_string()],
+            "a `<datalist>` option carries its text in `value`, which is what a browser announces"
+        );
+    }
+
+    #[test]
+    fn an_options_label_attribute_wins_over_its_text() {
+        let nodes = tree(r#"<select><option label="Sixty four bits">u64</option></select>"#);
+        assert_eq!(
+            names(&nodes, "option"),
+            vec!["Sixty four bits".to_string()],
+            "HTML gives `label` precedence over an option's own text"
+        );
+    }
+
     #[test]
     fn a_tooltip_says_what_it_says() {
         let nodes = tree(REPRO);

From 2f8f214856ee814da6321608162f3d77bda6ba8b Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:20:09 +0700
Subject: [PATCH 06/13] fix(agent): a name is made of what is rendered

A control with a short label for narrow viewports and a long one for wide ones
writes both and shows one. `sm:hidden` on the first and `hidden sm:inline` on
the second came back as "Book Book a diagnostic": a name no viewer sees at any
width, and one no check can be written against, because the string it asserts
depends on which half the author expected to win.

`name_text` now skips an element child that is not rendered, which is
`display: none`, `visibility: hidden`, the `hidden` attribute and
`aria-hidden="true"` -- the set `node_is_individually_visible` already answers,
and the set accname states directly. Text nodes are not filtered: a text node
has no display of its own and is present exactly when the element holding it is.

`LabelIndex` reads its labels the same way, through `name_text` rather than
`textContent`. A label becomes a name the moment it reaches a control, so the
half of a responsive label that is not rendered, and a `<style>` inside one, had
to be left out on that path too.
---
 crates/tauri-runtime-blitz/src/agent.rs | 67 ++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index b62f29d..4b0a5e4 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -599,7 +599,11 @@ impl LabelIndex {
             if element.name.local.as_ref() != "label" {
                 continue;
             }
-            let text = node.text_content();
+            // Read the same way a name is, not with `textContent`. A label is a
+            // name once it reaches a control, so a stylesheet inside it, or the
+            // half of a responsive label that is not rendered at this width,
+            // has to be left out here too.
+            let text = name_text(node, document);
             if let Some(control) = element_attr(element, "for") {
                 by_control_id.insert(control.to_owned(), text.clone());
             }
@@ -708,6 +712,20 @@ fn name_text(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument) -> Stri
             let Some(child) = document.get_node(*child) else {
                 continue;
             };
+            // What is not rendered is not part of the name.
+            //
+            // A responsive control writes both labels and shows one:
+            // `sm:hidden` on the short one, `hidden sm:inline` on the long one.
+            // Folding both together produced "Book Book a diagnostic", a name
+            // no viewer at any width can see and no check can be written
+            // against. `visibility: hidden` and `aria-hidden` are excluded for
+            // the same reason, which is the rule accname states directly.
+            //
+            // Elements only. A text node carries no display of its own, so it
+            // is present exactly when the element holding it is.
+            if child.element_data().is_some() && !node_is_individually_visible(child) {
+                continue;
+            }
             // A boundary either side, so a block between two others is
             // separated from both. `normalize_name` collapses the runs.
             let separate = !is_inline(child);
@@ -2038,6 +2056,53 @@ mod semantic_tests {
         );
     }
 
+    /// Both halves of a responsive label, the way Tailwind writes one.
+    ///
+    /// `sm:hidden` on the short one and `hidden sm:inline` on the long one is a
+    /// single control that says "Book" on a phone and "Book a diagnostic" on a
+    /// laptop. Exactly one of them is rendered at any width, and folding both
+    /// into the name produced "Book Book a diagnostic", which matches nothing a
+    /// person can see and nothing a check can be written against.
+    const RESPONSIVE_LABEL: &str = r#"<button>
+         <span>Book</span>
+         <span style="display: none">Book a diagnostic</span>
+       </button>"#;
+
+    #[test]
+    fn a_name_skips_a_subtree_that_is_not_rendered() {
+        let nodes = tree(RESPONSIVE_LABEL);
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Book".to_string()],
+            "a display:none subtree contributes nothing to a name"
+        );
+    }
+
+    #[test]
+    fn a_name_skips_a_subtree_that_is_hidden_or_aria_hidden() {
+        let nodes = tree(
+            r#"<button>Save<span style="visibility: hidden">draft</span><span aria-hidden="true">now</span></button>"#,
+        );
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Save".to_string()],
+            "an invisible box and an aria-hidden one are both outside the name"
+        );
+    }
+
+    #[test]
+    fn a_label_skips_what_it_does_not_show() {
+        let nodes = tree(
+            r#"<label for="url">Endpoint<span style="display: none"> (advanced)</span></label>
+               <input id="url" type="text">"#,
+        );
+        assert_eq!(
+            names(&nodes, "textbox"),
+            vec!["Endpoint".to_string()],
+            "the label a control is named by is read the same way a name is"
+        );
+    }
+
     #[test]
     fn a_value_only_option_is_named_by_its_value() {
         let nodes = tree(REPRO);

From d13e5a3bf6355a2d8f3e696ad66e82252b18cf29 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:24:35 +0700
Subject: [PATCH 07/13] feat(agent): the text a page shows is in the tree

`inspect_document` skipped every node that was not an element, so text that is
not some element's accessible name could not be read at all: a paragraph, a
`<pre>`, a code block, the prose of a documentation page. A check could assert
that a control exists and not that the page says anything.

That is not only a limit on checks. A browser exposes those text runs, and so
does blitz-dom, whose accessibility tree gives every text node `Role::TextRun`
carrying its content. This tree disagreed with both, and a QA host reading it
had no way to tell "the page renders no prose" from "the tree does not carry
prose".

Exposed as `role: "text"`, with the text as the name, which is the field a
harness already matches on and the shape the ARIA snapshot formats use. A text
run has nothing to press and no state, so `enabled` is true, `selected` is false
and `value` is empty; `visible` follows the chain of boxes it is drawn in rather
than a box of its own, because a text node has no client rect.

Text that already names a node is left out. It is in the tree, as that node's
name, and that node is the one a harness can act on; reporting it twice would
make "the page says this once" false and hand a check a node it cannot click for
words it can already read. `<style>` and `<script>` content is excluded for the
reason `name_text` excludes it.

Only the agent snapshot. The diagnostics snapshot in `snapshot_document` reports
a layout and computed-style row per node, and those rows describe element boxes;
adding text runs to it would add rows with nothing in them.
---
 crates/tauri-runtime-blitz/src/agent.rs | 159 ++++++++++++++++++++++--
 1 file changed, 147 insertions(+), 12 deletions(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index 4b0a5e4..f59a9c1 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -860,9 +860,21 @@ pub(crate) fn semantic_name(
                 .flatten()
         })
         .unwrap_or_default();
-    let mut normalized = String::with_capacity(name.len().min(512));
+    normalize_text(&name)
+}
+
+/// One space between words, and 512 characters at most.
+///
+/// A name crosses a socket and is matched against by a check, so the runs of
+/// newlines and indentation that markup puts between two words are noise in
+/// both places. The cap is on the value that leaves here rather than on the
+/// text that arrives, so a name made of a long subtree still starts with the
+/// words a person would read first.
+#[cfg(all(feature = "agent-control", unix))]
+pub(crate) fn normalize_text(text: &str) -> String {
+    let mut normalized = String::with_capacity(text.len().min(512));
     let mut characters = 0;
-    for word in name.split_whitespace() {
+    for word in text.split_whitespace() {
         if !normalized.is_empty() && characters < 512 {
             normalized.push(' ');
             characters += 1;
@@ -878,6 +890,70 @@ pub(crate) fn semantic_name(
     normalized
 }
 
+/// The text a node contributes to the tree in its own right, if any.
+///
+/// # Why text is in this tree at all
+///
+/// Everything that is not an element was dropped, so text that is not some
+/// element's accessible name could not be read at all: a paragraph, a `<pre>`,
+/// a code block, the prose of a documentation page. A check could assert that a
+/// button exists and not that the page says what the button does.
+///
+/// It is not only a check limitation. A browser exposes those text runs, and so
+/// does blitz-dom, whose own accessibility tree gives every text node
+/// `Role::TextRun` with its content. This tree disagreed with both.
+///
+/// # Why not every text node
+///
+/// Text under a role that is named by its contents is already in the tree, as
+/// that node's name, and that node is the one a harness can act on. Reporting
+/// it twice would make "the page says this once" false and hand a check a node
+/// it cannot click for text it can already read. It is the rule the ARIA
+/// snapshot formats apply as well: a button carries its label, and no separate
+/// text line appears under it.
+///
+/// `<style>`, `<script>` and friends are excluded for the reason `name_text`
+/// excludes them: their content is not rendered, and reading it out returns a
+/// stylesheet.
+#[cfg(all(feature = "agent-control", unix))]
+pub(crate) fn exposed_text(
+    document: &blitz_dom::BaseDocument,
+    id: blitz_dom::NodeId,
+    node: &blitz_dom::Node,
+) -> Option<String> {
+    let blitz_dom::node::NodeData::Text(text) = &node.data else {
+        return None;
+    };
+    let normalized = normalize_text(&text.content);
+    if normalized.is_empty() {
+        return None;
+    }
+    // Every element above it, not only the nearest one: the text of
+    // `<button><span>Save</span></button>` is the button's name however many
+    // wrappers sit between the two, and the span it is written in does not make
+    // it a second appearance of the same words.
+    let mut current = document.get_node(id)?.parent;
+    for _ in 0..64 {
+        let Some(ancestor) = current else {
+            break;
+        };
+        let ancestor_node = document.get_node(ancestor)?;
+        if let Some(element) = ancestor_node.element_data() {
+            if matches!(
+                element.name.local.as_ref(),
+                "style" | "script" | "template" | "noscript" | "title"
+            ) {
+                return None;
+            }
+            if names_from_contents(&semantic_role(element)) {
+                return None;
+            }
+        }
+        current = ancestor_node.parent;
+    }
+    Some(normalized)
+}
+
 #[cfg(all(feature = "agent-control", unix))]
 fn semantic_value(element: &blitz_dom::ElementData) -> Option<String> {
     element
@@ -1186,11 +1262,36 @@ pub fn inspect_document(
         .filter_map(|candidate| {
             let id = candidate.id;
             let node = inner.get_node(id)?;
-            let element = node.element_data()?;
             if layout_validity.get(&id) != Some(&true) {
                 return None;
             }
             let rect = inner.get_client_bounding_rect(id);
+            let bounds = rect.and_then(|rect| {
+                let bounds = [rect.x, rect.y, rect.width, rect.height];
+                bounds
+                    .iter()
+                    .all(|value| value.is_finite())
+                    .then_some(bounds)
+            });
+            let Some(element) = node.element_data() else {
+                // Text the page shows in its own right. A text run has no
+                // attributes, no state and nothing to press, so every field
+                // below the name describes the box it is drawn in.
+                let text = exposed_text(&inner, id, node)?;
+                return Some(SemanticNode {
+                    dom_id: None,
+                    id: id.as_u64(),
+                    parent: candidate.parent.map(|id| id.as_u64()),
+                    role: "text".to_owned(),
+                    name: text,
+                    value: None,
+                    enabled: true,
+                    visible: candidate.visible,
+                    selected: false,
+                    bounds,
+                    slot: None,
+                });
+            };
             let visible = candidate.visible
                 && rect
                     .as_ref()
@@ -1209,13 +1310,7 @@ pub fn inspect_document(
                     && element_attr(element, "aria-disabled") != Some("true"),
                 visible,
                 selected: semantic_selected(element),
-                bounds: rect.and_then(|rect| {
-                    let bounds = [rect.x, rect.y, rect.width, rect.height];
-                    bounds
-                        .iter()
-                        .all(|value| value.is_finite())
-                        .then_some(bounds)
-                }),
+                bounds,
                 slot: element_attr(element, "data-slot").map(str::to_owned),
             })
         })
@@ -1517,7 +1612,7 @@ pub(crate) fn semantic_subtree_ids(
         let Some(node) = document.get_node(node_id) else {
             continue;
         };
-        if node.element_data().is_some() {
+        if node.element_data().is_some() || node.is_text_node() {
             out.push(node_id);
         }
         for &child_id in node.children.iter().rev() {
@@ -1687,7 +1782,10 @@ pub(crate) fn attached_semantic_candidates(
         if is_element && max_depth != 0 && depth > max_depth {
             continue;
         }
-        if is_element {
+        // Elements, and the text a page shows in its own right. `exposed_text`
+        // decides which text nodes survive; offering them all here keeps that
+        // one rule in one place, and the walk already visits them.
+        if is_element || node.is_text_node() {
             candidates.push(SemanticCandidate {
                 id,
                 parent: semantic_parent,
@@ -2056,6 +2154,43 @@ mod semantic_tests {
         );
     }
 
+    #[test]
+    fn text_the_page_shows_is_in_the_tree() {
+        let nodes = tree(REPRO);
+        assert!(
+            names(&nodes, "text").contains(&"plain text in a pre".to_string()),
+            "a `<pre>`'s text is not any element's name, so without a text node it is unreadable: \
+             {:?}",
+            names(&nodes, "text")
+        );
+    }
+
+    #[test]
+    fn text_that_already_names_a_node_is_not_repeated() {
+        let nodes = tree(REPRO);
+        let text = names(&nodes, "text");
+        assert!(
+            !text.contains(&"worktable".to_string()),
+            "the cell carries this text as its name, and the cell is the node a harness can act \
+             on: {text:?}"
+        );
+        let nodes = tree(r#"<button><span>Save</span></button>"#);
+        assert!(
+            names(&nodes, "text").is_empty(),
+            "a wrapper between a control and its text does not make the text a second node"
+        );
+    }
+
+    #[test]
+    fn a_stylesheet_is_not_text() {
+        let nodes = tree("<style>.a { color: red }</style><p>shown</p>");
+        assert_eq!(
+            names(&nodes, "text"),
+            vec!["shown".to_string()],
+            "a `<style>` is not rendered, and reading it out returns a stylesheet"
+        );
+    }
+
     /// Both halves of a responsive label, the way Tailwind writes one.
     ///
     /// `sm:hidden` on the short one and `hidden sm:inline` on the long one is a

From 5bf219d7083d2fdae1cf97a14eedb1aca56d39f6 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:25:07 +0700
Subject: [PATCH 08/13] release: 0.3.8

A version bump on master is the release trigger, and this is what carries the
semantic tree fixes to the QA hosts that read it: tables that are named rather
than a grid of anonymous boxes, header cells that say which column they head,
named sections as landmarks, and the text a page shows in its own right.

A patch bump on purpose. The role and name changes correct what a node reports
rather than change the shape of the wire type, and the new `text` node is
additive, so every consumer pinned at `^0.3` picks these up without a repin.
---
 Cargo.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Cargo.toml b/Cargo.toml
index 81f1c6c..a534be2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/tauri-runtime-blitz"]
 
 [workspace.package]
-version = "0.3.7"
+version = "0.3.8"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 publish = true

From 58554b5c42b5eaa92a2d28a28f6c4e48490a790a Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:28:22 +0700
Subject: [PATCH 09/13] perf(agent): answer a role without allocating one

Exposing text made every text node ask each element above it whether that
element is already named by those words, and the owned `semantic_role` built a
`String` per ancestor to compare against a fixed list and drop it. On a page of
a few thousand nodes that is thousands of allocations per inspection, and the
inspector is polled, not called once.

A role is either a `&'static str` or the `role` attribute's own text, so
`semantic_role_ref` hands both back borrowed and `semantic_role` is one
`to_owned` on top of it.
---
 crates/tauri-runtime-blitz/src/agent.rs | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index f59a9c1..4a3d6a6 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -490,8 +490,20 @@ pub(crate) fn element_attr<'a>(element: &'a blitz_dom::ElementData, name: &str)
 
 #[cfg(all(feature = "agent-control", unix))]
 pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
+    semantic_role_ref(element).to_owned()
+}
+
+/// The same answer without owning it.
+///
+/// A text node asks every element above it whether that element is already
+/// named by the words in question, and the owned form allocated a `String` per
+/// ancestor per text node to be compared against a fixed list and dropped. The
+/// role is either a `&'static str` or the `role` attribute's own text, so
+/// nothing here needs a copy.
+#[cfg(all(feature = "agent-control", unix))]
+pub(crate) fn semantic_role_ref(element: &blitz_dom::ElementData) -> &str {
     if let Some(role) = element_attr(element, "role") {
-        return role.into();
+        return role;
     }
     let tag = element.name.local.as_ref();
     match tag {
@@ -558,7 +570,6 @@ pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
         },
         _ => "generic",
     }
-    .into()
 }
 
 /// Where the labels are, so a control can be asked what names it.
@@ -945,7 +956,7 @@ pub(crate) fn exposed_text(
             ) {
                 return None;
             }
-            if names_from_contents(&semantic_role(element)) {
+            if names_from_contents(semantic_role_ref(element)) {
                 return None;
             }
         }

From bc0f9c27a926ffe95898dfc020d01803d1798588 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 18:29:24 +0700
Subject: [PATCH 10/13] test(agent): a text run refuses a click instead of
 crashing

Text runs are new ids in a tree a harness drives by id, so the first thing a
suite will do with one is press it by accident. It resolves to no client rect,
which the activation path already answers with `notInteractable`; this pins that
down so the answer cannot become a panic inside the control server.
---
 crates/tauri-runtime-blitz/src/agent.rs | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index 4a3d6a6..e0147b3 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -2176,6 +2176,28 @@ mod semantic_tests {
         );
     }
 
+    #[test]
+    fn a_text_run_refuses_a_click_rather_than_panicking() {
+        // Text runs are new ids in a tree a harness drives by id, so the
+        // failure mode when one is pressed has to be a typed refusal and not a
+        // crash inside the control server.
+        let mut document =
+            ScriptDocument::from_html("<pre>plain text in a pre</pre>", DocumentConfig::default());
+        document.inner_mut().resolve(0.0);
+        let DebugResponse::AgentSnapshot(snapshot) = inspect_document(&mut document, None, 0, 1)
+        else {
+            panic!("inspection did not answer with a tree");
+        };
+        let text = snapshot
+            .nodes
+            .iter()
+            .find(|node| node.role == "text")
+            .expect("the pre's text is in the tree");
+        let error = activate_agent_node(&mut document, text.id, 1)
+            .expect_err("a text run has no box to press");
+        assert_eq!(error.code, "notInteractable", "unexpected error: {error:?}");
+    }
+
     #[test]
     fn text_that_already_names_a_node_is_not_repeated() {
         let nodes = tree(REPRO);

From 24ba5464bf89654375e04ad607187b4a07014420 Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 20:44:38 +0700
Subject: [PATCH 11/13] fix(agent): follow aria-labelledby to the elements that
 name

An element named by pointing at other elements arrived anonymous, because
the reference was never resolved. Two independent reports: a QA agent
gave a dashboard card on ui-starter-app an identity this way, found the
region came back unnamed and fell back to `aria-label`; and the section
rule added in this branch reads `aria-labelledby` to decide an element is
a `region`, so such a section got the landmark role and an empty name,
which is worse than the wrapper it used to be reported as.

The attribute is a space-separated list of ids. Each referenced element's
rendered text is read in the order the ids are written and joined by a
single space, and the result outranks `aria-label`, which outranks the
host language's own labelling, which outranks name from contents.

Resolved out of `LabelIndex`, whose single pass over the document now
also records every `id` and the node holding it. The node rather than its
text: a reference is read for the few elements that carry one, and naming
every element up front to answer a question almost none of them ask would
walk each subtree twice per snapshot. So the index stays one pass, and a
reference costs a hash lookup per id plus the subtree walk that id's text
requires. Nothing here walks ancestors or scans the document per node.

A referenced element contributes its text even when it is not rendered,
which is the opposite of the rule applied inside a name's own subtree.
Both are accname: a node that is hidden and not referenced returns the
empty string, while one directly referenced is exempt from that check.
The exemption is the whole point of the pattern, since an element written
only to be pointed at is routinely not shown, and it stops at the element
named by the id: hidden elements inside it are still skipped.

A reference resolves through `name_text`, which reads text, and never
through `semantic_name`, which would consult the attribute again. A
self-reference is named by its own contents and terminates, and no cycle
between elements can exist to be guarded against.

An id that matches nothing contributes nothing rather than abandoning the
whole name, and a reference that resolves to no text at all is the
absence of a name rather than an empty one, so the rules below it stay
reachable.

Eight tests. Six fail against this branch's tip. The two that do not are
the fall-through guards, and both fail against the same resolver without
its emptiness filter, which is the shape that made a contents arm
returning `Some("")` unreachable earlier in this branch.
---
 crates/tauri-runtime-blitz/src/agent.rs | 237 +++++++++++++++++++++++-
 1 file changed, 233 insertions(+), 4 deletions(-)

diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
index e0147b3..d72c970 100644
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ b/crates/tauri-runtime-blitz/src/agent.rs
@@ -528,8 +528,8 @@ pub(crate) fn semantic_role_ref(element: &blitz_dom::ElementData) -> &str {
         // point and computing it here would walk the section's whole subtree for
         // every element in the document. That is the same set an accessible name
         // can come from for a container: `aria-labelledby` is included so an
-        // author who names a section that way still gets the landmark, even
-        // though `semantic_name` does not yet resolve that reference.
+        // author who names a section that way still gets the landmark, and
+        // `semantic_name` resolves that reference to the name itself.
         "section"
             if ["aria-label", "aria-labelledby", "title"]
                 .iter()
@@ -590,12 +590,23 @@ pub(crate) fn semantic_role_ref(element: &blitz_dom::ElementData) -> &str {
 /// Built once per snapshot rather than searched per node, because the lookup is
 /// "which label points at me" and answering that from the control costs a scan
 /// of the document each time.
+///
+/// `aria-labelledby` is resolved from here too, for the same reason and against
+/// the same single pass: it points at other elements by `id`, and finding them
+/// from the referring node is a document scan per reference.
 #[cfg(all(feature = "agent-control", unix))]
 pub(crate) struct LabelIndex {
     /// The `for` attribute's value, to that label's text.
     by_control_id: std::collections::HashMap<String, String>,
     /// Labels by node id, so an ancestor walk can recognise one it is inside.
     labels: std::collections::HashMap<blitz_dom::NodeId, String>,
+    /// Every `id` in the document, to the node carrying it.
+    ///
+    /// The node rather than its text, because the text a reference resolves to
+    /// is only ever read for the few elements that carry an `aria-labelledby`.
+    /// Naming every element in the document up front to answer a question almost
+    /// none of them ask would walk each subtree twice per snapshot.
+    by_dom_id: std::collections::HashMap<String, blitz_dom::NodeId>,
 }
 
 #[cfg(all(feature = "agent-control", unix))]
@@ -603,10 +614,18 @@ impl LabelIndex {
     pub(crate) fn build(document: &blitz_dom::BaseDocument) -> Self {
         let mut by_control_id = std::collections::HashMap::new();
         let mut labels = std::collections::HashMap::new();
+        let mut by_dom_id = std::collections::HashMap::new();
         for (id, node) in document.tree().iter() {
             let Some(element) = node.element_data() else {
                 continue;
             };
+            // The first one wins, which is what `getElementById` answers when a
+            // document repeats an `id`. Duplicate ids are invalid markup and a
+            // reference to one is ambiguous by construction, so the rule here is
+            // only about answering the same way twice.
+            if let Some(dom_id) = element_attr(element, "id") {
+                by_dom_id.entry(dom_id.to_owned()).or_insert(id);
+            }
             if element.name.local.as_ref() != "label" {
                 continue;
             }
@@ -623,7 +642,81 @@ impl LabelIndex {
         Self {
             by_control_id,
             labels,
+            by_dom_id,
+        }
+    }
+
+    /// The name an element gives itself by pointing at other elements.
+    ///
+    /// # Why this exists
+    ///
+    /// `aria-labelledby` was not followed at all, so an element named that way
+    /// arrived anonymous. Two reports, independently: a QA agent giving a
+    /// dashboard card an identity on ui-starter-app found the region came back
+    /// unnamed and had to fall back to `aria-label`, and the `<section>` rule
+    /// beside this one reads `aria-labelledby` to decide the element is a
+    /// `region`, so such a section got the landmark role and an empty name,
+    /// which is worse than the wrapper it used to be reported as.
+    ///
+    /// # What it computes
+    ///
+    /// The attribute is a space-separated list of ids. Each referenced element's
+    /// rendered text is read in the order the ids are written, and the results
+    /// are joined by a single space.
+    ///
+    /// # Hidden referenced elements
+    ///
+    /// A referenced element contributes its text **even when it is not
+    /// rendered**, which is the opposite of the rule `name_text` applies inside
+    /// a subtree. Both are accname: a node that is hidden and *not* referenced
+    /// returns the empty string, while one directly referenced by
+    /// `aria-labelledby` is exempt from that check. The exemption is the whole
+    /// point of the pattern -- `<span hidden id="units">bytes per second</span>`
+    /// exists to name something without appearing itself -- and a resolver that
+    /// skipped it would name nothing on exactly the markup written to use it.
+    ///
+    /// The exemption is for the element named by the id, not for its subtree:
+    /// `name_text` goes on skipping hidden elements inside it, so the half of a
+    /// responsive label that is not shown stays out of the name. An element
+    /// nested inside a `display: none` referenced element is not hidden by that
+    /// rule, because its own computed display is not `none`, which is the answer
+    /// a browser gives for the same markup.
+    ///
+    /// # Termination
+    ///
+    /// A reference resolves through `name_text`, which reads text, and never
+    /// through `semantic_name`, which would consult `aria-labelledby` again. So
+    /// `<h2 id="h" aria-labelledby="h">Fleet</h2>` is named "Fleet" rather than
+    /// recursing, and no cycle between elements can exist to be guarded against.
+    /// ARIA reaches the same answer by forbidding the second traversal.
+    fn labelled_by(
+        &self,
+        document: &blitz_dom::BaseDocument,
+        element: &blitz_dom::ElementData,
+    ) -> Option<String> {
+        let reference = element_attr(element, "aria-labelledby")?;
+        let mut name = String::new();
+        for token in reference.split_ascii_whitespace() {
+            // An id that matches nothing contributes nothing, rather than
+            // abandoning the whole name. A list of ids is written by hand and
+            // one of them going stale is the common way it breaks; the names
+            // that do still resolve are worth more than an empty string.
+            let Some(node) = self
+                .by_dom_id
+                .get(token)
+                .and_then(|id| document.get_node(*id))
+            else {
+                continue;
+            };
+            if !name.is_empty() {
+                name.push(' ');
+            }
+            name.push_str(&name_text(node, document));
         }
+        // Nothing resolved, or everything that did was blank. That is the
+        // absence of a name rather than a name, and returning it would make
+        // every rule below this one unreachable for the element.
+        (!name.trim().is_empty()).then_some(name)
     }
 
     /// The label text for a control, by association or by containment.
@@ -821,8 +914,17 @@ pub(crate) fn semantic_name(
     id: blitz_dom::NodeId,
     labels: &LabelIndex,
 ) -> String {
-    let name = element_attr(element, "aria-label")
-        .map(std::borrow::Cow::Borrowed)
+    // The elements an author pointed at, which outrank everything below.
+    //
+    // ARIA's order: `aria-labelledby` first, then `aria-label`, then the host
+    // language's own labelling, then contents. It is first because it is the
+    // most deliberate thing an author can write. Naming one element by the
+    // visible text of another says the two belong together, and it is the only
+    // rule here that can name something from outside itself.
+    let name = labels
+        .labelled_by(document, element)
+        .map(std::borrow::Cow::Owned)
+        .or_else(|| element_attr(element, "aria-label").map(std::borrow::Cow::Borrowed))
         // The label a form control was given. After `aria-label`, which is the
         // author overriding the visible text on purpose, and before `title`,
         // which is a tooltip rather than a name.
@@ -2310,4 +2412,131 @@ mod semantic_tests {
              plain sections does not grow a landmark per wrapper"
         );
     }
+
+    /// The shape both reports arrived as: a heading names the region under it.
+    ///
+    /// A card with a title above its body is how a dashboard is written, and
+    /// `aria-labelledby` pointing at that title is the markup for saying so
+    /// without repeating the words in an attribute.
+    #[test]
+    fn a_region_is_named_by_the_heading_it_points_at() {
+        let nodes = tree(
+            r#"<h2 id="title">Fleet health</h2>
+               <section aria-labelledby="title"><p>text</p></section>"#,
+        );
+        assert_eq!(
+            names(&nodes, "region"),
+            vec!["Fleet health".to_string()],
+            "a section named by reference is a named landmark, not an anonymous one"
+        );
+    }
+
+    #[test]
+    fn a_list_of_references_is_joined_in_the_order_it_is_written() {
+        let nodes = tree(
+            r#"<span id="unit">per second</span><span id="what">Requests</span>
+               <button aria-labelledby="what unit">?</button>"#,
+        );
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Requests per second".to_string()],
+            "the ids are read in the order the author listed them, not in document order, \
+             and their text is joined by a single space"
+        );
+    }
+
+    #[test]
+    fn a_reference_outranks_an_aria_label_and_the_contents() {
+        let nodes = tree(
+            r#"<span id="title">Fleet health</span>
+               <button aria-labelledby="title" aria-label="overridden">Save</button>"#,
+        );
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Fleet health".to_string()],
+            "ARIA ranks `aria-labelledby` above `aria-label`, which is above name from contents"
+        );
+    }
+
+    /// ARIA exempts a directly referenced element from the hidden check, which
+    /// is the opposite of the rule applied inside a name's own subtree. It has
+    /// to be, or the pattern the exemption exists for names nothing: an element
+    /// written only to be pointed at is routinely not shown.
+    #[test]
+    fn a_referenced_element_names_even_when_it_is_not_rendered() {
+        let nodes = tree(
+            r#"<span id="title" style="display: none">Fleet <b>health</b></span>
+               <section aria-labelledby="title"><p>text</p></section>"#,
+        );
+        assert_eq!(
+            names(&nodes, "region"),
+            vec!["Fleet health".to_string()],
+            "a referenced element contributes its whole text even when it is hidden"
+        );
+    }
+
+    /// The other half of that rule, so the exemption stays as narrow as ARIA
+    /// makes it: the element named by the id is exempt, its subtree is not.
+    #[test]
+    fn a_reference_still_skips_what_is_hidden_inside_it() {
+        let nodes = tree(
+            r#"<span id="title">Book<span style="display: none"> a diagnostic</span></span>
+               <button aria-labelledby="title">?</button>"#,
+        );
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Book".to_string()],
+            "the hidden half of a responsive label stays out of a name reached by reference too"
+        );
+    }
+
+    #[test]
+    fn a_reference_to_nothing_falls_through_to_the_next_rule() {
+        let nodes = tree(r#"<button aria-labelledby="deleted" aria-label="Save">?</button>"#);
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Save".to_string()],
+            "an id that matches no element is not a name, so the rules below it stay reachable"
+        );
+        let nodes = tree(r#"<button aria-labelledby="deleted">Save</button>"#);
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Save".to_string()],
+            "with nothing else declared the control is still named by its own contents"
+        );
+    }
+
+    #[test]
+    fn a_reference_that_resolves_to_no_text_falls_through_too() {
+        let nodes = tree(
+            r#"<span id="title"></span>
+               <button aria-labelledby="title">Save</button>"#,
+        );
+        assert_eq!(
+            names(&nodes, "button"),
+            vec!["Save".to_string()],
+            "an element that exists and says nothing gives no name, which is not the same as \
+             giving an empty one"
+        );
+    }
+
+    /// A self-reference resolves to the element's own text and terminates.
+    ///
+    /// The `aria-label` is what makes this an assertion rather than a tautology.
+    /// A resolver that followed a reference by computing the referenced
+    /// element's *name* would either not terminate here or, with a cycle guard,
+    /// abandon the reference and answer "overridden". Reading the reference as
+    /// text is what gives the heading's own words, and it is why no cycle guard
+    /// is needed anywhere in this path.
+    #[test]
+    fn an_element_that_references_itself_is_named_by_its_own_contents() {
+        let nodes = tree(
+            r#"<h2 id="self" aria-labelledby="self" aria-label="overridden">Fleet health</h2>"#,
+        );
+        assert_eq!(
+            names(&nodes, "heading"),
+            vec!["Fleet health".to_string()],
+            "a reference is read as text and never as another name computation"
+        );
+    }
 }

From c846d15ba48c7edec26dff28626a6e8be1ddd85c Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 23:23:25 +0700
Subject: [PATCH 12/13] refactor: the control surface leaves the runtime

A runtime bridges Tauri to Blitz and owns a native window. It does not
proxy an inspection service, and this crate was doing exactly that: the
document reader, the action dispatch, the capture, the socket server and
a re-export of the wire vocabulary all lived here, so anything that
wanted to name an `AgentControlRequest` compiled Tauri to get it. On
Linux that reaches GTK, which is how a headless host ended up needing
system libraries to build a binary that opens nothing.

All of it is `blitz-control-protocol` now: `engine` reads and drives a
document, `capture` paints it offscreen, `server` is the socket, and
`in_process` is the transport an embedder holding the document calls
straight into. `agent.rs` and `agent_control_server.rs` are gone rather
than emptied, and nothing here re-exports what replaced them. A crate
that forwards a dependency has not removed the edge, only renamed it.

`set_agent_control_handler` and `set_diagnostics_handler` go with them.
The first is `blitz_control_protocol::lifecycle`, because what `Relaunch`
means is the embedder's answer and reaching a window runtime to register
it was the same misplacement one level up. The second let an embedder
replace the whole diagnostics answer, which is a runtime proxying an
inspection service by another name, and nothing installed one.

What is left is the wiring only a runtime can do: which window's document
is the active one, the listener's lifetime, what `Quit` does to an event
loop, and the native window composition a renderer capture cannot see.
No public item in this crate names a protocol type any more.

The manifest loses `endpoint-libs`, `keyboard-types`, `serde`,
`serde_json`, `base64`, `blitz-paint` and `anyrender_vello_cpu`: the
framing, the key table, the request types and the offscreen renderer of a
surface this crate no longer implements. `serde_json` returns as a
dev-dependency, which is what the IPC round-trip test always used it as.
---
 crates/tauri-runtime-blitz/Cargo.toml         |   63 +-
 crates/tauri-runtime-blitz/src/agent.rs       | 2542 -----------------
 .../src/agent_control_server.rs               |  812 ------
 crates/tauri-runtime-blitz/src/lib.rs         |   65 +-
 crates/tauri-runtime-blitz/src/runtime.rs     | 1443 +---------
 5 files changed, 208 insertions(+), 4717 deletions(-)
 delete mode 100644 crates/tauri-runtime-blitz/src/agent.rs
 delete mode 100644 crates/tauri-runtime-blitz/src/agent_control_server.rs

diff --git a/crates/tauri-runtime-blitz/Cargo.toml b/crates/tauri-runtime-blitz/Cargo.toml
index 8b22122..aa671a7 100644
--- a/crates/tauri-runtime-blitz/Cargo.toml
+++ b/crates/tauri-runtime-blitz/Cargo.toml
@@ -20,36 +20,34 @@ style = { version = "0.20.0", package = "stylo" }
 # not here: `system-fonts` should never have been a default of `blitz-dom`, and
 # every consumer copying its default list is a copy that goes stale the next
 # time a default is added. Fixed at the source in pathscale/ps-blitz#87.
-blitz-dom = { package = "ps-blitz-dom", version = "^0.4", optional = true }
+# Still named directly: the runtime downcasts a window.s document and reads
+# `NodeId` and the `Document` trait. Nothing about roles, names or capture is
+# reached from here any more.
+blitz-dom = { package = "ps-blitz-dom", version = "^0.4.8", optional = true }
 # No `system-fonts`. It reaches `fontique/system` and, on Linux, the
 # `yeslogic-fontconfig-sys` system library, so enabling it here would decide
 # that every consumer of this crate needs one installed, including a headless
 # one that reads no font catalogue. An application that wants the machine's
 # fonts asks for them itself, and both consumers already do.
 blitz-script = { package = "ps-blitz-script", version = "^0.4" }
-blitz-control-protocol = { version = "^0.4", optional = true }
+# The control surface: the vocabulary, the core, and the socket transport this
+# runtime serves its own document over. `capture` carries the offscreen paint
+# and the diagnostic snapshots, and pulls `engine` and `blitz-shell` with it.
+blitz-control-protocol = { version = "^0.5", default-features = false, optional = true }
+# The window renderer's own alpha mode, which is why this is not optional: the
+# offscreen capture that used to need it here is `blitz-control-protocol`'s.
 anyrender = { package = "ps-anyrender", version = "^0.13.0" }
-# Offscreen capture, behind `diagnostics` so a shipping build carries neither.
-#
-# The CPU renderer on purpose: capture must not need a GPU, a surface or a
-# display server, or it stops working in the places it is most needed (CI, a
-# headless Linux box, an Android target). It draws the same scene through the
-# same `blitz-paint` entry point the window uses, so what it returns is the
-# real frame rather than a second opinion about it.
-anyrender_vello_cpu = { package = "ps-anyrender-vello-cpu", version = "^0.17.0", optional = true }
-blitz-paint = { package = "ps-blitz-paint", version = "^0.4", optional = true }
-base64 = { version = "0.22", optional = true }
 peniko = "0.6"
 
 blitz-shell = { package = "ps-blitz-shell", version = "^0.4", default-features = false, features = ["clipboard", "svg"] }
 blitz-traits = { package = "ps-blitz-traits", version = "^0.4", optional = true }
 http = "1"
-endpoint-libs = { version = "^3", default-features = false, features = ["agent-control"], optional = true }
-keyboard-types = { version = "0.7", optional = true }
+# No `endpoint-libs`, `keyboard-types`, `serde` or `serde_json`. They were the
+# wire framing, the key table and the request types of a control surface this
+# crate no longer implements; `blitz-control-protocol` names them now, and a
+# consumer that wants them names it.
 libc = "0.2"
 raw-window-handle = "0.6"
-serde = { version = "1", features = ["derive"], optional = true }
-serde_json = { version = "1", optional = true }
 tauri = { version = "2", default-features = false, optional = true }
 tauri-runtime = { version = "2", optional = true }
 tauri-utils = { version = "2", optional = true }
@@ -81,15 +79,27 @@ runtime = [
     "dep:tauri-utils",
     "dep:anyrender_vello",
 ]
-agent-control = ["blitz-shell/debug-control", "dep:blitz-control-protocol", "dep:blitz-dom", "dep:blitz-traits", "dep:endpoint-libs", "dep:keyboard-types", "dep:serde", "dep:serde_json", "dep:tokio"]
-debug-control = ["blitz-script/debug-control", "blitz-shell/debug-control"]
-diagnostics = [
-    "agent-control",
-    "debug-control",
-    "dep:anyrender_vello_cpu",
-    "dep:base64",
-    "dep:blitz-paint",
+# Serve this runtime's own document over the control socket.
+#
+# The surface itself is `blitz-control-protocol`: `engine` is the core that
+# reads and drives a document, `server` is the socket. Neither is this crate.
+# What this feature adds here is the wiring: which window's document is the
+# active one, the listener's lifetime, and what `Relaunch` and `Quit` mean for
+# a process this runtime started.
+agent-control = [
+    "blitz-control-protocol/engine",
+    "blitz-control-protocol/server",
+    "blitz-shell/debug-control",
+    "dep:blitz-control-protocol",
+    "dep:blitz-dom",
+    "dep:blitz-traits",
+    "dep:tokio",
 ]
+debug-control = ["blitz-script/debug-control", "blitz-shell/debug-control"]
+# Collection, which is where the expense is. The offscreen renderer, the
+# snapshot readers and the frame metrics are all `blitz-control-protocol`'s
+# `capture`; a shipping build that leaves this off carries none of them.
+diagnostics = ["agent-control", "blitz-control-protocol/capture", "debug-control"]
 # Swap the general-purpose Vello renderer for the lighter hybrid pipeline.
 # UI is overwhelmingly rectangles and text, which Vello tessellates and bins
 # through a compute pass built for arbitrary vector art. The hybrid backend
@@ -107,6 +117,11 @@ macos-private-api = ["runtime", "tauri/macos-private-api", "tauri-runtime/macos-
 
 [dev-dependencies]
 tauri = { version = "2", default-features = false, features = ["test"] }
+# The IPC round-trip test builds a request body and reads the reply back. It was
+# a dev use of a dependency the crate itself carried for the control protocol,
+# so removing that left the test with no JSON: a test dependency now, which is
+# what it always was.
+serde_json = "1"
 
 # Only on macOS, and only for the one test that needs a face:
 # `setting_a_node_value_replaces_text_and_dispatches_input`. Replacing a
diff --git a/crates/tauri-runtime-blitz/src/agent.rs b/crates/tauri-runtime-blitz/src/agent.rs
deleted file mode 100644
index d72c970..0000000
--- a/crates/tauri-runtime-blitz/src/agent.rs
+++ /dev/null
@@ -1,2542 +0,0 @@
-//! Inspecting, capturing and driving a document, with no window involved.
-//!
-//! Split out of the runtime because none of it needs one. A headless
-//! inspection host wants exactly these functions: it serves a socket, answers
-//! `Inspect`, and activates nodes. It opens nothing.
-//!
-//! While they lived beside the Tauri runtime, depending on them meant
-//! compiling Tauri, and on Linux that means GTK -- system libraries pulled in
-//! to build a binary that never creates a window, and a crate that would not
-//! compile there at all. The dependency edge was wrong, not the platform.
-
-use std::collections::HashMap;
-
-#[cfg(all(feature = "agent-control", unix))]
-use blitz_control_protocol::{
-    AgentSnapshot, DebugError, DebugResponse, KeyPhase, Modifiers as ControlModifiers, SemanticNode,
-};
-#[cfg(all(feature = "diagnostics", unix))]
-use blitz_control_protocol::{
-    DebugSnapshot, FrameMetrics, FrameWindowMetrics, LayoutBounds, LayoutDiagnosticRow,
-    LayoutEdges, LayoutOffset, LayoutSize, RendererMetrics, RevisionSet, ScriptMetrics,
-    ScriptSource, SnapshotCost, SnapshotRequest, TimingStats,
-};
-#[cfg(all(feature = "agent-control", unix))]
-use blitz_dom::Document;
-use blitz_script::ScriptDocument;
-#[cfg(all(feature = "agent-control", unix))]
-use blitz_traits::events::{
-    BlitzKeyEvent, BlitzPointerEvent, BlitzPointerId, DomEvent, DomEventData, KeyState,
-    MouseEventButton, MouseEventButtons, Point, PointerCoords, PointerDetails, UiEvent,
-};
-#[cfg(all(feature = "diagnostics", unix))]
-use blitz_traits::node_id::NodeId;
-#[cfg(all(feature = "agent-control", unix))]
-use keyboard_types::{Code, Key, Location, Modifiers as KeyboardModifiers};
-
-/// The live inspector's reusable offscreen surface.
-///
-/// A capture used to construct this whole renderer for every frame. Besides
-/// reallocating the viewport-sized RGBA buffer, that threw away the CPU text
-/// renderer's glyph resources, so a stability assertion shaped and rasterised
-/// every label four times. The surface belongs to one runtime and is resized
-/// only when the window or requested scale changes.
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) struct CaptureSurface {
-    pub(crate) width: u32,
-    pub(crate) height: u32,
-    pub(crate) renderer: anyrender_vello_cpu::VelloCpuImageRenderer,
-    pub(crate) rgba: Vec<u8>,
-}
-
-/// Reusable offscreen renderer for captures of one document.
-///
-/// A headless inspection host asks for several adjacent frames when it checks
-/// visual stability. Reusing this object preserves the CPU renderer's glyph
-/// resources and pixel allocation between those requests instead of rebuilding
-/// an entire renderer for every sample.
-#[cfg(all(feature = "diagnostics", unix))]
-pub struct DocumentCapture {
-    surface: Option<CaptureSurface>,
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-impl DocumentCapture {
-    pub fn new() -> Self {
-        Self { surface: None }
-    }
-
-    pub fn capture(
-        &mut self,
-        document: &mut ScriptDocument,
-        request: blitz_control_protocol::CaptureRequest,
-    ) -> Result<blitz_control_protocol::CapturedImage, DebugError> {
-        capture_document_with_surface(document, request, &mut self.surface)
-    }
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-impl Default for DocumentCapture {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-impl CaptureSurface {
-    pub(crate) fn new(width: u32, height: u32) -> Self {
-        use anyrender::ImageRenderer as _;
-
-        Self {
-            width,
-            height,
-            renderer: anyrender_vello_cpu::VelloCpuImageRenderer::new(width, height),
-            rgba: Vec::with_capacity((width as usize) * (height as usize) * 4),
-        }
-    }
-
-    pub(crate) fn size_to(&mut self, width: u32, height: u32) {
-        use anyrender::ImageRenderer as _;
-
-        if self.width == width && self.height == height {
-            return;
-        }
-        self.renderer.resize(width, height);
-        self.width = width;
-        self.height = height;
-    }
-}
-
-/// Draw a standalone script document through the same CPU paint path used by
-/// runtime diagnostics.
-///
-/// Headless QA hosts intentionally have no `RuntimeApplication`, but they must
-/// not substitute a second renderer for native visual checks. Keeping the
-/// capture implementation here makes a host capture and a live-app capture
-/// byte-for-byte comparable.
-#[cfg(all(feature = "diagnostics", unix))]
-pub fn capture_document(
-    script_document: &mut ScriptDocument,
-    request: blitz_control_protocol::CaptureRequest,
-) -> Result<blitz_control_protocol::CapturedImage, DebugError> {
-    DocumentCapture::new().capture(script_document, request)
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) fn capture_document_with_surface(
-    script_document: &mut ScriptDocument,
-    request: blitz_control_protocol::CaptureRequest,
-    surface: &mut Option<CaptureSurface>,
-) -> Result<blitz_control_protocol::CapturedImage, DebugError> {
-    use anyrender::ImageRenderer;
-    use base64::Engine as _;
-
-    // Clamped rather than trusted. A scale of zero produces a zero-sized
-    // buffer and a negative one panics inside the rasteriser, and neither
-    // should be reachable from a debug socket.
-    let scale = if request.scale.is_finite() && request.scale > 0.0 {
-        request.scale.clamp(0.1, 8.0)
-    } else {
-        1.0
-    };
-
-    let node_id = request.node_id;
-
-    // Style and layout first, so the capture reflects pending mutations
-    // rather than the frame before them. Same call `collect_diagnostics`
-    // makes, for the same reason.
-    script_document.inner_mut().resolve(0.0);
-
-    // Copied out rather than held: the guard is a `Ref` and the borrow has
-    // to end before the mutable one the paint below needs.
-    let (full_width, full_height) = {
-        let inner = script_document.inner();
-        let viewport = inner.viewport();
-        (viewport.window_size.0, viewport.window_size.1)
-    };
-    if full_width == 0 || full_height == 0 {
-        return Err(debug_error(
-            "captureUnavailable",
-            "the document has no viewport to draw",
-        ));
-    }
-
-    // The region to keep, in unscaled document pixels.
-    let (crop_x, crop_y, crop_width, crop_height) = match node_id {
-        None => (
-            0.0_f64,
-            0.0_f64,
-            f64::from(full_width),
-            f64::from(full_height),
-        ),
-        Some(id) => {
-            let inner = script_document.inner();
-            let node = inner
-                .get_node(NodeId::from_u64(id))
-                .ok_or_else(|| debug_error("unknownNode", &format!("no node {id}")))?;
-            let layout = node.final_layout();
-            let position = node.absolute_position(0.0, 0.0);
-            if layout.size.width <= 0.0 || layout.size.height <= 0.0 {
-                return Err(debug_error(
-                    "captureEmpty",
-                    &format!("node {id} has a zero-sized box, so there is nothing to capture"),
-                ));
-            }
-            let box_ = (
-                f64::from(position.x),
-                f64::from(position.y),
-                f64::from(layout.size.width),
-                f64::from(layout.size.height),
-            );
-            drop(inner);
-            box_
-        }
-    };
-
-    let full_pixel_width = ((f64::from(full_width) * f64::from(scale)).round() as u32).max(1);
-    let full_pixel_height = ((f64::from(full_height) * f64::from(scale)).round() as u32).max(1);
-    // Clamp before painting: a node partly offscreen yields the visible part,
-    // and the regional renderer never allocates pixels that will be discarded.
-    let left = ((crop_x * f64::from(scale)).round().max(0.0) as u32).min(full_pixel_width);
-    let top = ((crop_y * f64::from(scale)).round().max(0.0) as u32).min(full_pixel_height);
-    let width = ((crop_width * f64::from(scale)).round() as u32)
-        .min(full_pixel_width.saturating_sub(left))
-        .max(1);
-    let height = ((crop_height * f64::from(scale)).round() as u32)
-        .min(full_pixel_height.saturating_sub(top))
-        .max(1);
-    // Leave room for the JSON-RPC and MCP envelopes inside the transport's
-    // fixed frame ceiling. The old 64-million-pixel limit allowed a 256 MiB
-    // raster and a 341 MiB base64 string, only for protocol encoding to reject
-    // the result against its 16 MiB frame limit after all that work was done.
-    const FRAME_ENVELOPE_RESERVE: usize = 64 * 1024;
-    const MAX_BASE64_BYTES: usize =
-        blitz_control_protocol::MAX_DEBUG_FRAME_BYTES - FRAME_ENVELOPE_RESERVE;
-    const MAX_RAW_BYTES: usize = (MAX_BASE64_BYTES / 4) * 3;
-    const MAX_PIXELS: u64 = (MAX_RAW_BYTES / 4) as u64;
-    if u64::from(width) * u64::from(height) > MAX_PIXELS {
-        return Err(debug_error(
-            "captureTooLarge",
-            &format!(
-                "{width}x{height} cannot fit in one diagnostic frame; capture a node or lower the scale"
-            ),
-        ));
-    }
-
-    let surface = surface.get_or_insert_with(|| CaptureSurface::new(width, height));
-    surface.size_to(width, height);
-    // `ImageRenderer` retains its scene between calls. A capture is a complete
-    // frame, not an incremental paint, so carrying the previous command list
-    // forward duplicates every shape and makes each sample slower than the
-    // last. Keep reusable renderer resources, but always begin with an empty
-    // scene.
-    surface.renderer.reset();
-    let mut document = script_document.inner_mut();
-    surface.renderer.render_to_vec(
-        |scene| {
-            if node_id.is_some() {
-                blitz_paint::paint_scene_region(
-                    scene,
-                    &mut document,
-                    blitz_paint::PaintRegion::crop(
-                        f64::from(scale),
-                        f64::from(left) / f64::from(scale),
-                        f64::from(top) / f64::from(scale),
-                        width,
-                        height,
-                    ),
-                );
-            } else {
-                blitz_paint::paint_scene(
-                    scene,
-                    &mut document,
-                    f64::from(scale),
-                    width,
-                    height,
-                    0,
-                    0,
-                );
-            }
-        },
-        &mut surface.rgba,
-    );
-
-    Ok(blitz_control_protocol::CapturedImage {
-        width,
-        height,
-        rgba_base64: base64::engine::general_purpose::STANDARD.encode(&surface.rgba),
-        node_id,
-    })
-}
-
-/// Collect the same typed diagnostic snapshot from a standalone Blitz document
-/// that the windowed runtime exposes over its control socket.
-///
-/// Headless component hosts own a `ScriptDocument` without a Tauri event loop.
-/// Keeping snapshot collection here gives those hosts the renderer's real DOM,
-/// layout and computed paint data instead of a partial or reimplemented view.
-#[cfg(all(feature = "diagnostics", unix))]
-pub fn snapshot_document(
-    document: &mut ScriptDocument,
-    request: SnapshotRequest,
-    revision: u64,
-) -> Result<DebugSnapshot, DebugError> {
-    let started = std::time::Instant::now();
-    let poll_started = std::time::Instant::now();
-    let mut polls = 0u64;
-    for _ in 0..100 {
-        polls += 1;
-        if !document.poll(None) {
-            break;
-        }
-    }
-    let poll_ms = poll_started.elapsed().as_secs_f64() * 1_000.0;
-    // This forces a style and layout pass so the snapshot reports current
-    // geometry. It is work the observer caused, so it is reported as snapshot
-    // cost, never as the cost of a frame the application drew.
-    let resolve_started = std::time::Instant::now();
-    document.inner_mut().resolve(0.0);
-    let snapshot_resolve_ms = resolve_started.elapsed().as_secs_f64() * 1_000.0;
-    let inner = document.inner();
-    let layout_node_limit = inner.tree().iter().count();
-    let active_element = inner.get_focussed_node_id().map(|id| id.as_u64());
-    // Once for the whole snapshot: the question a control asks is "which label
-    // points at me", and answering it from the control costs a document scan
-    // each time.
-    let labels = LabelIndex::build(&inner);
-    let nodes: Vec<SemanticNode> = inner
-        .tree()
-        .iter()
-        .filter_map(|(id, node)| {
-            if !request.node_ids.is_empty() && !request.node_ids.contains(&id.as_u64()) {
-                return None;
-            }
-            let element = node.element_data()?;
-            if !dom_chain_is_attached(&inner, id, layout_node_limit)
-                || !layout_chain_is_valid(&inner, id, layout_node_limit)
-            {
-                return None;
-            }
-            let rect = inner.get_client_bounding_rect(id);
-            let visible = node_is_visible(&inner, id)
-                && rect
-                    .as_ref()
-                    .is_some_and(|rect| rect.width > 0.0 && rect.height > 0.0);
-            let role = semantic_role(element);
-            let value = if role == "generic" {
-                Some(
-                    element
-                        .attrs()
-                        .iter()
-                        .map(|attribute| format!("{}={}", attribute.name.local, attribute.value))
-                        .collect::<Vec<_>>()
-                        .join(" "),
-                )
-            } else {
-                semantic_value(element)
-            };
-            Some(SemanticNode {
-                dom_id: element_attr(element, "id").map(str::to_owned),
-                id: id.as_u64(),
-                parent: semantic_parent(&inner, id, None).map(|id| id.as_u64()),
-                name: semantic_name(element, node, &role, &inner, id, &labels),
-                role,
-                value,
-                enabled: element_attr(element, "disabled").is_none()
-                    && element_attr(element, "aria-disabled") != Some("true"),
-                visible,
-                selected: semantic_selected(element),
-                bounds: rect.and_then(|rect| {
-                    let bounds = [rect.x, rect.y, rect.width, rect.height];
-                    bounds
-                        .iter()
-                        .all(|value| value.is_finite())
-                        .then_some(bounds)
-                }),
-                slot: element_attr(element, "data-slot").map(str::to_owned),
-            })
-        })
-        .collect();
-    let total_ms = started.elapsed().as_secs_f64() * 1_000.0;
-    // The runtime keeps one counter and stamps it onto all four revision
-    // fields. Style, layout and paint are not versioned independently
-    // anywhere in blitz, so four copies of one number would claim a
-    // resolution that does not exist. Report the counter once, as the
-    // document revision, and leave the rest at zero.
-    let revisions = RevisionSet {
-        document: revision,
-        style: 0,
-        layout: 0,
-        paint: 0,
-    };
-    // Real per-frame timings, published by blitz-shell from `View::redraw`.
-    // These describe frames the application actually presented. Everything
-    // measured inside this function describes the snapshot collection instead,
-    // and is reported under `snapshot` so the two never get mixed up again.
-    let frame_stats = blitz_shell::latest_frame_stats();
-    let metrics = RendererMetrics {
-        revisions: revisions.clone(),
-        queue_depth: None,
-        invalidations_coalesced: polls.saturating_sub(1),
-        frame: frame_stats.as_ref().map(|stats| FrameMetrics {
-            input_to_present_ms: None,
-            style_ms: None,
-            layout_ms: None,
-            resolve_ms: stats.latest.resolve_ms,
-            scene_ms: stats.latest.paint_ms,
-            submit_ms: None,
-            present_ms: None,
-            renderer_ms: stats.latest.renderer_ms,
-            total_ms: stats.latest.total_ms,
-            age_ms: stats.latest.age_ms,
-        }),
-        frame_window: frame_stats.as_ref().map(|stats| FrameWindowMetrics {
-            frames_total: stats.frames_total,
-            window_frames: stats.window_frames,
-            resolve: timing_stats(stats.resolve),
-            scene: timing_stats(stats.paint),
-            renderer: timing_stats(stats.renderer),
-            total: timing_stats(stats.frame_total),
-            interval: timing_stats(stats.interval),
-            active_fps: stats.active_fps,
-            missed_refreshes: stats.missed_refreshes,
-            display_refresh_hz: stats.display_refresh_hz,
-        }),
-        snapshot: Some(SnapshotCost {
-            poll_ms,
-            resolve_ms: snapshot_resolve_ms,
-            total_ms,
-        }),
-        // The other half of a frame. Everything above this line is the
-        // engine; this is the language runtime the application actually
-        // spends its time in.
-        script: blitz_script::script_stats::latest_script_stats().map(|stats| ScriptMetrics {
-            mean_ms: stats.mean_ms,
-            p95_ms: stats.p95_ms,
-            max_ms: stats.max_ms,
-            window_polls: stats.window_polls,
-            total_polls: stats.total_polls,
-            productive_polls: stats.productive_polls,
-            spent_ms: stats.spent_ms,
-            breakdown: blitz_script::script_stats::work_breakdown()
-                .into_iter()
-                .take(12)
-                .map(|(label, calls, total_ms, worst_ms)| ScriptSource {
-                    label,
-                    calls,
-                    total_ms,
-                    worst_ms,
-                })
-                .collect(),
-        }),
-        resident_bytes: resident_bytes(),
-    };
-    let dom = request
-        .include_dom
-        .then(|| serde_json::to_value(&nodes).unwrap_or(serde_json::Value::Null));
-    let layout = request.include_layout.then(|| {
-        nodes
-            .iter()
-            .filter_map(|node| diagnostic_layout_row(&inner, node))
-            .collect()
-    });
-    /*
-     * Resolved colours, folded into the layout rows.
-     *
-     * This used to answer `computedStyleUnavailable`, which left one class
-     * of bug unanswerable from outside: an element whose *declared* colour
-     * is correct and whose *painted* colour is not. Reading the stylesheet
-     * cannot settle that - the cascade, the custom-property chain and the
-     * `@supports` gating all sit between the two - and neither can a DOM
-     * test environment, which has no cascade at all.
-     *
-     * Only the four that decide legibility, rather than a full style dump:
-     * a snapshot of every longhand for 4,500 nodes is megabytes of JSON
-     * nobody reads, and these are what a "why is this text invisible"
-     * question actually needs.
-     */
-    let computed_style = request.include_computed_style.then(|| {
-        serde_json::Value::Array(
-            nodes
-                .iter()
-                .filter_map(|node| diagnostic_style_row(&inner, node))
-                .collect(),
-        )
-    });
-    Ok(DebugSnapshot {
-        revisions,
-        active_window: Some("blitz-main".into()),
-        active_element,
-        dom,
-        layout,
-        computed_style,
-        metrics,
-    })
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn element_attr<'a>(element: &'a blitz_dom::ElementData, name: &str) -> Option<&'a str> {
-    element
-        .attrs()
-        .iter()
-        .find(|attribute| attribute.name.local.as_ref() == name)
-        // `as_ref`, not `as_str`. Attribute values are an interned atom as of
-        // ps-blitz-dom 0.3.0-beta.11, and `str::as_str` is still unstable, so
-        // `as_str` here resolved to the nightly-only inherent method and
-        // failed to build on stable. `as_ref` borrows the atom as a `&str`,
-        // which is what this signature returns.
-        .map(|attribute| attribute.value.as_ref())
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
-    semantic_role_ref(element).to_owned()
-}
-
-/// The same answer without owning it.
-///
-/// A text node asks every element above it whether that element is already
-/// named by the words in question, and the owned form allocated a `String` per
-/// ancestor per text node to be compared against a fixed list and dropped. The
-/// role is either a `&'static str` or the `role` attribute's own text, so
-/// nothing here needs a copy.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn semantic_role_ref(element: &blitz_dom::ElementData) -> &str {
-    if let Some(role) = element_attr(element, "role") {
-        return role;
-    }
-    let tag = element.name.local.as_ref();
-    match tag {
-        "a" if element_attr(element, "href").is_some() => "link",
-        "button" => "button",
-        "textarea" => "textbox",
-        "select" => "combobox",
-        "option" => "option",
-        "img" => "img",
-        "nav" => "navigation",
-        "main" => "main",
-        // A named section is a landmark; an unnamed one is nothing.
-        //
-        // HTML-AAM: `<section>` maps to `region` when it has an accessible
-        // name, and to `generic` otherwise. Both halves matter. A named section
-        // is how a page says "this part is the connection settings", and it
-        // arrived indistinguishable from the `<div>`s around it; an unnamed one
-        // is a wrapper, and promoting those would put a landmark around every
-        // block on a page that reaches for `<section>` as a synonym for `<div>`.
-        //
-        // Attributes only, because the name has not been computed yet at this
-        // point and computing it here would walk the section's whole subtree for
-        // every element in the document. That is the same set an accessible name
-        // can come from for a container: `aria-labelledby` is included so an
-        // author who names a section that way still gets the landmark, and
-        // `semantic_name` resolves that reference to the name itself.
-        "section"
-            if ["aria-label", "aria-labelledby", "title"]
-                .iter()
-                .any(|name| {
-                    element_attr(element, name).is_some_and(|value| !value.trim().is_empty())
-                }) =>
-        {
-            "region"
-        }
-        "form" => "form",
-        "ul" | "ol" => "list",
-        "li" => "listitem",
-        "table" => "table",
-        "tr" => "row",
-        "td" => "cell",
-        // A header cell is not a cell.
-        //
-        // HTML-AAM maps `<th>` to `columnheader` or `rowheader`, and blitz-dom's
-        // own accessibility tree already does exactly this, so the two trees
-        // disagreed about the same document. What a header is for is saying
-        // which column or row the values under it belong to, and a check that
-        // wants "the Version column" has nothing to ask for while every header
-        // is spelled the same as the data beneath it.
-        //
-        // `scope` decides. Without one this is a column header, which is the
-        // common case (a `<thead>` row) and what blitz-dom falls back to.
-        "th" => match element_attr(element, "scope") {
-            Some("row") | Some("rowgroup") => "rowheader",
-            _ => "columnheader",
-        },
-        "h1" | "h2" | "h3" | "h4" | "h5" | "h6" => "heading",
-        "input" => match element_attr(element, "type").unwrap_or("text") {
-            "checkbox" => "checkbox",
-            "radio" => "radio",
-            "button" | "submit" | "reset" => "button",
-            "range" => "slider",
-            _ => "textbox",
-        },
-        _ => "generic",
-    }
-}
-
-/// Where the labels are, so a control can be asked what names it.
-///
-/// # Why this exists
-///
-/// A name was computed from `aria-label`, `alt` and `title` and from nothing
-/// else, so the ordinary way to label a form control -- a `<label for>` beside
-/// it, or a `<label>` wrapped around it -- produced no name at all. Every text
-/// field on every page in the fleet arrived in the semantic tree anonymous.
-///
-/// That is not only a reporting defect. A harness addresses a control by name,
-/// so an anonymous field cannot be typed into, and a check that means "enter a
-/// URL and save" cannot be written. Measured on support.cafe's connection
-/// settings: three `Input.Field`s, each with a correct `<Label for>` beside it,
-/// all three reported as `textbox ""`.
-///
-/// Built once per snapshot rather than searched per node, because the lookup is
-/// "which label points at me" and answering that from the control costs a scan
-/// of the document each time.
-///
-/// `aria-labelledby` is resolved from here too, for the same reason and against
-/// the same single pass: it points at other elements by `id`, and finding them
-/// from the referring node is a document scan per reference.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) struct LabelIndex {
-    /// The `for` attribute's value, to that label's text.
-    by_control_id: std::collections::HashMap<String, String>,
-    /// Labels by node id, so an ancestor walk can recognise one it is inside.
-    labels: std::collections::HashMap<blitz_dom::NodeId, String>,
-    /// Every `id` in the document, to the node carrying it.
-    ///
-    /// The node rather than its text, because the text a reference resolves to
-    /// is only ever read for the few elements that carry an `aria-labelledby`.
-    /// Naming every element in the document up front to answer a question almost
-    /// none of them ask would walk each subtree twice per snapshot.
-    by_dom_id: std::collections::HashMap<String, blitz_dom::NodeId>,
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-impl LabelIndex {
-    pub(crate) fn build(document: &blitz_dom::BaseDocument) -> Self {
-        let mut by_control_id = std::collections::HashMap::new();
-        let mut labels = std::collections::HashMap::new();
-        let mut by_dom_id = std::collections::HashMap::new();
-        for (id, node) in document.tree().iter() {
-            let Some(element) = node.element_data() else {
-                continue;
-            };
-            // The first one wins, which is what `getElementById` answers when a
-            // document repeats an `id`. Duplicate ids are invalid markup and a
-            // reference to one is ambiguous by construction, so the rule here is
-            // only about answering the same way twice.
-            if let Some(dom_id) = element_attr(element, "id") {
-                by_dom_id.entry(dom_id.to_owned()).or_insert(id);
-            }
-            if element.name.local.as_ref() != "label" {
-                continue;
-            }
-            // Read the same way a name is, not with `textContent`. A label is a
-            // name once it reaches a control, so a stylesheet inside it, or the
-            // half of a responsive label that is not rendered at this width,
-            // has to be left out here too.
-            let text = name_text(node, document);
-            if let Some(control) = element_attr(element, "for") {
-                by_control_id.insert(control.to_owned(), text.clone());
-            }
-            labels.insert(id, text);
-        }
-        Self {
-            by_control_id,
-            labels,
-            by_dom_id,
-        }
-    }
-
-    /// The name an element gives itself by pointing at other elements.
-    ///
-    /// # Why this exists
-    ///
-    /// `aria-labelledby` was not followed at all, so an element named that way
-    /// arrived anonymous. Two reports, independently: a QA agent giving a
-    /// dashboard card an identity on ui-starter-app found the region came back
-    /// unnamed and had to fall back to `aria-label`, and the `<section>` rule
-    /// beside this one reads `aria-labelledby` to decide the element is a
-    /// `region`, so such a section got the landmark role and an empty name,
-    /// which is worse than the wrapper it used to be reported as.
-    ///
-    /// # What it computes
-    ///
-    /// The attribute is a space-separated list of ids. Each referenced element's
-    /// rendered text is read in the order the ids are written, and the results
-    /// are joined by a single space.
-    ///
-    /// # Hidden referenced elements
-    ///
-    /// A referenced element contributes its text **even when it is not
-    /// rendered**, which is the opposite of the rule `name_text` applies inside
-    /// a subtree. Both are accname: a node that is hidden and *not* referenced
-    /// returns the empty string, while one directly referenced by
-    /// `aria-labelledby` is exempt from that check. The exemption is the whole
-    /// point of the pattern -- `<span hidden id="units">bytes per second</span>`
-    /// exists to name something without appearing itself -- and a resolver that
-    /// skipped it would name nothing on exactly the markup written to use it.
-    ///
-    /// The exemption is for the element named by the id, not for its subtree:
-    /// `name_text` goes on skipping hidden elements inside it, so the half of a
-    /// responsive label that is not shown stays out of the name. An element
-    /// nested inside a `display: none` referenced element is not hidden by that
-    /// rule, because its own computed display is not `none`, which is the answer
-    /// a browser gives for the same markup.
-    ///
-    /// # Termination
-    ///
-    /// A reference resolves through `name_text`, which reads text, and never
-    /// through `semantic_name`, which would consult `aria-labelledby` again. So
-    /// `<h2 id="h" aria-labelledby="h">Fleet</h2>` is named "Fleet" rather than
-    /// recursing, and no cycle between elements can exist to be guarded against.
-    /// ARIA reaches the same answer by forbidding the second traversal.
-    fn labelled_by(
-        &self,
-        document: &blitz_dom::BaseDocument,
-        element: &blitz_dom::ElementData,
-    ) -> Option<String> {
-        let reference = element_attr(element, "aria-labelledby")?;
-        let mut name = String::new();
-        for token in reference.split_ascii_whitespace() {
-            // An id that matches nothing contributes nothing, rather than
-            // abandoning the whole name. A list of ids is written by hand and
-            // one of them going stale is the common way it breaks; the names
-            // that do still resolve are worth more than an empty string.
-            let Some(node) = self
-                .by_dom_id
-                .get(token)
-                .and_then(|id| document.get_node(*id))
-            else {
-                continue;
-            };
-            if !name.is_empty() {
-                name.push(' ');
-            }
-            name.push_str(&name_text(node, document));
-        }
-        // Nothing resolved, or everything that did was blank. That is the
-        // absence of a name rather than a name, and returning it would make
-        // every rule below this one unreachable for the element.
-        (!name.trim().is_empty()).then_some(name)
-    }
-
-    /// The label text for a control, by association or by containment.
-    ///
-    /// `for` first, matching the order a browser resolves them in: an explicit
-    /// association wins over the label the control happens to sit inside.
-    fn name_for(
-        &self,
-        document: &blitz_dom::BaseDocument,
-        id: blitz_dom::NodeId,
-        element: &blitz_dom::ElementData,
-    ) -> Option<String> {
-        if let Some(dom_id) = element_attr(element, "id")
-            && let Some(text) = self.by_control_id.get(dom_id)
-            && !text.trim().is_empty()
-        {
-            return Some(text.clone());
-        }
-        // A wrapping label, walked outward. Bounded rather than open, because
-        // a malformed tree must not cost a traversal per node.
-        //
-        // An empty label does not stop the walk. Labels nested inside labels
-        // are invalid markup, but they happen: a checkbox component that draws
-        // its own `<label>` around a styled box, wrapped again by the page to
-        // add the text beside it. The inner label has no text, and returning
-        // its emptiness here made the control anonymous while a name sat one
-        // level further out. Skipping it costs nothing when the markup is
-        // well formed, because a real label has text.
-        let mut current = document.get_node(id)?.parent;
-        for _ in 0..16 {
-            let ancestor = current?;
-            if let Some(text) = self.labels.get(&ancestor)
-                && !text.trim().is_empty()
-            {
-                return Some(text.clone());
-            }
-            current = document.get_node(ancestor)?.parent;
-        }
-        None
-    }
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-/// The text a name is made of, which is not the same as `textContent`.
-///
-/// `textContent` is the DOM property and includes every text node under the
-/// element, `<style>` and `<script>` among them. An accessible name does not:
-/// those elements are not rendered, and a name computation that walks into
-/// them reads out a stylesheet.
-///
-/// Measured on honey.id, whose header logo is an anchor wrapping an inline SVG
-/// with a `<style>` in it. The site's home link arrived named
-/// ".animated-logo path { fill-opacity: 0; stroke: currentColor; ... }",
-/// which is unusable to a person and unaddressable to a check.
-///
-/// Measured on crates.vip, whose failure alert stacks two block-level lines.
-/// It arrived named "This page could not loadWebSocket connection failed",
-/// because every text node was concatenated with nothing between it and the
-/// next. A browser puts a space there: accname appends each descendant's
-/// contribution separated by a space unless the descendant is inline, which
-/// is why "<span>a</span><span>b</span>" is still "ab".
-fn name_text(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument) -> String {
-    /// Whether this node's contribution runs into its siblings' or stands
-    /// apart from them. Text and inline-level elements run together; anything
-    /// laid out as a block, a flex item's container, a table cell and so on
-    /// is a separate run. An element with no resolved style is treated as
-    /// inline, which keeps a name from gaining spaces that are not there.
-    fn is_inline(node: &blitz_dom::Node) -> bool {
-        use style::values::specified::box_::{DisplayInside, DisplayOutside};
-        if node.element_data().is_none() {
-            return true;
-        }
-        node.primary_styles().is_none_or(|styles| {
-            let display = styles.clone_display();
-            // Inline flow only. `inline-block` and `inline-flex` are atomic
-            // inlines: they establish their own box and a browser separates
-            // them from their siblings, which is the same rule
-            // `dom-accessibility-api` applies by comparing the computed
-            // display against the string "inline".
-            display.outside() == DisplayOutside::Inline && display.inside() == DisplayInside::Flow
-        })
-    }
-
-    fn write(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument, out: &mut String) {
-        if let Some(element) = node.element_data()
-            && matches!(
-                element.name.local.as_ref(),
-                "style" | "script" | "template" | "noscript"
-            )
-        {
-            return;
-        }
-        if let blitz_dom::node::NodeData::Text(text) = &node.data {
-            out.push_str(&text.content);
-        }
-        for child in &node.children {
-            let Some(child) = document.get_node(*child) else {
-                continue;
-            };
-            // What is not rendered is not part of the name.
-            //
-            // A responsive control writes both labels and shows one:
-            // `sm:hidden` on the short one, `hidden sm:inline` on the long one.
-            // Folding both together produced "Book Book a diagnostic", a name
-            // no viewer at any width can see and no check can be written
-            // against. `visibility: hidden` and `aria-hidden` are excluded for
-            // the same reason, which is the rule accname states directly.
-            //
-            // Elements only. A text node carries no display of its own, so it
-            // is present exactly when the element holding it is.
-            if child.element_data().is_some() && !node_is_individually_visible(child) {
-                continue;
-            }
-            // A boundary either side, so a block between two others is
-            // separated from both. `normalize_name` collapses the runs.
-            let separate = !is_inline(child);
-            if separate {
-                out.push(' ');
-            }
-            write(child, document, out);
-            if separate {
-                out.push(' ');
-            }
-        }
-    }
-    let mut out = String::new();
-    write(node, document, &mut out);
-    out
-}
-
-/// Whether a role takes its accessible name from its own subtree when the
-/// author wrote no explicit one.
-///
-/// ARIA's *nameFrom: author, contents*, and nothing else. The list is closed on
-/// purpose: a role that is not on it is named only by what the author declared,
-/// because a container's text content is its whole subtree and naming those
-/// would give every wrapper on a page a name made of the page.
-///
-/// `alert` and `status` are here because they are the roles an application uses
-/// to say something happened -- a refusal, a saved confirmation -- and what they
-/// say is their content. Without them a live region arrives anonymous, so "the
-/// reason is shown" is not a question a suite can ask, and every validation
-/// outcome has to be approximated by something else that moved.
-///
-/// `menuitem`, `tab` and `treeitem` are the menu, tab and tree equivalents of
-/// `option`. Leaving them out made every dropdown item in the fleet anonymous:
-/// a `<button role="menuitem">Platform Admin</button>` came back with an empty
-/// name, so nothing was announced and no check could name the option it meant
-/// to press.
-///
-/// The table roles are here because ARIA gives all five of them
-/// *nameFrom: contents*, and their absence is why whole tables of crate names,
-/// versions and column types were unreadable: the cells were in the tree and
-/// every one of them was anonymous, which reads from outside as a table that is
-/// not in the tree at all. A row's name being the run of its cells is not an
-/// accident of that rule, it is the rule: it is what a screen reader announces
-/// when the caret enters the row.
-///
-/// `semantic_role` returns a `role` attribute verbatim, so an author who writes
-/// one of these opts into the naming this list provides.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn names_from_contents(role: &str) -> bool {
-    matches!(
-        role,
-        "button"
-            | "link"
-            | "heading"
-            | "option"
-            | "alert"
-            | "status"
-            // The same class as `alert` and `status`: a tooltip exists to say
-            // one thing, and what it says is its content. Anonymous, it is a
-            // node reporting that some explanation is on screen without
-            // reporting the explanation.
-            | "tooltip"
-            | "menuitem"
-            | "menuitemcheckbox"
-            | "menuitemradio"
-            | "tab"
-            | "treeitem"
-            | "cell"
-            | "gridcell"
-            | "columnheader"
-            | "rowheader"
-            | "row"
-    )
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn semantic_name(
-    element: &blitz_dom::ElementData,
-    node: &blitz_dom::Node,
-    role: &str,
-    document: &blitz_dom::BaseDocument,
-    id: blitz_dom::NodeId,
-    labels: &LabelIndex,
-) -> String {
-    // The elements an author pointed at, which outrank everything below.
-    //
-    // ARIA's order: `aria-labelledby` first, then `aria-label`, then the host
-    // language's own labelling, then contents. It is first because it is the
-    // most deliberate thing an author can write. Naming one element by the
-    // visible text of another says the two belong together, and it is the only
-    // rule here that can name something from outside itself.
-    let name = labels
-        .labelled_by(document, element)
-        .map(std::borrow::Cow::Owned)
-        .or_else(|| element_attr(element, "aria-label").map(std::borrow::Cow::Borrowed))
-        // The label a form control was given. After `aria-label`, which is the
-        // author overriding the visible text on purpose, and before `title`,
-        // which is a tooltip rather than a name.
-        .or_else(|| {
-            labels
-                .name_for(document, id, element)
-                .map(std::borrow::Cow::Owned)
-        })
-        .or_else(|| element_attr(element, "alt").map(std::borrow::Cow::Borrowed))
-        .or_else(|| element_attr(element, "title").map(std::borrow::Cow::Borrowed))
-        // An option's `label`, which HTML gives precedence over the option's
-        // own text: `<option label="Sixty four bits">u64</option>` announces the
-        // label.
-        .or_else(|| {
-            (role == "option")
-                .then(|| element_attr(element, "label"))
-                .flatten()
-                .map(std::borrow::Cow::Borrowed)
-        })
-        // Named by their own content.
-        //
-        // Empty contents are not a name, and stopping here on an empty string
-        // is how the fallbacks below became unreachable for the roles on this
-        // list.
-        .or_else(|| {
-            names_from_contents(role)
-                .then(|| name_text(node, document))
-                .filter(|text| !text.trim().is_empty())
-                .map(std::borrow::Cow::Owned)
-        })
-        // What is left of an option that carries no text at all: a
-        // `<datalist>` entry is written `<option value="u64">`, and its value is
-        // what a browser announces and what a person sees in the list.
-        .or_else(|| {
-            (role == "option")
-                .then(|| element_attr(element, "value"))
-                .flatten()
-                .map(std::borrow::Cow::Borrowed)
-        })
-        // A placeholder is the last resort a browser falls back to, and it is
-        // the only thing naming a great many search and filter fields. Last, so
-        // it never displaces a real label.
-        .or_else(|| {
-            matches!(role, "textbox" | "combobox")
-                .then(|| element_attr(element, "placeholder").map(std::borrow::Cow::Borrowed))
-                .flatten()
-        })
-        .unwrap_or_default();
-    normalize_text(&name)
-}
-
-/// One space between words, and 512 characters at most.
-///
-/// A name crosses a socket and is matched against by a check, so the runs of
-/// newlines and indentation that markup puts between two words are noise in
-/// both places. The cap is on the value that leaves here rather than on the
-/// text that arrives, so a name made of a long subtree still starts with the
-/// words a person would read first.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn normalize_text(text: &str) -> String {
-    let mut normalized = String::with_capacity(text.len().min(512));
-    let mut characters = 0;
-    for word in text.split_whitespace() {
-        if !normalized.is_empty() && characters < 512 {
-            normalized.push(' ');
-            characters += 1;
-        }
-        for character in word.chars() {
-            if characters == 512 {
-                return normalized;
-            }
-            normalized.push(character);
-            characters += 1;
-        }
-    }
-    normalized
-}
-
-/// The text a node contributes to the tree in its own right, if any.
-///
-/// # Why text is in this tree at all
-///
-/// Everything that is not an element was dropped, so text that is not some
-/// element's accessible name could not be read at all: a paragraph, a `<pre>`,
-/// a code block, the prose of a documentation page. A check could assert that a
-/// button exists and not that the page says what the button does.
-///
-/// It is not only a check limitation. A browser exposes those text runs, and so
-/// does blitz-dom, whose own accessibility tree gives every text node
-/// `Role::TextRun` with its content. This tree disagreed with both.
-///
-/// # Why not every text node
-///
-/// Text under a role that is named by its contents is already in the tree, as
-/// that node's name, and that node is the one a harness can act on. Reporting
-/// it twice would make "the page says this once" false and hand a check a node
-/// it cannot click for text it can already read. It is the rule the ARIA
-/// snapshot formats apply as well: a button carries its label, and no separate
-/// text line appears under it.
-///
-/// `<style>`, `<script>` and friends are excluded for the reason `name_text`
-/// excludes them: their content is not rendered, and reading it out returns a
-/// stylesheet.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn exposed_text(
-    document: &blitz_dom::BaseDocument,
-    id: blitz_dom::NodeId,
-    node: &blitz_dom::Node,
-) -> Option<String> {
-    let blitz_dom::node::NodeData::Text(text) = &node.data else {
-        return None;
-    };
-    let normalized = normalize_text(&text.content);
-    if normalized.is_empty() {
-        return None;
-    }
-    // Every element above it, not only the nearest one: the text of
-    // `<button><span>Save</span></button>` is the button's name however many
-    // wrappers sit between the two, and the span it is written in does not make
-    // it a second appearance of the same words.
-    let mut current = document.get_node(id)?.parent;
-    for _ in 0..64 {
-        let Some(ancestor) = current else {
-            break;
-        };
-        let ancestor_node = document.get_node(ancestor)?;
-        if let Some(element) = ancestor_node.element_data() {
-            if matches!(
-                element.name.local.as_ref(),
-                "style" | "script" | "template" | "noscript" | "title"
-            ) {
-                return None;
-            }
-            if names_from_contents(semantic_role_ref(element)) {
-                return None;
-            }
-        }
-        current = ancestor_node.parent;
-    }
-    Some(normalized)
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-fn semantic_value(element: &blitz_dom::ElementData) -> Option<String> {
-    element
-        .text_input_data()
-        .map(|input| input.editor.text().to_string())
-        .or_else(|| {
-            element
-                .checkbox_input_checked()
-                .map(|checked| checked.to_string())
-        })
-        .or_else(|| element_attr(element, "aria-valuenow").map(str::to_string))
-        .or_else(|| element_attr(element, "value").map(str::to_string))
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn semantic_selected(element: &blitz_dom::ElementData) -> bool {
-    /*
-     * A real checkbox answers from its live state, not from its markup.
-     *
-     * `checkbox_input_checked` is the value the DOM updates when the control is
-     * toggled; the attributes below are the document as it was parsed and never
-     * move again. Asking the attributes about an input that has one is how a
-     * toggle reports the same state for ever.
-     */
-    if let Some(checked) = element.checkbox_input_checked() {
-        return checked;
-    }
-
-    /*
-     * Presence is not truth for these two.
-     *
-     * `checked` and `selected` are HTML boolean attributes, so bare `checked`
-     * means on. But a framework that renders a controlled value writes the
-     * value out: Solid emits `checked="false"`, and `.is_some()` called that
-     * selected. Every Switch, Radio and Checkbox in the QA harness reported
-     * `selected: true` before anything was pressed and could never change,
-     * which read as three components that ignore a click.
-     *
-     * Explicitly `"false"` is off; anything else present is on.
-     */
-    let attribute_on = |name| match element_attr(element, name) {
-        Some("false") => false,
-        Some(_) => true,
-        None => false,
-    };
-
-    element_attr(element, "aria-selected") == Some("true")
-        || element_attr(element, "aria-pressed") == Some("true")
-        || element_attr(element, "aria-checked") == Some("true")
-        || element_attr(element, "aria-current").is_some_and(|value| value != "false")
-        || attribute_on("checked")
-        || attribute_on("selected")
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-fn semantic_parent(
-    document: &blitz_dom::BaseDocument,
-    node_id: blitz_dom::NodeId,
-    root: Option<blitz_dom::NodeId>,
-) -> Option<blitz_dom::NodeId> {
-    if Some(node_id) == root {
-        return None;
-    }
-    let mut current = document.get_node(node_id)?.parent;
-    while let Some(id) = current {
-        let node = document.get_node(id)?;
-        if node.element_data().is_some() {
-            return Some(id);
-        }
-        current = node.parent;
-    }
-    None
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn node_is_visible(
-    document: &blitz_dom::BaseDocument,
-    node_id: blitz_dom::NodeId,
-) -> bool {
-    let mut current = Some(node_id);
-    while let Some(id) = current {
-        let Some(node) = document.get_node(id) else {
-            return false;
-        };
-        if !node_is_individually_visible(node) {
-            return false;
-        }
-        current = node.parent;
-    }
-    true
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn dom_chain_is_attached(
-    document: &blitz_dom::BaseDocument,
-    node_id: blitz_dom::NodeId,
-    node_limit: usize,
-) -> bool {
-    let root = document.root_node().id;
-    let mut current = Some(node_id);
-    // Removed DOM nodes intentionally remain allocated while JavaScript may
-    // still hold wrappers for them. They are not part of the document unless
-    // their parent chain reaches the one document root.
-    for _ in 0..=node_limit {
-        let Some(id) = current else {
-            return false;
-        };
-        if id == root {
-            return true;
-        }
-        let Some(node) = document.get_node(id) else {
-            return false;
-        };
-        current = node.parent;
-    }
-    false
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn layout_chain_is_valid(
-    document: &blitz_dom::BaseDocument,
-    node_id: blitz_dom::NodeId,
-    node_limit: usize,
-) -> bool {
-    let mut current = Some(node_id);
-    // A valid layout chain reaches its root in no more steps than there are
-    // nodes. The bound also rejects corrupt cycles instead of hanging control.
-    for _ in 0..=node_limit {
-        let Some(id) = current else {
-            return true;
-        };
-        let Some(node) = document.get_node(id) else {
-            return false;
-        };
-        current = node.layout_parent.get();
-    }
-    false
-}
-
-/// Activate the node the caller selected, without asking hit-testing to select
-/// it a second time from a screen coordinate.
-///
-/// The coordinates carried by DOM events are still the node's own geometry,
-/// because handlers use offsets and text fields use them for caret placement.
-/// They never choose the target. An overflowed or clipped node therefore gets
-/// the same pointer, mouse and click sequence as an on-screen one.
-#[cfg(all(feature = "agent-control", unix))]
-/// Click a semantic node, by id, the way the runtime does.
-///
-/// Dispatches pointer, mouse and click events in browser order against the
-/// document directly, so a headless host can drive a control without a window,
-/// a pointer or a compositor. This is what makes the interaction checks
-/// runnable at all: a still picture of the tree cannot answer what a control
-/// does when it is pressed.
-#[cfg(all(feature = "agent-control", unix))]
-/// Send one key to a document, down then up.
-///
-/// Only keys, deliberately. The pointer and wheel arms of the runtime's input
-/// handler carry pointer position and button state on the runtime itself, and a
-/// headless host has no window for those to mean anything against. A key needs
-/// nothing but the document.
-///
-/// Escape closing a menu is a real assertion in a check suite, and it is the one
-/// that says a control does not trap the person using it. Without this a host
-/// answers those checks with `unsupported`, which is honest but leaves the
-/// suite unable to run them at all.
-#[cfg(all(feature = "agent-control", unix))]
-/// Move the pointer onto a semantic node, by id.
-///
-/// The position comes from the node's own box, so this needs no pointer
-/// bookkeeping and works in a host that has no window to own a cursor. A
-/// control revealed on hover cannot be reached any other way, and a defect that
-/// only appears on the second entry cannot be reached at all without it.
-#[cfg(all(feature = "agent-control", unix))]
-pub fn hover_agent_node(
-    document: &mut ScriptDocument,
-    node_id: u64,
-) -> Result<(f32, f32), DebugError> {
-    let position = resolve_agent_node(document, node_id)?.1;
-    document.handle_ui_event(UiEvent::PointerMove(pointer_event(
-        position,
-        MouseEventButton::Main,
-        MouseEventButtons::default(),
-        KeyboardModifiers::empty(),
-    )));
-    Ok(position)
-}
-
-pub fn press_agent_key(
-    document: &mut ScriptDocument,
-    key: &str,
-    code: &str,
-) -> Result<(), DebugError> {
-    let parsed_key = key
-        .parse::<Key>()
-        .unwrap_or_else(|_| Key::Character(key.to_owned()));
-    let parsed_code = code.parse::<Code>().unwrap_or(Code::Unidentified);
-    for phase in [KeyPhase::Down, KeyPhase::Up] {
-        let event = key_event(
-            phase,
-            parsed_key.clone(),
-            parsed_code,
-            keyboard_modifiers(Default::default()),
-        );
-        document.handle_ui_event(match phase {
-            KeyPhase::Down => UiEvent::KeyDown(event),
-            KeyPhase::Up => UiEvent::KeyUp(event),
-        });
-    }
-    Ok(())
-}
-
-pub fn click_agent_node(
-    document: &mut ScriptDocument,
-    node_id: u64,
-    count: u8,
-) -> Result<(f32, f32), DebugError> {
-    activate_agent_node(document, node_id, count)
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub fn focus_agent_node(
-    document: &mut ScriptDocument,
-    node_id: blitz_dom::NodeId,
-) -> Result<(), DebugError> {
-    let focusable = document
-        .inner()
-        .get_node(node_id)
-        .and_then(|node| node.element_data())
-        .is_some_and(focuses_on_click);
-    if !focusable {
-        return Err(debug_error(
-            "notFocusable",
-            "node does not accept keyboard focus",
-        ));
-    }
-    document.inner_mut().set_focus_to(node_id);
-    Ok(())
-}
-
-/// Read a document's semantic tree.
-///
-/// Split out of the runtime's `Inspect` handler so a host that is not this
-/// runtime can answer the same request from the same code. Nothing in it is
-/// window-dependent: it polls the document, resolves layout and reads the tree.
-///
-/// Sharing the implementation is the point. A second copy of "what is a node's
-/// name" drifts from this one immediately. A QA harness that reimplemented
-/// naming against `build_accessibility_tree` got a different answer than the
-/// inspector for every element on the page, because that builder names only
-/// text nodes and carries no geometry at all.
-#[cfg(all(feature = "agent-control", unix))]
-pub fn inspect_document(
-    document: &mut ScriptDocument,
-    root: Option<u64>,
-    max_depth: u32,
-    revision: u64,
-) -> DebugResponse {
-    /*
-     * Drain immediately runnable script work, but do not force a full style and
-     * layout pass for an already committed document. Agent actions resolve
-     * before their Ack and the window loop resolves asynchronous frames; an
-     * idle inspection is an observer, not another frame driver. Re-resolving
-     * every 25ms made scoped outcome latency proportional to the entire retained
-     * application even though the response contained one pane.
-     */
-    let mut ran_script = false;
-    for _ in 0..100 {
-        if !document.poll(None) {
-            break;
-        }
-        ran_script = true;
-    }
-    if ran_script {
-        document.inner_mut().resolve(0.0);
-    }
-    let inner = document.inner();
-    let root = root.map(blitz_dom::NodeId::from_u64);
-    if root.is_some_and(|id| inner.get_node(id).is_none()) {
-        return control_error("unknownNode", "the requested root node does not exist");
-    }
-    let focused_node = inner.get_focussed_node_id().map(|id| id.as_u64());
-    // Built over the whole document even when a subtree was asked for: a label
-    // is frequently a sibling of the control rather than a descendant of the
-    // node the caller rooted at.
-    let labels = LabelIndex::build(&inner);
-    let node_limit = inner.tree().iter().count();
-    let candidates = if let Some(root) = root {
-        semantic_subtree_ids(&inner, root, max_depth)
-            .into_iter()
-            .filter_map(|id| {
-                inner.get_node(id)?;
-                dom_chain_is_attached(&inner, id, node_limit).then(|| SemanticCandidate {
-                    id,
-                    parent: semantic_parent(&inner, id, Some(root)),
-                    visible: node_is_visible(&inner, id),
-                })
-            })
-            .collect()
-    } else {
-        attached_semantic_candidates(&inner, max_depth)
-    };
-    let layout_validity = layout_chain_validities(&inner, &candidates, node_limit);
-    let nodes = candidates
-        .into_iter()
-        .filter_map(|candidate| {
-            let id = candidate.id;
-            let node = inner.get_node(id)?;
-            if layout_validity.get(&id) != Some(&true) {
-                return None;
-            }
-            let rect = inner.get_client_bounding_rect(id);
-            let bounds = rect.and_then(|rect| {
-                let bounds = [rect.x, rect.y, rect.width, rect.height];
-                bounds
-                    .iter()
-                    .all(|value| value.is_finite())
-                    .then_some(bounds)
-            });
-            let Some(element) = node.element_data() else {
-                // Text the page shows in its own right. A text run has no
-                // attributes, no state and nothing to press, so every field
-                // below the name describes the box it is drawn in.
-                let text = exposed_text(&inner, id, node)?;
-                return Some(SemanticNode {
-                    dom_id: None,
-                    id: id.as_u64(),
-                    parent: candidate.parent.map(|id| id.as_u64()),
-                    role: "text".to_owned(),
-                    name: text,
-                    value: None,
-                    enabled: true,
-                    visible: candidate.visible,
-                    selected: false,
-                    bounds,
-                    slot: None,
-                });
-            };
-            let visible = candidate.visible
-                && rect
-                    .as_ref()
-                    .is_some_and(|rect| rect.width > 0.0 && rect.height > 0.0);
-            let role = semantic_role(element);
-            let name = semantic_name(element, node, &role, &inner, id, &labels);
-            let value = semantic_value(element);
-            Some(SemanticNode {
-                dom_id: element_attr(element, "id").map(str::to_owned),
-                id: id.as_u64(),
-                parent: candidate.parent.map(|id| id.as_u64()),
-                role,
-                name,
-                value,
-                enabled: element_attr(element, "disabled").is_none()
-                    && element_attr(element, "aria-disabled") != Some("true"),
-                visible,
-                selected: semantic_selected(element),
-                bounds,
-                slot: element_attr(element, "data-slot").map(str::to_owned),
-            })
-        })
-        .collect();
-    DebugResponse::AgentSnapshot(AgentSnapshot {
-        revision,
-        active_window: Some("blitz-main".into()),
-        focused_node,
-        nodes,
-    })
-}
-
-/// Carry blitz-shell's timing summary onto the wire type.
-///
-/// The two structs are deliberately separate: the protocol is versioned by this
-/// crate, while the shell type is free to grow fields that have no wire meaning.
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) fn timing_stats(stats: blitz_shell::TimingStats) -> TimingStats {
-    TimingStats {
-        mean_ms: stats.mean_ms,
-        p95_ms: stats.p95_ms,
-        max_ms: stats.max_ms,
-    }
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn debug_error(code: &str, message: &str) -> DebugError {
-    DebugError {
-        code: code.into(),
-        message: message.into(),
-    }
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn focuses_on_click(element: &blitz_dom::ElementData) -> bool {
-    let tag = element.name.local.as_ref();
-    matches!(tag, "button" | "input" | "select" | "textarea")
-        || tag == "a" && element_attr(element, "href").is_some()
-        || element_attr(element, "tabindex")
-            .and_then(|value| value.parse::<i32>().ok())
-            .is_some_and(|value| value >= 0)
-        || element_attr(element, "contenteditable").is_some_and(|value| value != "false")
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) fn resident_bytes() -> Option<u64> {
-    let output = std::process::Command::new("ps")
-        .args(["-o", "rss=", "-p", &std::process::id().to_string()])
-        .output()
-        .ok()?;
-    if !output.status.success() {
-        return None;
-    }
-    std::str::from_utf8(&output.stdout)
-        .ok()?
-        .trim()
-        .parse::<u64>()
-        .ok()
-        .and_then(|kilobytes| kilobytes.checked_mul(1_024))
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn node_is_individually_visible(node: &blitz_dom::Node) -> bool {
-    if !node.flags.is_in_document() || node.is_display_none() {
-        return false;
-    }
-    /*
-     * `visibility: hidden` counts too, not just `display: none`.
-     *
-     * The two are different in layout and identical to a viewer: a hidden
-     * node keeps its box and paints nothing. Reporting it as visible made
-     * an audit of the running application call it a fault, because the box
-     * was there and the pixels were not. Tailwind's `invisible` is exactly
-     * this, and it is how a control that is deliberately dormant - a Stop
-     * button with no run to stop - is expressed.
-     *
-     * `Collapse` is included: on anything that is not a table row it means
-     * the same as `Hidden`, and on a row it removes the row entirely, so
-     * treating it as not-visible is right in both cases.
-     */
-    if node.primary_styles().is_some_and(|style| {
-        use style::computed_values::visibility::T as Visibility;
-        matches!(
-            style.clone_visibility(),
-            Visibility::Hidden | Visibility::Collapse
-        )
-    }) {
-        return false;
-    }
-    !node.element_data().is_some_and(|element| {
-        element_attr(element, "hidden").is_some()
-            || element_attr(element, "aria-hidden") == Some("true")
-    })
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn resolve_agent_node(
-    document: &mut ScriptDocument,
-    raw_node_id: u64,
-) -> Result<(blitz_dom::NodeId, (f32, f32)), DebugError> {
-    resolve_agent_node_inner(document, raw_node_id, Area::Required)
-}
-
-/// Whether the caller needs the node to have a box a pointer could land in.
-#[cfg(all(feature = "agent-control", unix))]
-#[derive(Clone, Copy, PartialEq, Eq)]
-pub(crate) enum Area {
-    /// A real pointer is going to travel to this box, so it has to have one.
-    Required,
-    /// The event is delivered to the node itself, and the coordinate only
-    /// fills in `clientX`/`clientY` for a handler that reads them.
-    Optional,
-}
-
-/// Resolve a node to press, and the point to say the press happened at.
-///
-/// The area requirement is a parameter because the two callers want different
-/// things from it. `Hover` and the pointer moves genuinely travel to a
-/// coordinate, and a box with no area has no honest one. `Click` does not:
-/// [`activate_agent_node`] dispatches every phase with
-/// `DomEvent::new(node_id, ..)`, so the node is the target and the position is
-/// only the number the event carries.
-///
-/// Requiring area of both was one predicate standing for two facts, and it
-/// made a whole class of control unpressable for a reason that has nothing to
-/// do with whether pressing it works. A control sized entirely by its label --
-/// a bare `<a>`, a trigger with no padding -- lays out at zero height on a host
-/// with no font catalogue, which is what a Linux CI runner is. It is attached,
-/// styled visible, enabled, and its handler runs perfectly well; only the
-/// coordinate it would never use was missing.
-///
-/// What still refuses is everything about the node itself: it must exist, be
-/// attached with a valid layout ancestry, not be `display: none`,
-/// `visibility: hidden`, `hidden` or `aria-hidden`, and not be disabled. Those
-/// are the reasons a press should not land, and none of them is a box size.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn resolve_agent_node_inner(
-    document: &mut ScriptDocument,
-    raw_node_id: u64,
-    area: Area,
-) -> Result<(blitz_dom::NodeId, (f32, f32)), DebugError> {
-    let node_id = blitz_dom::NodeId::from_u64(raw_node_id);
-    document.inner_mut().resolve(0.0);
-    let inner = document.inner();
-    let node = inner
-        .get_node(node_id)
-        .ok_or_else(|| debug_error("unknownNode", "node does not exist"))?;
-    if !node_is_visible(&inner, node_id) {
-        return Err(debug_error("notInteractable", "node is not visible"));
-    }
-    let node_limit = inner.tree().iter().count();
-    if !dom_chain_is_attached(&inner, node_id, node_limit)
-        || !layout_chain_is_valid(&inner, node_id, node_limit)
-    {
-        return Err(debug_error(
-            "notInteractable",
-            "node has a detached layout ancestor",
-        ));
-    }
-    if node
-        .element_data()
-        .is_some_and(|element| element_attr(element, "disabled").is_some())
-    {
-        return Err(debug_error("notInteractable", "node is disabled"));
-    }
-    let rect = inner
-        .get_client_bounding_rect(node_id)
-        .filter(|rect| area == Area::Optional || (rect.width > 0.0 && rect.height > 0.0))
-        .ok_or_else(|| {
-            debug_error(
-                "notInteractable",
-                match area {
-                    // The node was never laid out at all, which is a different
-                    // thing from being laid out flat and is worth saying so.
-                    Area::Optional => "node has no layout box",
-                    Area::Required => "node has no layout box a pointer can reach",
-                },
-            )
-        })?;
-    Ok((
-        node_id,
-        (
-            (rect.x + rect.width / 2.0) as f32,
-            (rect.y + rect.height / 2.0) as f32,
-        ),
-    ))
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn pointer_event(
-    position: (f32, f32),
-    button: MouseEventButton,
-    buttons: MouseEventButtons,
-    modifiers: KeyboardModifiers,
-) -> BlitzPointerEvent {
-    BlitzPointerEvent {
-        id: BlitzPointerId::Mouse,
-        is_primary: true,
-        coords: pointer_coords(position),
-        button,
-        buttons,
-        mods: modifiers,
-        details: PointerDetails::default(),
-        element: Point::default(),
-        active_pointers: Default::default(),
-    }
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) struct SemanticCandidate {
-    pub(crate) id: blitz_dom::NodeId,
-    pub(crate) parent: Option<blitz_dom::NodeId>,
-    pub(crate) visible: bool,
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-#[derive(Clone, Copy)]
-enum LayoutChainState {
-    Visiting,
-    Valid,
-    Invalid,
-}
-
-/// Resolve layout ancestry once for every inspected node.
-///
-/// DOM ancestry and layout ancestry are not interchangeable, but they share
-/// the same performance trap: walking every node back to a root makes a full
-/// inspection proportional to `nodes * depth`. Memoize each layout ancestor so
-/// later candidates stop at the first result the traversal already proved.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn layout_chain_validities(
-    document: &blitz_dom::BaseDocument,
-    candidates: &[SemanticCandidate],
-    node_limit: usize,
-) -> HashMap<blitz_dom::NodeId, bool> {
-    let mut states = HashMap::with_capacity(candidates.len());
-
-    for candidate in candidates {
-        if matches!(
-            states.get(&candidate.id),
-            Some(LayoutChainState::Valid | LayoutChainState::Invalid)
-        ) {
-            continue;
-        }
-
-        let mut chain = Vec::new();
-        let mut current = Some(candidate.id);
-        let valid = loop {
-            let Some(id) = current else {
-                break true;
-            };
-            match states.get(&id) {
-                Some(LayoutChainState::Valid) => break true,
-                Some(LayoutChainState::Invalid | LayoutChainState::Visiting) => break false,
-                None => {}
-            }
-            if chain.len() > node_limit {
-                break false;
-            }
-            let Some(node) = document.get_node(id) else {
-                break false;
-            };
-            states.insert(id, LayoutChainState::Visiting);
-            chain.push(id);
-            current = node.layout_parent.get();
-        };
-
-        let resolved = if valid {
-            LayoutChainState::Valid
-        } else {
-            LayoutChainState::Invalid
-        };
-        for id in chain {
-            states.insert(id, resolved);
-        }
-    }
-
-    states
-        .into_iter()
-        .filter_map(|(id, state)| match state {
-            LayoutChainState::Valid => Some((id, true)),
-            LayoutChainState::Invalid => Some((id, false)),
-            LayoutChainState::Visiting => None,
-        })
-        .collect()
-}
-
-/// Collect one rooted DOM subtree in document order without visiting retained
-/// panes outside it.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn semantic_subtree_ids(
-    document: &blitz_dom::BaseDocument,
-    root: blitz_dom::NodeId,
-    max_depth: u32,
-) -> Vec<blitz_dom::NodeId> {
-    let mut out = Vec::new();
-    let mut stack = vec![(root, 0_u32)];
-    while let Some((node_id, depth)) = stack.pop() {
-        let Some(node) = document.get_node(node_id) else {
-            continue;
-        };
-        if node.element_data().is_some() || node.is_text_node() {
-            out.push(node_id);
-        }
-        for &child_id in node.children.iter().rev() {
-            let child_depth = depth.saturating_add(
-                document
-                    .get_node(child_id)
-                    .is_some_and(|child| child.element_data().is_some()) as u32,
-            );
-            if max_depth == 0 || child_depth <= max_depth {
-                stack.push((child_id, child_depth));
-            }
-        }
-    }
-    out
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn pointer_coords((x, y): (f32, f32)) -> PointerCoords {
-    PointerCoords {
-        page_x: x,
-        page_y: y,
-        screen_x: x,
-        screen_y: y,
-        client_x: x,
-        client_y: y,
-    }
-}
-
-/// The colours a node actually resolved to, as `#rrggbbaa`.
-///
-/// The point of reporting these rather than the stylesheet is that they are the
-/// end of the chain: the cascade, every custom-property indirection and the
-/// `@supports` gating have already been applied, so a disagreement between what
-/// a rule declares and what an element paints shows up here and nowhere else.
-/// That disagreement is exactly the shape of "this text is invisible and the CSS
-/// says it should not be", which cannot be settled by reading files.
-///
-/// Four properties rather than a full longhand dump: a complete style for every
-/// node in a real application is megabytes of JSON that nobody reads, and these
-/// are the ones legibility depends on.
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) fn diagnostic_style_row(
-    document: &blitz_dom::BaseDocument,
-    node: &SemanticNode,
-) -> Option<serde_json::Value> {
-    let dom_node = document.get_node(NodeId::from_u64(node.id))?;
-    let styles = dom_node.primary_styles()?;
-
-    let current = styles.clone_color();
-    // The same conversion `blitz-paint` does before handing a colour to the
-    // rasteriser, inlined so this crate does not need that extension trait.
-    let hex = |absolute: style::color::AbsoluteColor| {
-        let [r, g, b, a] = *absolute
-            .to_color_space(style::color::ColorSpace::Srgb)
-            .raw_components();
-        let channel = |value: f32| (value.clamp(0.0, 1.0) * 255.0).round() as u8;
-        format!(
-            "#{:02x}{:02x}{:02x}{:02x}",
-            channel(r),
-            channel(g),
-            channel(b),
-            channel(a),
-        )
-    };
-
-    /*
-     * Reported as a plain number of pixels rather than stylo's debug shape,
-     * which nothing reading this over the wire can parse - and being able to
-     * read it is the entire reason the field exists.
-     */
-    let radius = format!("{:?}", styles.get_border().border_top_left_radius.0.width);
-    let border = styles.get_border();
-    let border_width = border.border_top_width.0.to_f64_px();
-    let font_size = styles.clone_font_size().computed_size().px();
-    let has_text_content = !dom_node.text_content().trim().is_empty();
-
-    Some(serde_json::json!({
-        "nodeId": node.id,
-        "color": hex(current),
-        "backgroundColor": hex(
-            styles.clone_background_color().resolve_to_absolute(&current),
-        ),
-        "borderColor": hex(border.border_top_color.resolve_to_absolute(&current)),
-        "borderWidth": format!("{border_width}px"),
-        "fontSize": format!("{font_size}px"),
-        "hasTextContent": has_text_content,
-        "opacity": styles.clone_opacity(),
-        /*
-         * The corner, as the renderer resolved it.
-         *
-         * Radius is set from three unrelated places in a themed application -
-         * the library's own component CSS, the theme's tokens, and utility
-         * classes at the call site - and which one wins is a cascade question
-         * that reading any single file cannot answer. Reported repeatedly as
-         * "radius is wrong" with no way to tell *which* of the three was
-         * responsible; this is what settles it per element.
-         */
-        "borderTopLeftRadius": radius,
-        "visibility": format!("{:?}", styles.clone_visibility()),
-    }))
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn keyboard_modifiers(modifiers: ControlModifiers) -> KeyboardModifiers {
-    let mut output = KeyboardModifiers::empty();
-    output.set(KeyboardModifiers::SHIFT, modifiers.shift);
-    output.set(KeyboardModifiers::CONTROL, modifiers.control);
-    output.set(KeyboardModifiers::ALT, modifiers.alt);
-    output.set(KeyboardModifiers::META, modifiers.meta);
-    output
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn key_event(
-    phase: KeyPhase,
-    key: Key,
-    code: Code,
-    modifiers: KeyboardModifiers,
-) -> BlitzKeyEvent {
-    let text = match (&key, phase) {
-        (Key::Character(value), KeyPhase::Down)
-            if !modifiers.intersects(
-                KeyboardModifiers::CONTROL | KeyboardModifiers::ALT | KeyboardModifiers::META,
-            ) =>
-        {
-            Some(value.clone().into())
-        }
-        _ => None,
-    };
-    BlitzKeyEvent {
-        key,
-        code,
-        modifiers,
-        location: Location::Standard,
-        is_auto_repeating: false,
-        is_composing: false,
-        state: match phase {
-            KeyPhase::Down => KeyState::Pressed,
-            KeyPhase::Up => KeyState::Released,
-        },
-        text,
-    }
-}
-
-/// Collect the attached document in one traversal.
-///
-/// The previous full inspection asked every node to rediscover its depth,
-/// semantic parent, attachment and inherited visibility by walking back to the
-/// root independently. A retained application therefore paid roughly
-/// `nodes * depth` before it serialized one byte. Carry those inherited facts
-/// down the tree once instead.
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn attached_semantic_candidates(
-    document: &blitz_dom::BaseDocument,
-    max_depth: u32,
-) -> Vec<SemanticCandidate> {
-    let root = document.root_node().id;
-    let mut candidates = Vec::new();
-    let mut stack = vec![(root, 0_u32, None, true)];
-
-    while let Some((id, depth, semantic_parent, ancestors_visible)) = stack.pop() {
-        let Some(node) = document.get_node(id) else {
-            continue;
-        };
-        let visible = ancestors_visible && node_is_individually_visible(node);
-        let is_element = node.element_data().is_some();
-        if is_element && max_depth != 0 && depth > max_depth {
-            continue;
-        }
-        // Elements, and the text a page shows in its own right. `exposed_text`
-        // decides which text nodes survive; offering them all here keeps that
-        // one rule in one place, and the walk already visits them.
-        if is_element || node.is_text_node() {
-            candidates.push(SemanticCandidate {
-                id,
-                parent: semantic_parent,
-                visible,
-            });
-        }
-
-        let child_depth = depth.saturating_add(is_element as u32);
-        let child_parent = if is_element {
-            Some(id)
-        } else {
-            semantic_parent
-        };
-        for &child in node.children.iter().rev() {
-            stack.push((child, child_depth, child_parent, visible));
-        }
-    }
-
-    candidates
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-pub(crate) fn control_error(code: &str, message: &str) -> DebugResponse {
-    DebugResponse::Error(debug_error(code, message))
-}
-
-#[cfg(all(feature = "diagnostics", unix))]
-pub(crate) fn diagnostic_layout_row(
-    document: &blitz_dom::BaseDocument,
-    node: &SemanticNode,
-) -> Option<LayoutDiagnosticRow> {
-    let bounds = node.bounds?;
-    let dom_node = document.get_node(NodeId::from_u64(node.id))?;
-    let layout = dom_node.final_layout();
-    let unzoom = |value: f32| match dom_node.primary_styles() {
-        Some(styles) => styles.effective_zoom.unzoom(value),
-        None => value,
-    };
-    // Every field here is unzoomed, including the two that used to be raw.
-    //
-    // `scrollOffset` and `scrollRange` came straight off the layout while
-    // `clientSize` and `scrollSize` went through `unzoom`, so a single row
-    // carried two unit systems and any arithmetic across them was wrong by the
-    // zoom factor. Under zoom that makes every scroller read as overscrolled,
-    // and it is not only a reading error: a consumer testing
-    // `scrollOffset < scrollSize - clientSize` for "is there more to scroll"
-    // gets a false negative at the true end, leaving an overflow control
-    // disabled while content remains off screen.
-    //
-    // Unzoomed is the right side to land on because it is what the DOM already
-    // reports: `blitz-script`'s `scrollLeft`/`scrollTop` unzoom before
-    // answering, so a raw diagnostic also disagreed with the same measurement
-    // taken from script.
-    //
-    // Not covered by a unit test, deliberately rather than by omission. The
-    // existing row test runs at zoom 1, where `unzoom` is the identity and a
-    // mixed row is indistinguishable from a consistent one. Reproducing it
-    // needs a scroller that is itself zoomed, and in this engine `zoom` on an
-    // `overflow-y:auto` element leaves `scroll_height()` at 0 while `zoom` on
-    // its child does not reach the scroller's own styles — so a test asserting
-    // the relation either holds vacuously (0 == 0) or fails its own setup.
-    // Verified against a zoomed live scroller where the raw offset exceeded
-    // the unzoomed range by exactly the zoom factor.
-    let scroll_offset = dom_node.scroll_offset();
-    Some(LayoutDiagnosticRow {
-        node_id: node.id,
-        bounds: LayoutBounds::from(bounds),
-        scroll_offset: LayoutOffset {
-            x: f64::from(unzoom(scroll_offset.x as f32)),
-            y: f64::from(unzoom(scroll_offset.y as f32)),
-        },
-        client_size: LayoutSize {
-            width: f64::from(unzoom(layout.size.width)),
-            height: f64::from(unzoom(layout.size.height)),
-        },
-        scroll_size: LayoutSize {
-            width: f64::from(unzoom(layout.size.width + layout.scroll_width())),
-            height: f64::from(unzoom(layout.size.height + layout.scroll_height())),
-        },
-        scroll_range: LayoutSize {
-            width: f64::from(unzoom(layout.scroll_width())),
-            height: f64::from(unzoom(layout.scroll_height())),
-        },
-        // Border and padding, so a box that renders taller than it was asked
-        // for can be attributed instead of guessed at.
-        //
-        // Without these the only readable numbers are the outer bounds and
-        // `clientSize`, and both are the border box: a pill declared `24px`
-        // that measures 27.8 offers no way to tell a 1px border from padding
-        // from a wrong height, and the difference decides which file to edit.
-        // Four consecutive wrong diagnoses of one composer pill came from
-        // inferring these from CSS files rather than reading what the engine
-        // computed, which is exactly the guessing this replaces.
-        //
-        // Edge order matches CSS shorthand: top, right, bottom, left.
-        border: LayoutEdges {
-            top: f64::from(unzoom(layout.border.top)),
-            right: f64::from(unzoom(layout.border.right)),
-            bottom: f64::from(unzoom(layout.border.bottom)),
-            left: f64::from(unzoom(layout.border.left)),
-        },
-        padding: LayoutEdges {
-            top: f64::from(unzoom(layout.padding.top)),
-            right: f64::from(unzoom(layout.padding.right)),
-            bottom: f64::from(unzoom(layout.padding.bottom)),
-            left: f64::from(unzoom(layout.padding.left)),
-        },
-        // The content box, which is what an author's `height` sets under the
-        // default `content-box` sizing. `clientSize` above is the border box.
-        content_size: LayoutSize {
-            width: f64::from(unzoom(
-                layout.size.width
-                    - layout.border.left
-                    - layout.border.right
-                    - layout.padding.left
-                    - layout.padding.right,
-            )),
-            height: f64::from(unzoom(
-                layout.size.height
-                    - layout.border.top
-                    - layout.border.bottom
-                    - layout.padding.top
-                    - layout.padding.bottom,
-            )),
-        },
-    })
-}
-
-pub(crate) fn activate_agent_node(
-    document: &mut ScriptDocument,
-    raw_node_id: u64,
-    count: u8,
-) -> Result<(f32, f32), DebugError> {
-    // `Area::Optional`: every phase below is dispatched with
-    // `DomEvent::new(node_id, ..)`, so the node is the target and `position`
-    // only fills in the coordinate the event carries. A control sized entirely
-    // by its label has no area on a host with no fonts and is still perfectly
-    // pressable.
-    let (node_id, position) = resolve_agent_node_inner(document, raw_node_id, Area::Optional)?;
-    let focusable = document
-        .inner()
-        .get_node(node_id)
-        .and_then(|node| node.element_data())
-        .is_some_and(focuses_on_click);
-
-    for _ in 0..count {
-        let down = pointer_event(
-            position,
-            MouseEventButton::Main,
-            MouseEventButtons::Primary,
-            KeyboardModifiers::empty(),
-        );
-        let up = pointer_event(
-            position,
-            MouseEventButton::Main,
-            MouseEventButtons::default(),
-            KeyboardModifiers::empty(),
-        );
-        for data in [
-            DomEventData::PointerDown(down.clone()),
-            DomEventData::MouseDown(down),
-            DomEventData::PointerUp(up.clone()),
-            DomEventData::MouseUp(up.clone()),
-            DomEventData::Click(up),
-        ] {
-            // A mousedown handler can deliberately replace its own control.
-            // The action already happened; later phases have no surviving
-            // target and must not be retargeted to whatever took its place.
-            if document.inner().get_node(node_id).is_none() {
-                break;
-            }
-            document.dispatch_dom_event(DomEvent::new(node_id, data));
-        }
-        if focusable && document.inner().get_node(node_id).is_some() {
-            document.inner_mut().set_focus_to(node_id);
-        }
-    }
-    Ok(position)
-}
-
-#[cfg(all(test, feature = "agent-control", unix))]
-mod tests {
-    use super::*;
-    use blitz_dom::{Document, DocumentConfig};
-
-    /// A control whose whole size is its label, next to one with padding.
-    ///
-    /// `font-size: 0` stands in for the host this exists for: a Linux CI
-    /// runner with no font catalogue, where every glyph shapes to nothing and
-    /// a trigger with no padding lays out flat. Written as a style rather than
-    /// reproduced by removing fonts, so the test says what it is testing and
-    /// does not depend on which faces the machine running it happens to have.
-    fn document() -> ScriptDocument {
-        let mut document = ScriptDocument::from_html(
-            r#"<style>
-                 button { border: 0; padding: 0; margin: 0; font-size: 0; }
-                 #padded { padding: 8px 12px; }
-               </style>
-               <button id="flat">Open dialog</button>
-               <button id="padded">Open dialog</button>"#,
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        document
-    }
-
-    fn node_id(document: &ScriptDocument, selector: &str) -> u64 {
-        document
-            .inner()
-            .query_selector(selector)
-            .unwrap()
-            .expect("the fixture should contain the selector")
-            .as_u64()
-    }
-
-    #[test]
-    fn a_control_with_no_area_is_still_pressable() {
-        let mut document = document();
-        let flat = node_id(&document, "#flat");
-        // The premise: this really is the degenerate case, not an accident of
-        // the fixture. Without it a passing test proves nothing.
-        let rect = document
-            .inner()
-            .get_client_bounding_rect(blitz_dom::NodeId::from_u64(flat));
-        assert!(
-            rect.is_some_and(|rect| rect.width == 0.0 || rect.height == 0.0),
-            "the flat button should lay out with no area"
-        );
-
-        activate_agent_node(&mut document, flat, 1)
-            .expect("a click is dispatched at the node, so it needs no area");
-    }
-
-    #[test]
-    fn a_control_with_no_area_still_refuses_a_pointer() {
-        let mut document = document();
-        let flat = node_id(&document, "#flat");
-        // The other half of the split: `Hover` moves a real pointer to a
-        // coordinate, and a flat box has no honest one. Keeping this failing
-        // is the point -- it is why the area requirement became a parameter
-        // rather than being deleted.
-        let error = hover_agent_node(&mut document, flat)
-            .expect_err("hover needs a box a pointer can land in");
-        assert!(
-            error.message.contains("no layout box"),
-            "unexpected error: {error:?}"
-        );
-    }
-
-    #[test]
-    fn a_hidden_control_is_still_refused() {
-        // The area gate was doing double duty. Deleting it for clicks must not
-        // have opened the door to a control the author hid, which is what the
-        // visibility gate above it is for.
-        let mut document = ScriptDocument::from_html(
-            r#"<button id="gone" style="display: none">Open dialog</button>"#,
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let gone = node_id(&document, "#gone");
-        let error = activate_agent_node(&mut document, gone, 1)
-            .expect_err("a display:none control must stay unpressable");
-        assert!(
-            error.message.contains("not visible"),
-            "unexpected error: {error:?}"
-        );
-    }
-}
-
-/// What the semantic tree says about one small document.
-///
-/// Every test here reads the tree through `inspect_document`, which is the
-/// entry point a headless QA host calls, rather than through the naming
-/// helpers directly. A role or a name that is right inside the crate and wrong
-/// by the time it reaches the socket is the defect these were written for.
-#[cfg(all(test, feature = "agent-control", unix))]
-mod semantic_tests {
-    use super::*;
-    use blitz_dom::DocumentConfig;
-
-    /// One document, reproducing every naming and role defect this module
-    /// covers. Kept whole rather than split per test so a fix that repairs one
-    /// case by breaking another is caught by the next assertion down.
-    const REPRO: &str = r#"<table aria-label="named table">
-  <thead><tr><th scope="col">Crate</th></tr></thead>
-  <tbody><tr><td>worktable</td></tr></tbody>
-</table>
-<section aria-label="a named section"><p>text</p></section>
-<datalist id="t"><option value="u64"></option></datalist>
-<pre>plain text in a pre</pre>
-<div role="tooltip">tooltip text</div>"#;
-
-    fn tree(html: &str) -> Vec<SemanticNode> {
-        let mut document = ScriptDocument::from_html(html, DocumentConfig::default());
-        document.inner_mut().resolve(0.0);
-        match inspect_document(&mut document, None, 0, 1) {
-            DebugResponse::AgentSnapshot(snapshot) => snapshot.nodes,
-            other => panic!("inspection did not answer with a tree: {other:?}"),
-        }
-    }
-
-    fn roles<'a>(nodes: &'a [SemanticNode], role: &str) -> Vec<&'a SemanticNode> {
-        nodes.iter().filter(|node| node.role == role).collect()
-    }
-
-    fn names(nodes: &[SemanticNode], role: &str) -> Vec<String> {
-        roles(nodes, role)
-            .into_iter()
-            .map(|node| node.name.clone())
-            .collect()
-    }
-
-    #[test]
-    fn a_header_cell_is_a_header() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            roles(&nodes, "columnheader").len(),
-            1,
-            "a `<th scope=\"col\">` is a column header, not an ordinary cell"
-        );
-        assert_eq!(roles(&nodes, "cell").len(), 1, "only the `<td>` is a cell");
-    }
-
-    #[test]
-    fn a_cell_is_named_by_what_it_holds() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            names(&nodes, "cell"),
-            vec!["worktable".to_string()],
-            "a data cell's text is its accessible name, so a table of values is readable"
-        );
-        assert_eq!(
-            names(&nodes, "columnheader"),
-            vec!["Crate".to_string()],
-            "a header cell is named by its content too"
-        );
-    }
-
-    #[test]
-    fn a_row_is_named_by_its_cells() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            names(&nodes, "row"),
-            vec!["Crate".to_string(), "worktable".to_string()],
-            "a row is named from its contents, which is what makes a table row addressable"
-        );
-    }
-
-    #[test]
-    fn a_row_scoped_header_is_a_row_header() {
-        let nodes = tree(r#"<table><tr><th scope="row">Crate</th><td>worktable</td></tr></table>"#);
-        assert_eq!(
-            roles(&nodes, "rowheader").len(),
-            1,
-            "`scope=\"row\"` makes a header describe its row, which is what blitz-dom reports"
-        );
-    }
-
-    #[test]
-    fn a_named_section_is_a_region() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            names(&nodes, "region"),
-            vec!["a named section".to_string()],
-            "a `<section>` with an accessible name is a landmark, not a wrapper"
-        );
-    }
-
-    #[test]
-    fn text_the_page_shows_is_in_the_tree() {
-        let nodes = tree(REPRO);
-        assert!(
-            names(&nodes, "text").contains(&"plain text in a pre".to_string()),
-            "a `<pre>`'s text is not any element's name, so without a text node it is unreadable: \
-             {:?}",
-            names(&nodes, "text")
-        );
-    }
-
-    #[test]
-    fn a_text_run_refuses_a_click_rather_than_panicking() {
-        // Text runs are new ids in a tree a harness drives by id, so the
-        // failure mode when one is pressed has to be a typed refusal and not a
-        // crash inside the control server.
-        let mut document =
-            ScriptDocument::from_html("<pre>plain text in a pre</pre>", DocumentConfig::default());
-        document.inner_mut().resolve(0.0);
-        let DebugResponse::AgentSnapshot(snapshot) = inspect_document(&mut document, None, 0, 1)
-        else {
-            panic!("inspection did not answer with a tree");
-        };
-        let text = snapshot
-            .nodes
-            .iter()
-            .find(|node| node.role == "text")
-            .expect("the pre's text is in the tree");
-        let error = activate_agent_node(&mut document, text.id, 1)
-            .expect_err("a text run has no box to press");
-        assert_eq!(error.code, "notInteractable", "unexpected error: {error:?}");
-    }
-
-    #[test]
-    fn text_that_already_names_a_node_is_not_repeated() {
-        let nodes = tree(REPRO);
-        let text = names(&nodes, "text");
-        assert!(
-            !text.contains(&"worktable".to_string()),
-            "the cell carries this text as its name, and the cell is the node a harness can act \
-             on: {text:?}"
-        );
-        let nodes = tree(r#"<button><span>Save</span></button>"#);
-        assert!(
-            names(&nodes, "text").is_empty(),
-            "a wrapper between a control and its text does not make the text a second node"
-        );
-    }
-
-    #[test]
-    fn a_stylesheet_is_not_text() {
-        let nodes = tree("<style>.a { color: red }</style><p>shown</p>");
-        assert_eq!(
-            names(&nodes, "text"),
-            vec!["shown".to_string()],
-            "a `<style>` is not rendered, and reading it out returns a stylesheet"
-        );
-    }
-
-    /// Both halves of a responsive label, the way Tailwind writes one.
-    ///
-    /// `sm:hidden` on the short one and `hidden sm:inline` on the long one is a
-    /// single control that says "Book" on a phone and "Book a diagnostic" on a
-    /// laptop. Exactly one of them is rendered at any width, and folding both
-    /// into the name produced "Book Book a diagnostic", which matches nothing a
-    /// person can see and nothing a check can be written against.
-    const RESPONSIVE_LABEL: &str = r#"<button>
-         <span>Book</span>
-         <span style="display: none">Book a diagnostic</span>
-       </button>"#;
-
-    #[test]
-    fn a_name_skips_a_subtree_that_is_not_rendered() {
-        let nodes = tree(RESPONSIVE_LABEL);
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Book".to_string()],
-            "a display:none subtree contributes nothing to a name"
-        );
-    }
-
-    #[test]
-    fn a_name_skips_a_subtree_that_is_hidden_or_aria_hidden() {
-        let nodes = tree(
-            r#"<button>Save<span style="visibility: hidden">draft</span><span aria-hidden="true">now</span></button>"#,
-        );
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Save".to_string()],
-            "an invisible box and an aria-hidden one are both outside the name"
-        );
-    }
-
-    #[test]
-    fn a_label_skips_what_it_does_not_show() {
-        let nodes = tree(
-            r#"<label for="url">Endpoint<span style="display: none"> (advanced)</span></label>
-               <input id="url" type="text">"#,
-        );
-        assert_eq!(
-            names(&nodes, "textbox"),
-            vec!["Endpoint".to_string()],
-            "the label a control is named by is read the same way a name is"
-        );
-    }
-
-    #[test]
-    fn a_value_only_option_is_named_by_its_value() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            names(&nodes, "option"),
-            vec!["u64".to_string()],
-            "a `<datalist>` option carries its text in `value`, which is what a browser announces"
-        );
-    }
-
-    #[test]
-    fn an_options_label_attribute_wins_over_its_text() {
-        let nodes = tree(r#"<select><option label="Sixty four bits">u64</option></select>"#);
-        assert_eq!(
-            names(&nodes, "option"),
-            vec!["Sixty four bits".to_string()],
-            "HTML gives `label` precedence over an option's own text"
-        );
-    }
-
-    #[test]
-    fn a_tooltip_says_what_it_says() {
-        let nodes = tree(REPRO);
-        assert_eq!(
-            names(&nodes, "tooltip"),
-            vec!["tooltip text".to_string()],
-            "a tooltip is named by its contents, and its contents are the whole point of it"
-        );
-    }
-
-    #[test]
-    fn an_unnamed_section_is_not_a_region() {
-        let nodes = tree("<section><p>text</p></section>");
-        assert!(
-            roles(&nodes, "region").is_empty(),
-            "HTML-AAM gives an unnamed section no landmark role, so a page of \
-             plain sections does not grow a landmark per wrapper"
-        );
-    }
-
-    /// The shape both reports arrived as: a heading names the region under it.
-    ///
-    /// A card with a title above its body is how a dashboard is written, and
-    /// `aria-labelledby` pointing at that title is the markup for saying so
-    /// without repeating the words in an attribute.
-    #[test]
-    fn a_region_is_named_by_the_heading_it_points_at() {
-        let nodes = tree(
-            r#"<h2 id="title">Fleet health</h2>
-               <section aria-labelledby="title"><p>text</p></section>"#,
-        );
-        assert_eq!(
-            names(&nodes, "region"),
-            vec!["Fleet health".to_string()],
-            "a section named by reference is a named landmark, not an anonymous one"
-        );
-    }
-
-    #[test]
-    fn a_list_of_references_is_joined_in_the_order_it_is_written() {
-        let nodes = tree(
-            r#"<span id="unit">per second</span><span id="what">Requests</span>
-               <button aria-labelledby="what unit">?</button>"#,
-        );
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Requests per second".to_string()],
-            "the ids are read in the order the author listed them, not in document order, \
-             and their text is joined by a single space"
-        );
-    }
-
-    #[test]
-    fn a_reference_outranks_an_aria_label_and_the_contents() {
-        let nodes = tree(
-            r#"<span id="title">Fleet health</span>
-               <button aria-labelledby="title" aria-label="overridden">Save</button>"#,
-        );
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Fleet health".to_string()],
-            "ARIA ranks `aria-labelledby` above `aria-label`, which is above name from contents"
-        );
-    }
-
-    /// ARIA exempts a directly referenced element from the hidden check, which
-    /// is the opposite of the rule applied inside a name's own subtree. It has
-    /// to be, or the pattern the exemption exists for names nothing: an element
-    /// written only to be pointed at is routinely not shown.
-    #[test]
-    fn a_referenced_element_names_even_when_it_is_not_rendered() {
-        let nodes = tree(
-            r#"<span id="title" style="display: none">Fleet <b>health</b></span>
-               <section aria-labelledby="title"><p>text</p></section>"#,
-        );
-        assert_eq!(
-            names(&nodes, "region"),
-            vec!["Fleet health".to_string()],
-            "a referenced element contributes its whole text even when it is hidden"
-        );
-    }
-
-    /// The other half of that rule, so the exemption stays as narrow as ARIA
-    /// makes it: the element named by the id is exempt, its subtree is not.
-    #[test]
-    fn a_reference_still_skips_what_is_hidden_inside_it() {
-        let nodes = tree(
-            r#"<span id="title">Book<span style="display: none"> a diagnostic</span></span>
-               <button aria-labelledby="title">?</button>"#,
-        );
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Book".to_string()],
-            "the hidden half of a responsive label stays out of a name reached by reference too"
-        );
-    }
-
-    #[test]
-    fn a_reference_to_nothing_falls_through_to_the_next_rule() {
-        let nodes = tree(r#"<button aria-labelledby="deleted" aria-label="Save">?</button>"#);
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Save".to_string()],
-            "an id that matches no element is not a name, so the rules below it stay reachable"
-        );
-        let nodes = tree(r#"<button aria-labelledby="deleted">Save</button>"#);
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Save".to_string()],
-            "with nothing else declared the control is still named by its own contents"
-        );
-    }
-
-    #[test]
-    fn a_reference_that_resolves_to_no_text_falls_through_too() {
-        let nodes = tree(
-            r#"<span id="title"></span>
-               <button aria-labelledby="title">Save</button>"#,
-        );
-        assert_eq!(
-            names(&nodes, "button"),
-            vec!["Save".to_string()],
-            "an element that exists and says nothing gives no name, which is not the same as \
-             giving an empty one"
-        );
-    }
-
-    /// A self-reference resolves to the element's own text and terminates.
-    ///
-    /// The `aria-label` is what makes this an assertion rather than a tautology.
-    /// A resolver that followed a reference by computing the referenced
-    /// element's *name* would either not terminate here or, with a cycle guard,
-    /// abandon the reference and answer "overridden". Reading the reference as
-    /// text is what gives the heading's own words, and it is why no cycle guard
-    /// is needed anywhere in this path.
-    #[test]
-    fn an_element_that_references_itself_is_named_by_its_own_contents() {
-        let nodes = tree(
-            r#"<h2 id="self" aria-labelledby="self" aria-label="overridden">Fleet health</h2>"#,
-        );
-        assert_eq!(
-            names(&nodes, "heading"),
-            vec!["Fleet health".to_string()],
-            "a reference is read as text and never as another name computation"
-        );
-    }
-}
diff --git a/crates/tauri-runtime-blitz/src/agent_control_server.rs b/crates/tauri-runtime-blitz/src/agent_control_server.rs
deleted file mode 100644
index 80671d3..0000000
--- a/crates/tauri-runtime-blitz/src/agent_control_server.rs
+++ /dev/null
@@ -1,812 +0,0 @@
-use std::fs::{OpenOptions, remove_file};
-use std::io::{self, Write};
-use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use std::thread::{self, JoinHandle};
-use std::time::{SystemTime, UNIX_EPOCH};
-
-use endpoint_libs::libs::ws::mcp_wire::{INVALID_REQUEST, JsonRpcError};
-use endpoint_libs::libs::ws::transport::{TransportStream, framed_json};
-use endpoint_libs::libs::ws::{MessageStream, StreamError, WireMessage};
-use tokio::net::{UnixListener, UnixStream};
-use tokio::sync::{oneshot, watch};
-
-use crate::control_protocol::{
-    AgentControlRequest, DebugDescriptor, DebugEvent, DebugResponse, DebugStream,
-    DiagnosticsRequest, IncomingRequest, decode_incoming_value, decode_wire_value,
-    encode_diagnostics_event, encode_initialize_response, encode_response, encode_rpc_error,
-    encode_tools_list_response, peek_value_request_id,
-};
-
-pub enum ControlBridgeRequest {
-    Agent(AgentControlRequest),
-    #[cfg(feature = "diagnostics")]
-    Diagnostics(DiagnosticsRequest),
-}
-
-/// How the server reaches whatever is holding the document.
-///
-/// A plain closure, deliberately: the server binds a socket, frames requests
-/// and hands them over, and knows nothing about windows, event loops or Tauri.
-/// The crate's own tests have always constructed one from a bare closure with
-/// nothing running, which is the proof that a host does not need a window to
-/// serve inspection.
-///
-/// Public so a headless host can serve one. While this was `pub(crate)` the
-/// only way to inspect a Blitz document from outside was to open a window,
-/// which is what pushed a QA harness into screenshot and tree-file workarounds
-/// that could not answer any question involving a click.
-pub type ControlBridge =
-    Arc<dyn Fn(ControlBridgeRequest) -> oneshot::Receiver<DebugResponse> + Send + Sync + 'static>;
-
-#[cfg(test)]
-pub(crate) static CONTROL_TEST_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
-
-pub struct AgentControlServer {
-    descriptor_path: PathBuf,
-    socket_path: PathBuf,
-    shutdown: Option<oneshot::Sender<()>>,
-    thread: Option<JoinHandle<()>>,
-    /// Holds deep-profiling collection open while a tool can attach.
-    ///
-    /// The consumer is out of process, so it cannot hold a session itself and
-    /// the server holds one on its behalf. The server's lifetime is the right
-    /// one: it exists exactly while the socket is listening, and a per-request
-    /// session would be useless, because the frames a snapshot reports were
-    /// presented before the request arrived.
-    ///
-    /// `None` when the profile does not permit sampling, which is the ordinary
-    /// case: inspection without deep profiling stays free.
-    _sampling: Option<blitz_shell::DeepProfilingSession>,
-}
-
-impl AgentControlServer {
-    /// Bind the inspection socket and announce the descriptor.
-    ///
-    /// Nothing here needs a window: it creates a Unix listener, writes a
-    /// descriptor file and serves frames from a thread. A headless host that
-    /// owns a document can call this and be inspected exactly like the real
-    /// application, which is what lets a QA sweep run with no display server
-    /// and still answer questions that require clicking.
-    pub fn start(bridge: ControlBridge) -> io::Result<Self> {
-        Self::start_inner(bridge, None)
-    }
-
-    /// Start with a bounded latest-value diagnostic event source.
-    ///
-    /// A watch receiver is deliberate: a slow inspector needs the newest
-    /// revision, not an ever-growing queue of every frame it failed to read.
-    pub fn start_with_events(
-        bridge: ControlBridge,
-        events: watch::Receiver<Option<DebugEvent>>,
-    ) -> io::Result<Self> {
-        Self::start_inner(bridge, Some(events))
-    }
-
-    fn start_inner(
-        bridge: ControlBridge,
-        events: Option<watch::Receiver<Option<DebugEvent>>>,
-    ) -> io::Result<Self> {
-        let instance_id = instance_id();
-        let descriptor_path = descriptor_path(&instance_id);
-        let socket_path = descriptor_path.with_extension("sock");
-        if let Some(parent) = socket_path.parent() {
-            std::fs::create_dir_all(parent)?;
-        }
-        let _ = remove_file(&socket_path);
-
-        let listener = std::os::unix::net::UnixListener::bind(&socket_path)?;
-        listener.set_nonblocking(true)?;
-        std::fs::set_permissions(&socket_path, std::fs::Permissions::from_mode(0o600))?;
-
-        let descriptor = DebugDescriptor {
-            protocol_version: crate::control_protocol::DEBUG_PROTOCOL_VERSION,
-            pid: std::process::id(),
-            instance_id,
-            address: format!("unix://{}", socket_path.display()),
-            renderer: "blitz".into(),
-            renderer_revision: env!("CARGO_PKG_VERSION").into(),
-        };
-        write_descriptor(&descriptor_path, &descriptor)?;
-        reap_dead_descriptors(&descriptor_path);
-
-        let (shutdown_tx, shutdown_rx) = oneshot::channel();
-        let thread = thread::Builder::new()
-            .name("blitz-agent-control".into())
-            .spawn(move || run(listener, bridge, events, shutdown_rx))?;
-
-        Ok(Self {
-            descriptor_path,
-            socket_path,
-            shutdown: Some(shutdown_tx),
-            thread: Some(thread),
-            // Taken after the socket is listening, so a permitted profile
-            // begins collecting for the tool that is now able to attach, and
-            // stops again when this server is dropped.
-            _sampling: blitz_shell::begin_deep_profiling(),
-        })
-    }
-
-    /// Where this server announced itself.
-    ///
-    /// A headless host prints this so a client can attach to that exact
-    /// instance. Searching the descriptor directory instead races every other
-    /// instance on the machine, and a component sweep runs one host after
-    /// another, so the newest descriptor is not reliably the right one.
-    ///
-    /// Was `#[cfg(test)]`, because inside this crate the runtime already knows
-    /// where it wrote the descriptor and only a test needed to ask.
-    pub fn descriptor_path(&self) -> &Path {
-        &self.descriptor_path
-    }
-
-    /// Reacquire the sampling session after an embedder changes permission.
-    ///
-    /// The server can start before application settings or CLI overrides are
-    /// loaded. In that order `_sampling` begins as `None`; merely granting
-    /// permission later does not mutate an already-running server, so every
-    /// diagnostic snapshot keeps reporting `script: null` until restart.
-    // Called from the runtime, which a headless consumer does not compile.
-    #[cfg_attr(not(feature = "runtime"), allow(dead_code))]
-    pub(crate) fn refresh_deep_profiling(&mut self) {
-        self._sampling = blitz_shell::begin_deep_profiling();
-    }
-
-    #[cfg(test)]
-    fn socket_path(&self) -> &Path {
-        &self.socket_path
-    }
-}
-
-impl Drop for AgentControlServer {
-    fn drop(&mut self) {
-        if let Some(shutdown) = self.shutdown.take() {
-            let _ = shutdown.send(());
-        }
-        if let Some(thread) = self.thread.take() {
-            let _ = thread.join();
-        }
-        let _ = remove_file(&self.socket_path);
-        let _ = remove_file(&self.descriptor_path);
-    }
-}
-
-fn run(
-    listener: std::os::unix::net::UnixListener,
-    bridge: ControlBridge,
-    events: Option<watch::Receiver<Option<DebugEvent>>>,
-    shutdown: oneshot::Receiver<()>,
-) {
-    let Ok(runtime) = tokio::runtime::Builder::new_current_thread()
-        .enable_io()
-        .build()
-    else {
-        return;
-    };
-    let local = tokio::task::LocalSet::new();
-    local.block_on(&runtime, async move {
-        let Ok(listener) = UnixListener::from_std(listener) else {
-            return;
-        };
-        tokio::pin!(shutdown);
-        loop {
-            tokio::select! {
-                _ = &mut shutdown => break,
-                accepted = listener.accept() => match accepted {
-                    Ok((stream, _)) => {
-                        let bridge = Arc::clone(&bridge);
-                        let events = events.clone();
-                        tokio::task::spawn_local(async move {
-                            handle_connection(stream, bridge, events).await;
-                        });
-                    }
-                    Err(_) => break,
-                }
-            }
-        }
-    });
-}
-
-enum ConnectionInput {
-    Message(Option<Result<WireMessage, StreamError>>),
-    Event(Result<(), watch::error::RecvError>),
-}
-
-fn stream_wants_event(streams: &[DebugStream], event: &DebugEvent) -> bool {
-    match event {
-        DebugEvent::Snapshot(_) => streams.contains(&DebugStream::Snapshots),
-        DebugEvent::Metrics(_) => streams.contains(&DebugStream::Metrics),
-        DebugEvent::Console(_) => streams.contains(&DebugStream::Console),
-        DebugEvent::RuntimeError(_) => streams.contains(&DebugStream::RuntimeErrors),
-        DebugEvent::PaintCommitted { .. } => streams.contains(&DebugStream::Paint),
-        _ => false,
-    }
-}
-
-async fn handle_connection(
-    stream: UnixStream,
-    bridge: ControlBridge,
-    mut events: Option<watch::Receiver<Option<DebugEvent>>>,
-) {
-    let mut stream = TransportStream::new(framed_json(stream));
-    let mut observed = Vec::<DebugStream>::new();
-    loop {
-        let input = if observed.is_empty() {
-            ConnectionInput::Message(stream.recv().await)
-        } else if let Some(receiver) = events.as_mut() {
-            tokio::select! {
-                message = stream.recv() => ConnectionInput::Message(message),
-                changed = receiver.changed() => ConnectionInput::Event(changed),
-            }
-        } else {
-            ConnectionInput::Message(stream.recv().await)
-        };
-
-        let message = match input {
-            ConnectionInput::Event(changed) => {
-                if changed.is_err() {
-                    events = None;
-                    continue;
-                }
-                let Some(event) = events
-                    .as_ref()
-                    .and_then(|receiver| receiver.borrow().clone())
-                else {
-                    continue;
-                };
-                if !stream_wants_event(&observed, &event) {
-                    continue;
-                }
-                let Ok(frame) = encode_diagnostics_event(&event) else {
-                    continue;
-                };
-                if stream.send(frame).await.is_err() {
-                    break;
-                }
-                continue;
-            }
-            ConnectionInput::Message(Some(message)) => message,
-            ConnectionInput::Message(None) => break,
-        };
-        let response = match message {
-            Ok(message) => match decode_wire_value(message) {
-                Ok(value) => {
-                    // Recover the id before typed decoding consumes the parsed
-                    // value. The previous path parsed the complete request once
-                    // for this id and again for the request itself.
-                    let request_id = peek_value_request_id(&value);
-                    match decode_incoming_value(value) {
-                        Ok(IncomingRequest::Initialize { id }) => {
-                            encode_initialize_response(id, env!("CARGO_PKG_VERSION"))
-                        }
-                        Ok(IncomingRequest::Initialized) => continue,
-                        Ok(IncomingRequest::ToolsList { id }) => {
-                            encode_tools_list_response(id, cfg!(feature = "diagnostics"))
-                        }
-                        Ok(IncomingRequest::Agent { id, request }) => {
-                            let response = bridge(ControlBridgeRequest::Agent(request))
-                                .await
-                                .unwrap_or_else(|_| {
-                                    DebugResponse::Error(crate::control_protocol::DebugError {
-                                        code: "bridgeClosed".into(),
-                                        message: "the UI-thread control bridge closed".into(),
-                                    })
-                                });
-                            encode_response(id, &response)
-                        }
-                        // The protocol defines diagnostics unconditionally; only
-                        // collection is feature-gated. A build without it answers
-                        // the caller instead of failing to compile the arm, which
-                        // is the whole reason the types are not gated.
-                        Ok(IncomingRequest::Diagnostics {
-                            id,
-                            request: DiagnosticsRequest::Observe { streams },
-                        }) => {
-                            observed = streams;
-                            // Arming observation establishes a revision baseline.
-                            // Do not immediately replay a paint that happened
-                            // before the action the caller is about to drive.
-                            if let Some(receiver) = events.as_mut() {
-                                receiver.borrow_and_update();
-                            }
-                            encode_response(id, &DebugResponse::Ack)
-                        }
-                        Ok(IncomingRequest::Diagnostics {
-                            id,
-                            request: _request,
-                        }) => {
-                            #[cfg(feature = "diagnostics")]
-                            let response = bridge(ControlBridgeRequest::Diagnostics(_request))
-                                .await
-                                .unwrap_or_else(|_| {
-                                    DebugResponse::Error(crate::control_protocol::DebugError {
-                                        code: "bridgeClosed".into(),
-                                        message: "the UI-thread diagnostics bridge closed".into(),
-                                    })
-                                });
-                            #[cfg(not(feature = "diagnostics"))]
-                            let response =
-                                DebugResponse::Error(crate::control_protocol::DebugError {
-                                    code: "diagnosticsUnavailable".into(),
-                                    message: "this build has no diagnostics feature; \
-                                      rebuild with tauri-runtime-blitz/diagnostics"
-                                        .into(),
-                                });
-                            encode_response(id, &response)
-                        }
-                        Ok(_) => encode_rpc_error(
-                            request_id,
-                            JsonRpcError::new(INVALID_REQUEST, "unsupported protocol request"),
-                        ),
-                        Err(error) => encode_rpc_error(
-                            request_id,
-                            JsonRpcError::new(INVALID_REQUEST, error.to_string()),
-                        ),
-                    }
-                }
-                Err(error) => {
-                    encode_rpc_error(None, JsonRpcError::new(INVALID_REQUEST, error.to_string()))
-                }
-            },
-            // A transport error is not a bad request: the framing is broken or
-            // the peer is gone, and the next read returns the same error
-            // immediately. Answering and continuing spun this task at a full
-            // core for the life of the process, one per client that ever
-            // disconnected, which is most of them. Measured on an idle app:
-            // 0.0% CPU without the control server, 55-76% with it after a few
-            // tools had connected and gone.
-            //
-            // So answer once, best effort, then stop reading this connection.
-            Err(error) => {
-                let farewell =
-                    encode_rpc_error(None, JsonRpcError::new(INVALID_REQUEST, error.to_string()));
-                if let Ok(farewell) = farewell {
-                    let _ = stream.send(farewell).await;
-                }
-                break;
-            }
-        };
-        let response = response.unwrap_or_else(|error| {
-            encode_rpc_error(
-                None,
-                JsonRpcError::new(
-                    INVALID_REQUEST,
-                    format!("could not encode response: {error}"),
-                ),
-            )
-            .expect("the fallback JSON-RPC error is serializable")
-        });
-        if stream.send(response).await.is_err() {
-            break;
-        }
-    }
-}
-
-fn instance_id() -> String {
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_nanos();
-    format!("{}-{nanos:x}", std::process::id())
-}
-
-/// Whether a pid still names a live process.
-///
-/// `kill(pid, 0)` without a libc dependency, and `/proc` does not exist on
-/// macOS. A `ps` that cannot be run at all reports "live", because deleting
-/// another instance's descriptor on a bad guess is far worse than keeping a
-/// stale file.
-fn pid_is_live(pid: u32) -> bool {
-    std::process::Command::new("ps")
-        .args(["-p", &pid.to_string()])
-        .output()
-        .map(|out| out.status.success())
-        .unwrap_or(true)
-}
-
-/// Delete descriptors whose process is gone.
-///
-/// The name carries a pid and a nanosecond stamp, so every launch leaves a new
-/// pair behind and nothing ever removed them: a developer machine accumulates
-/// them indefinitely, and one here had **99**. `Drop` cleans up an orderly
-/// exit, but a crash, a `kill -9`, or a rebuild that unlinks the socket under a
-/// running instance all skip it.
-///
-/// That is not merely untidy. A tool discovering the current descriptor has to
-/// distinguish them, and a directory full of dead entries
-/// is what makes "attached to a stale socket and reported numbers for a process
-/// nobody is looking at" a routine failure rather than a rare one.
-///
-/// Only entries whose pid is dead are removed, so concurrent instances are left
-/// strictly alone — and this one's own descriptor is skipped by path, since it
-/// has just been written and its pid is obviously live.
-fn reap_dead_descriptors(own: &Path) {
-    reap_dead_descriptors_with(own, pid_is_live);
-}
-
-fn reap_dead_descriptors_with(own: &Path, is_live: impl Fn(u32) -> bool) {
-    let Some(dir) = own.parent() else { return };
-    let Ok(entries) = std::fs::read_dir(dir) else {
-        return;
-    };
-    for entry in entries.flatten() {
-        let path = entry.path();
-        if path == own || path.extension().is_none_or(|ext| ext != "json") {
-            continue;
-        }
-        let Ok(text) = std::fs::read_to_string(&path) else {
-            continue;
-        };
-        let Ok(descriptor) = serde_json::from_str::<DebugDescriptor>(&text) else {
-            continue;
-        };
-        if is_live(descriptor.pid) {
-            continue;
-        }
-        let _ = remove_file(path.with_extension("sock"));
-        let _ = remove_file(&path);
-    }
-}
-
-fn descriptor_path(instance_id: &str) -> PathBuf {
-    std::env::temp_dir()
-        .join("tauri-blitz-agent")
-        .join(format!("{instance_id}.json"))
-}
-
-fn write_descriptor(path: &Path, descriptor: &DebugDescriptor) -> io::Result<()> {
-    if let Some(parent) = path.parent() {
-        std::fs::create_dir_all(parent)?;
-    }
-    let mut file = OpenOptions::new()
-        .create(true)
-        .truncate(true)
-        .write(true)
-        .mode(0o600)
-        .open(path)?;
-    serde_json::to_writer_pretty(&mut file, descriptor).map_err(io::Error::other)?;
-    file.write_all(b"\n")?;
-    file.sync_all()
-}
-
-#[cfg(test)]
-mod tests {
-    use endpoint_libs::libs::ws::mcp_wire::{JsonRpcId, JsonRpcMessage, JsonRpcRequest};
-
-    use super::*;
-    use crate::control_protocol::{
-        AgentAction, AgentControlRequest, DebugResponse, MCP_INITIALIZE, MCP_TOOLS_LIST,
-        decode_response, decode_rpc, encode_agent_request, encode_rpc,
-    };
-    #[cfg(feature = "diagnostics")]
-    use crate::control_protocol::{
-        DebugEvent, DebugSnapshot, DebugStream, DiagnosticsRequest, RendererMetrics, RevisionSet,
-        SnapshotRequest, decode_diagnostics_event, encode_diagnostics_request,
-    };
-
-    #[tokio::test(flavor = "current_thread")]
-    async fn local_server_is_mcp_compatible_and_needs_no_session_or_token() {
-        let _guard = CONTROL_TEST_LOCK.lock().await;
-        let bridge: ControlBridge = Arc::new(|request| {
-            let (sender, receiver) = oneshot::channel();
-            assert!(matches!(
-                request,
-                ControlBridgeRequest::Agent(AgentControlRequest::Act(AgentAction::Click {
-                    node_id: 42
-                }))
-            ));
-            sender.send(DebugResponse::Ack).unwrap();
-            receiver
-        });
-        let server = AgentControlServer::start(bridge).unwrap();
-        assert!(server.descriptor_path().is_file());
-        assert_eq!(
-            server
-                .descriptor_path()
-                .metadata()
-                .unwrap()
-                .permissions()
-                .mode()
-                & 0o777,
-            0o600
-        );
-
-        let stream = UnixStream::connect(server.socket_path()).await.unwrap();
-        let mut stream = TransportStream::new(framed_json(stream));
-        stream
-            .send(
-                encode_rpc(JsonRpcMessage::Request(JsonRpcRequest::call(
-                    JsonRpcId::Number(1),
-                    MCP_INITIALIZE,
-                    serde_json::json!({"protocolVersion": "2025-06-18"}),
-                )))
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert!(matches!(
-            decode_rpc(stream.recv().await.unwrap().unwrap()).unwrap(),
-            JsonRpcMessage::Response(_)
-        ));
-        stream
-            .send(
-                encode_rpc(JsonRpcMessage::Request(JsonRpcRequest::call(
-                    JsonRpcId::Number(2),
-                    MCP_TOOLS_LIST,
-                    serde_json::json!({}),
-                )))
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert!(matches!(
-            decode_rpc(stream.recv().await.unwrap().unwrap()).unwrap(),
-            JsonRpcMessage::Response(_)
-        ));
-        let id = JsonRpcId::Number(42);
-        stream
-            .send(
-                encode_agent_request(
-                    id.clone(),
-                    &AgentControlRequest::Act(AgentAction::Click { node_id: 42 }),
-                )
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        let response = stream.recv().await.unwrap().unwrap();
-        assert_eq!(decode_response(response).unwrap(), (id, DebugResponse::Ack));
-
-        let second = UnixStream::connect(server.socket_path()).await.unwrap();
-        let mut second = TransportStream::new(framed_json(second));
-        let id = JsonRpcId::String("second-observer".into());
-        second
-            .send(
-                encode_agent_request(
-                    id.clone(),
-                    &AgentControlRequest::Act(AgentAction::Click { node_id: 42 }),
-                )
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert_eq!(
-            decode_response(second.recv().await.unwrap().unwrap()).unwrap(),
-            (id, DebugResponse::Ack)
-        );
-
-        drop(server);
-    }
-
-    #[cfg(feature = "diagnostics")]
-    #[tokio::test(flavor = "current_thread")]
-    async fn diagnostics_metrics_reach_the_runtime_bridge_over_mcp() {
-        let _guard = CONTROL_TEST_LOCK.lock().await;
-        let bridge: ControlBridge = Arc::new(|request| {
-            let (sender, receiver) = oneshot::channel();
-            assert!(matches!(
-                request,
-                ControlBridgeRequest::Diagnostics(DiagnosticsRequest::Metrics)
-            ));
-            sender
-                .send(DebugResponse::Metrics(RendererMetrics {
-                    resident_bytes: Some(8192),
-                    ..Default::default()
-                }))
-                .unwrap();
-            receiver
-        });
-        let server = AgentControlServer::start(bridge).unwrap();
-        let stream = UnixStream::connect(server.socket_path()).await.unwrap();
-        let mut stream = TransportStream::new(framed_json(stream));
-        let id = JsonRpcId::Number(91);
-
-        stream
-            .send(encode_diagnostics_request(id.clone(), &DiagnosticsRequest::Metrics).unwrap())
-            .await
-            .unwrap();
-
-        assert_eq!(
-            decode_response(stream.recv().await.unwrap().unwrap()).unwrap(),
-            (
-                id,
-                DebugResponse::Metrics(RendererMetrics {
-                    resident_bytes: Some(8192),
-                    ..Default::default()
-                })
-            )
-        );
-    }
-
-    #[cfg(feature = "diagnostics")]
-    #[tokio::test(flavor = "current_thread")]
-    async fn observe_pushes_only_requested_latest_value_events() {
-        let _guard = CONTROL_TEST_LOCK.lock().await;
-        let bridge: ControlBridge = Arc::new(|_request| {
-            panic!("observe is connection-local and must not reach the UI bridge")
-        });
-        let (events, receiver) = watch::channel(None);
-        let server = AgentControlServer::start_with_events(bridge, receiver).unwrap();
-        let stream = UnixStream::connect(server.socket_path()).await.unwrap();
-        let mut stream = TransportStream::new(framed_json(stream));
-        let id = JsonRpcId::Number(92);
-
-        stream
-            .send(
-                encode_diagnostics_request(
-                    id.clone(),
-                    &DiagnosticsRequest::Observe {
-                        streams: vec![DebugStream::Paint],
-                    },
-                )
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert_eq!(
-            decode_response(stream.recv().await.unwrap().unwrap()).unwrap(),
-            (id, DebugResponse::Ack)
-        );
-
-        let event = DebugEvent::PaintCommitted { revision: 7 };
-        events.send_replace(Some(event.clone()));
-        assert_eq!(
-            decode_diagnostics_event(stream.recv().await.unwrap().unwrap()).unwrap(),
-            event
-        );
-    }
-
-    #[cfg(feature = "diagnostics")]
-    #[tokio::test(flavor = "current_thread")]
-    async fn large_snapshot_keeps_the_socket_open_for_follow_up_requests() {
-        let _guard = CONTROL_TEST_LOCK.lock().await;
-        const LARGE_DOM_BYTES: usize = 9 * 1024 * 1024;
-        let bridge: ControlBridge = Arc::new(|request| {
-            let (sender, receiver) = oneshot::channel();
-            let response = match request {
-                ControlBridgeRequest::Diagnostics(DiagnosticsRequest::Snapshot(_)) => {
-                    DebugResponse::Snapshot(DebugSnapshot {
-                        revisions: RevisionSet::default(),
-                        active_window: Some("main".into()),
-                        active_element: None,
-                        dom: Some(serde_json::Value::String("x".repeat(LARGE_DOM_BYTES))),
-                        layout: None,
-                        computed_style: None,
-                        metrics: RendererMetrics::default(),
-                    })
-                }
-                ControlBridgeRequest::Diagnostics(DiagnosticsRequest::Metrics) => {
-                    DebugResponse::Metrics(RendererMetrics {
-                        resident_bytes: Some(4096),
-                        ..Default::default()
-                    })
-                }
-                _ => panic!("unexpected request"),
-            };
-            sender.send(response).unwrap();
-            receiver
-        });
-        let server = AgentControlServer::start(bridge).unwrap();
-        let stream = UnixStream::connect(server.socket_path()).await.unwrap();
-        let mut stream = TransportStream::new(framed_json(stream));
-
-        let snapshot_id = JsonRpcId::Number(92);
-        stream
-            .send(
-                encode_diagnostics_request(
-                    snapshot_id.clone(),
-                    &DiagnosticsRequest::Snapshot(SnapshotRequest {
-                        include_dom: true,
-                        include_layout: false,
-                        include_computed_style: false,
-                        node_ids: Vec::new(),
-                    }),
-                )
-                .unwrap(),
-            )
-            .await
-            .unwrap();
-        let (response_id, response) =
-            decode_response(stream.recv().await.unwrap().unwrap()).unwrap();
-        assert_eq!(response_id, snapshot_id);
-        let DebugResponse::Snapshot(snapshot) = response else {
-            panic!("expected a diagnostic snapshot")
-        };
-        assert_eq!(
-            snapshot.dom.unwrap().as_str().unwrap().len(),
-            LARGE_DOM_BYTES
-        );
-
-        let metrics_id = JsonRpcId::Number(93);
-        stream
-            .send(
-                encode_diagnostics_request(metrics_id.clone(), &DiagnosticsRequest::Metrics)
-                    .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert_eq!(
-            decode_response(stream.recv().await.unwrap().unwrap()).unwrap(),
-            (
-                metrics_id,
-                DebugResponse::Metrics(RendererMetrics {
-                    resident_bytes: Some(4096),
-                    ..Default::default()
-                })
-            )
-        );
-    }
-
-    #[test]
-    fn initialize_payload_uses_json_rpc() {
-        let message = encode_initialize_response(JsonRpcId::Number(1), "0.1.0").unwrap();
-        let WireMessage::Text(payload) = message else {
-            panic!("initialize response must be text")
-        };
-        let decoded: JsonRpcMessage = serde_json::from_str(&payload).unwrap();
-        assert!(matches!(decoded, JsonRpcMessage::Response(_)));
-    }
-
-    /**
-     * A dead instance's descriptor goes; a live one's stays.
-     *
-     * The filename carries a pid and a nanosecond stamp, so every launch leaves
-     * a new pair behind and nothing removed them — one machine had 99. `Drop`
-     * handles an orderly exit, but a crash, a `kill -9`, or a rebuild that
-     * unlinks the socket under a running instance all skip it. A tool then has
-     * to guess which is current, which is how attaching to a stale socket
-     * became routine.
-     *
-     * The asymmetry is the whole point: reaping too eagerly would delete a
-     * concurrent instance's descriptor, which is worse than leaving litter.
-     */
-    #[test]
-    fn reaping_removes_dead_descriptors_and_spares_live_ones() {
-        let dir = std::env::temp_dir().join(format!(
-            "blitz-reap-{}-{:x}",
-            std::process::id(),
-            SystemTime::now()
-                .duration_since(UNIX_EPOCH)
-                .unwrap_or_default()
-                .as_nanos()
-        ));
-        std::fs::create_dir_all(&dir).expect("scratch directory is created");
-
-        let write = |name: &str, pid: u32| {
-            let path = dir.join(format!("{name}.json"));
-            write_descriptor(
-                &path,
-                &DebugDescriptor {
-                    protocol_version: crate::control_protocol::DEBUG_PROTOCOL_VERSION,
-                    pid,
-                    instance_id: name.into(),
-                    address: format!("unix://{}", dir.join(format!("{name}.sock")).display()),
-                    renderer: "blitz".into(),
-                    renderer_revision: "0.0.0".into(),
-                },
-            )
-            .expect("descriptor is written");
-            std::fs::write(dir.join(format!("{name}.sock")), b"").expect("socket stub is written");
-            path
-        };
-
-        // Liveness is injected here because process inspection may be denied by
-        // the test sandbox. This test owns descriptor cleanup, not `ps` itself.
-        let own = write("own", std::process::id());
-        let live = write("live", 1);
-        let dead = write("dead", 2);
-
-        reap_dead_descriptors_with(&own, |pid| pid == std::process::id() || pid == 1);
-
-        assert!(own.exists(), "the caller's own descriptor is never reaped");
-        assert!(live.exists(), "a live instance must keep its descriptor");
-        assert!(!dead.exists(), "a dead instance's descriptor is removed");
-        assert!(
-            !dir.join("dead.sock").exists(),
-            "the orphaned socket goes with it"
-        );
-
-        let _ = std::fs::remove_dir_all(&dir);
-    }
-}
diff --git a/crates/tauri-runtime-blitz/src/lib.rs b/crates/tauri-runtime-blitz/src/lib.rs
index 7b803d7..b440ee9 100644
--- a/crates/tauri-runtime-blitz/src/lib.rs
+++ b/crates/tauri-runtime-blitz/src/lib.rs
@@ -2,6 +2,26 @@
 //!
 //! The first implementation target is Tauri 2.11.x. Its runtime traits are not semver-stable,
 //! so versions stay exact and upgrades are deliberate.
+//!
+//! # What is not here
+//!
+//! The Blitz control surface. The vocabulary, the core that reads and drives a
+//! document, the socket transport and the in-process transport are all
+//! `blitz-control-protocol`, and this crate re-exports none of them.
+//!
+//! Nothing about inspecting a document needs a window, and while it lived here
+//! depending on it meant compiling Tauri: on Linux that reaches GTK, so a
+//! headless host pulled in system libraries to build a binary that opens
+//! nothing. A runtime bridges Tauri to Blitz and owns a native window. It does
+//! not proxy an inspection service, because a runtime that forwards one has not
+//! removed the dependency edge, only renamed it.
+//!
+//! An embedder that names a control type depends on `blitz-control-protocol`
+//! directly, and registers what `Relaunch` means for its process with
+//! `blitz_control_protocol::lifecycle`. What this crate keeps is
+//! `set_agent_control_enabled` and `apply_runtime_debug_options`, which are
+//! about *this runtime's* listener rather than about the protocol, and which
+//! name no protocol type. Nothing public here does.
 
 #[cfg(feature = "runtime")]
 use tauri_runtime::Icon;
@@ -20,35 +40,6 @@ use tauri_utils::{Theme, TitleBarStyle};
 mod ipc;
 #[cfg(feature = "runtime")]
 pub use ipc::attach_ipc_handler;
-#[cfg(all(feature = "agent-control", unix))]
-mod agent_control_server;
-/// Answer an `Inspect` request against a document, from the same code the
-/// runtime uses. A headless host needs this to serve the socket it now can
-/// host; reimplementing it is how a harness ends up disagreeing with the
-/// inspector about what a node is called.
-#[cfg(all(feature = "agent-control", unix))]
-pub use agent::{
-    click_agent_node, focus_agent_node, hover_agent_node, inspect_document, press_agent_key,
-};
-/// Serving inspection from a host that is not this runtime.
-///
-/// The server binds a socket and forwards framed requests to a closure; it has
-/// no window, no event loop and no Tauri in it, and the module's own tests
-/// start one from a bare closure. Exported so a headless host holding a
-/// document can be inspected the same way the application is.
-///
-/// While this was private, inspecting a Blitz document from outside required
-/// opening a window. A QA harness that must not take over the desktop was
-/// pushed into screenshots and tree-file dumps instead, and neither can answer
-/// a question that involves clicking something.
-#[cfg(all(feature = "agent-control", unix))]
-pub use agent_control_server::{AgentControlServer, ControlBridge, ControlBridgeRequest};
-/// The wire protocol, which lives in its own crate so clients can speak it
-/// without building a renderer. Re-exported under the name this crate has
-/// always used it by, so `control_protocol::` paths keep resolving.
-#[cfg(feature = "agent-control")]
-pub use blitz_control_protocol as control_protocol;
-mod agent;
 #[cfg(feature = "runtime")]
 mod script_queue;
 #[cfg(feature = "runtime")]
@@ -57,13 +48,14 @@ pub use script_queue::ScriptQueue;
 mod runtime;
 #[cfg(all(target_os = "macos", feature = "runtime"))]
 mod window_effects;
-#[cfg(all(feature = "diagnostics", unix))]
-pub use agent::{DocumentCapture, capture_document, snapshot_document};
+/// The two capability switches an owner sets, as one decision.
+///
+/// `blitz-traits` owns the type because the collectors it governs are spread
+/// across the shell and script crates. It is the argument of this crate's own
+/// [`apply_runtime_debug_options`], so it is named here rather than leaving an
+/// embedder to depend on `blitz-traits` for one struct.
 #[cfg(feature = "agent-control")]
 pub use blitz_traits::profiling::DebugOptions as RuntimeDebugOptions;
-#[cfg(all(feature = "diagnostics", unix))]
-#[cfg(feature = "runtime")]
-pub use runtime::set_diagnostics_handler;
 #[cfg(feature = "runtime")]
 pub use runtime::{
     BlitzEventLoopProxy, BlitzRuntime, BlitzRuntimeHandle, builder, set_document_factory,
@@ -71,10 +63,7 @@ pub use runtime::{
 };
 #[cfg(all(feature = "agent-control", unix))]
 #[cfg(feature = "runtime")]
-pub use runtime::{
-    agent_control_enabled, apply_runtime_debug_options, set_agent_control_enabled,
-    set_agent_control_handler,
-};
+pub use runtime::{agent_control_enabled, apply_runtime_debug_options, set_agent_control_enabled};
 #[cfg(feature = "agent-control")]
 #[cfg(feature = "runtime")]
 pub use runtime::{
diff --git a/crates/tauri-runtime-blitz/src/runtime.rs b/crates/tauri-runtime-blitz/src/runtime.rs
index 67c92bc..16d0e88 100644
--- a/crates/tauri-runtime-blitz/src/runtime.rs
+++ b/crates/tauri-runtime-blitz/src/runtime.rs
@@ -2,11 +2,13 @@ use std::cell::RefCell;
 use std::collections::HashMap;
 use std::fmt;
 use std::marker::PhantomData;
+#[cfg(all(feature = "agent-control", unix))]
+use std::sync::Weak;
 #[cfg(target_os = "macos")]
 use std::sync::atomic::AtomicBool;
 use std::sync::atomic::{AtomicU32, Ordering};
 use std::sync::mpsc::{Receiver, Sender, channel};
-use std::sync::{Arc, Mutex, OnceLock, RwLock, Weak};
+use std::sync::{Arc, Mutex, OnceLock, RwLock};
 use std::thread::{ThreadId, current};
 
 #[cfg(not(feature = "hybrid-renderer"))]
@@ -39,61 +41,55 @@ use winit::window::{WindowAttributes, WindowButtons, WindowLevel};
 use winit::platform::macos::{ApplicationHandlerExtMacOS, WindowAttributesMacOS};
 
 #[cfg(all(feature = "diagnostics", unix))]
-use crate::agent::{CaptureSurface, capture_document_with_surface, snapshot_document};
-#[cfg(all(feature = "agent-control", unix))]
-/*
- * Gated to match the items themselves. The capture path is `diagnostics`, the
- * activation path is `agent-control`, and importing both under one attribute
- * made a build with only the latter fail on three names it never uses.
- */
-#[cfg(all(feature = "agent-control", unix))]
-use crate::agent::{
-    activate_agent_node, control_error, debug_error, focus_agent_node, inspect_document, key_event,
-    keyboard_modifiers, pointer_coords, pointer_event, resolve_agent_node,
-};
-#[cfg(all(feature = "agent-control", unix, test))]
-use crate::agent_control_server::CONTROL_TEST_LOCK;
+use blitz_control_protocol::document::snapshot_document;
 #[cfg(all(feature = "diagnostics", unix))]
-use crate::control_protocol::{
+use blitz_control_protocol::{
     DebugSnapshot, DiagnosticsRequest, SnapshotRequest, WindowComposition,
 };
+/*
+ * The control surface is `blitz-control-protocol`, not this crate.
+ *
+ * The vocabulary, the core that reads and drives a document, the socket and
+ * the in-process transport over it all live there. What is left here is a
+ * window runtime that happens to own a document, wiring its own document into
+ * that surface: `DocumentControl` performs the actions, this decides which
+ * window's document to perform them on and what to do about `Relaunch` and
+ * `Quit`, which are about the process rather than the document.
+ *
+ * Nothing is re-exported. A consumer that names a control type depends on the
+ * crate that defines it, because a runtime that forwards one has not removed
+ * the edge, only renamed it.
+ */
 use crate::window_dispatch::{BlitzWindowDispatcher, NativeWindowState};
 use crate::{
     BlitzWebviewDispatcher, BlitzWindowBuilder, PreparedBlitzWebview, prepare_pending_webview,
 };
 #[cfg(all(feature = "agent-control", unix))]
-use crate::{
-    agent_control_server::{AgentControlServer, ControlBridge, ControlBridgeRequest},
-    control_protocol::{
-        AgentAction, AgentControlRequest, DebugError, DebugEvent, DebugResponse, InputCommand,
-        KeyPhase, PointerPhase,
-    },
-};
-use blitz_dom::Document;
+use blitz_control_protocol::in_process::DocumentControl;
 #[cfg(all(feature = "agent-control", unix))]
-use blitz_traits::events::{
-    BlitzImeEvent, BlitzWheelDelta, BlitzWheelEvent, MouseEventButton, MouseEventButtons, Point,
-    UiEvent,
+use blitz_control_protocol::server::{
+    AgentControlServer, ControlBridge, ControlBridgeRequest, Host,
 };
 #[cfg(all(feature = "agent-control", unix))]
-use keyboard_types::{Code, Key, Modifiers as KeyboardModifiers};
+use blitz_control_protocol::{AgentControlRequest, DebugError, DebugEvent, DebugResponse};
 
 type DocumentFactory = dyn Fn(&str) -> Result<ScriptDocument, String> + Send + Sync + 'static;
 type RuntimeTrace = dyn Fn(&str) + Send + Sync + 'static;
-#[cfg(all(feature = "agent-control", unix))]
-type AgentControlHandler = dyn Fn(AgentControlRequest) -> DebugResponse + Send + Sync + 'static;
-#[cfg(all(feature = "diagnostics", unix))]
-type DiagnosticsHandler = dyn Fn(DiagnosticsRequest) -> DebugResponse + Send + Sync + 'static;
 
 static DOCUMENT_FACTORY: OnceLock<RwLock<Option<Arc<DocumentFactory>>>> = OnceLock::new();
 static RUNTIME_TRACE: OnceLock<RwLock<Option<Arc<RuntimeTrace>>>> = OnceLock::new();
 #[cfg(all(feature = "agent-control", unix))]
-static AGENT_CONTROL_HANDLER: OnceLock<RwLock<Option<Arc<AgentControlHandler>>>> = OnceLock::new();
-#[cfg(all(feature = "agent-control", unix))]
 static AGENT_CONTROL_RUNTIME: OnceLock<Mutex<Option<Weak<Mutex<AgentControlRuntime>>>>> =
     OnceLock::new();
-#[cfg(all(feature = "diagnostics", unix))]
-static DIAGNOSTICS_HANDLER: OnceLock<RwLock<Option<Arc<DiagnosticsHandler>>>> = OnceLock::new();
+
+/// One lock for every test that starts or stops the control server.
+///
+/// `AGENT_CONTROL_RUNTIME` is process-wide, so two tests that enable
+/// inspection at the same time fight over one listener. This crate keeps its
+/// own lock rather than sharing the transport's: the state being serialised is
+/// this runtime's, and the transport has no idea a second one exists.
+#[cfg(all(feature = "agent-control", unix, test))]
+static CONTROL_TEST_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
 
 thread_local! {
     static CURRENT_BLITZ_APPLICATION: std::cell::Cell<*const ()> = const {
@@ -130,17 +126,6 @@ pub fn set_runtime_trace(trace: impl Fn(&str) + Send + Sync + 'static) {
         .unwrap() = Some(Arc::new(trace));
 }
 
-/// Install the UI-thread handler used by the local agent-control socket.
-#[cfg(all(feature = "agent-control", unix))]
-pub fn set_agent_control_handler(
-    handler: impl Fn(AgentControlRequest) -> DebugResponse + Send + Sync + 'static,
-) {
-    *AGENT_CONTROL_HANDLER
-        .get_or_init(|| RwLock::new(None))
-        .write()
-        .unwrap() = Some(Arc::new(handler));
-}
-
 #[cfg(all(feature = "agent-control", unix))]
 struct AgentControlRuntime {
     bridge: ControlBridge,
@@ -166,6 +151,11 @@ pub fn set_agent_control_enabled(enabled: bool) -> std::io::Result<()> {
         (true, false) => {
             runtime.server = Some(AgentControlServer::start_with_events(
                 runtime.bridge.clone(),
+                Host {
+                    name: env!("CARGO_PKG_NAME").into(),
+                    version: env!("CARGO_PKG_VERSION").into(),
+                    diagnostics: cfg!(feature = "diagnostics"),
+                },
                 runtime.events.subscribe(),
             )?)
         }
@@ -206,6 +196,9 @@ pub fn apply_runtime_debug_options(
     // place; otherwise a server created while profiling was off holds `None`
     // forever and diagnostics silently return `script: null` after the owner
     // turns profiling on.
+    // Only a build that can collect diagnostics holds a sampling session, so
+    // only that build has one to refresh.
+    #[cfg(feature = "diagnostics")]
     if options.inspection_and_agent_control {
         let runtime = AGENT_CONTROL_RUNTIME
             .get_or_init(|| Mutex::new(None))
@@ -260,17 +253,6 @@ pub fn deep_profiling_enabled() -> bool {
     blitz_traits::profiling::deep_profiling_enabled()
 }
 
-/// Install the UI-thread handler used by the feature-gated diagnostics tool.
-#[cfg(all(feature = "diagnostics", unix))]
-pub fn set_diagnostics_handler(
-    handler: impl Fn(DiagnosticsRequest) -> DebugResponse + Send + Sync + 'static,
-) {
-    *DIAGNOSTICS_HANDLER
-        .get_or_init(|| RwLock::new(None))
-        .write()
-        .unwrap() = Some(Arc::new(handler));
-}
-
 fn runtime_trace(message: &str) {
     let callback = RUNTIME_TRACE
         .get_or_init(|| RwLock::new(None))
@@ -560,18 +542,18 @@ struct RuntimeApplication<T: UserEvent> {
     ready: bool,
     #[cfg(all(feature = "agent-control", unix))]
     _agent_control: Arc<Mutex<AgentControlRuntime>>,
+    /// The in-process transport over this window's document.
+    ///
+    /// It performs the actions and holds what one request leaves for the next:
+    /// the revision, the injected pointer, which buttons it holds, and the
+    /// capture surface. All of that was here, in fields beside a second copy of
+    /// the action dispatch that had already drifted from the browser's.
     #[cfg(all(feature = "agent-control", unix))]
-    agent_revision: u64,
+    control: DocumentControl,
     #[cfg(all(feature = "agent-control", unix))]
     paint_revision: u64,
     #[cfg(all(feature = "agent-control", unix))]
     control_events: tokio::sync::watch::Sender<Option<DebugEvent>>,
-    #[cfg(all(feature = "agent-control", unix))]
-    agent_pointer: (f32, f32),
-    #[cfg(all(feature = "agent-control", unix))]
-    agent_buttons: MouseEventButtons,
-    #[cfg(all(feature = "diagnostics", unix))]
-    capture_surface: Option<CaptureSurface>,
 }
 
 impl<T: UserEvent> RuntimeApplication<T> {
@@ -581,7 +563,7 @@ impl<T: UserEvent> RuntimeApplication<T> {
         }
     }
 
-    #[cfg(all(feature = "agent-control", unix))]
+    #[cfg(all(feature = "diagnostics", unix))]
     fn agent_document(&mut self) -> Option<&mut ScriptDocument> {
         self.blitz
             .get_mut()
@@ -590,29 +572,36 @@ impl<T: UserEvent> RuntimeApplication<T> {
             .find_map(|view| view.try_downcast_doc_mut::<ScriptDocument>())
     }
 
+    /// Answer one agent-control request against this window's document.
+    ///
+    /// Reading the tree and performing an action are the in-process transport's
+    /// job, and it does them the same way for every host. What is left here is
+    /// what only a runtime can answer: which window's document is the active
+    /// one, and what `Relaunch` and `Quit` mean for a process it started.
     #[cfg(all(feature = "agent-control", unix))]
     fn handle_builtin_agent(&mut self, request: AgentControlRequest) -> DebugResponse {
         match request {
-            AgentControlRequest::Inspect { root, max_depth } => {
-                self.agent_revision += 1;
-                let revision = self.agent_revision;
-                let Some(document) = self.agent_document() else {
-                    return control_error("documentUnavailable", "no active script document");
+            AgentControlRequest::Inspect { .. } | AgentControlRequest::Act(_) => {
+                let Self { blitz, control, .. } = self;
+                let Some(document) = blitz
+                    .get_mut()
+                    .windows
+                    .values_mut()
+                    .find_map(|view| view.try_downcast_doc_mut::<ScriptDocument>())
+                else {
+                    return DebugResponse::Error(DebugError {
+                        code: "documentUnavailable".into(),
+                        message: "no active script document".into(),
+                    });
                 };
-                inspect_document(document, root, max_depth, revision)
+                control.agent(document, request)
             }
-            AgentControlRequest::Act(action) => match self.perform_agent_action(action) {
-                Ok(()) => {
-                    self.agent_revision += 1;
-                    DebugResponse::Ack
-                }
-                Err(error) => DebugResponse::Error(error),
-            },
-            AgentControlRequest::Relaunch => AGENT_CONTROL_HANDLER
-                .get_or_init(|| RwLock::new(None))
-                .read()
-                .unwrap()
-                .clone()
+            // The embedder's answer if it registered one, and this runtime's
+            // own if it did not. Whose answer it is is not this crate's to
+            // decide: an application that must drain a database before it
+            // restarts registers with `blitz_control_protocol::lifecycle`, and
+            // does not reach a window runtime to do it.
+            AgentControlRequest::Relaunch => blitz_control_protocol::lifecycle::lifecycle_handler()
                 .map(|handler| handler(AgentControlRequest::Relaunch))
                 .unwrap_or_else(|| match relaunch_current_process() {
                     Ok(()) => DebugResponse::Ack,
@@ -622,10 +611,10 @@ impl<T: UserEvent> RuntimeApplication<T> {
                     }),
                 }),
             AgentControlRequest::Quit => DebugResponse::Ack,
-            _ => control_error(
-                "unsupportedRequest",
-                "this runtime does not implement that agent-control request",
-            ),
+            _ => DebugResponse::Error(DebugError {
+                code: "unsupportedRequest".into(),
+                message: "this runtime does not implement that agent-control request".into(),
+            }),
         }
     }
 
@@ -654,6 +643,10 @@ impl<T: UserEvent> RuntimeApplication<T> {
                 })
                 .map(|snapshot| DebugResponse::Idle(snapshot.revisions))
                 .unwrap_or_else(DebugResponse::Error),
+            // The one diagnostic only a runtime can answer. A renderer capture
+            // cannot see whether an opaque platform window or a tinted native
+            // glass view was placed behind its transparent root, and this crate
+            // is what put it there.
             DiagnosticsRequest::WindowComposition => {
                 DebugResponse::WindowComposition(native_window_composition())
             }
@@ -661,14 +654,16 @@ impl<T: UserEvent> RuntimeApplication<T> {
                 .capture_image(request)
                 .map(DebugResponse::Captured)
                 .unwrap_or_else(DebugResponse::Error),
-            DiagnosticsRequest::Observe { .. } => control_error(
-                "streamingUnavailable",
-                "diagnostic subscriptions are not implemented; request snapshots or metrics",
-            ),
-            _ => control_error(
-                "unsupportedRequest",
-                "this runtime does not implement that diagnostics request",
-            ),
+            DiagnosticsRequest::Observe { .. } => DebugResponse::Error(DebugError {
+                code: "streamingUnavailable".into(),
+                message: "diagnostic subscriptions are not implemented; request snapshots or \
+                          metrics"
+                    .into(),
+            }),
+            _ => DebugResponse::Error(DebugError {
+                code: "unsupportedRequest".into(),
+                message: "this runtime does not implement that diagnostics request".into(),
+            }),
         }
     }
 
@@ -677,31 +672,23 @@ impl<T: UserEvent> RuntimeApplication<T> {
     /// The point of this is that it is the *same* paint. `blitz_paint::paint_scene`
     /// is the entry point the window renderer uses, so a capture cannot agree
     /// with a broken frame or disagree with a good one: whatever the window
-    /// would show is what lands in this buffer. Anything less than that is a
-    /// second implementation of the renderer, and a test against a second
-    /// implementation only proves the two implementations match.
-    ///
-    /// A node capture crops rather than re-laying-out. Laying the subtree out in
-    /// isolation would answer a different question - "can this element draw on
-    /// its own" - when the one worth asking is whether it drew *here*, inside
-    /// the page that actually exists, with the styles it actually inherited.
+    /// would show is what lands in this buffer.
     #[cfg(all(feature = "diagnostics", unix))]
     fn capture_image(
         &mut self,
         request: blitz_control_protocol::CaptureRequest,
     ) -> Result<blitz_control_protocol::CapturedImage, DebugError> {
-        let Self {
-            blitz,
-            capture_surface,
-            ..
-        } = self;
+        let Self { blitz, control, .. } = self;
         let document = blitz
             .get_mut()
             .windows
             .values_mut()
             .find_map(|view| view.try_downcast_doc_mut::<ScriptDocument>())
-            .ok_or_else(|| debug_error("documentUnavailable", "no active script document"))?;
-        capture_document_with_surface(document, request, capture_surface)
+            .ok_or_else(|| DebugError {
+                code: "documentUnavailable".into(),
+                message: "no active script document".into(),
+            })?;
+        control.capture(document, request)
     }
 }
 
@@ -711,220 +698,16 @@ impl<T: UserEvent> RuntimeApplication<T> {
         &mut self,
         request: SnapshotRequest,
     ) -> Result<DebugSnapshot, DebugError> {
-        self.agent_revision += 1;
-        let revision = self.agent_revision;
-        let document = self
-            .agent_document()
-            .ok_or_else(|| debug_error("documentUnavailable", "no active script document"))?;
+        let revision = self.control.next_revision();
+        let document = self.agent_document().ok_or_else(|| DebugError {
+            code: "documentUnavailable".into(),
+            message: "no active script document".into(),
+        })?;
         snapshot_document(document, request, revision)
     }
 }
 
 impl<T: UserEvent> RuntimeApplication<T> {
-    #[cfg(all(feature = "agent-control", unix))]
-    fn perform_agent_action(&mut self, action: AgentAction) -> Result<(), DebugError> {
-        match action {
-            AgentAction::Focus { node_id } => {
-                let node_id = blitz_dom::NodeId::from_u64(node_id);
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                focus_agent_node(document, node_id)?;
-            }
-            AgentAction::Click { node_id } => {
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                self.agent_pointer = activate_agent_node(document, node_id, 1)?;
-            }
-            AgentAction::DoubleClick { node_id } => {
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                self.agent_pointer = activate_agent_node(document, node_id, 2)?;
-            }
-            AgentAction::Hover { node_id } => {
-                let (node_id, position) = {
-                    let document = self
-                        .agent_document()
-                        .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                    resolve_agent_node(document, node_id)?
-                };
-                self.agent_pointer = position;
-                let document = self.agent_document().unwrap();
-                document.handle_pointer_move_to_node(
-                    pointer_event(
-                        position,
-                        MouseEventButton::Main,
-                        MouseEventButtons::default(),
-                        KeyboardModifiers::empty(),
-                    ),
-                    node_id,
-                );
-            }
-            AgentAction::SetValue { node_id, value } => {
-                let node_id = blitz_dom::NodeId::from_u64(node_id);
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                set_agent_node_value(document, node_id, value)?;
-            }
-            AgentAction::ScrollIntoView { node_id } => {
-                let node_id = blitz_dom::NodeId::from_u64(node_id);
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                if document.inner().get_node(node_id).is_none() {
-                    return Err(debug_error("unknownNode", "node does not exist"));
-                }
-                let mut events = Vec::new();
-                document
-                    .inner_mut()
-                    .scroll_to_node_with_events(node_id, |event| events.push(event));
-                for event in events {
-                    document.dispatch_dom_event(event);
-                }
-            }
-            AgentAction::ScrollBy {
-                node_id,
-                delta_x,
-                delta_y,
-            } => {
-                let node_id = blitz_dom::NodeId::from_u64(node_id);
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                if document.inner().get_node(node_id).is_none() {
-                    return Err(debug_error("unknownNode", "node does not exist"));
-                }
-                let mut events = Vec::new();
-                document
-                    .inner_mut()
-                    .scroll_nearest_container_by_with_events(node_id, delta_x, delta_y, |event| {
-                        events.push(event)
-                    });
-                for event in events {
-                    document.dispatch_dom_event(event);
-                }
-            }
-            AgentAction::Input(input) => self.perform_agent_input(input)?,
-            _ => {
-                return Err(debug_error(
-                    "unsupportedAction",
-                    "this runtime does not implement that agent action",
-                ));
-            }
-        }
-
-        /*
-         * An acknowledged action includes its synchronous application result.
-         *
-         * DOM event handlers enqueue Solid's reactive work on the document
-         * poll hook. Returning before that hook runs makes the next Inspect
-         * observe the tree from before the click or input, and tight QA loops
-         * can keep reading that stale tree until the client disconnects. Drain
-         * every immediately runnable consequence here; timers and authored
-         * animation frames remain asynchronous and are observed normally.
-         */
-        let document = self
-            .agent_document()
-            .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-        settle_agent_action(document)
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    fn perform_agent_input(&mut self, input: InputCommand) -> Result<(), DebugError> {
-        match input {
-            InputCommand::Key {
-                phase,
-                key,
-                code,
-                modifiers,
-            } => {
-                let parsed_key = key.parse::<Key>().unwrap_or(Key::Character(key));
-                let parsed_code = code.parse::<Code>().unwrap_or(Code::Unidentified);
-                let event = key_event(
-                    phase,
-                    parsed_key,
-                    parsed_code,
-                    keyboard_modifiers(modifiers),
-                );
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                document.handle_ui_event(match phase {
-                    KeyPhase::Down => UiEvent::KeyDown(event),
-                    KeyPhase::Up => UiEvent::KeyUp(event),
-                });
-            }
-            InputCommand::Pointer {
-                phase,
-                x,
-                y,
-                button,
-                modifiers,
-            } => {
-                let button = mouse_button(button)?;
-                self.agent_pointer = (x as f32, y as f32);
-                match phase {
-                    PointerPhase::Down => self.agent_buttons.insert(button.into()),
-                    PointerPhase::Up | PointerPhase::Cancel => {
-                        self.agent_buttons.remove(button.into())
-                    }
-                    PointerPhase::Move => {}
-                }
-                let event = pointer_event(
-                    self.agent_pointer,
-                    button,
-                    self.agent_buttons,
-                    keyboard_modifiers(modifiers),
-                );
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                document.handle_ui_event(match phase {
-                    PointerPhase::Move => UiEvent::PointerMove(event),
-                    PointerPhase::Down => UiEvent::PointerDown(event),
-                    PointerPhase::Up => UiEvent::PointerUp(event),
-                    PointerPhase::Cancel => UiEvent::PointerCancel(event),
-                });
-            }
-            InputCommand::Wheel {
-                delta_x,
-                delta_y,
-                modifiers,
-                ..
-            } => {
-                let coords = pointer_coords(self.agent_pointer);
-                let hover_at = self.agent_pointer;
-                let event = BlitzWheelEvent {
-                    delta: BlitzWheelDelta::Pixels(delta_x, delta_y),
-                    coords,
-                    buttons: self.agent_buttons,
-                    mods: keyboard_modifiers(modifiers),
-                    element: Point::default(),
-                };
-                let document = self
-                    .agent_document()
-                    .ok_or_else(|| debug_error("documentUnavailable", "no active document"))?;
-                // A wheel event targets the hovered node, and hover is resolved
-                // by the shell from real cursor movement. An injected pointer
-                // move never touches it, so an injected wheel had no target and
-                // scrolled nothing, making remote wheel input look accepted
-                // while the document remained unchanged.
-                document.inner_mut().set_hover_to(hover_at.0, hover_at.1);
-                document.handle_ui_event(UiEvent::Wheel(event));
-            }
-            _ => {
-                return Err(debug_error(
-                    "unsupportedInput",
-                    "this runtime does not implement that input command",
-                ));
-            }
-        }
-        Ok(())
-    }
-
     fn drain_runtime_messages(&mut self, event_loop: &dyn ActiveEventLoop) {
         while let Ok(message) = self.receiver.try_recv() {
             match message {
@@ -953,11 +736,8 @@ impl<T: UserEvent> RuntimeApplication<T> {
                             DebugResponse::Ack
                         }
                         ControlBridgeRequest::Agent(AgentControlRequest::Relaunch) => {
-                            let delegated = AGENT_CONTROL_HANDLER
-                                .get_or_init(|| RwLock::new(None))
-                                .read()
-                                .unwrap()
-                                .is_some();
+                            let delegated =
+                                blitz_control_protocol::lifecycle::lifecycle_handler().is_some();
                             let result = self.handle_builtin_agent(AgentControlRequest::Relaunch);
                             if !delegated && matches!(result, DebugResponse::Ack) {
                                 self.emit(RunEvent::ExitRequested {
@@ -970,14 +750,33 @@ impl<T: UserEvent> RuntimeApplication<T> {
                             result
                         }
                         ControlBridgeRequest::Agent(request) => self.handle_builtin_agent(request),
+                        // A build without `diagnostics` answers rather than
+                        // failing to compile the arm. The transport forwards
+                        // every request now, because whether a host can collect
+                        // a snapshot is the host's answer and not something a
+                        // socket can infer; `Host::diagnostics` is what keeps
+                        // the tool out of `tools/list` so a client is not
+                        // invited to ask in the first place.
+                        #[cfg(not(feature = "diagnostics"))]
+                        ControlBridgeRequest::Diagnostics(_) => DebugResponse::Error(DebugError {
+                            code: "diagnosticsUnavailable".into(),
+                            message: "this build has no diagnostics feature; rebuild with \
+                                      tauri-runtime-blitz/diagnostics"
+                                .into(),
+                        }),
+                        // Answered here, and only here. There used to be a
+                        // `set_diagnostics_handler` an embedder could install
+                        // to answer instead, which is a runtime proxying an
+                        // inspection service: the collectors, the offscreen
+                        // paint and the snapshot readers are all
+                        // `blitz-control-protocol`, and an embedder that wants
+                        // to serve them serves them itself rather than through
+                        // the crate that owns the window. Nothing installed
+                        // one.
                         #[cfg(feature = "diagnostics")]
-                        ControlBridgeRequest::Diagnostics(request) => DIAGNOSTICS_HANDLER
-                            .get_or_init(|| RwLock::new(None))
-                            .read()
-                            .unwrap()
-                            .clone()
-                            .map(|handler| handler(request.clone()))
-                            .unwrap_or_else(|| self.handle_builtin_diagnostics(request)),
+                        ControlBridgeRequest::Diagnostics(request) => {
+                            self.handle_builtin_diagnostics(request)
+                        }
                     };
                     let _ = response.send(result);
                 }
@@ -1140,8 +939,16 @@ impl<T: UserEvent> Runtime<T> for BlitzRuntime<T> {
             // application is still booting.
             let server = if std::env::args().any(|arg| arg == "--blitz-control") {
                 Some(
-                    AgentControlServer::start_with_events(bridge.clone(), event_receiver)
-                        .map_err(|error| Error::CreateWebview(Box::new(error)))?,
+                    AgentControlServer::start_with_events(
+                        bridge.clone(),
+                        Host {
+                            name: env!("CARGO_PKG_NAME").into(),
+                            version: env!("CARGO_PKG_VERSION").into(),
+                            diagnostics: cfg!(feature = "diagnostics"),
+                        },
+                        event_receiver,
+                    )
+                    .map_err(|error| Error::CreateWebview(Box::new(error)))?,
                 )
             } else {
                 None
@@ -1177,17 +984,11 @@ impl<T: UserEvent> Runtime<T> for BlitzRuntime<T> {
             #[cfg(all(feature = "agent-control", unix))]
             _agent_control: agent_control,
             #[cfg(all(feature = "agent-control", unix))]
-            agent_revision: 0,
+            control: DocumentControl::new(),
             #[cfg(all(feature = "agent-control", unix))]
             paint_revision: 0,
             #[cfg(all(feature = "agent-control", unix))]
             control_events,
-            #[cfg(all(feature = "agent-control", unix))]
-            agent_pointer: (0.0, 0.0),
-            #[cfg(all(feature = "agent-control", unix))]
-            agent_buttons: MouseEventButtons::default(),
-            #[cfg(all(feature = "diagnostics", unix))]
-            capture_surface: None,
         };
         runtime_trace("BlitzRuntime::new completed");
         Ok(Self {
@@ -1295,43 +1096,6 @@ impl<T: UserEvent> Runtime<T> for BlitzRuntime<T> {
     }
 }
 
-#[cfg(all(feature = "agent-control", unix))]
-fn set_agent_node_value(
-    document: &mut ScriptDocument,
-    node_id: blitz_dom::NodeId,
-    value: String,
-) -> Result<(), DebugError> {
-    if !document
-        .inner()
-        .get_node(node_id)
-        .and_then(|node| node.element_data())
-        .is_some_and(|element| element.text_input_data().is_some())
-    {
-        return Err(debug_error("notEditable", "node is not a text input"));
-    }
-    document.inner_mut().set_focus_to(node_id);
-    document
-        .inner_mut()
-        .with_text_input(node_id, |mut editor| editor.select_all());
-    document.handle_ui_event(UiEvent::Ime(BlitzImeEvent::Commit(value)));
-    Ok(())
-}
-
-#[cfg(all(feature = "agent-control", unix))]
-fn mouse_button(button: u16) -> Result<MouseEventButton, DebugError> {
-    match button {
-        0 => Ok(MouseEventButton::Main),
-        1 => Ok(MouseEventButton::Auxiliary),
-        2 => Ok(MouseEventButton::Secondary),
-        3 => Ok(MouseEventButton::Fourth),
-        4 => Ok(MouseEventButton::Fifth),
-        _ => Err(debug_error(
-            "unsupportedButton",
-            "pointer button must be 0 through 4",
-        )),
-    }
-}
-
 #[cfg(all(feature = "agent-control", unix))]
 fn relaunch_current_process() -> std::io::Result<()> {
     let executable = std::env::current_exe()?;
@@ -1359,31 +1123,6 @@ fn containing_app_bundle(executable: &std::path::Path) -> Option<std::path::Path
         .then(|| bundle.to_path_buf())
 }
 
-#[cfg(all(feature = "agent-control", unix))]
-const MAX_AGENT_SETTLE_POLLS: usize = 100;
-
-/// Drain the synchronous consequences of one driven action before acknowledging it.
-///
-/// Timers and animation frames remain asynchronous. A poll hook that stays runnable
-/// is different: returning `Ack` in that state lets the next inspection observe a
-/// half-applied action. Report the exhaustion so callers can fail the interaction
-/// instead of compensating with an arbitrary sleep.
-#[cfg(all(feature = "agent-control", unix))]
-fn settle_agent_action(document: &mut ScriptDocument) -> Result<(), DebugError> {
-    for _ in 0..MAX_AGENT_SETTLE_POLLS {
-        if !document.poll(None) {
-            document.inner_mut().resolve(0.0);
-            return Ok(());
-        }
-    }
-
-    document.inner_mut().resolve(0.0);
-    Err(debug_error(
-        "actionDidNotSettle",
-        "the action kept synchronous script work runnable past the settlement budget",
-    ))
-}
-
 #[cfg(feature = "debug-control")]
 fn debug_screenshot_size_from_env() -> Option<(u32, u32)> {
     let value = std::env::var("TAURI_BLITZ_DRIVER_SCREENSHOT_SIZE").ok()?;
@@ -1619,12 +1358,6 @@ fn window_attributes(builder: &BlitzWindowBuilder) -> WindowAttributes {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::agent::{
-        SemanticCandidate, diagnostic_layout_row, diagnostic_style_row, dom_chain_is_attached,
-        element_attr, layout_chain_is_valid, layout_chain_validities, node_is_visible,
-        semantic_name, semantic_role, semantic_selected,
-    };
-    use crate::control_protocol::SemanticNode;
     use blitz_dom::DocumentConfig;
     use tauri_runtime::window::WindowBuilder;
 
@@ -1672,898 +1405,6 @@ mod tests {
         assert!(!attributes.decorations);
     }
 
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn semantic_visibility_includes_display_none_ancestors() {
-        let mut document = ScriptDocument::from_html(
-            "<main><button id='shown'>Run</button><div style='display:none'><button id='hidden'>Hidden</button></div></main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let node_id = |value: &str| {
-            inner
-                .tree()
-                .iter()
-                .find_map(|(id, node)| {
-                    node.element_data()
-                        .is_some_and(|element| element_attr(element, "id") == Some(value))
-                        .then_some(id)
-                })
-                .unwrap()
-        };
-        let shown = node_id("shown");
-        let hidden = node_id("hidden");
-        assert!(node_is_visible(&inner, shown));
-        assert!(!node_is_visible(&inner, hidden));
-        let shown_node = inner.get_node(shown).unwrap();
-        let shown_element = shown_node.element_data().unwrap();
-        assert_eq!(semantic_role(shown_element), "button");
-        let labels = crate::agent::LabelIndex::build(&inner);
-        assert_eq!(
-            semantic_name(shown_element, shown_node, "button", &inner, shown, &labels),
-            "Run"
-        );
-    }
-
-    /// A name is made of rendered text, so a `<style>` inside a link is not
-    /// part of it.
-    ///
-    /// `textContent` is the DOM property and includes every text node in the
-    /// subtree, stylesheets and scripts among them. An accessible name does
-    /// not, because those elements are not rendered.
-    ///
-    /// Measured on honey.id, whose header logo is an anchor wrapping an inline
-    /// SVG with a `<style>` in it. The home link arrived named
-    /// ".animated-logo path { fill-opacity: 0; ... }", which is unusable to a
-    /// person and unaddressable to a check.
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn a_style_element_is_not_part_of_a_name() {
-        let mut document = ScriptDocument::from_html(
-            "<main>\
-               <a id='logo' href='/'>\
-                 <svg><style>.logo path { fill: red; }</style></svg>\
-                 Honey\
-               </a>\
-               <a id='scripted' href='/x'><script>var noise = 1;</script>Docs</a>\
-             </main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let labels = crate::agent::LabelIndex::build(&inner);
-        let named = |value: &str| {
-            let id = inner
-                .tree()
-                .iter()
-                .find_map(|(id, node)| {
-                    node.element_data()
-                        .is_some_and(|element| element_attr(element, "id") == Some(value))
-                        .then_some(id)
-                })
-                .unwrap();
-            let node = inner.get_node(id).unwrap();
-            let element = node.element_data().unwrap();
-            let role = semantic_role(element);
-            semantic_name(element, node, &role, &inner, id, &labels)
-        };
-
-        assert_eq!(named("logo"), "Honey", "a stylesheet is not part of a name");
-        assert_eq!(named("scripted"), "Docs", "and neither is a script");
-    }
-
-    /// Two stacked lines make two words, not one run-on word.
-    ///
-    /// crates.vip's failure alert is a column of two block-level lines, and it
-    /// arrived named "This page could not loadWebSocket connection failed":
-    /// every text node was concatenated with nothing between it and the next.
-    /// A name a person cannot read is a name a check cannot address.
-    ///
-    /// The inline case is the other half of the assertion, and it is what
-    /// stops the fix being "put a space everywhere": a name built from two
-    ///
-    /// `inline-block` is the third case, and it is why the test is not
-    /// "outside is inline": an atomic inline establishes its own box, so a
-    /// browser separates it the way it separates a block.
-    /// spans is still one word, because that is what the page draws.
-    #[test]
-    fn stacked_lines_are_separated_and_inline_ones_are_not() {
-        let mut document = ScriptDocument::from_html(
-            "<main>\
-               <div id='stacked' role='alert'>\
-                 <div>This page could not load</div>\
-                 <div>WebSocket connection failed</div>\
-               </div>\
-               <div id='inline' role='alert'><span>Work</span><span>Tables</span></div>\
-               <div id='atomic' role='alert'>\
-                 <span style='display: inline-block'>Registry</span>\
-                 <span style='display: inline-block'>unavailable</span>\
-               </div>\
-             </main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let labels = crate::agent::LabelIndex::build(&inner);
-        let named = |value: &str| {
-            let id = inner
-                .tree()
-                .iter()
-                .find_map(|(id, node)| {
-                    node.element_data()
-                        .is_some_and(|element| element_attr(element, "id") == Some(value))
-                        .then_some(id)
-                })
-                .unwrap();
-            let node = inner.get_node(id).unwrap();
-            let element = node.element_data().unwrap();
-            let role = semantic_role(element);
-            semantic_name(element, node, &role, &inner, id, &labels)
-        };
-
-        assert_eq!(
-            named("stacked"),
-            "This page could not load WebSocket connection failed",
-            "block-level lines are separate words"
-        );
-        assert_eq!(
-            named("inline"),
-            "WorkTables",
-            "inline spans are one word, as the page draws them"
-        );
-        assert_eq!(
-            named("atomic"),
-            "Registry unavailable",
-            "an inline-block is an atomic inline, and a browser separates it"
-        );
-    }
-
-    /// A form control is named by the label pointing at it.
-    ///
-    /// The name came from `aria-label`, `alt` and `title` and from nothing
-    /// else, so the ordinary way to label a field produced no name at all and
-    /// every text input on every page arrived anonymous. That is not only a
-    /// reporting defect: a harness addresses a control by name, so an
-    /// anonymous field cannot be typed into and a check that means "enter a URL
-    /// and save" cannot be written.
-    ///
-    /// Measured on support.cafe's connection settings, whose three fields each
-    /// carry a correct `<Label for>` and all reported as `textbox ""`.
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn a_field_is_named_by_its_label() {
-        let mut document = ScriptDocument::from_html(
-            "<main>\
-               <label for='endpoint'>Endpoint URL</label><input id='endpoint'>\
-               <label>Wrapped<input id='wrapped'></label>\
-               <label for='overridden'>Ignored</label>\
-               <input id='overridden' aria-label='Author own name'>\
-               <input id='placeheld' placeholder='Search everything'>\
-               <input id='nameless'>\
-             </main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let labels = crate::agent::LabelIndex::build(&inner);
-        let named = |value: &str| {
-            let id = inner
-                .tree()
-                .iter()
-                .find_map(|(id, node)| {
-                    node.element_data()
-                        .is_some_and(|element| element_attr(element, "id") == Some(value))
-                        .then_some(id)
-                })
-                .unwrap();
-            let node = inner.get_node(id).unwrap();
-            let element = node.element_data().unwrap();
-            let role = semantic_role(element);
-            semantic_name(element, node, &role, &inner, id, &labels)
-        };
-
-        assert_eq!(named("endpoint"), "Endpoint URL", "a `for` association");
-        assert_eq!(named("wrapped"), "Wrapped", "a label wrapped around it");
-        assert_eq!(
-            named("overridden"),
-            "Author own name",
-            "`aria-label` is the author overriding the visible text, and wins"
-        );
-        assert_eq!(
-            named("placeheld"),
-            "Search everything",
-            "a placeholder is the last resort, and names most search fields"
-        );
-        assert_eq!(named("nameless"), "", "nothing names it, so it has no name");
-    }
-
-    /// A live region is named by what it says.
-    ///
-    /// `alert` and `status` are the roles an application uses to report that
-    /// something happened -- a refusal, a saved confirmation -- and what they
-    /// report is their content. Anonymous, "the reason is shown" is not a
-    /// question a check can ask, so every validation outcome has to be
-    /// approximated by something else that moved.
-    ///
-    /// The negative half is the point of the test. A wrapper's text content is
-    /// its whole subtree, so naming generic containers would give every one of
-    /// them a name made of the entire page, and any name-matching selector
-    /// would then match everything.
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn a_live_region_is_named_by_what_it_says() {
-        let mut document = ScriptDocument::from_html(
-            "<main>\
-               <p id='refusal' role='alert'>that is not an address</p>\
-               <p id='saved' role='status'>Settings saved</p>\
-               <div id='wrapper'><span>inner text</span></div>\
-             </main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let labels = crate::agent::LabelIndex::build(&inner);
-        let named = |value: &str| {
-            let id = inner
-                .tree()
-                .iter()
-                .find_map(|(id, node)| {
-                    node.element_data()
-                        .is_some_and(|element| element_attr(element, "id") == Some(value))
-                        .then_some(id)
-                })
-                .unwrap();
-            let node = inner.get_node(id).unwrap();
-            let element = node.element_data().unwrap();
-            let role = semantic_role(element);
-            semantic_name(element, node, &role, &inner, id, &labels)
-        };
-
-        assert_eq!(named("refusal"), "that is not an address");
-        assert_eq!(named("saved"), "Settings saved");
-        assert_eq!(
-            named("wrapper"),
-            "",
-            "a container named by its subtree would make every selector match everything"
-        );
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn rooted_inspection_returns_only_the_requested_dom_subtree() {
-        let mut document = ScriptDocument::from_html(
-            "<main><section id='left'><button>Left action</button></section><section id='right'><button>Right action</button></section></main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let root = document
-            .inner()
-            .query_selector("#left")
-            .unwrap()
-            .unwrap()
-            .as_u64();
-
-        let DebugResponse::AgentSnapshot(snapshot) =
-            inspect_document(&mut document, Some(root), 40, 7)
-        else {
-            panic!("rooted inspection did not return a semantic snapshot");
-        };
-        let names: Vec<_> = snapshot
-            .nodes
-            .iter()
-            .map(|node| node.name.as_str())
-            .collect();
-        assert!(names.contains(&"Left action"));
-        assert!(!names.contains(&"Right action"));
-        assert_eq!(snapshot.revision, 7);
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn semantic_geometry_rejects_a_detached_layout_ancestor() {
-        let mut document = ScriptDocument::from_html(
-            "<main><button id='target'>Run</button></main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let inner = document.inner();
-        let target = inner.query_selector("#target").unwrap().unwrap();
-        let node_limit = inner.tree().iter().count();
-        assert!(layout_chain_is_valid(&inner, target, node_limit));
-        let candidate = || SemanticCandidate {
-            id: target,
-            parent: None,
-            visible: true,
-        };
-        assert_eq!(
-            layout_chain_validities(&inner, &[candidate()], node_limit).get(&target),
-            Some(&true)
-        );
-
-        let missing_parent = (1..=1024)
-            .map(blitz_dom::NodeId::from_u64)
-            .find(|id| inner.get_node(*id).is_none())
-            .expect("the fixture must leave at least one node id unused");
-        inner
-            .get_node(target)
-            .unwrap()
-            .layout_parent
-            .set(Some(missing_parent));
-
-        assert!(!layout_chain_is_valid(&inner, target, node_limit));
-        assert_eq!(
-            layout_chain_validities(&inner, &[candidate()], node_limit).get(&target),
-            Some(&false)
-        );
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn semantic_geometry_rejects_a_retained_dom_subtree() {
-        let mut document = ScriptDocument::from_html(
-            "<main><section id='removed'><button id='target'>Run</button></section></main>",
-            DocumentConfig::default(),
-        );
-        let (removed, target) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#removed").unwrap().unwrap(),
-                inner.query_selector("#target").unwrap().unwrap(),
-            )
-        };
-        let node_limit = document.inner().tree().iter().count();
-        assert!(dom_chain_is_attached(&document.inner(), target, node_limit));
-
-        blitz_dom::DocumentMutator::new(&mut document.inner_mut()).remove_node(removed);
-
-        let inner = document.inner();
-        assert!(
-            inner.get_node(target).is_some(),
-            "the DOM keeps detached nodes alive for JavaScript wrappers"
-        );
-        assert!(!dom_chain_is_attached(&inner, target, node_limit));
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn semantic_selection_includes_native_and_aria_states() {
-        let document = ScriptDocument::from_html(
-            r#"
-            <button id="pressed" aria-pressed="true">Pressed</button>
-            <div id="checked" role="radio" aria-checked="true">Checked</div>
-            <div id="selected" role="option" aria-selected="true">Selected</div>
-            <button id="current-page" aria-current="page">Current page</button>
-            <input id="native" type="checkbox" checked>
-            <button id="plain">Plain</button>
-            <!--
-              A framework rendering a controlled value writes the value out
-              rather than omitting the attribute. Solid emits `checked="false"`
-              for `checked={false}`, and reading presence alone called that
-              selected: every Switch, Radio and Checkbox in the QA harness
-              reported `selected: true` before anything was pressed, and could
-              never change, which read as three components ignoring a click.
-            -->
-            <input id="native-unchecked" type="checkbox" checked="false">
-            <div id="aria-false" role="option" aria-selected="false">Not selected</div>
-            <button id="current-false" aria-current="false">Not current</button>
-            <div id="selected-false" role="option" selected="false">Not selected</div>
-            "#,
-            DocumentConfig::default(),
-        );
-        let inner = document.inner();
-        let selected = |selector: &str| {
-            let id = inner.query_selector(selector).unwrap().unwrap();
-            semantic_selected(inner.get_node(id).unwrap().element_data().unwrap())
-        };
-
-        assert!(selected("#pressed"));
-        assert!(selected("#checked"));
-        assert!(selected("#selected"));
-        assert!(selected("#current-page"));
-        assert!(selected("#native"));
-        assert!(!selected("#plain"));
-        assert!(!selected("#native-unchecked"));
-        assert!(!selected("#aria-false"));
-        assert!(!selected("#current-false"));
-        assert!(!selected("#selected-false"));
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn node_activation_reaches_an_offscreen_mousedown_handler() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <button id="target" style="position:absolute;left:-900px;width:80px;height:30px">Run</button>
-            <output id="result"></output>
-            <script>
-              const target = document.getElementById("target");
-              const result = document.getElementById("result");
-              target.addEventListener("mousedown", () => result.textContent += "down ");
-              target.addEventListener("click", () => result.textContent += "click");
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        document.inner_mut().resolve(0.0);
-        let (target, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#target").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-        assert!(
-            document
-                .inner()
-                .get_client_bounding_rect(target)
-                .is_some_and(|rect| rect.x < 0.0),
-            "the fixture must be outside the viewport"
-        );
-
-        activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
-
-        assert_eq!(
-            document.inner().get_node(result).unwrap().text_content(),
-            "down click"
-        );
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn node_activation_bubbles_to_delegated_handlers() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <main id="root">
-              <button id="target" style="width:80px;height:30px">Run</button>
-              <output id="result"></output>
-            </main>
-            <script>
-              const root = document.getElementById("root");
-              const result = document.getElementById("result");
-              root.addEventListener("mousedown", event => {
-                if (event.target.id === "target") result.textContent += "down ";
-              });
-              root.addEventListener("click", event => {
-                if (event.target.id === "target") result.textContent += "click";
-              });
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        document.inner_mut().resolve(0.0);
-        let (target, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#target").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-
-        activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
-
-        assert_eq!(
-            document.inner().get_node(result).unwrap().text_content(),
-            "down click"
-        );
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn node_activation_reaches_solid_style_document_delegation() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <main id="root">
-              <button id="target" style="width:80px;height:30px">Run</button>
-              <output id="result"></output>
-            </main>
-            <script>
-              const target = document.getElementById("target");
-              const result = document.getElementById("result");
-              target.$$click = () => result.textContent = "delegated";
-              document.addEventListener("click", event => {
-                let node = event.target;
-                while (node) {
-                  if (node.$$click) node.$$click(event);
-                  node = node.parentNode;
-                }
-              });
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        document.inner_mut().resolve(0.0);
-        let (target, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#target").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-
-        activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
-
-        assert_eq!(
-            document.inner().get_node(result).unwrap().text_content(),
-            "delegated"
-        );
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn node_activation_applies_the_native_focus_default() {
-        let mut document = ScriptDocument::from_html(
-            r#"<main><div id="slider" role="slider" tabindex="0" style="width:80px;height:30px">Value</div></main>"#,
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let slider = document.inner().query_selector("#slider").unwrap().unwrap();
-
-        activate_agent_node(&mut document, slider.as_u64(), 1).unwrap();
-
-        assert_eq!(document.inner().get_focussed_node_id(), Some(slider));
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn semantic_focus_does_not_activate_the_target() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <main>
-              <button id="target" style="width:80px;height:30px">Start fork</button>
-              <output id="result"></output>
-            </main>
-            <script>
-              document.getElementById("target").addEventListener("click", () => {
-                document.getElementById("result").textContent = "activated";
-              });
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        document.inner_mut().resolve(0.0);
-        let (target, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#target").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-
-        focus_agent_node(&mut document, target).unwrap();
-
-        assert_eq!(document.inner().get_focussed_node_id(), Some(target));
-        assert_eq!(
-            document.inner().get_node(result).unwrap().text_content(),
-            ""
-        );
-    }
-
-    /// macOS rather than `unix`, because this one needs a face.
-    ///
-    /// `set_agent_node_value` must *replace* a field's contents, not append to
-    /// them, and that comes down to select-all selecting something. Selection
-    /// is over shaped text, so with no font registered parley measures nothing,
-    /// the select-all covers nothing, and the replacement lands after the old
-    /// value. The assertion then fails for a reason that has nothing to do with
-    /// this crate's value plumbing.
-    ///
-    /// It was deleted outright once, on the grounds that it was really a test
-    /// of the font stack. It is not: the plumbing it covers is this crate's,
-    /// and only the *observation* of it needs a face. So it runs where one is
-    /// guaranteed and free, through Core Text, with no `fontconfig` and nothing
-    /// installed. On Linux it compiles out and this crate stays clean.
-    #[cfg(all(feature = "agent-control", target_os = "macos"))]
-    #[test]
-    fn setting_a_node_value_replaces_text_and_dispatches_input() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <main>
-              <input id="field" value="old" style="width:80px;height:30px">
-              <output id="result"></output>
-            </main>
-            <script>
-              const field = document.getElementById("field");
-              const result = document.getElementById("result");
-              field.addEventListener("input", event => result.textContent = event.target.value);
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        document.inner_mut().resolve(0.0);
-        let (field, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#field").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-
-        let replacement = "https://example.test/org/repository/issues/40?view=full#comment-2";
-        set_agent_node_value(&mut document, field, replacement.into()).unwrap();
-
-        let inner = document.inner();
-        let text = inner
-            .get_node(field)
-            .unwrap()
-            .element_data()
-            .unwrap()
-            .text_input_data()
-            .unwrap()
-            .editor
-            .raw_text();
-        assert_eq!(text, replacement);
-        assert_eq!(inner.get_node(result).unwrap().text_content(), replacement);
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn node_double_click_is_one_runtime_action() {
-        let mut document = ScriptDocument::from_html(
-            r#"
-            <button id="target" style="width:80px;height:30px">Open row</button>
-            <output id="result"></output>
-            <script>
-              document.getElementById("target").addEventListener("dblclick", () => {
-                document.getElementById("result").textContent = "double";
-              });
-            </script>
-            "#,
-            DocumentConfig::default(),
-        );
-        document.execute_scripts();
-        let (target, result) = {
-            let inner = document.inner();
-            (
-                inner.query_selector("#target").unwrap().unwrap(),
-                inner.query_selector("#result").unwrap().unwrap(),
-            )
-        };
-
-        activate_agent_node(&mut document, target.as_u64(), 2).unwrap();
-
-        assert_eq!(
-            document.inner().get_node(result).unwrap().text_content(),
-            "double"
-        );
-    }
-
-    #[cfg(all(feature = "diagnostics", unix))]
-    #[test]
-    fn repeated_live_captures_reuse_one_surface_and_keep_identical_pixels() {
-        use blitz_traits::shell::{ColorScheme, Viewport};
-
-        let mut document = ScriptDocument::from_html(
-            "<body style='margin:0;background:transparent'><main style='width:320px;height:200px;background:rgba(24,32,42,.55);color:#f4f5f7'>\
-               <h1>Capture cache</h1><button>Ready</button>\
-             </main></body>",
-            DocumentConfig::default(),
-        );
-        document
-            .inner_mut()
-            .set_viewport(Viewport::new(320, 200, 1.0, ColorScheme::Dark));
-        document.inner_mut().resolve(0.0);
-
-        let mut surface = None;
-        let request = blitz_control_protocol::CaptureRequest::default();
-        let first = capture_document_with_surface(&mut document, request, &mut surface).unwrap();
-        let first_renderer = surface
-            .as_ref()
-            .map(|cached| std::ptr::from_ref(&cached.renderer))
-            .unwrap();
-        let second = capture_document_with_surface(&mut document, request, &mut surface).unwrap();
-        let second_renderer = surface
-            .as_ref()
-            .map(|cached| std::ptr::from_ref(&cached.renderer))
-            .unwrap();
-
-        assert_eq!(first_renderer, second_renderer);
-        assert_eq!(first.width, 320);
-        assert_eq!(first.height, 200);
-        assert_eq!(first.rgba_base64, second.rgba_base64);
-    }
-
-    #[cfg(all(feature = "diagnostics", unix))]
-    #[test]
-    fn node_region_matches_the_same_pixels_cut_from_a_full_document_capture() {
-        use base64::Engine as _;
-        use blitz_traits::shell::{ColorScheme, Viewport};
-
-        let mut document = ScriptDocument::from_html(
-            "<main style='width:320px;height:200px;background:#18202a;padding:24px'>\
-               <button id='target' style='width:96px;height:40px;background:#d24db8;color:#111'>Ready</button>\
-             </main>",
-            DocumentConfig::default(),
-        );
-        document
-            .inner_mut()
-            .set_viewport(Viewport::new(320, 200, 1.0, ColorScheme::Dark));
-        document.inner_mut().resolve(0.0);
-        let (target, left, top) = {
-            let inner = document.inner();
-            let target = inner.query_selector("#target").unwrap().unwrap();
-            let position = inner.get_node(target).unwrap().absolute_position(0.0, 0.0);
-            (
-                target,
-                position.x.round() as usize,
-                position.y.round() as usize,
-            )
-        };
-
-        let mut surface = None;
-        let full = capture_document_with_surface(
-            &mut document,
-            blitz_control_protocol::CaptureRequest::default(),
-            &mut surface,
-        )
-        .unwrap();
-        let node = capture_document_with_surface(
-            &mut document,
-            blitz_control_protocol::CaptureRequest {
-                node_id: Some(target.as_u64()),
-                scale: 1.0,
-            },
-            &mut surface,
-        )
-        .unwrap();
-
-        let full_rgba = base64::engine::general_purpose::STANDARD
-            .decode(full.rgba_base64)
-            .unwrap();
-        let node_rgba = base64::engine::general_purpose::STANDARD
-            .decode(node.rgba_base64)
-            .unwrap();
-        let mut expected = Vec::with_capacity(node_rgba.len());
-        for row in 0..node.height as usize {
-            let start = ((top + row) * full.width as usize + left) * 4;
-            expected.extend_from_slice(&full_rgba[start..start + node.width as usize * 4]);
-        }
-
-        assert!(node.width > 0);
-        assert!(node.height > 0);
-        assert_eq!(node_rgba, expected);
-    }
-
-    #[cfg(all(feature = "diagnostics", unix))]
-    #[test]
-    fn diagnostic_layout_reports_scroll_state_without_script_evaluation() {
-        let mut document = ScriptDocument::from_html(
-            "<section id='scroller' style='height:100px;overflow-y:auto'><div style='height:400px'>tail</div></section>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let scroller = document
-            .inner()
-            .tree()
-            .iter()
-            .find_map(|(id, node)| {
-                node.element_data()
-                    .is_some_and(|element| element_attr(element, "id") == Some("scroller"))
-                    .then_some(id)
-            })
-            .unwrap();
-        document
-            .inner_mut()
-            .get_node_mut(scroller)
-            .unwrap()
-            .scroll_offset_mut()
-            .y = 60.0;
-
-        let inner = document.inner();
-        let row = diagnostic_layout_row(
-            &inner,
-            &SemanticNode {
-                dom_id: Some("scroller".into()),
-                id: scroller.as_u64(),
-                parent: None,
-                role: "generic".into(),
-                name: "Scrollable region".into(),
-                value: None,
-                enabled: true,
-                visible: true,
-                selected: false,
-                bounds: Some([0.0, 0.0, 100.0, 100.0]),
-                slot: None,
-            },
-        )
-        .unwrap();
-
-        assert_eq!(row.scroll_offset.y, 60.0);
-        assert_eq!(row.client_size.height, 100.0);
-        assert!(row.scroll_size.height >= 100.0);
-        assert!(row.scroll_range.height >= 0.0);
-    }
-
-    #[cfg(all(feature = "diagnostics", unix))]
-    #[test]
-    fn diagnostic_style_reports_resolved_font_and_border() {
-        let mut document = ScriptDocument::from_html(
-            "<main id='target' style='font-size:1.4375rem;border:2px solid #123456'>Readable</main>",
-            DocumentConfig::default(),
-        );
-        document.inner_mut().resolve(0.0);
-        let target = document.inner().query_selector("#target").unwrap().unwrap();
-        let inner = document.inner();
-        let row = diagnostic_style_row(
-            &inner,
-            &SemanticNode {
-                dom_id: Some("target".into()),
-                id: target.as_u64(),
-                parent: None,
-                role: "main".into(),
-                name: "Readable".into(),
-                value: None,
-                enabled: true,
-                visible: true,
-                selected: false,
-                bounds: Some([0.0, 0.0, 100.0, 24.0]),
-                slot: None,
-            },
-        )
-        .unwrap();
-
-        assert_eq!(row["fontSize"], "23px");
-        assert_eq!(row["borderColor"], "#123456ff");
-        assert_eq!(row["borderWidth"], "2px");
-        assert_eq!(row["hasTextContent"], true);
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn native_key_event_preserves_physical_code_and_modifiers() {
-        let event = key_event(
-            KeyPhase::Down,
-            Key::Character("2".into()),
-            Code::Digit2,
-            KeyboardModifiers::META,
-        );
-        assert_eq!(event.code, Code::Digit2);
-        assert!(event.modifiers.meta());
-        assert!(event.text.is_none());
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn agent_action_settlement_drains_until_the_document_is_idle() {
-        let mut document =
-            ScriptDocument::from_html("<main>Ready</main>", DocumentConfig::default());
-        let polls = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
-        let observed = std::sync::Arc::clone(&polls);
-        document.set_poll_hook(move |_, _| {
-            observed.fetch_add(1, std::sync::atomic::Ordering::Relaxed) < 3
-        });
-
-        settle_agent_action(&mut document).unwrap();
-
-        assert_eq!(polls.load(std::sync::atomic::Ordering::Relaxed), 4);
-    }
-
-    #[cfg(all(feature = "agent-control", unix))]
-    #[test]
-    fn agent_action_settlement_never_acks_a_still_runnable_document() {
-        let mut document =
-            ScriptDocument::from_html("<main>Busy</main>", DocumentConfig::default());
-        let polls = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
-        let observed = std::sync::Arc::clone(&polls);
-        document.set_poll_hook(move |_, _| {
-            observed.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
-            true
-        });
-
-        let error = settle_agent_action(&mut document).unwrap_err();
-
-        assert_eq!(error.code, "actionDidNotSettle");
-        assert_eq!(
-            polls.load(std::sync::atomic::Ordering::Relaxed),
-            MAX_AGENT_SETTLE_POLLS
-        );
-    }
-
     #[cfg(all(feature = "agent-control", unix))]
     #[tokio::test(flavor = "current_thread")]
     async fn control_interface_is_absent_until_explicitly_enabled() {

From 5b392a6f0a919fc9e664c4b505c8f661e29f0c5a Mon Sep 17 00:00:00 2001
From: meh <no-reply@pathscale.com>
Date: Wed, 9 Sep 2026 23:26:04 +0700
Subject: [PATCH 13/13] release: 0.4.0

A minor bump, not a patch. `set_agent_control_handler`,
`set_diagnostics_handler`, the `control_protocol` re-export and the
`agent`/`agent_control_server` exports are gone, so a build that named
any of them stops compiling rather than resolving to something subtly
different. That is the whole point of the removal, and a version that
claims compatibility with it would be lying.
---
 Cargo.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Cargo.toml b/Cargo.toml
index a534be2..8ab9165 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/tauri-runtime-blitz"]
 
 [workspace.package]
-version = "0.3.8"
+version = "0.4.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 publish = true