facett_core/

harness.rs

//! Headless test harness — **fire up a `Facet`, inject data, render it offscreen,
//! and capture what it drew**: its `state_json` + a vertex count (a "it drew
//! something" proxy) + a stderr activity trail. No display, no GPU. This is the
//! basis of facett's auto test matrix, and mirrors nornir viz's
//! `NORNIR_VIZ_STATE` introspection — every component is observable from outside.

use crate::Facet;

/// What a headless render of one facet looked like.
#[derive(Debug, Clone)]
pub struct RenderReport {
    pub title: String,
    /// The component's observable state (its `Facet::state_json`).
    pub state: serde_json::Value,
    /// Tessellated mesh vertices — a proxy for "it actually drew something".
    pub vertices: usize,
}

impl RenderReport {
    pub fn drew(&self) -> bool {
        self.vertices > 0
    }
}

/// Render `facet` once into the given context at `size`, capturing its state +
/// a vertex count. A panic in `ui` propagates — that's the point of the test.
#[allow(deprecated)] // ctx.run / CentralPanel::show are the headless-render path
fn capture(ctx: &egui::Context, facet: &mut dyn Facet, size: (f32, f32)) -> RenderReport {
    let title = facet.title().to_string();
    // Structured trace IN: which facet + at what size this render was handed
    // (the typed sibling of the `trail`/`log` lines below — see `trace`).
    crate::trace::emit_in(
        "facet.render",
        &serde_json::json!({ "title": title, "size": [size.0, size.1] }),
    );
    let input = egui::RawInput {
        screen_rect: Some(egui::Rect::from_min_size(egui::pos2(0.0, 0.0), egui::vec2(size.0, size.1))),
        ..Default::default()
    };
    let output = ctx.run(input, |ctx| {
        egui::CentralPanel::default().show(ctx, |ui| facet.ui(ui));
    });
    let prims = ctx.tessellate(output.shapes, output.pixels_per_point);
    let vertices = prims
        .iter()
        .map(|p| match &p.primitive {
            egui::epaint::Primitive::Mesh(m) => m.vertices.len(),
            _ => 0,
        })
        .sum();
    let report = RenderReport { title, state: facet.state_json(), vertices };
    log(&report);
    trail(Kind::Render, format!("{} size={}x{} → {} verts", report.title, size.0 as i32, size.1 as i32, vertices));
    dump_state(&report);
    // Structured trace OUT: the real data the facet rendered — its full
    // observable state + the vertex proof — so an agent reads back exactly what
    // was drawn, no screenshot. (`state` is the same Value `dump_state` prints.)
    crate::trace::emit_out(
        "facet.render",
        &serde_json::json!({
            "title": report.title,
            "vertices": report.vertices,
            "drew": report.drew(),
            "state": report.state,
        }),
    );
    report
}

/// Headless render at `size` (default theme).
pub fn render_sized(facet: &mut dyn Facet, size: (f32, f32)) -> RenderReport {
    capture(&egui::Context::default(), facet, size)
}

/// `render_sized` at a default 800×600.
pub fn headless_render(facet: &mut dyn Facet) -> RenderReport {
    render_sized(facet, (800.0, 600.0))
}

/// Headless render with a theme applied (asserts the themed paint path works).
pub fn render_themed(facet: &mut dyn Facet, theme: crate::Theme) -> RenderReport {
    let ctx = egui::Context::default();
    crate::set_theme(&ctx, theme);
    capture(&ctx, facet, (800.0, 600.0))
}

/// **Test/host hook (additive).** Headless render at `size` WITH `theme` applied —
/// the themed + sized paint path the graph-skin call-chain matrix sweeps (theme ×
/// canvas is a distinct painter path). Same `capture` the other helpers use, so it
/// IS the render the pixels come from; additive, no signature change to the existing
/// helpers.
pub fn render_themed_sized(facet: &mut dyn Facet, theme: crate::Theme, size: (f32, f32)) -> RenderReport {
    let ctx = egui::Context::default();
    crate::set_theme(&ctx, theme);
    capture(&ctx, facet, size)
}

