justerm-core 0.17.0

//! Issue #6 — binary wire format for a damage frame. The acceptance is a
//! round-trip: `decode(encode(frame)) == frame`, tested here through the public
//! API only (no engine/PTY/transport). Format spec: `docs/architecture.md`
//! §Serialization + ADR-0005.

// `round_trip_overlay_marker_lines` and `frame_reports_off_viewport_marker_in_marker_lines`
// lived here until v16 removed the group they covered (#490). What they asserted — that an
// off-viewport marker is still reachable — is now `Engine::marker_index`'s, and
// `marker_index.rs` owns it.
use justerm_core::{
    Cell, CellFlags, Color, Engine, Frame, FrameKind, MarkerId, MarkerKind, MarkerPosition,
    MouseEvents, Overlay, ScrollOp, SelectionSpan, SelectionType, Side, Span, decode, encode,
};
use std::collections::BTreeMap;

/// Tracer bullet: an empty Partial frame (header only, no scroll, no spans)
/// round-trips. Proves the frame envelope encodes and decodes end-to-end.
#[test]
fn round_trip_empty_partial_frame() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #108: the overlay section round-trips both groups — selection spans and
/// search-match spans — as viewport `(row, left, right)` triples. Positions
/// only (no colour); the consumer resolves highlight colour.
#[test]
fn round_trip_overlay_selection_and_match_spans() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay {
            selection: vec![
                SelectionSpan {
                    row: 0,
                    left: 2,
                    right: 7,
                },
                SelectionSpan {
                    row: 1,
                    left: 0,
                    right: 4,
                },
            ],
            matches: vec![SelectionSpan {
                row: 3,
                left: 10,
                right: 12,
            }],
            markers: vec![],
            active_match: vec![],
        },
    };
    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #428 (wire v12): the fifth overlay group — the consumer-designated ACTIVE
/// search match's spans — round-trips as `(row, left, right)` triples appended
/// after the marker-lines group. The active member also stays in `matches`
/// (ranking, not exclusion, resolves the overlap downstream), so both groups
/// carry it here.
#[test]
fn round_trip_overlay_active_match_spans() {
    let mut frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    // A wrapped active match: two spans, both also present in the match group.
    let active = vec![
        SelectionSpan {
            row: 2,
            left: 5,
            right: 9,
        },
        SelectionSpan {
            row: 3,
            left: 0,
            right: 1,
        },
    ];
    frame.overlay.matches = active.clone();
    frame.overlay.active_match = active;
    let bytes = encode(&frame);
    let decoded = decode(&bytes).expect("decode");
    assert_eq!(decoded, frame);
    // Explicit side condition: the two groups decode independently (an encoder
    // that dropped the fifth group would still satisfy a matches-only check).
    assert_eq!(decoded.overlay.active_match, decoded.overlay.matches);
    assert_eq!(decoded.overlay.active_match.len(), 2);
}

