~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
659 lines · 26.5 KB Raw History
//! The kit that draws a call's tree, and the tree fitted to it. HUD's
//! renderers, on the web (`@hud/renderer`), iOS (HUDKit) and Android
//! (hudkit), are released as HUD's one version, but a build of an app in
//! someone's hands keeps the renderer it was built with while the views it
//! draws change on the server. So each kit says its version as it calls
//! (`Kit::of_params`, `Kit::said`), and each tree is fitted to it before it
//! is sent (`fit`): a part a view gates on the kit (`when` or `unless`
//! `{"$kit": requirement}` on a Stack, Pane or Bar, which the resolver
//! leaves marked `$kit`) is kept or left out, and a component newer than
//! the kit (its catalog `since`) is drawn as its children, else its
//! `fallback`, else nothing, as a kit draws a component it doesn't know.
//!
//! A kit says itself in a modern MCP request's client capabilities, as the
//! extension `place.hud/kit`, `{ platform, version }`; through
//! `place.hud.callTool`, as its input's `kit`. HUD's own web renderer is as
//! current as the server: the web shell says so (`platform` web), and an
//! MCP host that draws HUD's view (MCP Apps' extension, or any legacy-era
//! host), the workspace and the playground are drawn as this HUD's version.
//! A client that says nothing is drawn for the oldest kit (`OLDEST`).
//!
//! `warnings` reads an operator's views for the oldest kit their apps
//! still serve (an app file's `kits.oldest`), naming each component and
//! prop newer than it that no kit gate or fallback covers.

use crate::catalog;
use semver::{Version, VersionReq};
use serde_json::{Map, Value, json};
use std::sync::LazyLock;

/// The oldest kit: HUD's version before kits said theirs, by which every
/// catalog entry without a later `since` had arrived. A client that says
/// no version, or an older one, is drawn for it.
pub const OLDEST: &str = "0.2.0";

/// The client capability a kit names itself by, `{ platform, version }`.
pub const EXTENSION: &str = "place.hud/kit";

/// MCP Apps' client capability: a host drawing HUD's own view, served by
/// this server and so as current as it.
const APPS: &str = "io.modelcontextprotocol/ui";

/// The key the resolver marks a node gated on the kit with: an array of
/// `{ when: requirement }` and `{ unless: requirement }`, each to hold.
pub(crate) const GATES: &str = "$kit";

static CURRENT: LazyLock<Version> =
    LazyLock::new(|| Version::parse(crate::operator::VERSION).expect("HUD's version is semver"));
static FIRST: LazyLock<Version> =
    LazyLock::new(|| Version::parse(OLDEST).expect("the oldest kit is semver"));

/// The kit a call's tree is drawn by.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Kit {
    /// The version its trees are fitted to.
    pub version: Version,
    /// What it said of itself, for the logs: `ios 0.3.0`, `web 0.3.0`,
    /// `view` (an MCP host's), `workspace`; none where it said nothing.
    pub said: Option<String>,
}

impl Kit {
    /// HUD's own web renderer, as current as this server, `said` so.
    pub fn current(said: impl Into<String>) -> Kit {
        Kit {
            version: CURRENT.clone(),
            said: Some(said.into()),
        }
    }

    /// A client that said no version: the oldest kit.
    pub fn oldest() -> Kit {
        Kit {
            version: FIRST.clone(),
            said: None,
        }
    }

    /// A kit as it says itself, `{ platform, version }`: the web as
    /// current as this server; another platform as its version, no older
    /// than the oldest kit. One that says no platform (lowercase letters,
    /// digits and `-`, at most 32) or no semver version is the oldest.
    pub fn said(kit: Option<&Value>) -> Kit {
        let platform = kit.and_then(|k| k["platform"].as_str()).filter(|p| {
            (1..=32).contains(&p.len())
                && p.bytes()
                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
        });
        let version = kit
            .and_then(|k| k["version"].as_str())
            .and_then(|v| Version::parse(v).ok());
        let (Some(platform), Some(version)) = (platform, version) else {
            return Kit::oldest();
        };
        let said = Some(format!("{platform} {version}"));
        let version = match platform {
            "web" => CURRENT.clone(),
            _ => version.max(FIRST.clone()),
        };
        Kit { version, said }
    }