/// Stderr activity trail (one line per render), like nornir viz's. The state is
/// capped so a large component can't flood the log.
pub fn log(r: &RenderReport) {
    let full = r.state.to_string();
    let shown: String = if full.chars().count() > 160 {
        full.chars().take(159).chain(std::iter::once('…')).collect()
    } else {
        full
    };
    eprintln!("facett: {:<14} {:>7} verts · {}", r.title, r.vertices, shown);
}

// ── action-log-style trail (mirrors nornir viz `action_log`) ─────────────────
//
// Nornir's viz emits a timestamped, kinded, sequenced trail
// (`HH:MM:SS.mmm  <seq> [KIND] detail`) on stderr + a greppable file so a human
// can follow "what the headless run did". These give facett's matrices the same
// observability. Dep-free: the stamp is derived from `SystemTime` and the seq
// from a process-global atomic — no chrono, no extra crate.

/// Coarse, greppable category for a trail entry — facett's analogue of nornir's
/// `action_log::Kind`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
    /// A facet was rendered headlessly.
    Render,
    /// A facet's full observable state was captured.
    State,
    /// A per-case matrix summary (component × theme × size).
    Case,
}

impl Kind {
    pub fn tag(self) -> &'static str {
        match self {
            Kind::Render => "RENDER",
            Kind::State => "STATE",
            Kind::Case => "CASE",
        }
    }
}

/// Process-global monotonic sequence — stable ordering even within one ms.
fn next_seq() -> u64 {
    use std::sync::atomic::{AtomicU64, Ordering};
    static SEQ: AtomicU64 = AtomicU64::new(0);
    SEQ.fetch_add(1, Ordering::Relaxed) + 1
}

/// `HH:MM:SS.mmm` local-ish wall stamp from `SystemTime` (UTC, no tz dep). Only
/// the time-of-day matters for following a trail, so this is intentionally
/// dependency-free rather than chrono-accurate.
fn now_stamp() -> String {
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default();
    let total_ms = now.as_millis();
    let ms = (total_ms % 1000) as u64;
    let secs = (total_ms / 1000) as u64;
    let h = (secs / 3600) % 24;
    let m = (secs / 60) % 60;
    let s = secs % 60;
    format!("{h:02}:{m:02}:{s:02}.{ms:03}")
}

/// Emit one greppable, timestamped, kinded trail line — facett's analogue of
/// nornir viz's `action_log` stderr sink:
///   `facett ACTION HH:MM:SS.mmm  <seq> [KIND] detail`
/// If `$FACETT_TRAIL` is set, the same line is appended to that file (greppable,
/// externally observable — mirrors how nornir mirrors `$NORNIR_VIZ_ACTIONLOG`).
pub fn trail(kind: Kind, detail: impl AsRef<str>) {
    let stamp = now_stamp();
    let seq = next_seq();
    let detail = detail.as_ref();
    let line = format!("facett ACTION {stamp} {seq:>5} [{}] {detail}", kind.tag());
    eprintln!("{line}");
    if let Ok(path) = std::env::var("FACETT_TRAIL") {
        use std::io::Write;
        if let Ok(mut f) = std::fs::OpenOptions::new().create(true).append(true).open(path) {
            let _ = writeln!(f, "{line}");
        }
    }
}

/// Dump a facet's FULL observable `state_json` as a single greppable line
/// (`facett STATE <title> = {…}`), the per-component analogue of viz_matrix's
/// `eprintln!("state_json = {pretty}")`. Untruncated so a Facet's rendered
/// contents are greppable in test output the way viz's are.
pub fn dump_state(r: &RenderReport) {
    eprintln!("facett STATE {} = {}", r.title, r.state);
    trail(Kind::State, format!("{} state={}", r.title, r.state));
}

/// Emit a uniform per-case matrix summary line + trail entry for one
/// component × axis case (e.g. a theme or a size), mirroring viz_matrix's
/// `[ws] releases=… tables=…` per-workspace summary. `axis` is a free-form
/// label like `theme=sci_fi` or `size=10000`.
pub fn case_summary(component: &str, axis: &str, r: &RenderReport) {
    eprintln!(
        "facett CASE  {:<14} {:<16} → {:>8} verts  drew={}  state={}",
        component,
        axis,
        r.vertices,
        r.drew(),
        r.state,
    );
    trail(Kind::Case, format!("{component} {axis} verts={} drew={}", r.vertices, r.drew()));
}

