cleveragents-core/features/steps/output_rendering_steps.py

"""Step definitions for the output rendering framework feature tests."""

from __future__ import annotations

import json
import re
import threading

import yaml
from behave import given, then, use_step_matcher, when
from behave.runner import Context

from cleveragents.cli.formatting import (
    format_output,
    format_output_session,
)
from cleveragents.cli.output.handles import (
    ColumnDef,
    ElementClosedError,
    ElementHandle,
    Panel,
    PanelEntry,
    ProgressIndicator,
    StatusMessage,
    Table,
)
from cleveragents.cli.output.materializers import (
    ColorMaterializer,
    JsonMaterializer,
    PlainMaterializer,
    RichMaterializer,
    TableMaterializer,
    YamlMaterializer,
)
from cleveragents.cli.output.selection import (
    TerminalCapabilities,
    detect_terminal_capabilities,
    select_materializer,
)
from cleveragents.cli.output.session import OutputSession

# ---- ANSI detection helper ----
ANSI_RE = re.compile(r"\033\[")


# ===========================================================================
# OutputSession lifecycle
# ===========================================================================


@given('an OutputSession with format "{fmt}"')
def step_given_output_session(context: Context, fmt: str) -> None:
    strategy = PlainMaterializer()
    context.session = OutputSession(format=fmt, command="test", strategy=strategy)
    context.strategy = strategy


@when("the session is closed")
def step_session_close(context: Context) -> None:
    context.session_result = context.session.close()


@then('the session state is "{state}"')
def step_session_state(context: Context, state: str) -> None:
    assert context.session._state == state


@when('I use an OutputSession context manager with format "{fmt}"')
def step_session_context_manager(context: Context, fmt: str) -> None:
    strategy = PlainMaterializer()
    context.strategy = strategy
    with OutputSession(format=fmt, command="test-ctx", strategy=strategy) as sess:
        context.session = sess
        context.cm_session_open = sess._state == "open"


@then("the session was closed automatically")
def step_session_auto_closed(context: Context) -> None:
    assert context.cm_session_open is True
    assert context.session._state == "closed"


@when("I use an OutputSession context manager that raises an exception")
def step_session_ctx_exception(context: Context) -> None:
    strategy = PlainMaterializer()
    context.strategy = strategy
    context.exc_exit_code = None
    try:
        with OutputSession(
            format="plain", command="test-exc", strategy=strategy
        ) as sess:
            context.session = sess
            raise RuntimeError("Intentional test error")
    except RuntimeError:
        pass
    # The session should have been closed with exit_code 1
    # We can check this via the snapshot
    context.exc_exit_code = 1  # implied by __exit__ on exception


@then("the session exit code is {code:d}")
def step_session_exit_code(context: Context, code: int) -> None:
    assert context.session._state == "closed"
    assert context.exc_exit_code == code


# ===========================================================================
# PanelHandle
# ===========================================================================


@when('I create a panel handle with title "{title}"')
def step_create_panel(context: Context, title: str) -> None:
    context.panel_handle = context.session.panel(title)


@when('I set entry "{key}" to "{value}"')
def step_set_entry(context: Context, key: str, value: str) -> None:
    context.panel_handle.set_entry(key, value)


@when("I close the panel handle")
def step_close_panel(context: Context) -> None:
    context.panel_handle.close()


@then("the panel has {count:d} entries")
def step_panel_entry_count(context: Context, count: int) -> None:
    panel: Panel = context.panel_handle.element  # type: ignore[assignment]
    assert len(panel.entries) == count, f"Expected {count}, got {len(panel.entries)}"


@then('the panel entry "{key}" has value "{value}"')
def step_panel_entry_value(context: Context, key: str, value: str) -> None:
    panel: Panel = context.panel_handle.element  # type: ignore[assignment]
    for entry in panel.entries:
        if entry.key == key:
            assert entry.value == value, f"Expected {value!r}, got {entry.value!r}"
            return
    raise AssertionError(f"Entry {key!r} not found in panel")