/// Every non-default header/overlay field at once round-trips — scroll op +
/// mouse mask + selection + marker together — so a new field (the v8 mask byte
/// between `scrollback_len` and the scroll op) cannot corrupt the layout when
/// the others are present. Driven through the engine, not a hand-built literal.
#[test]
fn round_trip_full_frame_all_fields_present() {
    let mut term = Engine::with_scrollback(20, 3, 100);
    term.feed(b"L0\r\nL1\r\nL2\r\nL3\r\nL4"); // scrollback + a scroll op
    term.feed(b"\x1b[?1002h"); // mouse mask = DOWN|UP|WHEEL|DRAG
    term.selection_begin(0, 0, Side::Left, SelectionType::Char);
    term.selection_extend(0, 2, Side::Right);
    term.add_marker(1);

    let frame = term.frame();
    assert!(frame.scroll.is_some() && !frame.mouse_events.is_empty());
    assert!(!frame.overlay.selection.is_empty() && !frame.overlay.markers.is_empty());

    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #129: the mouse wanted-events mask round-trips in the header (a flag byte,
/// like the cursor scalars).
#[test]
fn round_trip_mouse_events_mask() {
    let mut frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: MouseEvents::empty(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    frame.mouse_events = MouseEvents::DOWN | MouseEvents::UP | MouseEvents::WHEEL;
    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #149: the alt-screen flag round-trips through the header (one byte beside the
/// mouse mask), so a frame-mode consumer reads the same primary/alt state the
/// engine holds.
#[test]
fn round_trip_alt_screen_flag() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: MouseEvents::empty(),
        alt_screen: true,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    let decoded = decode(&encode(&frame)).expect("decode");
    assert!(decoded.alt_screen);
    assert_eq!(decoded, frame);
}

/// #118: the overlay's third group — marker positions — round-trips as
/// `(marker_id, row)` pairs (a different record shape from the span groups).
#[test]
fn round_trip_overlay_marker_positions() {
    let mut frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    frame.overlay.markers = vec![
        MarkerPosition {
            id: MarkerId(5),
            row: 3,
            kind: MarkerKind::Plain,
        },
        MarkerPosition {
            id: MarkerId(99),
            row: 0,
            kind: MarkerKind::Plain,
        },
    ];
    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #159 (wire v10): a marker's kind + optional exit code (OSC 133 command marks)
/// survive the wire. Every `MarkerKind` variant round-trips — including
/// `CommandFinished`'s `Some`/`None` exit — extending the v7 `(id, row)` record
/// with a kind discriminant + a presence-gated `i32` exit.
#[test]
fn round_trip_overlay_marker_kinds() {
    let mut frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    frame.overlay.markers = vec![
        MarkerPosition {
            id: MarkerId(1),
            row: 0,
            kind: MarkerKind::Plain,
        },
        MarkerPosition {
            id: MarkerId(2),
            row: 1,
            kind: MarkerKind::PromptStart,
        },
        MarkerPosition {
            id: MarkerId(3),
            row: 2,
            kind: MarkerKind::CommandStart,
        },
        MarkerPosition {
            id: MarkerId(4),
            row: 3,
            kind: MarkerKind::OutputStart,
        },
        MarkerPosition {
            id: MarkerId(5),
            row: 4,
            kind: MarkerKind::CommandFinished(Some(130)),
        },
        MarkerPosition {
            id: MarkerId(6),
            row: 5,
            kind: MarkerKind::CommandFinished(None),
        },
    ];
    let bytes = encode(&frame);
    assert_eq!(decode(&bytes).expect("decode"), frame);
}

/// #159 hostile input: the marker decoder rejects an unknown kind discriminant
/// with an error (not a silent misread that swallows the next record's bytes),
/// and a truncated `CommandFinished` exit errors rather than panicking — the
/// error paths the decode-safety audit exercised, pinned as permanent coverage.
#[test]
fn decode_rejects_bad_marker_kind_and_truncated_exit() {
    let mut frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Overlay::default(),
    };
    frame.overlay.markers = vec![MarkerPosition {
        id: MarkerId(1),
        row: 0,
        kind: MarkerKind::CommandFinished(Some(7)),
    }];
    let bytes = encode(&frame);
    // With every prior section empty, the tail is the marker group `count(2)` + record
    // `id(4) row(2) kind(1) present(1) exit(4)`, then the v12 active-match group
    // `count(4)` (0 here).
    //
    // Two widths meet here and the offsets are not symmetric: the viewport-projected
    // overlay groups widened their counts to 4 bytes in v14 (#621) while the marker
    // group deliberately did not. **v16 removed the marker-lines group that used to sit
    // between them** (#490), so everything below moved 2 bytes closer to the end.
    // Counting back: active-match count 4, exit 4, present 1 — the kind byte is 10 from
    // the end and the exit occupies [len-8, len-4).
    let mut bad_kind = bytes.clone();
    let k = bad_kind.len() - 10;
    bad_kind[k] = 5; // unknown discriminant (valid kinds are 0..=4)
    assert!(
        decode(&bad_kind).is_err(),
        "an unknown marker kind must be rejected, not misread"
    );

    let mut truncated = bytes.clone();
    // Drop the tail group count (4 since v14, #621; the 2-byte marker-lines count that
    // also sat here is gone in v16) and two bytes into the i32 exit — the point is to
    // land *inside* the exit, not merely before it.
    truncated.truncate(truncated.len() - 6);
    assert!(
        decode(&truncated).is_err(),
        "a truncated exit must error, not panic"
    );
}

/// Scroll position (display_offset + scrollback_len) survives the wire round-trip
/// (#112 / ADR-0013, wire v5). It rides in the header like the cursor, for the
/// consumer's scrollbar.
#[test]
fn round_trip_scroll_position() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 7,
        scrollback_len: 250,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    let decoded = decode(&encode(&frame)).expect("decode");
    assert_eq!(decoded.display_offset, 7);
    assert_eq!(decoded.scrollback_len, 250);
    assert_eq!(decoded, frame);
}

/// Cursor position + visibility survive the wire round-trip (#38). The cursor
/// moves with almost every frame, so it rides in the frame header alongside
/// `cols`/`rows` rather than in a span.
#[test]
fn round_trip_cursor_position_and_visibility() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 9,
        cursor_col: 19,
        cursor_visible: false,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// A Partial frame with one span of plain ASCII cells round-trips — exercises
/// the fixed-width cell record and span bodies.
#[test]
fn round_trip_span_of_plain_cells() {
    let cells: Vec<Cell> = "hi!"
        .chars()
        .map(|c| Cell::from_parts(c, Color::Default, Color::Default, CellFlags::empty()))
        .collect();
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![Span {
            line: 3,
            left: 10,
            right: 12,
            cells,
            combining: BTreeMap::new(),
            links: BTreeMap::new(),
            ucolors: BTreeMap::new(),
        }],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// All three colour references round-trip and stay distinct — the format's
/// mandatory tag keeps `Default`, `Indexed(0)` and `Rgb(0,0,0)` from collapsing.
#[test]
fn round_trip_distinct_colour_references() {
    let mk = |fg, bg| Cell::from_parts('x', fg, bg, CellFlags::empty());
    let cells = vec![
        mk(Color::Default, Color::Default),
        mk(Color::Indexed(0), Color::Indexed(255)),
        mk(Color::Rgb(0, 0, 0), Color::Rgb(1, 2, 3)),
    ];
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![Span {
            line: 0,
            left: 0,
            right: 2,
            cells,
            combining: BTreeMap::new(),
            links: BTreeMap::new(),
            ucolors: BTreeMap::new(),
        }],
        link_table: vec![],
        overlay: Default::default(),
    };
    let d = decode(&encode(&frame)).expect("decode");
    assert_eq!(d, frame);
    let row = &d.spans[0].cells;
    assert_ne!(
        row[0].fg(),
        row[1].fg(),
        "Default must differ from Indexed(0)"
    );
    assert_ne!(
        row[1].fg(),
        row[2].fg(),
        "Indexed(0) must differ from Rgb(0,0,0)"
    );
}

/// SGR attributes *and* layout markers (wide-char lead + spacer) survive the
/// `flags` field — the consumer needs both halves of a wide glyph to render it.
#[test]
fn round_trip_cell_flags_incl_layout_markers() {
    let lead = Cell::from_parts(
        '한',
        Color::Default,
        Color::Default,
        CellFlags::BOLD | CellFlags::WIDE_CHAR,
    );
    let spacer = Cell::from_parts(
        ' ',
        Color::Default,
        Color::Default,
        CellFlags::WIDE_CHAR_SPACER,
    );
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![Span {
            line: 5,
            left: 0,
            right: 1,
            cells: vec![lead, spacer],
            combining: BTreeMap::new(),
            links: BTreeMap::new(),
            ucolors: BTreeMap::new(),
        }],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// Decode rejects malformed input instead of panicking — a consumer feeds bytes
/// straight off a transport, so the error path is part of the contract.
#[test]
fn decode_rejects_malformed_input() {
    assert!(decode(&[]).is_err(), "empty");
    assert!(decode(b"XXxxxxxxx").is_err(), "bad magic");
    assert!(decode(b"JT").is_err(), "truncated mid-header");
}

/// A buffer from a superseded wire version fails loudly with `BadVersion`,
/// never a silent misparse — a consumer pinned to the old encoder is rejected
/// at the version gate (#38 bumped `VERSION` 2 -> 3).
#[test]
fn decode_rejects_superseded_version() {
    let frame = Frame {
        cols: 1,
        rows: 1,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    let mut bytes = encode(&frame);
    bytes[2] = 2; // the VERSION byte sits right after the 2-byte magic
    assert!(matches!(
        decode(&bytes),
        Err(justerm_core::DecodeError::BadVersion(2))
    ));
}

/// The wire is gated at version 14 (#621 moved the grapheme and hyperlink references
/// off the cell record into sparse per-span groups and widened their counts/lengths
/// to u32, atop the #520 per-span underline-colour group, the #428 active-match
/// group, #120 S3 marker-lines, #159 marker kind + exit, #149 alt-screen flag, #129
/// mouse mask and #118 marker group). Both the exported `WIRE_VERSION` constant and
/// the byte the encoder emits must read 14 — the value the WASM decoder's
/// `wire_version()` mirrors in lockstep (ADR-0008), so a drift here trips before it
/// can desync a binding.
#[test]
fn wire_version_is_sixteen() {
    assert_eq!(justerm_core::WIRE_VERSION, 16);
    let mut term = Engine::new(1, 1);
    term.feed(b"x");
    let bytes = encode(&term.frame());
    assert_eq!(bytes[2], justerm_core::WIRE_VERSION); // VERSION byte after magic
}

/// A combining-mark cluster round-trips: the cell carries only its combining bit,
/// the frame-local index rides on the span's `combining` map, and the code points
/// live in `side_table`.
#[test]
fn round_trip_grapheme_side_table() {
    let mut accented = Cell::from_parts('e', Color::Default, Color::Default, CellFlags::empty());
    accented.set_combined(true);
    let plain = Cell::from_parts('x', Color::Default, Color::Default, CellFlags::empty());
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![Span {
            line: 0,
            left: 0,
            right: 1,
            cells: vec![accented, plain],
            // The cluster sits at its column, not behind an index into a table
            // (v14, #621) — combining acute accent.
            combining: BTreeMap::from([(0, vec!['\u{0301}'])]),
            links: BTreeMap::new(),
            ucolors: BTreeMap::new(),
        }],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// Acceptance #2: cells stay fixed-width — each added cell costs exactly 14
/// bytes, so a grapheme or linked cell is no wider than a plain one (the cluster
/// and the URI reference ride sparse per-span groups). Measured as the per-cell
/// delta, independent of header size.
///
/// It was 18 until v14 (#621): the record also carried `extra` and `link`, two u16
/// references that no frame without a cluster or a hyperlink had any use for. The
/// number here is the *fixed* part of the trade — a cell that carries neither now
/// pays 4 bytes less, measured at −20.9% on an ordinary 80×24 frame — while the two
/// cells that do carry one pay for it in their own group.
#[test]
fn cell_record_is_fixed_14_bytes() {
    let span_of = |n: usize| Frame {
        cols: 1,
        rows: 1,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![Span {
            line: 0,
            left: 0,
            right: (n - 1) as u16,
            cells: vec![Cell::default(); n],
            combining: BTreeMap::new(),
            links: BTreeMap::new(),
            ucolors: BTreeMap::new(),
        }],
        link_table: vec![],
        overlay: Default::default(),
    };
    let one = encode(&span_of(1)).len();
    let two = encode(&span_of(2)).len();
    assert_eq!(two - one, 14, "each added cell must cost exactly 14 bytes");
    assert_eq!(
        two - one,
        justerm_core::CELL_RECORD_LEN,
        "the measured stride and the exported constant are the same number — an \
         alternate consumer lays cells out by that constant (ADR-0008), so the two \
         drifting apart is the failure this pins",
    );
}

/// A recorded scroll op round-trips. It is encoded ahead of the spans so the
/// decoder shifts rows before applying column damage (ADR-0003).
#[test]
fn round_trip_scroll_op() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: Some(ScrollOp {
            top: 0,
            bottom: 23,
            count: 3,
        }),
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// A `Full` frame round-trips its kind (resize / alt-clear redraw-everything).
#[test]
fn round_trip_full_frame_kind() {
    let frame = Frame {
        cols: 40,
        rows: 12,
        kind: FrameKind::Full,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

// ===========================================================================
// Engine -> Frame producer (#6 next slice): build a Frame from live engine
// state (damage + grid + grapheme pool), remapping the global side-table to
// frame-local indices.
// ===========================================================================

/// Tracer: a fresh engine fed "hi" produces a Partial frame whose line-0 spans
/// carry the written cells.
#[test]
fn engine_frame_captures_written_cells() {
    let mut term = Engine::new(5, 2);
    term.feed(b"hi");
    let f = term.frame();
    assert_eq!((f.cols, f.rows), (5, 2));
    assert_eq!(f.kind, FrameKind::Partial);
    let chars: String = f
        .spans
        .iter()
        .filter(|s| s.line == 0)
        .flat_map(|s| s.cells.iter().map(|c| c.c()))
        .collect();
    assert!(chars.contains('h') && chars.contains('i'), "got {chars:?}");
}

/// The frame reports the live cursor position (#38). The engine only exposes
/// where the cursor is; *drawing* it stays the consumer's renderer adapter.
#[test]
fn engine_frame_reports_cursor_position() {
    let mut term = Engine::new(80, 24);
    term.feed(b"\x1b[10;20H"); // CUP to row 10, col 20 (1-based) -> (9, 19)
    let f = term.frame();
    assert_eq!((f.cursor_row, f.cursor_col), (9, 19));
    assert!(f.cursor_visible, "cursor is visible by default");
}

/// Cursor visibility follows DECTCEM (`?25l` hides, `?25h` shows) — the frame
/// reflects the engine's hide/show so the consumer can stop drawing the caret.
#[test]
fn engine_frame_reports_cursor_visibility_via_dectcem() {
    let mut term = Engine::new(80, 24);
    term.feed(b"\x1b[?25l"); // DECTCEM hide
    assert!(!term.frame().cursor_visible, "hidden after ?25l");
    term.feed(b"\x1b[?25h"); // DECTCEM show
    assert!(term.frame().cursor_visible, "visible again after ?25h");
}

/// DECTCEM visibility is a standalone mode, *not* part of the alt-screen
/// (`?1049`) cursor save/restore — matches xterm/alacritty, where `?25` is a
/// Term mode never carried by the alt grid swap. So hiding the cursor *on* the
/// alt screen persists after leaving it, and showing it persists too. (#38: the
/// alt path used to restore the whole saved `Cursor` incl. `visible`, wrongly
/// resurrecting / re-hiding the caret.)
#[test]
fn engine_cursor_visibility_is_independent_of_alt_screen() {
    // Hide on alt → stays hidden after leaving.
    let mut term = Engine::new(80, 24);
    term.feed(b"\x1b[?1049h\x1b[?25l\x1b[?1049l");
    assert!(
        !term.frame().cursor_visible,
        "?25l on alt must persist after ?1049l"
    );

    // Hidden before alt, shown on alt → stays shown after leaving.
    let mut term = Engine::new(80, 24);
    term.feed(b"\x1b[?25l\x1b[?1049h\x1b[?25h\x1b[?1049l");
    assert!(
        term.frame().cursor_visible,
        "?25h on alt must persist after ?1049l"
    );
}

/// Interaction (cursor × resize): shrinking the screen below the cursor's old
/// position must not panic when the next frame folds cursor-move damage, and the
/// reported cursor is clamped into the new bounds. (#38 adversarial)
#[test]
fn engine_frame_cursor_survives_resize_shrink() {
    let mut term = Engine::new(80, 24);
    term.feed(b"\x1b[20;70H"); // cursor to (19, 69)
    term.reset_damage(); // prev_cursor = (19, 69)
    term.resize(10, 5); // shrink well below the old cursor
    let f = term.frame(); // must not panic
    assert!(
        f.cursor_row < 5 && f.cursor_col < 10,
        "cursor clamped to new bounds, got ({}, {})",
        f.cursor_row,
        f.cursor_col
    );
}

/// The recorded scroll op reaches the frame (content scrolled off the top).
#[test]
fn engine_frame_carries_scroll_op() {
    let mut term = Engine::new(5, 2);
    term.feed(b"x\r\ny\r\nz"); // 3 lines into a 2-row screen -> one scroll
    assert!(term.frame().scroll.is_some());
}

/// After a resize the frame is Full and ships every row at the new dimensions.
#[test]
fn engine_frame_is_full_after_resize() {
    let mut term = Engine::new(5, 2);
    term.feed(b"hi");
    term.resize(6, 3);
    let f = term.frame();
    assert_eq!(f.kind, FrameKind::Full);
    assert_eq!((f.cols, f.rows), (6, 3));
    assert_eq!(f.spans.len(), 3, "Full ships every row");
}

/// Trap #2: a frame ships only *live* clusters. Overwriting a combined cell clears
/// its bit, so its (now stale) row-map entry is never gathered — only the surviving
/// combined cell contributes a cluster.
///
/// The claim is unchanged by v14 (#621); only where the cluster sits is. It used to
/// be asserted through a frame-local index into `Frame::side_table`; now the cluster
/// is *at* its column, so the test reads it directly. That is strictly the stronger
/// assertion: the old form could pass with the right index pointing at the wrong
/// table entry, and this one names the characters.
#[test]
fn engine_frame_ships_only_live_combining_clusters() {
    let mut term = Engine::new(5, 1);
    term.feed("e\u{0301}".as_bytes()); // col0 'e' + acute -> combined
    term.feed(b"\rx"); // CR to col0, overwrite 'e' with 'x' -> col0 bit cleared
    term.feed("o\u{0308}".as_bytes()); // col1 'o' + diaeresis -> combined
    let f = term.frame();
    // Exactly one span column carries combining, and it is the 'o'. The overwritten
    // 'e' contributes nothing — a second entry here would be the stale row-map read.
    let carried: Vec<_> = f
        .spans
        .iter()
        .flat_map(|s| s.combining.iter().map(move |(&col, c)| (s, col, c)))
        .collect();
    assert_eq!(carried.len(), 1, "only the live cluster ships");
    let (span, col, cluster) = &carried[0];
    assert_eq!(*cluster, &vec!['\u{0308}'], "the diaeresis, not the acute");
    assert_eq!(span.cells[*col].c(), 'o');
    assert!(span.cells[*col].is_combined());
}

/// Integration: feed colours + a wide glyph + a combining mark, then the live
/// engine's frame survives a full encode/decode round-trip.
#[test]
fn engine_frame_round_trips_through_bytes() {
    let mut term = Engine::new(8, 1);
    term.feed("\x1b[31m한e\u{0301}".as_bytes());
    let f = term.frame();
    assert_eq!(decode(&encode(&f)).expect("decode"), f);
}

/// Integration on real captured streams (the #20 dogfood fixtures): after
/// replaying a real app, the live engine's frame round-trips through the wire
/// format — exercising colours, wide glyphs, scroll, and full-screen content.
#[test]
fn engine_frame_round_trips_real_captures() {
    for raw in [
        include_bytes!("fixtures/vim_redraw.raw").as_slice(),
        include_bytes!("fixtures/top.raw").as_slice(),
        include_bytes!("fixtures/htop.raw").as_slice(),
    ] {
        let mut term = Engine::new(80, 24);
        term.feed(raw);
        let f = term.frame();
        assert_eq!(
            decode(&encode(&f)).expect("decode"),
            f,
            "real-capture round-trip"
        );
    }
}

/// #661 — the same round-trip over a long run of ordinary output. `ScrollOp::count`
/// is `isize` in memory and `i16` on the wire, and the accumulator had no cap, so
/// the engine could build a frame that does not survive its own encode: measured
/// before the fix, a **single 32 770-byte `feed()` of newlines** (32 768 net
/// scrolls — no ack starvation required) encoded `32768` as `-32768`, and 40 000
/// newlines encoded `39998` as `-25538`. A `Partial` frame, so the renderer's
/// "a Full frame ignores `scroll`" exemption does not cover it either.
///
/// The three tests above are the property this broke; this one is the input class
/// they structurally cannot reach, since each of them scrolls a handful of times.
#[test]
fn engine_frame_with_a_long_scroll_run_round_trips() {
    let mut term = Engine::new(80, 24);
    term.reset_damage();
    term.feed(&vec![b'\n'; 40_000]);
    let f = term.frame();

    // Or the test passes for the wrong reason — a frame carrying no scroll op at
    // all round-trips trivially.
    let op = f.scroll.expect("the run must still report a scroll op");
    assert_eq!((op.top, op.bottom), (0, 23));

    assert_eq!(decode(&encode(&f)).expect("decode"), f);
}

/// The representational half of the same cap (#661): a count sitting exactly on the
/// wire's `i16` bound, in a region taller than that bound, survives the round-trip.
/// `MAX_ROWS` is `u16::MAX`, so such a region is legal and capping at its *height*
/// alone would not have been enough.
///
/// Hand-built rather than engine-driven on purpose. Reaching this through `Engine`
/// costs ~10⁹ element moves (a 40 000-row `line_damage` rotated 32 768 times —
/// measured at 15.8 s in a debug build), and it would be testing the same clamp
/// twice: `term.rs`'s `cap_scroll` unit tests own the bound, `tests/damage.rs` owns
/// `scroll_delta` applying it, and this owns the byte that carries the result.
#[test]
fn a_scroll_count_at_the_wire_bound_round_trips() {
    let frame = Frame {
        cols: 4,
        rows: 40_000,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: Some(ScrollOp {
            top: 0,
            bottom: 39_999,
            count: i16::MAX as isize,
        }),
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);

    // The negative bound is the half the defect actually produced — a wrapped count
    // arrived as a *down*-scroll — so assert it rather than assuming symmetry.
    let down = Frame {
        scroll: Some(ScrollOp {
            top: 0,
            bottom: 39_999,
            count: -(i16::MAX as isize),
        }),
        ..frame
    };
    assert_eq!(decode(&encode(&down)).expect("decode"), down);
}

/// The same round-trip over the two axes the corpus above structurally cannot
/// contain: OSC 8 hyperlinks and combining clusters (#621,
/// `fixtures/capture-hyperlink.sh`).
///
/// Measured before these fixtures existed: replaying **all ten** checked-in
/// captures at 80×24 yielded `combining cells 0, linked cells 0, link_table 0`
/// — every one of them. So the test above was green through the entire v13→v14
/// wire change while asserting nothing about it. The cause is structural, not
/// an oversight in what was recorded: the corpus is full-screen TUIs, and a TUI
/// emits neither. (Same shape as #554, one axis over.)
///
/// The round trip is the witness *and the char grid is not*: a combining mark is
/// not in the grid at all — the grid holds the base codepoint and the marks live
/// in the row's side map — so a char-grid golden is blind to exactly what this
/// capture is for. `Frame` equality compares the combining and link maps and the
/// presence bits `decode` re-arms, which is what #621 moved.
#[test]
fn engine_frame_round_trips_hyperlink_and_combining_captures() {
    let mut term = Engine::new(80, 24);
    term.feed(include_bytes!("fixtures/hyperlink_combining.raw"));
    let f = term.frame();

    // The capture must still carry the material, or this test quietly becomes the
    // one it was written to replace. Counted, not assumed.
    let linked: usize = f.spans.iter().map(|s| s.links.len()).sum();
    let combining: usize = f.spans.iter().map(|s| s.combining.len()).sum();
    assert!(linked > 0 && combining > 0, "capture lost its material");
    assert!(
        f.link_table.len() < linked,
        "one URI is deliberately repeated across cells and rows, so the interned \
         table must be strictly smaller than the linked-cell count — this ratio is \
         what makes the capture able to tell the two candidate wire shapes apart",
    );
    // The combination neither axis reaches alone: a column keyed in *both* sparse
    // groups. They are keyed the same way, so this is where their keying can
    // disagree, and no single-feature fixture produces it.
    assert!(
        f.spans
            .iter()
            .any(|s| s.links.keys().any(|c| s.combining.contains_key(c))),
        "capture must carry a cell that is both linked and combining",
    );
    assert_eq!(decode(&encode(&f)).expect("decode"), f);

    // And the real application's own bytes, so the shape is not only one the
    // capture script believes in.
    let mut term = Engine::new(80, 24);
    term.feed(include_bytes!("fixtures/ls_hyperlink.raw"));
    let f = term.frame();
    assert!(
        f.spans.iter().map(|s| s.links.len()).sum::<usize>() > 0,
        "real `ls --hyperlink` capture lost its links",
    );
    assert_eq!(decode(&encode(&f)).expect("decode"), f);
}

/// A `cols`×`rows` v16 header with no scroll op, followed by a one-span count and that
/// span's `(line, left, right)` triple — the shortest buffer that reaches the span
/// validation. Nothing follows it: every case below is rejected at the triple, before a
/// single cell record is read, so the absent payload is never reached.
///
/// **Both fixtures that used to build this by hand had rotted twice over**, and the two
/// rots hid each other. The version byte was a literal `1`, so from v2 onward `decode`
/// bailed at `BadVersion`; and the field list stopped after `rows`, so even with the
/// version fixed the reader ran out of bytes 15 header bytes early and answered
/// `Truncated`. Both were invisible because the assertion was `is_err()`. Written once,
/// here, and asserted against an *exact* error at each call site — a header field added
/// later fails these loudly instead of quietly re-pointing them at a different guard.
fn header_with_one_span(cols: u16, rows: u16, line: u16, left: u16, right: u16) -> Vec<u8> {
    let mut b = Vec::new();
    b.extend_from_slice(b"JT"); // magic
    b.push(justerm_core::WIRE_VERSION); // version — never a literal
    b.push(0); // has_scroll
    b.push(1); // kind = Partial
    b.extend_from_slice(&cols.to_le_bytes());
    b.extend_from_slice(&rows.to_le_bytes());
    b.extend_from_slice(&0u16.to_le_bytes()); // cursor_row
    b.extend_from_slice(&0u16.to_le_bytes()); // cursor_col
    b.push(1); // cursor_visible
    b.push(0); // cursor_shape = Block
    b.push(0); // cursor_blink
    b.extend_from_slice(&0u32.to_le_bytes()); // display_offset
    b.extend_from_slice(&0u32.to_le_bytes()); // scrollback_len
    b.extend_from_slice(&0u64.to_le_bytes()); // evicted_total (v15, #490)
    b.extend_from_slice(&0u32.to_le_bytes()); // marker_epoch (v15, #490)
    b.extend_from_slice(&0u32.to_le_bytes()); // marker_count (v16, #490)
    b.push(0); // mouse_events
    b.push(0); // alt_screen
    b.extend_from_slice(&1u16.to_le_bytes()); // span count
    b.extend_from_slice(&line.to_le_bytes());
    b.extend_from_slice(&left.to_le_bytes());
    b.extend_from_slice(&right.to_le_bytes());
    b
}

/// A crafted frame whose span has left > right must be a clean error, not a
/// u16-underflow panic — decode consumes untrusted bytes off a transport.
#[test]
fn decode_rejects_span_with_left_past_right() {
    let b = header_with_one_span(80, 24, 0, 5, 0); // left = 5, right = 0
    assert_eq!(
        decode(&b),
        Err(justerm_core::DecodeError::BadSpan),
        "left>right must error, not panic"
    );
}

/// The two axes #582 added, on the same shortest buffer: a span reaching past the
/// declared width, and a span sitting past the declared height. Neither carries a cell
/// payload, which is the point — the frame is rejected on its own header, not on length.
#[test]
fn decode_rejects_a_span_outside_the_declared_geometry() {
    assert_eq!(
        decode(&header_with_one_span(4, 2, 0, 0, 8)),
        Err(justerm_core::DecodeError::BadSpan),
        "right = 8 past cols = 4"
    );
    assert_eq!(
        decode(&header_with_one_span(80, 2, 99, 0, 3)),
        Err(justerm_core::DecodeError::BadSpan),
        "line = 99 past rows = 2"
    );
    // The boundary on both axes is exclusive, and a valid span must still get past it —
    // otherwise the two asserts above would also pass with an off-by-one that rejects
    // everything.
    assert_eq!(
        decode(&header_with_one_span(4, 2, 1, 0, 3)),
        Err(justerm_core::DecodeError::Truncated),
        "the last legal span of the frame is accepted, then runs out of cells"
    );
}

/// A span with `left=0, right=65535` is a valid `right >= left`, but the run length
/// `right - left + 1` overflows `u16` (65535 + 1) — a panic under overflow checks, found
/// by `cargo fuzz run serialize` (#33).
///
/// **The version byte must be `WIRE_VERSION`, not a literal, and this test is why.** It
/// pushed a literal `1`, so from the first bump onward `decode` bailed at
/// `BadVersion` and the span parser was never reached: the assertion was `is_err()`, which
/// a header rejection satisfies just as well as the defect it was written for. It had been
/// vacuous for twelve wire versions. `robustness.rs` records the identical rot in its
/// generator, caught at v10 by #159; this is the same failure in a hand-built fixture, and
/// the same repair.
///
/// Restored, it now pins the *ordering* rather than the overflow: since #582 the bounds
/// check runs first, so `right = 65535` against `cols = 80` is `BadSpan` and the widening
/// below it is unreachable — kept as the cheaper of the two guarantees, not as the live
/// one. Asserting the exact error is what makes the difference visible; `is_err()` is what
/// let this test rot in the first place.
#[test]
fn decode_rejects_span_length_u16_overflow() {
    let b = header_with_one_span(80, 24, 0, 0, 65535); // right = 65535 -> len overflows u16
    assert_eq!(
        decode(&b),
        Err(justerm_core::DecodeError::BadSpan),
        "a span past the frame's own width is rejected before its length is computed"
    );
}

/// A Full frame carrying real cells (not just the kind flag) round-trips.
#[test]
fn round_trip_full_frame_with_cells() {
    let row = |line| Span {
        line,
        left: 0,
        right: 2,
        cells: "abc"
            .chars()
            .map(|c| Cell::from_parts(c, Color::Default, Color::Default, CellFlags::empty()))
            .collect(),
        combining: BTreeMap::new(),
        links: BTreeMap::new(),
        ucolors: BTreeMap::new(),
    };
    let frame = Frame {
        cols: 3,
        rows: 2,
        kind: FrameKind::Full,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: None,
        spans: vec![row(0), row(1)],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// A downward scroll (negative count, e.g. RI at the top margin) round-trips —
/// the count is signed on the wire.
#[test]
fn round_trip_negative_scroll_count() {
    let frame = Frame {
        cols: 80,
        rows: 24,
        kind: FrameKind::Partial,
        cursor_row: 0,
        cursor_col: 0,
        cursor_visible: true,
        cursor_shape: justerm_core::CursorShape::Block,
        cursor_blink: false,
        display_offset: 0,
        scrollback_len: 0,
        evicted_total: 0,
        marker_epoch: 0,
        marker_count: 0,
        mouse_events: Default::default(),
        alt_screen: false,
        scroll: Some(ScrollOp {
            top: 2,
            bottom: 23,
            count: -4,
        }),
        spans: vec![],
        link_table: vec![],
        overlay: Default::default(),
    };
    assert_eq!(decode(&encode(&frame)).expect("decode"), frame);
}

/// Trap #6: with nothing damaged since the ack, the engine yields an *empty
/// Partial* frame (0 spans, no scroll) — not Full and not "no frame" — so the
/// consumer can ack without redrawing.
#[test]
fn engine_frame_undamaged_is_empty_partial_not_full() {
    let mut term = Engine::new(5, 2);
    term.feed(b"hi");
    term.reset_damage(); // consumer applied + ack'd the frame
    let f = term.frame();
    assert_eq!(f.kind, FrameKind::Partial);
    assert!(f.spans.is_empty(), "no damage since ack -> no spans");
    assert!(f.scroll.is_none());
}