// ── Elm headless driver (FC-2 as a testable property) ────────────────────────
//
// The Facet helpers above render a facet offscreen and read its pixels/state. The
// pair below drive an [`Elm`](crate::Elm) component with **no egui and no GPU at
// all**: apply a `Vec<Msg>`, collect the `Effect`s, then snapshot `state()`. That
// is exactly FC-2 → FC-3 as a property a `proptest` (contract §5.1) can assert:
// *feed inputs, observe state*. `view()` (the only part that touches egui) is never
// called here, so these run anywhere, deterministically, with zero device.

/// Apply `msgs` to `component` in order via [`Elm::update`](crate::Elm::update),
/// returning **every** [`Effect`](crate::Elm::Effect) produced, in emission order.
/// No rendering happens — this is the pure state-transition driver.
pub fn drive<C: crate::Elm>(component: &mut C, msgs: impl IntoIterator<Item = C::Msg>) -> Vec<C::Effect> {
    let mut effects = Vec::new();
    for m in msgs {
        effects.extend(component.update(m));
    }
    effects
}

/// [`drive`] `component` through `msgs`, then return a **clone** of the resulting
/// [`Model`](crate::Elm::Model) — the headless FC-3 snapshot a test asserts on.
pub fn snapshot<C: crate::Elm>(component: &mut C, msgs: impl IntoIterator<Item = C::Msg>) -> C::Model {
    drive(component, msgs);
    component.state().clone()
}

/// [`drive`] `component` through `msgs`, then serialize the resulting
/// [`Model`](crate::Elm::Model) to JSON (FC-3). The machine-readable observable
/// state after the input sequence, with no render in the loop.
pub fn snapshot_json<C: crate::Elm>(component: &mut C, msgs: impl IntoIterator<Item = C::Msg>) -> serde_json::Value {
    drive(component, msgs);
    state_json(component)
}

/// Serialize an [`Elm`](crate::Elm) component's current [`Model`](crate::Elm::Model)
/// to JSON without applying any `Msg` (FC-3).
pub fn state_json<C: crate::Elm>(component: &C) -> serde_json::Value {
    serde_json::to_value(component.state()).unwrap_or(serde_json::Value::Null)
}

// ── Generic `dyn Facet` functional probe (the discovery-driven matrix path) ──
//
// The `drive`/`snapshot` pair above are *typed* — they need the component's
// concrete `Msg`/`Model`, so a leaf's test must know the pane's type. The probe
// below works on the **object-safe** `dyn Facet` seam (`title`/`ui`/`state_json`/
// `update_json`) that EVERY facett pane already implements. It headless-renders
// the pane, then plays a scripted list of `update_json` messages, snapshotting
// `state_json` after each, so ONE shared function gives a pane the two proofs a
// functional matrix cell needs — "it drew real geometry" and "it exposes live,
// input-responsive state" — WITHOUT the caller knowing the concrete Msg type.
// This is the single path the ~14 zero-cell panes call (each builds its pane via
// its own `local()` demo constructor and hands it here) instead of re-writing
// render+emit boilerplate per crate. Pair it with
// [`testmatrix::emit_facet_probe`](crate::testmatrix::emit_facet_probe).

/// One scripted `update_json` step against a facet: the message applied, the
/// vertex count of the re-render after it, and whether `state_json` changed.
#[derive(Debug, Clone)]
pub struct ProbeStep {
    /// The JSON message string handed to [`Facet::update_json`](crate::Facet::update_json).
    pub msg: String,
    /// Tessellated vertices of the re-render after this message.
    pub vertices: usize,
    /// Did this message move `state_json` (a live, input-responsive pane)?
    pub changed: bool,
    /// The pane's full `state_json` snapshot after this message.
    pub state: serde_json::Value,
}

/// The result of a full [`probe_facet`] run over one `dyn Facet`.
#[derive(Debug, Clone)]
pub struct FacetProbe {
    pub title: String,
    /// Vertices of the initial headless render (before any message).
    pub vertices: usize,
    /// `state_json` before any message was applied.
    pub initial_state: serde_json::Value,
    /// `state_json` after the last scripted message (== `initial_state` when no
    /// messages were scripted).
    pub final_state: serde_json::Value,
    /// Per-message observations, in order.
    pub steps: Vec<ProbeStep>,
}