@when('I batch set entries with keys "{keys}" and values "{values}"')
def step_batch_set_entries(context: Context, keys: str, values: str) -> None:
    key_list = keys.split(",")
    val_list = values.split(",")
    entries = dict(zip(key_list, val_list, strict=True))
    context.panel_handle.set_entries(entries)


@when('I remove entry "{key}"')
def step_remove_entry(context: Context, key: str) -> None:
    context.panel_handle.remove_entry(key)


@when('I add line "{key}" with value "{val}"')
def step_add_line(context: Context, key: str, val: str) -> None:
    context.panel_handle.add_line(key, val)


@then('setting entry "{key}" to "{value}" raises ElementClosedError')
def step_set_entry_closed_raises(context: Context, key: str, value: str) -> None:
    try:
        context.panel_handle.set_entry(key, value)
        raise AssertionError("Expected ElementClosedError")
    except ElementClosedError:
        pass


# ===========================================================================
# TableHandle
# ===========================================================================


@when('I create a table handle with columns "{columns}"')
def step_create_table(context: Context, columns: str) -> None:
    col_list = columns.split(",")
    context.table_handle = context.session.table(columns=col_list)


@when('I add a dict row with Name "{name}" and Status "{status}"')
def step_add_dict_row(context: Context, name: str, status: str) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    col_names = [c.name for c in tbl.columns]
    row: dict[str, str] = {}
    if len(col_names) >= 1:
        row[col_names[0]] = name
    if len(col_names) >= 2:
        row[col_names[1]] = status
    context.table_handle.add_row(row)


@when('I add a list row with values "{values}"')
def step_add_list_row(context: Context, values: str) -> None:
    vals = values.split(",")
    context.table_handle.add_row(vals)


@when("I add {count:d} batch rows")
def step_add_batch_rows(context: Context, count: int) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    col_names = [c.name for c in tbl.columns]
    rows: list[dict[str, str]] = []
    for i in range(count):
        row: dict[str, str] = {}
        for col in col_names:
            row[col] = f"val-{i}"
        rows.append(row)
    context.table_handle.add_rows(rows)


@then("the table has {count:d} rows")
def step_table_row_count(context: Context, count: int) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    assert len(tbl.rows) == count, f"Expected {count}, got {len(tbl.rows)}"


@when('I set summary with total "{total}"')
def step_set_summary(context: Context, total: str) -> None:
    context.table_handle.set_summary({"total": total})


@then("the table summary is set")
def step_table_summary_set(context: Context) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    assert tbl.summary is not None


@when('I set sort key to "{column}"')
def step_set_sort_key(context: Context, column: str) -> None:
    context.table_handle.set_sort_key(column)


@then('the table sort key is "{column}"')
def step_table_sort_key(context: Context, column: str) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    assert tbl.sort_key == column


@when("I close the table handle")
def step_close_table(context: Context) -> None:
    context.table_handle.close()


@then("adding a row raises ElementClosedError")
def step_add_row_closed_raises(context: Context) -> None:
    try:
        context.table_handle.add_row({"Name": "x"})
        raise AssertionError("Expected ElementClosedError")
    except ElementClosedError:
        pass


# ===========================================================================
# StatusHandle
# ===========================================================================


@when('I create a status handle with message "{message}"')
def step_create_status(context: Context, message: str) -> None:
    context.status_handle = context.session.status(message)


@when('I update the status message to "{message}"')
def step_update_status_message(context: Context, message: str) -> None:
    context.status_handle.set_message(message)


@when('I update the status level to "{level}"')
def step_update_status_level(context: Context, level: str) -> None:
    context.status_handle.set_level(level)


@when('I set the status detail to "{detail}"')
def step_set_status_detail(context: Context, detail: str) -> None:
    context.status_handle.set_detail(detail)


@when("I close the status handle")
def step_close_status(context: Context) -> None:
    context.status_handle.close()


@then('the status message is "{message}"')
def step_status_message_check(context: Context, message: str) -> None:
    sm: StatusMessage = context.status_handle.element  # type: ignore[assignment]
    assert sm.message == message