    /// The kit of an MCP request, by its params: a modern one's (its
    /// `_meta` names its protocol version) by its client capabilities' kit,
    /// else MCP Apps' (HUD's view), else the oldest; a legacy-era one's,
    /// HUD's view, which every host of that era draws with.
    pub fn of_params(params: Option<&Value>) -> Kit {
        let meta = params.and_then(|p| p.get("_meta"));
        if meta
            .and_then(|m| m.get("io.modelcontextprotocol/protocolVersion"))
            .is_none()
        {
            return Kit::current("view");
        }
        let extensions = meta
            .and_then(|m| m.get("io.modelcontextprotocol/clientCapabilities"))
            .and_then(|c| c.get("extensions"))
            .and_then(Value::as_object);
        match extensions {
            Some(e) if e.contains_key(EXTENSION) => Kit::said(e.get(EXTENSION)),
            Some(e) if e.contains_key(APPS) => Kit::current("view"),
            _ => Kit::oldest(),
        }
    }
}

/// A version of the catalog's (`since`), as semver.
fn version(v: &str) -> Version {
    Version::parse(v).expect("the catalog's versions are semver")
}

/// The version the component `c` arrived in; none for one the catalog
/// doesn't have (`Error`).
fn component_since(c: &str) -> Option<Version> {
    catalog::component(c).map(|c| version(c.since))
}

/// Whether a kit of `version` passes a node's gates: each `when`'s
/// requirement met, each `unless`'s not.
fn passes(gates: &Value, version: &Version) -> bool {
    gates.as_array().into_iter().flatten().all(|gate| {
        let met = |key: &str| {
            gate[key]
                .as_str()
                .and_then(|r| VersionReq::parse(r).ok())
                .is_some_and(|r| r.matches(version))
        };
        match gate.get("when") {
            Some(_) => met("when"),
            None => !met("unless"),
        }
    })
}

/// A tree being fitted to a kit: its version, when each component arrived,
/// and whether anything changed.
struct Fitting<'a> {
    version: &'a Version,
    since: &'a dyn Fn(&str) -> Option<Version>,
    changed: bool,
}

/// The components that draw nothing once fitting leaves them no children.
const CONTAINERS: &[&str] = &["Stack", "Row", "Split", "Menu", "Panes", "Pane"];

/// A tool's `_meta` with its tree (`ui`, where it has one) fitted to `kit`.
pub fn fit(meta: &mut Value, kit: &Kit) {
    fit_with(meta, &kit.version, &component_since);
}

/// A tree (a `_meta.ui`) fitted to `kit`, as `fit` fits a tool's.
pub fn fit_tree(tree: &mut Value, kit: &Kit) {
    let mut meta = json!({ "ui": tree.take() });
    fit(&mut meta, kit);
    *tree = meta["ui"].take();
}

/// `fit`, each component having arrived as `since` says.
fn fit_with(meta: &mut Value, version: &Version, since: &dyn Fn(&str) -> Option<Version>) {
    let Some(ui) = meta.get_mut("ui").filter(|ui| ui.get("root").is_some()) else {
        return;
    };
    let mut f = Fitting {
        version,
        since,
        changed: false,
    };
    let root = fit_node(ui["root"].take(), &mut f);
    ui["root"] = root.unwrap_or_else(|| json!({ "c": "Stack", "k": [] }));
    // The picture it draws first may have gone with what was left out.
    if f.changed {
        crate::ui::set_hero(ui);
    }
}