impl FacetProbe {
    /// The initial render produced primitives.
    pub fn drew(&self) -> bool {
        self.vertices > 0
    }
    /// At least one scripted message moved `state_json` — proof the pane's input
    /// surface is live, not a no-op stub. Always `false` when no messages were
    /// scripted (there was nothing to respond to).
    pub fn responded(&self) -> bool {
        self.steps.iter().any(|s| s.changed)
    }
    /// A generic "how much domain data does this pane report" hint derived from
    /// `final_state`: the largest array length found in the state tree, else the
    /// number of top-level object keys, else 0. Lets a dead pane (empty state)
    /// score a RED render cell even if it drew chrome vertices — a 0-row table
    /// draws its header but reports `cardinality == 0`. A heuristic, not a
    /// contract; a caller with an exact count can emit its own row.
    pub fn cardinality(&self) -> usize {
        json_cardinality(&self.final_state)
    }
}

/// Largest array length anywhere in `v`, else (for an object with no arrays) its
/// key count, else 0. See [`FacetProbe::cardinality`].
pub fn json_cardinality(v: &serde_json::Value) -> usize {
    match v {
        serde_json::Value::Array(a) => a
            .iter()
            .map(json_cardinality)
            .max()
            .unwrap_or(0)
            .max(a.len()),
        serde_json::Value::Object(o) => {
            let deepest = o.values().map(json_cardinality).max().unwrap_or(0);
            deepest.max(o.len())
        }
        _ => 0,
    }
}