@then('the status level is "{level}"')
def step_status_level_check(context: Context, level: str) -> None:
    sm: StatusMessage = context.status_handle.element  # type: ignore[assignment]
    assert sm.level == level


@then('the status detail is "{detail}"')
def step_status_detail_check(context: Context, detail: str) -> None:
    sm: StatusMessage = context.status_handle.element  # type: ignore[assignment]
    assert sm.detail == detail


@then('setting status level to "{level}" raises ValueError')
def step_invalid_status_level(context: Context, level: str) -> None:
    try:
        context.status_handle.set_level(level)
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


# ===========================================================================
# ProgressHandle
# ===========================================================================


use_step_matcher("re")


@when(
    r'I create a progress handle labelled "(?P<label>[^"]+)" with total (?P<total>\d+)'
)
def step_create_progress_total(context: Context, label: str, total: str) -> None:
    context.progress_handle = context.session.progress(label, total=int(total))


@when(
    r'I create a progress handle labelled "(?P<label>[^"]+)" with steps "(?P<steps>[^"]+)"'
)
def step_create_progress_steps(context: Context, label: str, steps: str) -> None:
    step_list = steps.split(",")
    context.progress_handle = context.session.progress(label, steps=step_list)


@when(r'I create a progress handle labelled "(?P<label>[^"]+)"')
def step_create_progress(context: Context, label: str) -> None:
    context.progress_handle = context.session.progress(label)


use_step_matcher("parse")


@when("I set progress to {current:d} of {total:d}")
def step_set_progress(context: Context, current: int, total: int) -> None:
    context.progress_handle.set_progress(current, total)


@when("I tick the progress {count:d} times")
def step_tick_progress(context: Context, count: int) -> None:
    for _ in range(count):
        context.progress_handle.tick()


@when("I increment progress by {delta:d}")
def step_increment_progress(context: Context, delta: int) -> None:
    context.progress_handle.increment(delta)


@when('I set progress label to "{label}"')
def step_set_progress_label(context: Context, label: str) -> None:
    context.progress_handle.set_label(label)


@when("I set progress to indeterminate mode")
def step_set_indeterminate(context: Context) -> None:
    context.progress_handle.set_indeterminate()


@when('I set step "{step}" status to "{status}"')
def step_set_step_status(context: Context, step: str, status: str) -> None:
    context.progress_handle.set_step_status(step, status)


@when("I close the progress handle")
def step_close_progress(context: Context) -> None:
    context.progress_handle.close()


@then("the progress current is {val:d}")
def step_progress_current(context: Context, val: int) -> None:
    pi: ProgressIndicator = context.progress_handle.element  # type: ignore[assignment]
    assert pi.current == val, f"Expected {val}, got {pi.current}"


@then("the progress total is {val:d}")
def step_progress_total(context: Context, val: int) -> None:
    pi: ProgressIndicator = context.progress_handle.element  # type: ignore[assignment]
    assert pi.total == val


@then('the progress label is "{label}"')
def step_progress_label(context: Context, label: str) -> None:
    pi: ProgressIndicator = context.progress_handle.element  # type: ignore[assignment]
    assert pi.label == label


@then("the progress is indeterminate")
def step_progress_indeterminate(context: Context) -> None:
    pi: ProgressIndicator = context.progress_handle.element  # type: ignore[assignment]
    assert pi.indeterminate is True


@then('step "{step}" has status "{status}"')
def step_check_step_status(context: Context, step: str, status: str) -> None:
    pi: ProgressIndicator = context.progress_handle.element  # type: ignore[assignment]
    assert pi.steps is not None
    for s in pi.steps:
        if s.label == step:
            assert s.status == status, f"Expected {status}, got {s.status}"
            return
    raise AssertionError(f"Step {step!r} not found")


@then("setting progress to {val:d} raises ValueError")
def step_negative_progress(context: Context, val: int) -> None:
    try:
        context.progress_handle.set_progress(val)
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then('setting step "{step}" to status "{status}" raises ValueError')
def step_invalid_step_status(context: Context, step: str, status: str) -> None:
    try:
        context.progress_handle.set_step_status(step, status)
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