/// A node as the kit draws it: left out where its gates don't pass, its
/// stand-in where its component is newer than the kit (`stand_in`), else
/// itself with its children, items and fallback fitted; a container
/// fitting left empty draws nothing, a Split left one side that side.
fn fit_node(mut n: Value, f: &mut Fitting) -> Option<Value> {
    let Some(o) = n.as_object_mut() else {
        return Some(n);
    };
    if let Some(gates) = o.remove(GATES) {
        f.changed = true;
        if !passes(&gates, f.version) {
            return None;
        }
    }
    let c = o
        .get("c")
        .and_then(Value::as_str)
        .unwrap_or_default()
        .to_string();
    if (f.since)(&c).is_some_and(|s| s > *f.version) {
        f.changed = true;
        return stand_in(n, f);
    }
    if let Some(fallback) = o.remove("fallback")
        && let Some(fallback) = fit_node(fallback, f)
    {
        o.insert("fallback".into(), fallback);
    }
    if let Some(Value::Array(items)) = o.get_mut("items") {
        items.iter_mut().for_each(|item| fit_item(item, f));
    }
    if c == "FeedContext"
        && let Some(Value::Object(thread)) = o.get_mut("p").and_then(|p| p.get_mut("thread"))
    {
        for part in ["top", "parent"] {
            if let Some(post) = thread.get_mut(part) {
                fit_item(post, f);
            }
        }
    }
    let Some(Value::Array(k)) = o.get_mut("k") else {
        return Some(n);
    };
    let had = k.len();
    fit_nodes(k, f);
    match k.len() {
        left if left == had => {}
        1 if c == "Split" => return k.pop(),
        0 if CONTAINERS.contains(&c.as_str()) => return None,
        0 => {
            o.remove("k");
        }
        _ => {}
    }
    Some(n)
}

/// Each of `k` fitted, those that draw nothing left out.
fn fit_nodes(k: &mut Vec<Value>, f: &mut Fitting) {
    *k = std::mem::take(k)
        .into_iter()
        .filter_map(|n| fit_node(n, f))
        .collect();
}

/// An item's nodes fitted: its children (`k`), and the items nested under
/// it (a tree's `children`).
fn fit_item(item: &mut Value, f: &mut Fitting) {
    if let Some(Value::Array(k)) = item.get_mut("k") {
        fit_nodes(k, f);
    }
    if let Some(Value::Array(nested)) = item.get_mut("children") {
        nested.iter_mut().for_each(|n| fit_item(n, f));
    }
}

/// What stands for a component the kit doesn't know, as a kit draws one:
/// its children, as a Stack; else its fallback; else nothing.
fn stand_in(mut n: Value, f: &mut Fitting) -> Option<Value> {
    match n["k"].take() {
        Value::Array(k) if !k.is_empty() => {
            fit_node(json!({ "c": "Stack", "p": { "gap": "md" }, "k": k }), f)
        }
        _ => fit_node(n.get_mut("fallback")?.take(), f),
    }
}

/// A Stack's, Pane's or Bar's gates on the kit, as the resolver marks its
/// node (`GATES`): its `when` and `unless` where each is `{"$kit":
/// requirement}`.
pub(crate) fn gates(p: &Value) -> Vec<Value> {
    ["when", "unless"]
        .into_iter()
        .filter_map(|key| Some(json!({ key: requirement(&p[key])? })))
        .collect()
}

/// The requirement of a kit gate, `{"$kit": requirement}`.
pub fn requirement(gate: &Value) -> Option<&str> {
    let o = gate.as_object().filter(|o| o.len() == 1)?;
    o.get("$kit")?.as_str()
}

/// Whether a gate is a kit gate whose requirement is semver's.
pub fn is_gate(gate: &Value) -> bool {
    requirement(gate).is_some_and(|r| VersionReq::parse(r).is_ok())
}

/// What `hud check` warns of in a view, the file `file`, for the oldest
/// kit its apps serve: each component and prop newer than `oldest` that a
/// kit of it would not draw, unless a kit gate covers it (a Stack's,
/// Pane's or Bar's `when` or `unless` `{"$kit": …}` at or above it) or, a
/// component, its own `fallback` does; each naming its file and where in
/// it.
pub fn warnings(file: &str, doc: &Value, oldest: &Version) -> Vec<String> {
    warnings_with(file, doc, oldest, &|c, prop| {
        let c = catalog::component(c)?;
        Some(version(match prop {
            None => c.since,
            Some(name) => c.props.iter().find(|p| p.name == name)?.since,
        }))
    })
}