/// Render `facet` headlessly once, then apply each JSON message in `msgs` via
/// [`Facet::update_json`](crate::Facet::update_json), re-rendering and snapshotting
/// `state_json` after each. Returns a [`FacetProbe`] with the initial render proof
/// plus per-message transitions. No display, no GPU. Pass `&[]` for a pure
/// render+state probe of a read-only pane.
pub fn probe_facet(facet: &mut dyn Facet, msgs: &[&str]) -> FacetProbe {
    let ctx = egui::Context::default();
    let first = capture(&ctx, facet, (800.0, 600.0));
    let initial_state = first.state.clone();
    let mut prev = initial_state.clone();
    let mut steps = Vec::with_capacity(msgs.len());
    for msg in msgs {
        facet.update_json(msg);
        let r = capture(&ctx, facet, (800.0, 600.0));
        let changed = r.state != prev;
        trail(
            Kind::Case,
            format!("{} update_json {} → changed={}", first.title, msg, changed),
        );
        prev = r.state.clone();
        steps.push(ProbeStep { msg: (*msg).to_string(), vertices: r.vertices, changed, state: r.state });
    }
    let final_state = steps.last().map(|s| s.state.clone()).unwrap_or_else(|| initial_state.clone());
    FacetProbe { title: first.title, vertices: first.vertices, initial_state, final_state, steps }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{Scene, hash_color};

    struct Tiny(Scene);
    impl Facet for Tiny {
        fn title(&self) -> &str {
            "tiny"
        }
        fn ui(&mut self, ui: &mut egui::Ui) {
            crate::draw(ui, &self.0, crate::Layout::Circular, "empty");
        }
        fn state_json(&self) -> serde_json::Value {
            serde_json::json!({ "nodes": self.0.nodes.len() })
        }
    }

    #[test]
    fn now_stamp_is_hms_millis_shaped() {
        let s = now_stamp();
        // HH:MM:SS.mmm — 12 chars, two ':' and one '.'.
        assert_eq!(s.len(), 12, "stamp `{s}` should be HH:MM:SS.mmm");
        assert_eq!(s.matches(':').count(), 2, "stamp `{s}` needs two colons");
        assert_eq!(s.matches('.').count(), 1, "stamp `{s}` needs one dot");
    }

    #[test]
    fn seq_is_monotonic() {
        let a = next_seq();
        let b = next_seq();
        assert!(b > a, "seq must strictly increase: {a} then {b}");
    }

    #[test]
    fn kind_tags_are_distinct() {
        let tags = [Kind::Render.tag(), Kind::State.tag(), Kind::Case.tag()];
        for (i, t) in tags.iter().enumerate() {
            assert!(!t.is_empty());
            assert!(!tags[..i].contains(t), "duplicate tag {t}");
        }
    }

    #[test]
    fn headless_render_captures_state_and_draws() {
        let mut scene = Scene::new();
        let a = scene.node("a", hash_color("a"));
        let b = scene.node("b", hash_color("b"));
        scene.edge(a, b);
        let mut t = Tiny(scene);
        let r = headless_render(&mut t);
        assert_eq!(r.title, "tiny");
        assert_eq!(r.state["nodes"], 2);
        assert!(r.drew(), "a 2-node graph should tessellate to vertices");
    }

    // ── Elm trait + macro + headless driver, proven end-to-end on a mock ─────────
    //
    // A miniature reference component in the same Model/Msg/Effect/pure-view shape
    // as `facett-security`. `facett-core` cannot depend on `facett-security` (that
    // would be a dependency cycle), so the trait/macro/harness are proven here on a
    // self-contained mock; `facett-security`'s own test suite proves them against
    // the real reference component.

    use crate::Elm;
    use serde::{Deserialize, Serialize};

    /// All observable state (FC-1 / FC-3).
    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
    struct CounterState {
        count: i64,
        selected: Option<String>,
    }

    /// Every input (FC-2).
    #[derive(Clone, Debug, PartialEq)]
    enum CounterMsg {
        Inc,
        Dec,
        Add(i64),
        Select(Option<String>),
    }

    /// No I/O (FC-8) — uninhabited on purpose.
    #[derive(Debug)]
    enum CounterEffect {}

    struct Counter {
        title: String,
        state: CounterState,
    }

    impl Counter {
        fn new() -> Self {
            Self { title: "counter".into(), state: CounterState { count: 0, selected: None } }
        }
    }

    impl Elm for Counter {
        type Model = CounterState;
        type Msg = CounterMsg;
        type Effect = CounterEffect;

        fn title(&self) -> &str {
            &self.title
        }
        fn state(&self) -> &CounterState {
            &self.state
        }
        fn update(&mut self, msg: CounterMsg) -> Vec<CounterEffect> {
            match msg {
                CounterMsg::Inc => self.state.count += 1,
                CounterMsg::Dec => self.state.count -= 1,
                CounterMsg::Add(n) => self.state.count += n,
                // Toggle: re-selecting the open id clears it (mirrors security).
                CounterMsg::Select(id) => {
                    self.state.selected = if self.state.selected == id { None } else { id };
                }
            }
            Vec::new()
        }
        fn view(&self, ui: &mut egui::Ui) -> Vec<CounterMsg> {
            // Pure: paints, returns Msgs (here: none — the driver feeds inputs).
            ui.label(format!("count = {}", self.state.count));
            Vec::new()
        }
    }

    // The macro under test: writes `impl Facet for Counter` from the `Elm` impl.
    crate::impl_facet_via_elm!(Counter);

    /// A component that publishes a RICHER `state_json` than plain `serde(state())`
    /// — the case that forced helix/timeline/plandag to hand-write `impl Facet`
    /// before form 3 existed. Reuses `CounterState`/`CounterMsg`/`CounterEffect`.
    struct RichCounter {
        state: CounterState,
    }
    impl Elm for RichCounter {
        type Model = CounterState;
        type Msg = CounterMsg;
        type Effect = CounterEffect;
        fn title(&self) -> &str {
            "rich"
        }
        fn state(&self) -> &CounterState {
            &self.state
        }
        fn update(&mut self, msg: CounterMsg) -> Vec<CounterEffect> {
            if let CounterMsg::Add(n) = msg {
                self.state.count += n;
            }
            Vec::new()
        }
        fn view(&self, _ui: &mut egui::Ui) -> Vec<CounterMsg> {
            Vec::new()
        }
    }
    // Form 3: `custom_state_json` suppresses the default; we emit the model PLUS a
    // derived `parity` key the default serde dump would never produce.
    crate::impl_facet_via_elm!(RichCounter, custom_state_json, {
        fn state_json(&self) -> serde_json::Value {
            serde_json::json!({ "count": self.state.count, "parity": self.state.count % 2 })
        }
    });

    /// Form 3 lets a rich component override `state_json` via the macro (no
    /// duplicate-method clash), so the deck/matrix see its derived introspection keys.
    #[test]
    fn form3_custom_state_json_overrides_the_default() {
        use crate::Facet;
        let mut c = RichCounter { state: CounterState { count: 0, selected: None } };
        let _ = c.update(CounterMsg::Add(7));
        let j = Facet::state_json(&c);
        assert_eq!(j["count"], 7, "custom state_json is emitted");
        assert_eq!(j["parity"], 1, "the DERIVED key the default serde dump omits is present");
        assert_eq!(Facet::title(&c), "rich");
    }

    #[test]
    fn harness_drives_msgs_and_snapshots_state() {
        let mut c = Counter::new();
        // Apply a Vec<Msg>, then snapshot state() — the FC-2 → FC-3 property, no GPU.
        let snap = snapshot(
            &mut c,
            [CounterMsg::Inc, CounterMsg::Inc, CounterMsg::Add(5), CounterMsg::Dec],
        );
        assert_eq!(snap.count, 6, "1+1+5-1 = 6");
        assert_eq!(c.state().count, 6, "the component holds the driven state");

        // Selection toggles (re-selecting the open id clears it).
        let snap = snapshot(&mut c, [CounterMsg::Select(Some("a".into())), CounterMsg::Select(Some("a".into()))]);
        assert_eq!(snap.selected, None, "toggle clears the re-selected id");
    }

    #[test]
    fn drive_returns_effects_and_snapshot_json_serializes_state() {
        let mut c = Counter::new();
        let effects = drive(&mut c, [CounterMsg::Inc, CounterMsg::Add(3)]);
        assert!(effects.is_empty(), "FC-8: this component does no I/O");
        let js = snapshot_json(&mut c, [CounterMsg::Inc]);
        assert_eq!(js["count"], 5, "1+3+1 = 5, observable as JSON");
        assert_eq!(js["selected"], serde_json::Value::Null);
    }

    #[test]
    fn macro_bridges_elm_to_facet() {
        // The macro-generated Facet impl: title from Elm, state_json = serde(state).
        let mut c = Counter::new();
        drive(&mut c, [CounterMsg::Add(9)]);
        assert_eq!(Facet::title(&c), "counter");
        assert_eq!(Facet::state_json(&c), state_json(&c), "macro state_json == serde(state())");
        assert_eq!(Facet::state_json(&c)["count"], 9);
        // And the generated `ui` (view + update loop) renders headlessly.
        let r = headless_render(&mut c);
        assert_eq!(r.title, "counter");
        assert_eq!(r.state["count"], 9);
        assert!(r.drew(), "the label tessellates to vertices");
    }

    #[test]
    fn proptest_style_msg_sequences_keep_state_wellformed() {
        // proptest-style (dependency-free, deterministic LCG): generate many Msg
        // sequences from arbitrary start states, apply them, and assert invariants
        // hold — no panic, serde round-trips, and the count matches an independent
        // reference fold. This is contract §5.1 (property layer) over `update`.
        let mut rng: u64 = 0x9E3779B97F4A7C15;
        let mut next = || {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng
        };
        for _ in 0..500 {
            let mut c = Counter::new();
            c.state.count = (next() % 21) as i64 - 10; // arbitrary start in -10..=10
            let mut expected = c.state.count;
            let mut expect_sel: Option<String> = None;
            c.state.selected = None;
            let len = (next() % 12) as usize;
            let msgs: Vec<CounterMsg> = (0..len)
                .map(|_| match next() % 4 {
                    0 => {
                        expected += 1;
                        CounterMsg::Inc
                    }
                    1 => {
                        expected -= 1;
                        CounterMsg::Dec
                    }
                    2 => {
                        let n = (next() % 7) as i64 - 3;
                        expected += n;
                        CounterMsg::Add(n)
                    }
                    _ => {
                        let id = format!("id{}", next() % 3);
                        let new = Some(id.clone());
                        expect_sel = if expect_sel == new { None } else { new };
                        CounterMsg::Select(Some(id))
                    }
                })
                .collect();

            let snap = snapshot(&mut c, msgs);
            // Invariant 1: the driven count matches the independent fold.
            assert_eq!(snap.count, expected);
            // Invariant 2: selection toggle matches the reference.
            assert_eq!(snap.selected, expect_sel);
            // Invariant 3: state round-trips through serde (FC-3).
            let json = serde_json::to_string(&snap).unwrap();
            let back: CounterState = serde_json::from_str(&json).unwrap();
            assert_eq!(back, snap);
        }
    }

    // ── Generic `dyn Facet` probe ────────────────────────────────────────────

    /// A pane with a LIVE `update_json` input surface (`{"push":"x"}` appends an
    /// item, `{"clear":true}` empties) — the shape the discovery probe drives.
    struct ListPane {
        items: Vec<String>,
    }
    impl Facet for ListPane {
        fn title(&self) -> &str {
            "listpane"
        }
        fn ui(&mut self, ui: &mut egui::Ui) {
            for it in &self.items {
                ui.label(it);
            }
        }
        fn state_json(&self) -> serde_json::Value {
            serde_json::json!({ "items": self.items })
        }
        fn update_json(&mut self, msg_json: &str) {
            let v: serde_json::Value = match serde_json::from_str(msg_json) {
                Ok(v) => v,
                Err(_) => return,
            };
            if let Some(s) = v.get("push").and_then(|x| x.as_str()) {
                self.items.push(s.to_string());
            }
            if v.get("clear").and_then(|x| x.as_bool()) == Some(true) {
                self.items.clear();
            }
        }
    }

    #[test]
    fn probe_facet_captures_render_and_transitions() {
        let mut pane = ListPane { items: vec!["seed".into()] };
        let probe = probe_facet(&mut pane, &[r#"{"push":"a"}"#, r#"{"push":"b"}"#, r#"{"clear":true}"#]);
        assert_eq!(probe.title, "listpane");
        assert!(probe.drew(), "a label list should tessellate to vertices");
        assert_eq!(probe.initial_state["items"].as_array().unwrap().len(), 1);
        assert_eq!(probe.steps.len(), 3);
        // Every scripted message here moves state → all three steps changed.
        assert!(probe.steps.iter().all(|s| s.changed), "each push/clear mutates state");
        assert!(probe.responded());
        // After push a, push b, clear → empty list.
        assert_eq!(probe.final_state["items"].as_array().unwrap().len(), 0);
    }

    #[test]
    fn probe_facet_no_msgs_is_pure_render() {
        let mut pane = ListPane { items: vec!["x".into(), "y".into()] };
        let probe = probe_facet(&mut pane, &[]);
        assert!(probe.steps.is_empty());
        assert!(!probe.responded(), "no messages → nothing to respond to");
        assert_eq!(probe.final_state, probe.initial_state);
        assert_eq!(probe.cardinality(), 2, "two items → cardinality 2");
    }

    #[test]
    fn probe_flags_a_dead_input_surface() {
        // `Tiny` never overrides `update_json` (default no-op) — a read-only pane.
        // Driving it with a message must report NO response, so the matrix can
        // catch a pane whose input surface is silently dead.
        let mut scene = Scene::new();
        scene.node("n", hash_color("n"));
        let mut t = Tiny(scene);
        let probe = probe_facet(&mut t, &[r#"{"anything":1}"#]);
        assert_eq!(probe.steps.len(), 1);
        assert!(!probe.responded(), "a no-op update_json must not register as responsive");
    }

    #[test]
    fn json_cardinality_finds_the_largest_collection() {
        assert_eq!(json_cardinality(&serde_json::json!({"rows": [1, 2, 3, 4]})), 4);
        assert_eq!(json_cardinality(&serde_json::json!([1, 2])), 2);
        assert_eq!(json_cardinality(&serde_json::json!({"a": 1, "b": 2})), 2, "no arrays → key count");
        assert_eq!(json_cardinality(&serde_json::json!(null)), 0);
        assert_eq!(
            json_cardinality(&serde_json::json!({"outer": {"inner": [1, 2, 3, 4, 5]}})),
            5,
            "reaches nested arrays"
        );
    }
}