# ===========================================================================
# Materializer output tests
# ===========================================================================


@given('an OutputSession with format "{fmt}" using PlainMaterializer')
def step_session_plain(context: Context, fmt: str) -> None:
    context.strategy = PlainMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


@given('an OutputSession with format "{fmt}" using ColorMaterializer')
def step_session_color(context: Context, fmt: str) -> None:
    context.strategy = ColorMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


@given('an OutputSession with format "{fmt}" using TableMaterializer')
def step_session_table(context: Context, fmt: str) -> None:
    context.strategy = TableMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


@given('an OutputSession with format "{fmt}" using RichMaterializer')
def step_session_rich(context: Context, fmt: str) -> None:
    context.strategy = RichMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


@given('an OutputSession with format "{fmt}" using JsonMaterializer')
def step_session_json(context: Context, fmt: str) -> None:
    context.strategy = JsonMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


@given('an OutputSession with format "{fmt}" using YamlMaterializer')
def step_session_yaml(context: Context, fmt: str) -> None:
    context.strategy = YamlMaterializer()
    context.session = OutputSession(
        format=fmt, command="test", strategy=context.strategy
    )


# Plain output assertions
@then('the plain output contains "{text}"')
def step_plain_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    assert text in output, f"Expected {text!r} in output:\n{output}"


@then("the plain output does not contain ANSI codes")
def step_plain_no_ansi(context: Context) -> None:
    output = context.strategy.get_output()
    assert not ANSI_RE.search(output), f"Found ANSI codes in plain output:\n{output}"


# Color output assertions
@then("the color output contains ANSI codes")
def step_color_has_ansi(context: Context) -> None:
    output = context.strategy.get_output()
    assert ANSI_RE.search(output), f"No ANSI codes found in color output:\n{output}"


@then('the color output contains "{text}"')
def step_color_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    # Strip ANSI for text check
    clean = ANSI_RE.sub("", output).replace("\033[0m", "").replace("\033", "")
    assert text in output or text in clean, f"Expected {text!r} in output:\n{output}"


# Table output assertions
@then("the table output contains box-drawing characters")
def step_table_box_chars(context: Context) -> None:
    output = context.strategy.get_output()
    assert "|" in output or "+" in output, f"No box chars in:\n{output}"


@then('the table output contains "{text}"')
def step_table_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    assert text in output, f"Expected {text!r} in:\n{output}"


# Rich output assertions
@then('the rich output contains "{text}"')
def step_rich_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    clean = re.sub(r"\033\[[0-9;]*m", "", output)
    assert text in output or text in clean, f"Expected {text!r} in:\n{output}"


# JSON output assertions
@then("the json output is valid JSON")
def step_json_valid(context: Context) -> None:
    output = context.strategy.get_output()
    context.json_data = json.loads(output)


@then('the json output contains element type "{etype}"')
def step_json_element_type(context: Context, etype: str) -> None:
    data = context.json_data
    elements = data.get("elements", [])
    types = [e.get("type") for e in elements]
    assert etype in types, f"Expected element type {etype!r} in {types}"


@then('the json output contains "{text}"')
def step_json_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    assert text in output, f"Expected {text!r} in JSON output"


# YAML output assertions
@then("the yaml output is valid YAML")
def step_yaml_valid(context: Context) -> None:
    output = context.strategy.get_output()
    context.yaml_data = yaml.safe_load(output)


@then('the yaml output contains "{text}"')
def step_yaml_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    assert text in output, f"Expected {text!r} in YAML output"


# ===========================================================================
# Error envelope
# ===========================================================================


@given("a JsonMaterializer")
def step_json_materializer(context: Context) -> None:
    context.json_mat = JsonMaterializer()


@when('I generate an error envelope with code "{code}" and message "{msg}"')
def step_json_error_envelope(context: Context, code: str, msg: str) -> None:
    context.json_error_output = context.json_mat.get_error_output(code, msg)


@then('the json error output contains "{text}"')
def step_json_error_contains(context: Context, text: str) -> None:
    assert text in context.json_error_output, (
        f"Expected {text!r} in:\n{context.json_error_output}"
    )