/// When a component (prop none) or its prop arrived, by the catalog.
type Since<'a> = &'a dyn Fn(&str, Option<&str>) -> Option<Version>;

/// `warnings`, each component and prop having arrived as `since` says.
fn warnings_with(file: &str, doc: &Value, oldest: &Version, since: Since) -> Vec<String> {
    let mut out = Vec::new();
    for mode in ["list", "record", "query", "page"] {
        if let Some(layout) = doc[mode].get("layout") {
            let at = format!("{file}: {mode}.layout");
            walk(layout, &at, false, oldest, since, &mut out);
        }
    }
    out
}

/// One node of a layout read for `warnings`, `gated` where a kit gate is
/// at or above it.
fn walk(n: &Value, at: &str, gated: bool, oldest: &Version, since: Since, out: &mut Vec<String>) {
    let Some(c) = n["component"].as_str() else {
        return;
    };
    let empty = Map::new();
    let props = n["props"].as_object().unwrap_or(&empty);
    let gated = gated
        || ["when", "unless"]
            .iter()
            .any(|k| props.get(*k).is_some_and(is_gate));
    let newer = |prop: Option<&str>| since(c, prop).filter(|s| s > oldest);
    if let Some(s) = newer(None).filter(|_| !gated && n.get("fallback").is_none()) {
        out.push(format!(
            "{at}: {c} arrived in HUD {s}, after the oldest kit served ({oldest}), which draws nothing in its place: gate it on the kit (a Stack's when {{\"$kit\": \">={s}\"}}) or give it a fallback"
        ));
    }
    for name in props.keys() {
        if let Some(s) = newer(Some(name)).filter(|_| !gated) {
            out.push(format!(
                "{at}.props.{name}: {c}'s {name} arrived in HUD {s}, after the oldest kit served ({oldest}), which ignores it: gate it on the kit (a Stack's when {{\"$kit\": \">={s}\"}})"
            ));
        }
    }
    if let Some(fallback) = n.get("fallback") {
        walk(
            fallback,
            &format!("{at}.fallback"),
            gated,
            oldest,
            since,
            out,
        );
    }
    for (i, child) in n["children"].as_array().into_iter().flatten().enumerate() {
        walk(
            child,
            &format!("{at}.children[{i}]"),
            gated,
            oldest,
            since,
            out,
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn v(s: &str) -> Version {
        Version::parse(s).unwrap()
    }

    /// A request's params with `_meta` naming the modern protocol and
    /// these client capabilities.
    fn modern(capabilities: Value) -> Value {
        json!({ "name": "query", "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientInfo": { "name": "hud-kit-ios", "version": "9.9.9" },
            "io.modelcontextprotocol/clientCapabilities": capabilities,
        } })
    }

    #[test]
    fn a_kit_is_what_it_says_and_the_oldest_when_it_says_nothing() {
        let ios = Kit::of_params(Some(&modern(json!({ "extensions": {
            EXTENSION: { "platform": "ios", "version": "0.3.1" } } }))));
        assert_eq!(
            ios,
            Kit {
                version: v("0.3.1"),
                said: Some("ios 0.3.1".into())
            }
        );
        // The web is as current as the server, whatever it says.
        let web = Kit::said(Some(&json!({ "platform": "web", "version": "0.1.0" })));
        assert_eq!(web.version, *CURRENT);
        assert_eq!(web.said.as_deref(), Some("web 0.1.0"));
        // No kit older than the oldest.
        let old = Kit::said(Some(&json!({ "platform": "android", "version": "0.1.0" })));
        assert_eq!(old.version, v(OLDEST));
        // A host drawing HUD's view, of either era, is current; clientInfo
        // alone says nothing.
        let apps = modern(
            json!({ "extensions": { APPS: { "mimeTypes": ["text/html;profile=mcp-app"] } } }),
        );
        assert_eq!(Kit::of_params(Some(&apps)), Kit::current("view"));
        assert_eq!(
            Kit::of_params(Some(&json!({ "name": "query" }))),
            Kit::current("view")
        );
        assert_eq!(Kit::of_params(None), Kit::current("view"));
        assert_eq!(Kit::of_params(Some(&modern(json!({})))), Kit::oldest());
        for wrong in [
            json!({ "version": "0.3.0" }),
            json!({ "platform": "iOS", "version": "0.3.0" }),
            json!({ "platform": "x".repeat(33), "version": "0.3.0" }),
            json!({ "platform": "ios", "version": "3" }),
            json!("ios 0.3.0"),
        ] {
            let said = modern(json!({ "extensions": { EXTENSION: wrong } }));
            assert_eq!(Kit::of_params(Some(&said)), Kit::oldest(), "{said}");
        }
        assert_eq!(Kit::said(None), Kit::oldest());
    }

    /// A tool's `_meta` with this tree's root.
    fn meta(root: Value) -> Value {
        json!({ "ui": { "v": 1, "trusted": true, "root": root } })
    }

    fn text(s: &str) -> Value {
        json!({ "c": "Text", "p": { "runs": [{ "text": s }] } })
    }

    /// Gauge arrived in 0.3.0; everything else is the oldest.
    fn since(c: &str) -> Option<Version> {
        match c {
            "Gauge" => Some(v("0.3.0")),
            "Error" => None,
            _ => Some(v(OLDEST)),
        }
    }

    fn fitted(root: Value, kit: &str) -> Value {
        let mut m = meta(root);
        fit_with(&mut m, &v(kit), &since);
        m["ui"]["root"].take()
    }

    #[test]
    fn a_gate_on_the_kit_resolves_per_kit() {
        let gated =
            |key: &str| json!({ "c": "Stack", "$kit": [{ key: ">=0.3.0" }], "k": [text(key)] });
        let root = json!({ "c": "Stack", "k": [gated("when"), gated("unless")] });
        assert_eq!(
            fitted(root.clone(), "0.3.0"),
            json!({ "c": "Stack", "k": [{ "c": "Stack", "k": [text("when")] }] })
        );
        assert_eq!(
            fitted(root.clone(), OLDEST),
            json!({ "c": "Stack", "k": [{ "c": "Stack", "k": [text("unless")] }] })
        );
        // Both, as a range.
        let both = json!({ "c": "Bar", "$kit": [{ "when": ">=0.3.0" }, { "unless": ">=0.4.0" }], "p": { "title": "x" } });
        assert_eq!(
            fitted(both.clone(), "0.3.5"),
            json!({ "c": "Bar", "p": { "title": "x" } })
        );
        assert_eq!(fitted(both, "0.4.0"), json!({ "c": "Stack", "k": [] }));
        // A gate no requirement is never met.
        let wrong = json!({ "c": "Stack", "$kit": [{ "when": "soon" }], "k": [text("x")] });
        assert_eq!(fitted(wrong, "9.0.0"), json!({ "c": "Stack", "k": [] }));
    }

    #[test]
    fn a_component_newer_than_the_kit_draws_its_children_else_its_fallback_else_nothing() {
        let with_children =
            json!({ "c": "Gauge", "p": { "value": 3 }, "k": [text("a")], "fallback": text("f") });
        let with_fallback = json!({ "c": "Gauge", "p": { "value": 3 }, "fallback": text("f") });
        let bare = json!({ "c": "Gauge", "p": { "value": 3 } });
        let root = json!({ "c": "Row", "k": [with_children.clone(), with_fallback.clone(), bare.clone(), text("b")] });
        assert_eq!(
            fitted(root.clone(), OLDEST),
            json!({ "c": "Row", "k": [
                { "c": "Stack", "p": { "gap": "md" }, "k": [text("a")] }, text("f"), text("b")] })
        );
        // A kit that knows it draws it, its fallback kept for a kit that
        // doesn't draw it on its platform.
        assert_eq!(fitted(root.clone(), "0.3.0"), root);
        // A fallback is fitted too: one newer still falls back again.
        let nested = json!({ "c": "Gauge", "fallback": with_fallback });
        assert_eq!(fitted(nested, OLDEST), text("f"));
        // Nothing left: an empty stack.
        assert_eq!(fitted(bare, OLDEST), json!({ "c": "Stack", "k": [] }));
    }

    #[test]
    fn what_fitting_empties_draws_as_the_resolver_draws_it() {
        let gone = json!({ "c": "Gauge" });
        // A Split left one side is that side; a container left nothing is nothing.
        let split = json!({ "c": "Split", "k": [gone.clone(), text("main")] });
        assert_eq!(fitted(split, OLDEST), text("main"));
        let stack = json!({ "c": "Stack", "k": [{ "c": "Row", "k": [gone.clone()] }, text("x")] });
        assert_eq!(
            fitted(stack, OLDEST),
            json!({ "c": "Stack", "k": [text("x")] })
        );
        // Another keeps itself, without children.
        let bar = json!({ "c": "Bar", "p": { "title": "t" }, "k": [gone.clone()] });
        assert_eq!(
            fitted(bar, OLDEST),
            json!({ "c": "Bar", "p": { "title": "t" } })
        );
        // Items' nodes, nested items' and a feed context's posts' too.
        let list =
            json!({ "c": "List", "items": [{ "k": [gone.clone(), text("i")] }, { "open": {} }] });
        assert_eq!(
            fitted(list, OLDEST),
            json!({ "c": "List", "items": [{ "k": [text("i")] }, { "open": {} }] })
        );
        let tree = json!({ "c": "Tree", "items": [{ "k": [text("p")], "children": [{ "k": [gone.clone()] }] }] });
        assert_eq!(
            fitted(tree, OLDEST),
            json!({ "c": "Tree", "items": [{ "k": [text("p")], "children": [{ "k": [] }] }] })
        );
        let context =
            json!({ "c": "FeedContext", "p": { "thread": { "top": { "k": [gone.clone()] } } } });
        assert_eq!(
            fitted(context, OLDEST),
            json!({ "c": "FeedContext", "p": { "thread": { "top": { "k": [] } } } })
        );
        // An error, and what is no node, are left as they are.
        let error = json!({ "c": "Error", "p": { "component": "Gauge", "message": "m" } });
        assert_eq!(fitted(error.clone(), OLDEST), error);
        let odd = json!({ "c": "Stack", "k": [5] });
        assert_eq!(fitted(odd.clone(), OLDEST), odd);
    }

    #[test]
    fn the_hero_follows_what_fitting_left() {
        let photo = json!({ "c": "Image", "p": { "src": { "src": "https://a.test/p.jpg" } } });
        let root = json!({ "c": "Stack", "k": [{ "c": "Stack", "$kit": [{ "when": ">=0.3.0" }], "k": [photo] }, text("x")] });
        let mut m = meta(root);
        m["ui"]["hero"] = json!("https://a.test/p.jpg");
        let mut newest = m.clone();
        fit_with(&mut newest, &v("0.3.0"), &since);
        assert_eq!(newest["ui"]["hero"], "https://a.test/p.jpg");
        fit_with(&mut m, &v(OLDEST), &since);
        assert_eq!(m["ui"].get("hero"), None);
        // A tree untouched keeps its own; a `_meta` without one is left be.
        let mut plain = meta(text("x"));
        plain["ui"]["hero"] = json!("kept");
        fit(&mut plain, &Kit::oldest());
        assert_eq!(plain["ui"]["hero"], "kept");
        let mut none = json!({ "viewer": {} });
        fit(&mut none, &Kit::oldest());
        assert_eq!(none, json!({ "viewer": {} }));
    }

    #[test]
    fn gates_are_read_from_when_and_unless() {
        let p = json!({ "when": { "$kit": ">=0.3.0" }, "unless": "kind.name" });
        assert_eq!(gates(&p), [json!({ "when": ">=0.3.0" })]);
        assert_eq!(
            gates(&json!({ "unless": { "$kit": "<1" } })),
            [json!({ "unless": "<1" })]
        );
        assert!(is_gate(&json!({ "$kit": ">=0.3.0, <0.5" })));
        for not in [
            json!({ "$kit": "later" }),
            json!({ "$kit": 3 }),
            json!({ "$kit": ">=1", "x": 1 }),
            json!("a"),
        ] {
            assert!(!is_gate(&not), "{not}");
        }
    }

    /// Gauge and Text's tone arrived in 0.3.0.
    fn since_props(c: &str, prop: Option<&str>) -> Option<Version> {
        match (c, prop) {
            ("Gauge", None) | ("Text", Some("tone")) => Some(v("0.3.0")),
            ("Nothing", _) => None,
            _ => Some(v(OLDEST)),
        }
    }

    #[test]
    fn hud_check_warns_of_what_the_oldest_kit_would_not_draw() {
        let gauge = json!({ "component": "Gauge", "props": { "value": 1 } });
        let toned = json!({ "component": "Text", "props": { "value": "x", "tone": "loud" } });
        let doc = json!({ "query": { "layout": { "component": "Stack", "children": [
            gauge,
            toned,
            { "component": "Gauge", "fallback": { "component": "Text", "props": { "value": "f", "tone": "loud" } } },
            { "component": "Stack", "props": { "when": { "$kit": ">=0.3.0" } }, "children": [
                { "component": "Gauge", "props": { "value": 1 } },
                { "component": "Text", "props": { "value": "x", "tone": "loud" } }] },
            { "component": "Nothing" },
            { "props": {} },
        ] } } });
        assert_eq!(
            warnings_with("views/v.json", &doc, &v(OLDEST), &since_props),
            [
                "views/v.json: query.layout.children[0]: Gauge arrived in HUD 0.3.0, after the oldest kit served (0.2.0), which draws nothing in its place: gate it on the kit (a Stack's when {\"$kit\": \">=0.3.0\"}) or give it a fallback",
                "views/v.json: query.layout.children[1].props.tone: Text's tone arrived in HUD 0.3.0, after the oldest kit served (0.2.0), which ignores it: gate it on the kit (a Stack's when {\"$kit\": \">=0.3.0\"})",
                "views/v.json: query.layout.children[2].fallback.props.tone: Text's tone arrived in HUD 0.3.0, after the oldest kit served (0.2.0), which ignores it: gate it on the kit (a Stack's when {\"$kit\": \">=0.3.0\"})",
            ]
        );
        // Served no older kit, nothing to say.
        assert!(warnings_with("v", &doc, &v("0.3.0"), &since_props).is_empty());
        // Every mode's layout is read; the catalog has nothing newer yet.
        let modes = json!({ "list": { "layout": { "component": "Text", "props": { "value": "x", "clamp": 2 } } },
                            "record": { "layout": { "component": "Stack" } }, "page": {} });
        assert!(warnings("v", &modes, &v(OLDEST)).is_empty());
        let unknown = json!({ "query": { "layout": { "component": "Stack", "children": [
            { "component": "Sparkle", "props": { "x": 1 } },
            { "component": "Text", "props": { "value": "x", "nope": 1 } }] } } });
        assert!(warnings("v", &unknown, &v(OLDEST)).is_empty());
    }

    /// Each kit says the version it was built as, HUD's one, which knope
    /// bumps in every file at once (knope.toml): HUDKit's `Kit.version`,
    /// hudkit's `hudVersion` (its BuildConfig), the web shell's package.
    #[test]
    fn every_kit_says_huds_version() {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
        let read = |p: &str| std::fs::read_to_string(root.join(p)).unwrap();
        let version = env!("CARGO_PKG_VERSION");
        let swift = read("ios/HUDKit/Sources/HUDKit/Support/Kit.swift");
        assert!(
            swift.contains(&format!("static let version = \"{version}\"\n")),
            "{swift}"
        );
        let gradle = read("android/gradle.properties");
        assert!(
            gradle.contains(&format!("hudVersion={version}\n")),
            "{gradle}"
        );
        let shell: Value = serde_json::from_str(&read("web/shell/package.json")).unwrap();
        assert_eq!(shell["version"], version);
    }
}