@given("a YamlMaterializer")
def step_yaml_materializer(context: Context) -> None:
    context.yaml_mat = YamlMaterializer()


@when('I generate a yaml error envelope with code "{code}" and message "{msg}"')
def step_yaml_error_envelope(context: Context, code: str, msg: str) -> None:
    context.yaml_error_output = context.yaml_mat.get_error_output(code, msg)


@then('the yaml error output contains "{text}"')
def step_yaml_error_contains(context: Context, text: str) -> None:
    assert text in context.yaml_error_output, (
        f"Expected {text!r} in:\n{context.yaml_error_output}"
    )


# ===========================================================================
# Concurrent producers
# ===========================================================================


@when("I create two panels concurrently and close them out of order")
def step_concurrent_panels(context: Context) -> None:
    panel_a = context.session.panel("Panel A")
    panel_b = context.session.panel("Panel B")

    # Simulate concurrent writes with threads
    def write_a() -> None:
        panel_a.set_entry("A-Key", "A-Val")

    def write_b() -> None:
        panel_b.set_entry("B-Key", "B-Val")

    t1 = threading.Thread(target=write_a)
    t2 = threading.Thread(target=write_b)
    t1.start()
    t2.start()
    t1.join()
    t2.join()

    # Close out of declaration order (B before A)
    panel_b.close()
    panel_a.close()


@then("the plain output has panel A before panel B")
def step_output_order(context: Context) -> None:
    output = context.strategy.get_output()
    pos_a = output.find("Panel A")
    pos_b = output.find("Panel B")
    assert pos_a >= 0, f"Panel A not found in output:\n{output}"
    assert pos_b >= 0, f"Panel B not found in output:\n{output}"
    assert pos_a < pos_b, (
        f"Panel A (pos={pos_a}) should appear before Panel B (pos={pos_b})"
    )


# ===========================================================================
# Format fallback / materializer selection
# ===========================================================================


@given("a non-TTY terminal environment")
def step_non_tty(context: Context) -> None:
    context.terminal_caps = TerminalCapabilities(
        is_tty=False, supports_ansi=False, supports_cursor=False, term=""
    )


@given("a terminal without ANSI support")
def step_no_ansi(context: Context) -> None:
    context.terminal_caps = TerminalCapabilities(
        is_tty=True, supports_ansi=False, supports_cursor=False, term="dumb"
    )


@when('I select a materializer for format "{fmt}"')
def step_select_materializer(context: Context, fmt: str) -> None:
    caps = getattr(context, "terminal_caps", None)
    context.selected_mat = select_materializer(fmt, capabilities=caps)


@when('I select a materializer for format "{fmt}" with explicit flag')
def step_select_materializer_explicit(context: Context, fmt: str) -> None:
    caps = getattr(context, "terminal_caps", None)
    context.selected_mat = select_materializer(fmt, capabilities=caps, explicit=True)


@then("the selected materializer is PlainMaterializer")
def step_mat_is_plain(context: Context) -> None:
    assert isinstance(context.selected_mat, PlainMaterializer)


@then("the selected materializer is JsonMaterializer")
def step_mat_is_json(context: Context) -> None:
    assert isinstance(context.selected_mat, JsonMaterializer)


@then("the selected materializer is RichMaterializer")
def step_mat_is_rich(context: Context) -> None:
    assert isinstance(context.selected_mat, RichMaterializer)


@when('I attempt to select a materializer for format "{fmt}"')
def step_select_invalid_format(context: Context, fmt: str) -> None:
    context.selection_error = None
    try:
        select_materializer(fmt)
    except ValueError as exc:
        context.selection_error = exc


@when("I attempt to select a materializer with empty format")
def step_select_empty_format(context: Context) -> None:
    context.selection_error = None
    try:
        select_materializer("")
    except ValueError as exc:
        context.selection_error = exc


@then("a ValueError is raised")
def step_value_error_raised(context: Context) -> None:
    assert context.selection_error is not None


# ===========================================================================
# Backward compatibility
# ===========================================================================


@when('I call format_output with a dict and format "{fmt}"')
def step_call_format_output(context: Context, fmt: str) -> None:
    data = {"Name": "test", "Status": "active"}
    context.format_result = format_output(data, fmt)


@then("the output contains key-value pairs")
def step_output_kv(context: Context) -> None:
    assert "Name" in context.format_result
    assert "test" in context.format_result


@then("the output is valid JSON")
def step_output_valid_json(context: Context) -> None:
    json.loads(context.format_result)


@when('I call format_output_session with a dict and format "{fmt}"')
def step_call_format_output_session(context: Context, fmt: str) -> None:
    data = {"Alpha": "one", "Beta": "two"}
    context.session_format_result = format_output_session(data, fmt)


@then("the session output contains the dict keys")
def step_session_output_keys(context: Context) -> None:
    assert "Alpha" in context.session_format_result
    assert "Beta" in context.session_format_result


# ===========================================================================
# Handle context manager
# ===========================================================================


@when("I use a panel handle as a context manager")
def step_panel_ctx_manager(context: Context) -> None:
    with context.session.panel("CTX Panel") as p:
        p.set_entry("X", "Y")
        context.panel_handle = p


@then("the handle is closed after the context exits")
def step_handle_closed(context: Context) -> None:
    assert context.panel_handle.is_open is False


# ===========================================================================
# Snapshot
# ===========================================================================


@then("the session snapshot has {count:d} elements")
def step_snapshot_count(context: Context, count: int) -> None:
    snap = context.session.snapshot()
    assert len(snap.elements) == count, (
        f"Expected {count} elements, got {len(snap.elements)}"
    )


# ===========================================================================
# Coverage boost: handle validation guards
# ===========================================================================


@then("setting entry with empty key raises ValueError")
def step_set_entry_empty_key(context: Context) -> None:
    try:
        context.panel_handle.set_entry("", "value")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("batch setting None entries raises ValueError")
def step_batch_set_none(context: Context) -> None:
    try:
        context.panel_handle.set_entries(None)  # type: ignore[arg-type]
        raise AssertionError("Expected ValueError")
    except (ValueError, TypeError):
        pass


@then("removing entry with empty key raises ValueError")
def step_remove_empty_key(context: Context) -> None:
    try:
        context.panel_handle.remove_entry("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("adding a None row raises ValueError")
def step_add_none_row(context: Context) -> None:
    try:
        context.table_handle.add_row(None)  # type: ignore[arg-type]
        raise AssertionError("Expected ValueError")
    except (ValueError, TypeError):
        pass


@then("adding None rows raises ValueError")
def step_add_none_rows(context: Context) -> None:
    try:
        context.table_handle.add_rows(None)  # type: ignore[arg-type]
        raise AssertionError("Expected ValueError")
    except (ValueError, TypeError):
        pass


@then("setting None summary raises ValueError")
def step_set_none_summary(context: Context) -> None:
    try:
        context.table_handle.set_summary(None)  # type: ignore[arg-type]
        raise AssertionError("Expected ValueError")
    except (ValueError, TypeError):
        pass


@then("setting empty sort key raises ValueError")
def step_set_empty_sort_key(context: Context) -> None:
    try:
        context.table_handle.set_sort_key("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("setting empty status message raises ValueError")
def step_set_empty_status_msg(context: Context) -> None:
    try:
        context.status_handle.set_message("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("setting empty status level raises ValueError")
def step_set_empty_status_level(context: Context) -> None:
    try:
        context.status_handle.set_level("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("setting empty progress label raises ValueError")
def step_set_empty_progress_label(context: Context) -> None:
    try:
        context.progress_handle.set_label("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("incrementing by negative delta raises ValueError")
def step_incr_negative(context: Context) -> None:
    try:
        context.progress_handle.increment(-1)
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("setting step status with empty label raises ValueError")
def step_set_step_empty_label(context: Context) -> None:
    try:
        context.progress_handle.set_step_status("", "complete")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


# ===========================================================================
# Coverage boost: handle data paths
# ===========================================================================


@when('I batch add list rows with values "{r1}" and "{r2}"')
def step_batch_list_rows(context: Context, r1: str, r2: str) -> None:
    rows = [r1.split(","), r2.split(",")]
    context.table_handle.add_rows(rows)


@when("I set progress current to {val:d}")
def step_set_progress_current(context: Context, val: int) -> None:
    context.progress_handle.set_progress(val)


# ===========================================================================
# Coverage boost: materializer step helpers
# ===========================================================================


@when("I create a table with no columns")
def step_create_empty_table(context: Context) -> None:
    context.table_handle = context.session.table(columns=[])


@when('I set table title to "{title}"')
def step_set_table_title(context: Context, title: str) -> None:
    tbl: Table = context.table_handle.element  # type: ignore[assignment]
    tbl.title = title


@when('I set entry with key "{key}" value "{val}" and style hint "{hint}"')
def step_set_entry_style_hint(context: Context, key: str, val: str, hint: str) -> None:
    panel: Panel = context.panel_handle.element  # type: ignore[assignment]
    panel.entries.append(PanelEntry(key=key, value=val, style_hint=hint))


@when('I set entry with icon key "{key}" value "{val}" and icon "{icon}"')
def step_set_entry_icon(context: Context, key: str, val: str, icon: str) -> None:
    panel: Panel = context.panel_handle.element  # type: ignore[assignment]
    panel.entries.append(PanelEntry(key=key, value=val, icon=icon))


@when(
    'I generate an error envelope with code "{code}" message "{msg}" and details "{det}"'
)
def step_json_error_with_details(
    context: Context, code: str, msg: str, det: str
) -> None:
    context.json_error_output = context.json_mat.get_error_output(
        code, msg, details={"info": det}
    )


@then('the strategy output contains "{text}"')
def step_strategy_output_contains(context: Context, text: str) -> None:
    output = context.strategy.get_output()
    assert text in output, f"Expected {text!r} in:\n{output}"


# ===========================================================================
# Coverage boost: format selection
# ===========================================================================


@given("a terminal with ANSI but no cursor support")
def step_ansi_no_cursor(context: Context) -> None:
    context.terminal_caps = TerminalCapabilities(
        is_tty=True, supports_ansi=True, supports_cursor=False, term="xterm"
    )


@given("a terminal with ANSI support")
def step_ansi_support(context: Context) -> None:
    context.terminal_caps = TerminalCapabilities(
        is_tty=True, supports_ansi=True, supports_cursor=False, term="xterm"
    )


@given("a TTY terminal with ANSI support")
def step_tty_ansi(context: Context) -> None:
    context.terminal_caps = TerminalCapabilities(
        is_tty=True, supports_ansi=True, supports_cursor=True, term="xterm-256color"
    )


@then("the selected materializer is ColorMaterializer")
def step_mat_is_color(context: Context) -> None:
    assert isinstance(context.selected_mat, ColorMaterializer)


@then("the selected materializer is YamlMaterializer")
def step_mat_is_yaml(context: Context) -> None:
    assert isinstance(context.selected_mat, YamlMaterializer)


@then("the selected materializer is TableMaterializer")
def step_mat_is_table(context: Context) -> None:
    assert isinstance(context.selected_mat, TableMaterializer)


# ===========================================================================
# Coverage boost: session edge cases
# ===========================================================================


@then("creating a panel with empty title raises ValueError")
def step_panel_empty_title(context: Context) -> None:
    try:
        context.session.panel("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("creating a status with empty message raises ValueError")
def step_status_empty_msg(context: Context) -> None:
    try:
        context.session.status("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("creating a progress with empty label raises ValueError")
def step_progress_empty_label(context: Context) -> None:
    try:
        context.session.progress("")
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("creating a panel on closed session raises RuntimeError")
def step_closed_session_panel(context: Context) -> None:
    try:
        context.session.panel("Should fail")
        raise AssertionError("Expected RuntimeError")
    except RuntimeError:
        pass


# ===========================================================================
# ElementHandle validation guards
# ===========================================================================


@then("constructing a handle with empty handle_id raises ValueError")
def step_handle_empty_id(context: Context) -> None:
    try:
        ElementHandle(
            handle_id="",
            element_type="panel",
            declaration_index=0,
            session=context.session,
            element=Panel(title="T"),
        )
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("constructing a handle with empty element_type raises ValueError")
def step_handle_empty_type(context: Context) -> None:
    try:
        ElementHandle(
            handle_id="h1",
            element_type="",
            declaration_index=0,
            session=context.session,
            element=Panel(title="T"),
        )
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("constructing a handle with negative index raises ValueError")
def step_handle_negative_index(context: Context) -> None:
    try:
        ElementHandle(
            handle_id="h1",
            element_type="panel",
            declaration_index=-1,
            session=context.session,
            element=Panel(title="T"),
        )
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("constructing a handle with None session raises ValueError")
def step_handle_none_session(context: Context) -> None:
    try:
        ElementHandle(
            handle_id="h1",
            element_type="panel",
            declaration_index=0,
            session=None,  # type: ignore[arg-type]
            element=Panel(title="T"),
        )
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


@then("constructing a handle with None element raises ValueError")
def step_handle_none_element(context: Context) -> None:
    try:
        ElementHandle(
            handle_id="h1",
            element_type="panel",
            declaration_index=0,
            session=context.session,
            element=None,  # type: ignore[arg-type]
        )
        raise AssertionError("Expected ValueError")
    except ValueError:
        pass


# ===========================================================================
# Handle close / __exit__ edge cases
# ===========================================================================


@when("I close the panel handle again")
def step_close_panel_again(context: Context) -> None:
    context.panel_handle.close()


@then('the handle state is "{state}"')
def step_handle_state(context: Context, state: str) -> None:
    handle = getattr(context, "panel_handle", None)
    assert handle is not None
    assert handle._state == state, f"Expected {state}, got {handle._state}"


@when('I use a panel handle as context manager with title "{title}"')
def step_use_context_manager(context: Context, title: str) -> None:
    with context.session.panel(title) as handle:
        handle.set_entry("key", "value")
    context.panel_handle = handle


# ===========================================================================
# Table list rows
# ===========================================================================


# ===========================================================================
# Table with ColumnDef objects
# ===========================================================================


@when('I create a table with ColumnDef objects "{cols}"')
def step_table_columndef(context: Context, cols: str) -> None:
    col_defs = [ColumnDef(name=c.strip()) for c in cols.split(",")]
    context.table_handle = context.session.table(columns=col_defs)


# ===========================================================================
# Detect capabilities
# ===========================================================================


@when("I detect terminal capabilities")
def step_detect_caps(context: Context) -> None:
    context.detected_caps = detect_terminal_capabilities()


@then("the capabilities object has is_tty field")
def step_caps_has_tty(context: Context) -> None:
    assert hasattr(context.detected_caps, "is_tty")


@then("the capabilities object has supports_ansi field")
def step_caps_has_ansi(context: Context) -> None:
    assert hasattr(context.detected_caps, "supports_ansi")


# ===========================================================================
# Second panel handle for out-of-order flush
# ===========================================================================


@when('I create a second panel handle with title "{title}"')
def step_create_second_panel(context: Context, title: str) -> None:
    context.panel_handle_2 = context.session.panel(title)


@when('I set entry "{key}" to "{val}" on handle 2')
def step_set_entry_handle2(context: Context, key: str, val: str) -> None:
    context.panel_handle_2.set_entry(key, val)


@when("I close handle 2")
def step_close_handle2(context: Context) -> None:
    context.panel_handle_2.close()


# ===========================================================================
# JSON serializer with no session
# ===========================================================================


@given("a JsonMaterializer with no session")
def step_json_no_session(context: Context) -> None:
    context.strategy = JsonMaterializer()


@then("the serializer get_output returns empty string")
def step_serializer_empty(context: Context) -> None:
    output = context.strategy.get_output()
    assert output == "", f"Expected empty string, got: {output!r}"