path: root/app/tests/test_tui.py

"""Tests for the DOS-style curses TUI widgets in tui.py.

The widget module imports curses lazily, so these tests swap the
curses module for a small fake (patched into sys.modules) and drive
the widgets with scripted keys against a recording screen. That works
without a terminal and lets the tests assert exact drawing
coordinates: theme colors, the left margin of list rows, and that no
row ever paints over the dialog border.
"""

import sys
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch

from ui import tui


class FakeCurses:
    """Minimal curses stand-in: attributes, key codes, color pairs."""

    A_BOLD = 1
    A_DIM = 2
    A_REVERSE = 4

    COLOR_BLACK = 0
    COLOR_RED = 1
    COLOR_GREEN = 2
    COLOR_YELLOW = 3
    COLOR_BLUE = 4
    COLOR_MAGENTA = 5
    COLOR_CYAN = 6
    COLOR_WHITE = 7

    KEY_DOWN = 0x101
    KEY_UP = 0x102
    KEY_LEFT = 0x103
    KEY_RIGHT = 0x104
    KEY_HOME = 0x105
    KEY_END = 0x106
    KEY_PPAGE = 0x107
    KEY_NPAGE = 0x108
    KEY_BACKSPACE = 0x109
    KEY_BTAB = 0x10A

    ACS_ULCORNER = "ul"
    ACS_URCORNER = "ur"
    ACS_LLCORNER = "ll"
    ACS_LRCORNER = "lr"
    ACS_VLINE = "v"
    ACS_HLINE = "h"
    ACS_RARROW = "ra"

    class error(Exception):
        pass

    def __init__(self):
        self.pairs = {}  # pair number -> (fg, bg)
        self.colors = True
        self.COLORS = 256

    def has_colors(self):
        return self.colors

    def start_color(self):
        pass

    def init_pair(self, number, fg, bg):
        self.pairs[number] = (fg, bg)

    def color_pair(self, number):
        return number << 8

    def curs_set(self, visibility):
        pass

    def endwin(self):
        pass


class FakeScreen:
    """Recording curses window; getch() replays scripted keys."""

    def __init__(self, keys=(), width=80, height=24):
        self.keys = list(keys)
        self.width = width
        self.height = height
        self.strings = []  # (y, x, text, attr) from addstr
        self.chars = []    # (y, x, ch, attr) from addch
        self.timeouts = []  # ms values passed to timeout()

    def timeout(self, ms):
        self.timeouts.append(ms)

    def getmaxyx(self):
        return self.height, self.width

    def erase(self):
        pass

    def refresh(self):
        pass

    def bkgd(self, ch, attr):
        pass

    def addstr(self, y, x, text, attr=0):
        self.strings.append((y, x, text, attr))

    def addch(self, y, x, ch, attr=0):
        self.chars.append((y, x, ch, attr))

    def hline(self, y, x, ch, n, attr=0):
        pass

    def redrawwin(self):
        pass

    def getch(self):
        if not self.keys:
            raise AssertionError("the script ran out of keys")
        return self.keys.pop(0)


class TuiTestCase(unittest.TestCase):
    """Base class: fresh theme + fake curses module for every test."""

    def setUp(self):
        tui._THEME.clear()
        self.curses = FakeCurses()
        self.screen = FakeScreen()
        patcher = patch.dict(sys.modules, {"curses": self.curses})
        patcher.start()
        self.addCleanup(patcher.stop)
        self.addCleanup(tui._THEME.clear)

    def dialog_box(self, screen=None):
        """(x0, x_right) border columns of the drawn dialog."""
        screen = screen or self.screen
        corners = screen.chars[:2]
        self.assertEqual(corners[0][2], FakeCurses.ACS_ULCORNER)
        self.assertEqual(corners[1][2], FakeCurses.ACS_URCORNER)
        return corners[0][1], corners[1][1]

    def assert_inside_border(self, screen=None):
        """No drawn string may reach the right border column."""
        screen = screen or self.screen
        _, x_right = self.dialog_box(screen)
        for _, x, text, _ in screen.strings:
            self.assertLessEqual(
                x + len(text), x_right,
                f"{text!r} painted over the border at x={x}")


class ThemeTests(TuiTestCase):
    def test_desktop_and_message_backgrounds_are_black(self):
        frame = tui.Frame(self.screen, "Title", "footer")
        theme, pairs = frame.theme, self.curses.pairs
        for name in ("desktop", "border", "title", "ok", "warn", "err",
                     "info", "input", "check", "accent"):
            fg, bg = pairs[theme[name] >> 8]
            self.assertEqual(bg, FakeCurses.COLOR_BLACK, name)

    def test_cursor_bar_and_active_button_stand_out(self):
        frame = tui.Frame(self.screen, "Title", "footer")
        theme, pairs = frame.theme, self.curses.pairs
        fg, bg = pairs[theme["bar"] >> 8]
        self.assertEqual((fg, bg),
                         (FakeCurses.COLOR_BLACK, FakeCurses.COLOR_CYAN))
        fg, bg = pairs[theme["btn_on"] >> 8]
        self.assertEqual((fg, bg),
                         (FakeCurses.COLOR_BLACK, FakeCurses.COLOR_GREEN))

    def test_inactive_button_is_white_on_dark_gray(self):
        frame = tui.Frame(self.screen, "Title", "footer")
        theme, pairs = frame.theme, self.curses.pairs
        fg, bg = pairs[theme["btn_off"] >> 8]
        self.assertEqual((fg, bg),
                         (FakeCurses.COLOR_WHITE, 236))
        self.assertFalse(theme["btn_off"] & FakeCurses.A_BOLD)

    def test_without_colors_theme_uses_plain_attributes(self):
        self.curses.colors = False
        frame = tui.Frame(self.screen, "Title", "footer")
        self.assertEqual(self.curses.pairs, {})
        self.assertEqual(frame.theme["desktop"], 0)
        self.assertEqual(frame.theme["title"], FakeCurses.A_BOLD)


class MenuTests(TuiTestCase):
    OPTIONS = [("first option", "one"), ("second option", "two")]

    def test_option_rows_left_justified_help_centered(self):
        screen = FakeScreen(keys=[10])
        value = tui.menu(screen, "Pick one", self.OPTIONS,
                         help_lines=["Help text"])
        self.assertEqual(value, "one")
        x0, x_right = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        for label in ("first option", "second option"):
            x = next(x for _, x, text, _ in screen.strings if text == label)
            self.assertEqual(x, margin, label)
        inner_w = x_right - x0 - 1
        help_x = next(x for _, x, text, _ in screen.strings
                      if text == "Help text")
        self.assertEqual(help_x, x0 + 1 + (inner_w - len("Help text")) // 2)
        self.assertGreater(help_x, margin)
        self.assert_inside_border(screen)

    def test_blank_line_below_the_title(self):
        # A titled dialog reserves a blank line between the title row
        # and the first body row.
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Pick", self.OPTIONS)
        title_y = next(y for y, _, text, _ in screen.strings
                       if text == " Pick ")
        first_y = next(y for y, _, text, _ in screen.strings
                       if text == "first option")
        self.assertEqual(first_y, title_y + 2)

    def test_up_wraps_around_to_last_option(self):
        screen = FakeScreen(keys=[FakeCurses.KEY_UP, 10])
        value = tui.menu(screen, "Pick one", self.OPTIONS)
        self.assertEqual(value, "two")

    def test_no_option_painted_over_the_border(self):
        screen = FakeScreen(keys=[FakeCurses.KEY_END, 10])
        tui.menu(screen, "Pick", [("a" * 60, "a"), ("b", "b")])
        self.assert_inside_border(screen)

    def test_empty_options_rejected(self):
        with self.assertRaises(ValueError):
            tui.menu(self.screen, "Pick", [])

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.menu(screen, "Pick", self.OPTIONS, back_value=marker),
            marker)

    def test_q_returns_back_value_like_esc(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.menu(screen, "Pick", self.OPTIONS, back_value=marker),
            marker)

    def test_q_aborts_without_back_value(self):
        screen = FakeScreen(keys=[ord("q")])
        with self.assertRaises(tui.WizardCancelled):
            tui.menu(screen, "Pick", self.OPTIONS)

    def test_separator_is_blank_and_skipped_by_cursor(self):
        options = [("build", "build"), tui.MENU_SEPARATOR,
                   ("quit", "quit")]
        # Down from the first option must skip the blank divider and land on
        # the third option (Enter returns its value, not the separator's).
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, 10])
        self.assertEqual(tui.menu(screen, "Pick", options), "quit")

    def test_separator_alone_is_rejected(self):
        with self.assertRaises(ValueError):
            tui.menu(self.screen, "Pick", [tui.MENU_SEPARATOR])

    def test_suffix_renders_in_its_theme_color(self):
        # default_index=1 keeps the suffixed option unselected, so its
        # segments keep their own colors instead of the cursor bar.
        options = [("Build audio.cpp Server", "build",
                    ("[recommended]", "warn")), ("other", "other")]
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Pick", options, default_index=1)
        text = "  [recommended]"
        attr = next(a for _, _, drawn, a in screen.strings
                    if drawn == text)
        self.assertEqual(attr, tui._THEME["warn"])
        label_attr = next(a for _, _, drawn, a in screen.strings
                          if drawn == "Build audio.cpp Server")
        self.assertEqual(label_attr, tui._THEME["body"])

    def test_selected_row_has_arrow_in_the_margin(self):
        # The highlighted option gets an ACS_RARROW in the blank margin
        # left of its text; unselected rows draw none.
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Pick", self.OPTIONS)
        x0, _ = self.dialog_box(screen)
        arrow_x = x0 + 1 + tui.Frame.LIST_MARGIN - 2
        arrows = [(y, x) for y, x, ch, _ in screen.chars
                  if ch == FakeCurses.ACS_RARROW]
        y_first = next(y for y, _, text, _ in screen.strings
                       if text == "first option")
        self.assertEqual(arrows, [(y_first, arrow_x)])

    def test_arrow_follows_the_cursor(self):
        # Down moves the arrow onto the second option on the redraw.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, 10])
        tui.menu(screen, "Pick", self.OPTIONS)
        x0, _ = self.dialog_box(screen)
        arrow_x = x0 + 1 + tui.Frame.LIST_MARGIN - 2
        arrows = [y for y, x, ch, _ in screen.chars
                  if ch == FakeCurses.ACS_RARROW and x == arrow_x]
        y_first = next(y for y, _, text, _ in screen.strings
                       if text == "first option")
        y_second = next(y for y, _, text, _ in screen.strings
                        if text == "second option")
        self.assertEqual(arrows, [y_first, y_second])

    def test_corner_indicator_counts_highlighted_options(self):
        # The corner " n/n " names the highlighted option, not the
        # first visible line: with the list still scrolled to the top,
        # two Downs must read 2/20 then 3/20 (the old label stayed at
        # 1/<total lines> until entries scrolled off-screen).
        options = [(f"option {i}", i) for i in range(20)]
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  10])
        value = tui.menu(screen, "Pick one", options,
                         help_lines=["Help text"])
        self.assertEqual(value, 2)
        labels = [text for _, _, text, _ in screen.strings
                  if text in (" 1/20 ", " 2/20 ", " 3/20 ")]
        self.assertEqual(labels, [" 1/20 ", " 2/20 ", " 3/20 "])


class MenuTableTests(TuiTestCase):
    """The optional status table: aligned columns and colored statuses."""

    ROWS = [("audio.cpp", "not installed", "err"),
            ("qwen-tts", "installed", "warn"),
            ("faster-qwen3-tts", "running", "ok")]

    def test_name_column_left_aligned_at_margin(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        x0, _ = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        for name, _, _ in self.ROWS:
            x = next(x for _, x, text, _ in screen.strings
                     if text.rstrip() == name)
            self.assertEqual(x, margin, name)

    def test_status_column_aligned_at_one_fixed_offset(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        x0, _ = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        name_w = max(len(name) for name, _, _ in self.ROWS)
        expected_x = margin + name_w  # the "  status" segment starts here
        for _, status, _ in self.ROWS:
            x = next(x for _, x, text, _ in screen.strings
                     if text.strip() == status)
            self.assertEqual(x, expected_x, status)

    def test_status_text_uses_the_theme_kind_color(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        want = {"err": tui._THEME["err"], "warn": tui._THEME["warn"],
                "ok": tui._THEME["ok"]}
        for _, status, kind in self.ROWS:
            attr = next(a for _, _, text, a in screen.strings
                        if text.strip() == status)
            self.assertEqual(attr, want[kind], status)

    def test_optional_name_kind_colors_the_name_column(self):
        # 4-element rows: the 4th value is a theme kind for the name.
        rows = [("gone", "unavailable", "err", "dim"),
                ("here", "running", "ok", "body")]
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")], table_rows=rows)
        drawn = {text.rstrip(): attr for _, _, text, attr in screen.strings}
        self.assertEqual(drawn["gone"], tui._THEME["dim"])
        self.assertEqual(drawn["here"], tui._THEME["body"])

    def test_three_element_rows_default_to_body_names(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        for name, _, _ in self.ROWS:
            attr = next(a for _, _, text, a in screen.strings
                        if text.rstrip() == name)
            self.assertEqual(attr, tui._THEME["body"], name)

    def test_table_title_is_dim_and_left_aligned(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        x0, _ = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        x, attr = next((x, a) for _, x, text, a in screen.strings
                       if text == "Backend Status")
        self.assertEqual(x, margin)
        self.assertEqual(attr, tui._THEME["dim"])

    def test_table_does_not_paint_over_the_border(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS)
        self.assert_inside_border(screen)

    def test_notice_line_is_red_and_above_the_table(self):
        screen = FakeScreen(keys=[10])
        tui.menu(screen, "Hub", [("Quit", "quit")],
                 table_title="Backend Status", table_rows=self.ROWS,
                 notice_lines=[("Warning: ffmpeg not installed!", "err")])
        x0, _ = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        x, attr = next((x, a) for _, x, text, a in screen.strings
                       if text == "Warning: ffmpeg not installed!")
        self.assertEqual(x, margin)
        self.assertEqual(attr, tui._THEME["err"])
        # The notice sits above the table title ("Backend Status").
        notice_y = next(y for y, _, text, _ in screen.strings
                        if text == "Warning: ffmpeg not installed!")
        title_y = next(y for y, _, text, _ in screen.strings
                       if text == "Backend Status")
        self.assertLess(notice_y, title_y)
        self.assert_inside_border(screen)


class ConfirmTests(TuiTestCase):
    def test_tab_switches_and_enter_activates(self):
        screen = FakeScreen(keys=[9, 10])
        self.assertFalse(tui.confirm(screen, "Overwrite?", default=True))

    def test_y_answers_directly(self):
        screen = FakeScreen(keys=[ord("y")])
        self.assertTrue(tui.confirm(screen, "Overwrite?", default=False))

    def test_enter_takes_the_default(self):
        screen = FakeScreen(keys=[10])
        self.assertTrue(tui.confirm(screen, "Overwrite?", default=True))

    def test_esc_aborts_without_cancel_value(self):
        screen = FakeScreen(keys=[27])
        with self.assertRaises(tui.WizardCancelled):
            tui.confirm(screen, "Overwrite?", default=True)

    def test_esc_returns_cancel_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.confirm(screen, "Overwrite?", default=True,
                        cancel_value=marker),
            marker)

    def test_q_returns_cancel_value(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.confirm(screen, "Overwrite?", default=True,
                        cancel_value=marker),
            marker)


class ConfirmYnCancelTests(TuiTestCase):
    def test_enter_takes_the_default_yes(self):
        screen = FakeScreen(keys=[10])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "yes")

    def test_tab_enter_selects_no_then_cancel(self):
        screen = FakeScreen(keys=[9, 10])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "no")
        screen = FakeScreen(keys=[9, 9, 10])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "cancel")

    def test_buttons_wrap_around(self):
        # Moving back from Yes lands on Cancel.
        screen = FakeScreen(keys=[FakeCurses.KEY_LEFT, 10])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "cancel")

    def test_y_and_n_answer_directly(self):
        screen = FakeScreen(keys=[ord("y")])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "yes")
        screen = FakeScreen(keys=[ord("n")])
        self.assertEqual(tui.confirm_yn_cancel(screen, "Save settings?"),
                         "no")

    def test_esc_and_q_count_as_cancel(self):
        for key in (27, ord("q")):
            screen = FakeScreen(keys=[key])
            self.assertEqual(
                tui.confirm_yn_cancel(screen, "Save settings?"), "cancel")


class LineEditTests(TuiTestCase):
    def test_typing_backspace_and_enter(self):
        keys = [ord("c"), ord("d"), FakeCurses.KEY_BACKSPACE, 10]
        screen = FakeScreen(keys=keys)
        value = tui.line_edit(screen, "Edit", "ab")
        self.assertEqual(value, "abc")

    def test_validation_error_keeps_editing(self):
        keys = [ord("x"), 10, FakeCurses.KEY_BACKSPACE, 10]
        screen = FakeScreen(keys=keys)
        value = tui.line_edit(
            screen, "Edit", "5",
            validate=lambda s: None if s.isdigit() else "digits only")
        self.assertEqual(value, "5")

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.line_edit(screen, "Edit", "text", back_value=marker),
            marker)

    def test_q_stays_typeable_with_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q"), 10])
        value = tui.line_edit(screen, "Edit", "te", back_value=marker)
        self.assertEqual(value, "teq")


class FormTests(TuiTestCase):
    def _fields(self):
        # Fresh dicts each call: form() edits field values in place, and a
        # shared class attribute would leak edits between tests.
        return [
            {"key": "fmt", "label": "Format", "kind": "choice",
             "value": "m4b", "choices": ["mp3", "m4b", "ogg"]},
            {"key": "chunk", "label": "Chunk", "kind": "text",
             "value": "250"},
        ]

    def test_save_returns_current_values(self):
        screen = FakeScreen(keys=[9, 10])  # Tab -> Save, Enter
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})

    def test_cancel_returns_back_value(self):
        marker = object()
        # Tab -> buttons, Left -> Cancel, Enter.
        screen = FakeScreen(keys=[9, FakeCurses.KEY_LEFT, 10])
        result = tui.form(screen, "Settings", self._fields(),
                          back_value=marker)
        self.assertIs(result, marker)

    def test_down_on_last_field_moves_to_save(self):
        # Down moves cursor to the last field, Down again steps onto the
        # Save button, Enter saves.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})

    def test_up_on_first_field_wraps_to_save(self):
        # Up from the first field wraps onto the Save button; Enter saves.
        screen = FakeScreen(keys=[FakeCurses.KEY_UP, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})

    def test_k_on_first_field_wraps_to_save(self):
        screen = FakeScreen(keys=[ord("k"), 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})

    def test_k_on_buttons_returns_to_fields(self):
        # Down to the last field, Down onto Save, k back into the fields;
        # editing then proves focus left the button row.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  ord("k"), 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250x"})

    def test_j_on_cancel_returns_to_fields(self):
        # Up wraps to Save, Left to Cancel, j back into the fields; the
        # choice editor opening proves focus left the button row.
        screen = FakeScreen(keys=[FakeCurses.KEY_UP, FakeCurses.KEY_LEFT,
                                  ord("j"), 10, 10, 9, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})

    def test_up_down_on_buttons_returns_to_fields(self):
        # Down (last field -> Save), Up returns to the last field, Enter
        # opens its text editor, then Tab -> Save, Enter.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  FakeCurses.KEY_UP, 10, ord("x"), 10,
                                  9, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250x"})

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.form(screen, "Settings", self._fields(), back_value=marker),
            marker)

    def test_q_returns_back_value_like_esc(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.form(screen, "Settings", self._fields(), back_value=marker),
            marker)

    def test_choice_field_picks_another_value(self):
        # Enter opens the choice menu on 'm4b' (index 1); Down moves to
        # 'ogg', Enter accepts; Tab -> Save, Enter.
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN, 10, 9, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "ogg", "chunk": "250"})

    def test_choice_row_shows_the_selected_label_not_the_raw_value(self):
        # A (label, value) choice's value can be a bare key ("qwen") while
        # its label is the display name ("qwen-tts"): the painted row shows
        # the label — the same text the pick menu shows — for both static
        # and callable choice lists.
        fields = [
            {"key": "backend", "label": "Backend", "kind": "choice",
             "value": "qwen",
             "choices": [("qwen-tts", "qwen"), ("audio.cpp", "audiocpp")]},
            {"key": "mode", "label": "Model", "kind": "choice",
             "value": "clone",
             "choices": lambda fs: [("Base (voice cloning)", "clone")]},
        ]
        screen = FakeScreen(keys=[27])
        marker = object()
        self.assertIs(tui.form(screen, "Form", fields, back_value=marker),
                      marker)
        painted = [text for _, _, text, _ in screen.strings]
        self.assertIn("  qwen-tts", painted)
        self.assertIn("  Base (voice cloning)", painted)
        self.assertNotIn("  qwen", painted)
        self.assertNotIn("  clone", painted)

    def test_text_field_edits_then_saves(self):
        # Down to the text row, Enter opens the editor, type 'x', Enter,
        # then Tab -> Save, Enter.
        screen = FakeScreen(
            keys=[FakeCurses.KEY_DOWN, 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Settings", self._fields())
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250x"})

    def test_validation_error_refuses_save_then_recovers(self):
        fields = [
            {"key": "chunk", "label": "Chunk", "kind": "text", "value": "bad",
             "validate": lambda s: None if s.isdigit() else "digits only"},
            {"key": "fmt", "label": "Format", "kind": "text", "value": "x"},
        ]
        # Tab->Save(Enter) fails, the flash consumes the next key; Enter
        # reopens the editor, Ctrl-U clears 'bad', type '120', Enter; then
        # Tab->Save(Enter).
        keys = [9, 10, 10, 10, 21, ord("1"), ord("2"), ord("0"), 10, 9, 10]
        screen = FakeScreen(keys=keys)
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"chunk": "120", "fmt": "x"})

    def test_rows_left_justified_inside_the_border(self):
        screen = FakeScreen(keys=[9, 10])
        tui.form(screen, "Settings", self._fields())
        self.assert_inside_border(screen)

    def test_empty_fields_rejected(self):
        with self.assertRaises(ValueError):
            tui.form(self.screen, "Settings", [])

    def test_dynamic_label_renders_with_column_alignment(self):
        # A callable label is resolved against the field list on every
        # redraw; static labels pad to the widest resolved label so all
        # value columns line up.
        fields = [
            {"key": "fmt", "kind": "choice", "value": "mp3",
             "label": lambda fs: "Dynamic-" + fs[0]["value"],
             "choices": ["mp3", "ogg"]},
            {"key": "chunk", "label": "Chunk", "kind": "text",
             "value": "250"},
        ]
        screen = FakeScreen(keys=[9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "mp3", "chunk": "250"})
        rows = [(y, x, text) for y, x, text, _ in screen.strings]
        label_row = next(r for r in rows if r[2].startswith("Dynamic-"))
        self.assertEqual(label_row[2], "Dynamic-mp3:")
        chunk_row = next(r for r in rows if r[2].startswith("Chunk:"))
        self.assertEqual(chunk_row[1], label_row[1])
        self.assert_inside_border(screen)

    def test_sub_dialog_title_uses_resolved_label(self):
        # The choice menu (and text/directory editors) are titled with the
        # resolved label, not the raw callable.
        fields = [
            {"key": "model", "label": "Model", "kind": "text",
             "value": "base"},
            {"key": "voice", "kind": "text", "value": "",
             "label": lambda fs: "Voice of " + fs[0]["value"]},
        ]
        # Down to the second field, Enter opens its editor (titled with the
        # resolved label), Esc backs out; Tab -> Save, Enter.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, 10, 27, 9, 10])
        tui.form(screen, "Settings", fields)
        titles = [text for _, _, text, _ in screen.strings
                  if "Voice of base" in text]
        self.assertTrue(titles)

    def test_help_lines_render_inside_the_edit_dialog(self):
        # A field's optional "help" list appears as dim lines in its line
        # editor (and callables resolve against the field list).
        fields = [
            {"key": "opt", "kind": "text", "value": "",
             "label": "Options",
             "help": lambda fs: ["First hint.", f"Value: {fs[0]['value']!r}"]},
            {"key": "plain", "label": "Plain", "kind": "text",
             "value": "", "help": ["Static hint."]},
        ]
        # Down to the second field, Enter opens it, Esc backs out; Tab ->
        # Save, Enter. The first field's editor is never opened, so only
        # the static second field's hints must appear.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, 10, 27, 9, 10])
        tui.form(screen, "Settings", fields)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertIn("Static hint.", texts)
        self.assertNotIn("First hint.", texts)
        # Open the first field's editor: dynamic help resolves per redraw.
        screen = FakeScreen(keys=[10, 27, 9, 10])
        tui.form(screen, "Settings", fields)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertIn("First hint.", texts)
        self.assertIn("Value: ''", texts)
        self.assert_inside_border(screen)

    def test_choice_menu_shows_the_fields_help_lines(self):
        # A choice field's "help" renders as dim lines inside its
        # selection menu (like the text editor's hints).
        fields = [
            {"key": "fmt", "label": "Format", "kind": "choice",
             "value": "mp3", "choices": ["mp3", "ogg"],
             "help": ["Check the format docs for supported codecs."]},
            {"key": "chunk", "label": "Chunk", "kind": "text",
             "value": "250"},
        ]
        # Enter opens the choice menu, Esc backs out; Tab -> Save, Enter.
        screen = FakeScreen(keys=[10, 27, 9, 10])
        tui.form(screen, "Settings", fields)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertIn("Check the format docs for supported codecs.", texts)
        self.assert_inside_border(screen)

        # Without the hint nothing renders it.
        fields[0].pop("help")
        screen = FakeScreen(keys=[10, 27, 9, 10])
        tui.form(screen, "Settings", fields)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertNotIn("Check the format docs for supported codecs.", texts)

    def test_field_note_renders_and_save(self):
        fields = self._fields()
        fields[1]["note"] = "A short section note"
        screen = FakeScreen(keys=[9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})
        self.assert_inside_border(screen)

    def test_highlight_skips_note_rows_to_the_field(self):
        fields = self._fields()
        fields[1]["note"] = "A short section note"
        snapshots = []
        original_draw = tui.Frame.draw

        def spy(frame):
            original_draw(frame)
            snapshots.append((frame.cursor,
                              [row["text"] if row["segments"] is None
                               else "".join(text for text, _ in row["segments"])
                               for row in frame.rows]))

        # Down moves from the first field to the one after the note block.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, 9, 10])
        with patch.object(tui.Frame, "draw", spy):
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})
        cursor, texts = snapshots[1]
        # The cursor must sit on the Chunk field's own row — not on one
        # of the blank/note rows inserted above it (the old base+index
        # math highlighted the blank line).
        self.assertEqual(texts[cursor], "Chunk:   250")

    def test_custom_button_labels_and_start_on_buttons(self):
        # buttons= overrides the labels; start_on_buttons=True means Enter
        # alone (with no navigation) accepts the defaults.
        screen = FakeScreen(keys=[10])
        result = tui.form(screen, "Convert", self._fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250"})
        texts = [text for _, _, text, _ in screen.strings]
        self.assertIn("[ Generate! ]", texts)
        self.assertIn("[ Cancel ]", texts)
        self.assertNotIn("[ Save ]", texts)

    def test_bool_field_toggles_with_enter(self):
        fields = [{"key": "combine", "label": "Combine", "kind": "bool",
                   "value": False}]
        # Enter toggles the bool to True, Tab -> button, Enter saves.
        screen = FakeScreen(keys=[10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"combine": True})

    def test_bool_field_toggles_with_space(self):
        fields = [{"key": "combine", "label": "Combine", "kind": "bool",
                   "value": False}]
        screen = FakeScreen(keys=[ord(" "), 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"combine": True})

    def test_toggle_field_cycles_with_enter(self):
        # Enter steps the toggle to its next choice in place (no menu
        # opens), Tab -> button, Enter saves.
        fields = [{"key": "transcripts", "label": "Transcripts",
                   "kind": "toggle", "value": "missing",
                   "choices": [("New voices", "missing"),
                               ("All voices", "all")]}]
        screen = FakeScreen(keys=[10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"transcripts": "all"})

    def test_toggle_field_cycles_with_space(self):
        fields = [{"key": "transcripts", "label": "Transcripts",
                   "kind": "toggle", "value": "missing",
                   "choices": [("New voices", "missing"),
                               ("All voices", "all")]}]
        screen = FakeScreen(keys=[ord(" "), 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"transcripts": "all"})

    def test_toggle_field_last_choice_wraps_to_the_first(self):
        fields = [{"key": "transcripts", "label": "Transcripts",
                   "kind": "toggle", "value": "all",
                   "choices": [("New voices", "missing"),
                               ("All voices", "all")]}]
        screen = FakeScreen(keys=[10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"transcripts": "missing"})

    def test_toggle_field_renders_the_matching_label(self):
        fields = [{"key": "transcripts", "label": "Transcripts",
                   "kind": "toggle", "value": "missing",
                   "choices": [("New voices", "missing"),
                               ("All voices", "all")]}]
        screen = FakeScreen(keys=[9, 10])  # straight to Save
        tui.form(screen, "Settings", fields)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertTrue(any("New voices" in text for text in texts))
        self.assertFalse(any("All voices" in text for text in texts))

    def test_toggle_field_fires_on_change(self):
        calls = []
        fields = [{"key": "transcripts", "label": "Transcripts",
                   "kind": "toggle", "value": "missing",
                   "choices": [("New voices", "missing"),
                               ("All voices", "all")],
                   "on_change": lambda fs: calls.append(1)}]
        screen = FakeScreen(keys=[10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(calls, [1])
        self.assertEqual(result, {"transcripts": "all"})

    def test_hidden_field_keeps_value_and_is_not_drawn(self):
        fields = self._fields()
        fields.append({"key": "hidden", "label": "Secret", "kind": "text",
                       "value": "kept", "visible": False})
        screen = FakeScreen(keys=[9, 10])
        result = tui.form(screen, "Settings", fields)
        # The hidden field's value is preserved and returned.
        self.assertEqual(result, {"fmt": "m4b", "chunk": "250",
                                  "hidden": "kept"})
        texts = [text for _, _, text, _ in screen.strings]
        self.assertNotIn("Secret:", texts)

    def test_visible_callable_hides_row_after_change(self):
        fields = [
            {"key": "fmt", "label": "Format", "kind": "choice",
             "value": "mp3", "choices": ["mp3", "m4b"]},
            {"key": "combine", "label": "Combine", "kind": "bool",
             "value": False,
             "visible": lambda fs: next(
                 f["value"] for f in fs if f["key"] == "fmt") != "m4b"},
        ]
        snapshots = []
        original_draw = tui.Frame.draw

        def spy(frame):
            original_draw(frame)
            snapshots.append([row["text"] if row["segments"] is None
                              else "".join(t for t, _ in row["segments"])
                              for row in frame.rows])

        # Enter on Format, Down to m4b, Enter; Tab -> button, Enter.
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN, 10, 9, 10])
        with patch.object(tui.Frame, "draw", spy):
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "m4b", "combine": False})
        self.assertTrue(any("Combine:" in row for row in snapshots[0]))
        self.assertFalse(any("Combine:" in row for row in snapshots[-1]))

    def test_callable_choices_resolve_at_open(self):
        fields = [{"key": "fmt", "label": "Format", "kind": "choice",
                   "value": "a", "choices": lambda fs: ["a", "b", "c"]}]
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN, 10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "b"})

    def test_empty_static_choices_flash_hint_and_keep_form_open(self):
        # A choice field with no options at all cannot be opened (menu()
        # would raise): the on_empty_choices hint flashes instead and the
        # form stays usable.
        fields = [{"key": "fmt", "label": "Format", "kind": "choice",
                   "value": "", "choices": [],
                   "on_empty_choices": "nothing to pick — add some"},
                  {"key": "chunk", "label": "Chunk", "kind": "text",
                   "value": "1"}]
        # Enter flashes (the next key dismisses it), Tab -> Save, Enter.
        screen = FakeScreen(keys=[10, ord("x"), 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "", "chunk": "1"})
        texts = [text for _, _, text, _ in screen.strings]
        self.assertTrue(any("nothing to pick" in text for text in texts))

    def test_empty_callable_choices_flash_without_opening_menu(self):
        # The regression this guards: a dynamic list that resolved empty
        # used to crash form() with ValueError from menu(). A message may
        # itself be a callable of the field list.
        fields = [{"key": "voice", "label": "Voice", "kind": "choice",
                   "value": None,
                   "choices": lambda fs: [],
                   "on_empty_choices":
                       lambda fs: f"{len(fs)} fields but no voices"}]
        # Enter opens nothing (the flash consumes the next key), then
        # Tab -> Save, Enter.
        screen = FakeScreen(keys=[10, ord("x"), 9, 10])
        with patch.object(tui, "menu",
                          side_effect=AssertionError("menu() was opened")):
            result = tui.form(screen, "Convert", fields)
        self.assertEqual(result, {"voice": None})
        texts = [text for _, _, text, _ in screen.strings]
        self.assertTrue(any("no voices" in text for text in texts))

    def test_on_change_fires_after_value_change(self):
        calls = []
        fields = [{"key": "fmt", "label": "Format", "kind": "choice",
                   "value": "a", "choices": ["a", "b"],
                   "on_change": lambda fs: calls.append("changed")}]
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN, 10, 9, 10])
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "b"})
        self.assertEqual(calls, ["changed"])

    def test_choice_field_validation_refuses_save(self):
        fields = [
            {"key": "fmt", "label": "Format", "kind": "choice",
             "value": "bad", "choices": ["good", "bad"],
             "validate": lambda v: None if v == "good" else "pick good"},
            {"key": "other", "label": "Other", "kind": "text", "value": "x"},
        ]
        # Tab -> Save fails on fmt; the flash consumes the next key; then
        # re-open fmt, Down to 'good', Enter; Tab -> Save, Enter.
        keys = [9, 10, 10, 10, FakeCurses.KEY_DOWN, 10, 9, 10]
        screen = FakeScreen(keys=keys)
        result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"fmt": "good", "other": "x"})

    def test_dir_field_opens_the_browser_and_saves_the_pick(self):
        picked = Path("/picked/voices")
        fields = [{"key": "voices", "label": "Voices directory",
                   "kind": "dir", "value": Path("/start")}]
        with patch.object(tui, "browse_directory",
                          return_value=picked) as mk_browser:
            # edit, Enter (focus jumped to Save after the pick).
            screen = FakeScreen(keys=[10, 10])
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"voices": picked})
        mk_browser.assert_called_once()
        self.assertEqual(Path(mk_browser.call_args[1]["start"]),
                         Path("/start"))

    def test_dir_field_passes_info_and_preview_to_the_browser(self):
        # A dir field may carry info/preview callbacks (e.g. the .wav
        # count alerts); the form forwards them to the browser untouched.
        def info(directory):
            return ("info text", "ok")

        def preview(directory):
            return ("preview text", "warn")

        picked = Path("/picked/voices")
        fields = [{"key": "voices", "label": "Voices directory",
                   "kind": "dir", "value": Path("/start"),
                   "info": info, "preview": preview}]
        with patch.object(tui, "browse_directory",
                          return_value=picked) as mk_browser:
            screen = FakeScreen(keys=[10, 10])
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"voices": picked})
        self.assertIs(mk_browser.call_args[1]["info"], info)
        self.assertIs(mk_browser.call_args[1]["preview"], preview)

    def test_dir_pick_moves_focus_to_the_accept_button(self):
        # Accepting a directory is a completed choice: focus lands on
        # Save, so the very next Enter submits — no Tab hunting.
        picked = Path("/picked/voices")
        fields = [{"key": "voices", "label": "Voices directory",
                   "kind": "dir", "value": Path("/start")}]
        with patch.object(tui, "browse_directory",
                          return_value=picked) as mk_browser:
            screen = FakeScreen(keys=[10, 10])
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"voices": picked})
        mk_browser.assert_called_once()

    def test_dir_field_back_out_keeps_the_old_value(self):
        # Backing out of the browser returns its back_value; the field
        # keeps the previous path and focus stays on the fields (Tab
        # then walks to Save).
        fields = [{"key": "voices", "label": "Voices directory",
                   "kind": "dir", "value": Path("/start")}]
        with patch.object(tui, "browse_directory",
                          side_effect=lambda *a, **k: k["back_value"]):
            screen = FakeScreen(keys=[10, 9, 10])
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"voices": Path("/start")})

    def test_dir_field_renders_its_path_and_fires_on_change(self):
        picked = Path("/picked")
        calls = []
        fields = [{"key": "voices", "label": "Voices", "kind": "dir",
                   "value": None, "on_change": lambda fs: calls.append(1)}]
        with patch.object(tui, "browse_directory", return_value=picked):
            screen = FakeScreen(keys=[10, 10])
            result = tui.form(screen, "Settings", fields)
        self.assertEqual(result, {"voices": picked})
        self.assertEqual(calls, [1])
        texts = [text for _, _, text, _ in screen.strings]
        self.assertTrue(any("Voices:" in text for text in texts))

    def _two_text_fields(self):
        return [{"key": "first", "label": "First", "kind": "text",
                 "value": "a"},
                {"key": "second", "label": "Second", "kind": "text",
                 "value": "b"}]

    def test_up_from_buttons_lands_on_last_field(self):
        # Focus starts on Generate!; Up wraps up through it onto the last
        # field (the list wraps: Up from the first button -> the bottom).
        screen = FakeScreen(keys=[
            FakeCurses.KEY_UP, 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Convert", self._two_text_fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"first": "a", "second": "bx"})

    def test_down_from_buttons_lands_on_first_field(self):
        # Down wraps down through the buttons back onto the first field.
        screen = FakeScreen(keys=[
            FakeCurses.KEY_DOWN, 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Convert", self._two_text_fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"first": "ax", "second": "b"})

    def test_k_from_buttons_lands_on_last_field(self):
        screen = FakeScreen(keys=[ord("k"), 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Convert", self._two_text_fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"first": "a", "second": "bx"})

    def test_tab_from_buttons_lands_on_first_field(self):
        screen = FakeScreen(keys=[9, 10, ord("x"), 10, 9, 10])
        result = tui.form(screen, "Convert", self._two_text_fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"first": "ax", "second": "b"})

    def test_btab_from_buttons_lands_on_last_field(self):
        screen = FakeScreen(keys=[FakeCurses.KEY_BTAB, 10, ord("x"), 10,
                                  9, 10])
        result = tui.form(screen, "Convert", self._two_text_fields(),
                          buttons=("Generate!", "Cancel"),
                          start_on_buttons=True)
        self.assertEqual(result, {"first": "a", "second": "bx"})


class BrowseDirectoryTests(TuiTestCase):
    def setUp(self):
        super().setUp()
        tmp = tempfile.TemporaryDirectory()
        self.addCleanup(tmp.cleanup)
        self.root = Path(tmp.name)
        for name in ("alpha", "beta", "zulu"):
            (self.root / name).mkdir()
        (self.root / "noise.txt").write_text("x", encoding="utf-8")

    def test_listing_rows_left_justified(self):
        screen = FakeScreen(keys=[10])
        chosen = tui.browse_directory(screen, "Pick", start=self.root)
        self.assertEqual(chosen, self.root.resolve())
        x0, x_right = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        for label in ("[ Use this directory ]", "..",
                      "alpha/", "beta/", "zulu/"):
            x = next(x for _, x, text, _ in screen.strings if text == label)
            self.assertEqual(x, margin, label)
        drawn = " ".join(text for _, _, text, _ in screen.strings)
        self.assertNotIn("noise.txt", drawn)
        self.assert_inside_border(screen)

    def test_enter_opens_highlighted_subdirectory(self):
        keys = [FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN, 10, 10]
        screen = FakeScreen(keys=keys)
        chosen = tui.browse_directory(screen, "Pick", start=self.root)
        self.assertEqual(chosen, (self.root / "alpha").resolve())
        self.assert_inside_border(screen)

    def test_corner_indicator_counts_use_and_parent_rows(self):
        # "[ Use this directory ]" and ".." are selectable rows like
        # any other: with the 23 subdirectories (3 from setUp + 20),
        # moving onto the first one ("alpha/") reads 3/25 in the corner.
        for i in range(20):
            (self.root / f"dir{i:02d}").mkdir()
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  27])
        with self.assertRaises(tui.WizardCancelled):
            tui.browse_directory(screen, "Pick", start=self.root)
        labels = [text for _, _, text, _ in screen.strings
                  if text in (" 1/25 ", " 2/25 ", " 3/25 ")]
        self.assertEqual(labels, [" 1/25 ", " 2/25 ", " 3/25 "])

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.browse_directory(screen, "Pick", start=self.root,
                                 back_value=marker),
            marker)

    def test_q_returns_back_value_like_esc(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.browse_directory(screen, "Pick", start=self.root,
                                 back_value=marker),
            marker)


class CheckboxTreeTests(TuiTestCase):
    FAMILIES = [
        {"label": "Family one", "detail": "tts",
         "options": [{"key": "pkg-a", "label": "pkg-a", "recommended": True},
                     {"key": "pkg-b", "label": "pkg-b", "recommended": False}]},
        {"label": "Family two", "detail": "tts, cloning",
         "options": [{"key": "pkg-c", "label": "pkg-c", "recommended": True}]},
    ]

    def test_all_nodes_start_collapsed(self):
        # Nothing is pre-checked and no family is expanded on the initial
        # draw: only family rows are visible, each with a '+' collapse
        # arrow, and no option rows are drawn.
        screen = FakeScreen(keys=[27])  # Esc aborts after the first draw
        with self.assertRaises(tui.WizardCancelled):
            tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        texts = [text for _, _, text, _ in screen.strings]
        self.assertIn("+ Family one", texts)
        self.assertIn("+ Family two", texts)
        for label in ("pkg-a", "pkg-b", "pkg-c"):
            self.assertNotIn(label, texts)

    def test_enter_checks_like_space(self):
        # Enter on a family row checks its recommended option, exactly
        # like Space; Tab then Confirm accepts the selection.
        screen = FakeScreen(keys=[10, 9, 10])
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        self.assertEqual(picked, [(0, "pkg-a")])

    def test_confirm_without_selection_flashes(self):
        # Confirm with nothing checked flashes and stays; the user then
        # checks a model and confirms for real.
        keys = [9, 10, ord(" "), 9, 10, 9, 10]
        screen = FakeScreen(keys=keys)
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        self.assertEqual(picked, [(0, "pkg-a")])

    def test_rows_left_justified_inside_the_border(self):
        screen = FakeScreen(keys=[ord(" "), 9, 10])
        tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        x0, x_right = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        strings = sorted((y, x, text) for y, x, text, _ in screen.strings)
        # Family row: its checkbox starts at the margin.
        y_family = next(y for y, _, text in strings if text == "- Family one")
        family_box_x = next(x for y, x, text in strings
                            if y == y_family and text == "[x] ")
        self.assertEqual(family_box_x, margin)
        # Option row: its checkbox sits one indent (2 columns) deeper.
        option_box_x = next(x for y, x, text in strings
                            if text == "[x] " and y != y_family)
        self.assertEqual(option_box_x, margin + 4)
        self.assert_inside_border(screen)

    def test_long_indented_options_do_not_paint_over_the_border(self):
        # A wide screen keeps the dialog width driven by the option row
        # itself (not the footer), the geometry where the old centered
        # segments drawing could paint over the right border.
        families = [{"label": "F", "detail": "tts",
                     "options": [{"key": "long", "label": "x" * 60,
                                  "recommended": True}]}]
        screen = FakeScreen(keys=[ord(" "), 9, 10], width=120)
        picked = tui.checkbox_tree(screen, "Pick", families)
        self.assertEqual(picked, [(0, "long")])
        self.assert_inside_border(screen)

    def test_space_checks_then_confirm_accepts(self):
        screen = FakeScreen(keys=[ord(" "), 9, 10])
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        self.assertEqual(picked, [(0, "pkg-a")])

    def test_space_toggles_option_row(self):
        # Enter on the family checks pkg-a and expands; Down twice lands
        # on the pkg-b option row; Space checks it; confirm returns both.
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN,
                                  FakeCurses.KEY_DOWN, ord(" "), 9, 10])
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        self.assertEqual(picked, [(0, "pkg-a"), (0, "pkg-b")])

    def test_enter_toggles_option_row(self):
        # Enter on the family checks pkg-a and expands; Down lands on the
        # pkg-a option row; Enter there unchecks it; Down to pkg-b, Space
        # checks it. Confirm returns only pkg-b.
        screen = FakeScreen(keys=[10, FakeCurses.KEY_DOWN, 10,
                                  FakeCurses.KEY_DOWN, ord(" "), 9, 10])
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES)
        self.assertEqual(picked, [(0, "pkg-b")])

    def test_unhandled_key_on_row_is_ignored(self):
        # A key that is neither motion nor toggle (here "x") must not
        # toggle anything or crash on either row kind; Esc then aborts.
        marker = object()
        screen = FakeScreen(keys=[ord("x"), FakeCurses.KEY_DOWN, ord("x"),
                                  27])
        self.assertIs(
            tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                              back_value=marker),
            marker)

    def test_prechecked_selection_confirmed(self):
        # checked= seeds the tree (modify flow): Tab then Confirm accepts
        # the pre-checked options without any extra key presses.
        screen = FakeScreen(keys=[9, 10])
        picked = tui.checkbox_tree(
            screen, "Pick models", self.FAMILIES,
            checked={(0, "pkg-b"), (1, "pkg-c")})
        self.assertEqual(picked, [(0, "pkg-b"), (1, "pkg-c")])

    def test_start_on_buttons_confirms_immediately(self):
        # start_on_buttons=True (the seeded modify flow): Enter alone
        # accepts the pre-checked tree with no Tab first.
        screen = FakeScreen(keys=[10])
        picked = tui.checkbox_tree(
            screen, "Pick models", self.FAMILIES,
            checked={(0, "pkg-b"), (1, "pkg-c")}, start_on_buttons=True)
        self.assertEqual(picked, [(0, "pkg-b"), (1, "pkg-c")])

    def test_start_on_buttons_without_selection_flashes(self):
        # Focus starting on Confirm changes nothing else: Enter with an
        # empty tree flashes and stays (the flash dismiss consumes one
        # scripted key); the user then moves back to the rows, checks
        # one, and confirms for real.
        keys = [10, 9, 9, 10, 9, 10]
        screen = FakeScreen(keys=keys)
        picked = tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                                   start_on_buttons=True)
        self.assertEqual(picked, [(0, "pkg-a")])

    def test_prechecked_options_draw_as_checked(self):
        screen = FakeScreen(keys=[9, 10])
        tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                          checked={(0, "pkg-b")})
        texts = [text for _, _, text, _ in screen.strings]
        # The pre-checked option row (indented) draws its box checked.
        self.assertIn("[x] ", texts)
        # ...and the family row is expanded (its options are listed).
        self.assertIn("- Family one", texts)

    def test_prechecked_family_cursor_starts_on_it(self):
        # Only the second family is pre-checked, so the cursor starts on it:
        # two Spaces clear then re-check that family (the cursor never
        # moves). If the cursor were still on the first family, the two
        # Spaces would check then clear family one and Confirm would flash
        # instead of accepting anything.
        screen = FakeScreen(keys=[ord(" "), ord(" "), 9, 10])
        picked = tui.checkbox_tree(
            screen, "Pick models", self.FAMILIES,
            checked={(1, "pkg-c")})
        self.assertEqual(picked, [(1, "pkg-c")])

    def test_back_button_returns_back_value(self):
        marker = object()
        # Tab -> buttons, Right -> Back, Enter.
        screen = FakeScreen(keys=[9, FakeCurses.KEY_RIGHT, 10])
        self.assertIs(
            tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                              back_value=marker),
            marker)

    def test_empty_families_rejected(self):
        with self.assertRaises(ValueError):
            tui.checkbox_tree(self.screen, "Pick", [])

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                              back_value=marker),
            marker)

    def test_q_returns_back_value_like_esc(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.checkbox_tree(screen, "Pick models", self.FAMILIES,
                              back_value=marker),
            marker)


class SuspendTests(TuiTestCase):
    """tui.suspend leaves curses, runs code, then repaints."""

    def test_suspend_runs_block_and_restores(self):
        ran = []
        with tui.suspend(self.screen):
            ran.append("inside")
        self.assertEqual(ran, ["inside"])

    def test_suspend_always_restores_on_exception(self):
        class Boom(Exception):
            pass
        with self.assertRaises(Boom):
            with tui.suspend(self.screen):
                raise Boom()


class FlashTests(TuiTestCase):
    """tui.flash shows a notice until any key is pressed."""

    def test_notice_dismissed_by_any_key(self):
        screen = FakeScreen(keys=[10])
        # Should return (None) after consuming one key; not raise.
        tui.flash(screen, "a notice", kind="warn")
        self.assertEqual(screen.keys, [])

    def test_message_is_shown_without_a_notice_heading(self):
        screen = FakeScreen(keys=[10])
        tui.flash(screen, "No backend is installed", kind="warn")
        texts = [text for _, _, text, _ in screen.strings]
        self.assertNotIn("Notice", texts)
        # The warning itself is the dialog's content, in its kind color.
        attr = next(a for _, _, text, a in screen.strings
                    if text == "No backend is installed")
        self.assertEqual(attr, tui._THEME["warn"])
        self.assert_inside_border(screen)

    def test_timed_out_reads_are_ignored_until_a_real_key(self):
        # A screen left in redraw-cadence mode feeds getch() -1s; the
        # notice must still wait for an actual key press.
        screen = FakeScreen(keys=[-1, -1, ord("x")])
        tui.flash(screen, "a notice", kind="err")
        self.assertEqual(screen.keys, [])

    def test_ctrl_c_still_aborts(self):
        screen = FakeScreen(keys=[-1, 3])
        with self.assertRaises(tui.WizardCancelled):
            tui.flash(screen, "a notice")

    def test_frame_flash_ignores_timed_out_reads_too(self):
        frame = tui.Frame(FakeScreen(keys=[-1, 10]), "Title", "footer")
        frame.flash("status line notice", "err")
        self.assertIsNone(frame.status)


class FrameStatusTests(TuiTestCase):
    """Frame status: a multi-line status stacks above the footer row.

    An embedded "\\n" must never spill onto the footer's row (the
    controls line) — the dialog grows and the block is drawn one line
    per row, ending just above the footer.
    """

    MESSAGE = "first line\nsecond line\n"  # trailing blank separator line

    def _draw(self):
        frame = tui.Frame(self.screen, "Generate Speech",
                          "Up/Down = move  Enter = edit")
        frame.mark("Model: qwen-tts", selectable=True)
        frame.buttons = (["Generate!", "Cancel"], 0)
        frame.status = (self.MESSAGE, "err")
        frame.draw()

    def _y_of(self, text, exact=True):
        matches = self.screen.strings if exact else \
            [(y, x, t, a) for y, x, t, a in self.screen.strings
             if t.strip() == text]
        return next(y for y, _, t, _ in matches
                    if (t == text if exact else True))

    def test_status_lines_stack_above_the_footer_row(self):
        self._draw()
        first_y = self._y_of("first line", exact=False)
        second_y = self._y_of("second line", exact=False)
        footer_y = self._y_of("Up/Down = move  Enter = edit")
        self.assertEqual(second_y, first_y + 1)
        # The trailing "\n" separates the error from the controls: the
        # footer sits one blank row below the last status line.
        self.assertEqual(footer_y, second_y + 2)
        self.assert_inside_border(self.screen)

    def test_buttons_clear_the_status_block(self):
        self._draw()
        buttons_y = self._y_of("[ Generate! ]")
        first_y = self._y_of("first line", exact=False)
        self.assertLess(buttons_y, first_y)
        self.assert_inside_border(self.screen)

    def test_single_line_status_sits_directly_above_the_footer(self):
        frame = tui.Frame(self.screen, "Title", "footer")
        frame.status = ("only line", "err")
        frame.draw()
        status_y = self._y_of("only line", exact=False)
        footer_y = self._y_of("footer")
        self.assertEqual(footer_y, status_y + 1)


class FrameIndicatorTests(TuiTestCase):
    """The corner overflow label's default reading.

    With a cursor the " n/n " counts selectable rows (which entry is
    highlighted); without one it keeps the first-visible-line reading.
    The Help screen's viewer overrides the label entirely, so nothing
    here touches its " lines x-y of z " counter.
    """

    def _frame(self):
        frame = tui.Frame(self.screen, "Title", "footer")
        for i in range(30):
            frame.mark(f"row {i}", selectable=True, align="left")
        return frame

    def test_label_counts_selectable_rows_with_a_cursor(self):
        # 30 rows with 17 visible: the cursor on the third row reads
        # 3/30 wherever the viewport sits.
        frame = self._frame()
        frame.cursor = 2
        frame.draw()
        self.assertIn(" 3/30 ",
                      [t for _, _, t, _ in self.screen.strings])

    def test_label_falls_back_to_visible_lines_without_a_cursor(self):
        # Frames without a cursor (e.g. focus on a form's buttons)
        # keep the old first-visible-line reading.
        frame = self._frame()
        frame.draw()
        self.assertIn(" 1/30 ",
                      [t for _, _, t, _ in self.screen.strings])
        frame.scroll = 10
        frame.draw()
        self.assertIn(" 11/30 ",
                      [t for _, _, t, _ in self.screen.strings])

    def test_non_selectable_rows_are_not_numbered(self):
        # Help/note rows do not shift the count: two unselectable rows
        # above 20 selectable ones put the third entry at 3/20.
        frame = tui.Frame(self.screen, "Title", "footer")
        frame.mark("note one")
        frame.mark("note two")
        for i in range(20):
            frame.mark(f"row {i}", selectable=True, align="left")
        frame.cursor = 4  # the third selectable row
        frame.draw()
        self.assertIn(" 3/20 ",
                      [t for _, _, t, _ in self.screen.strings])


class TextViewerTests(TuiTestCase):
    """tui.text_viewer: a scrollable read-only dialog; Esc/q/Enter closes."""

    LINES = ["first line", "second line", "third line"]

    def _last_frame(self, screen, title=" Help "):
        """Texts of the final draw after the title (strings accumulate)."""
        titles = [i for i, entry in enumerate(screen.strings)
                  if entry[2] == title]
        return [entry[2] for entry in screen.strings[titles[-1] + 1:]]

    def _top_line(self, drawn):
        """First body-row text of a frame's drawn strings."""
        return next(text for text in drawn if not text.startswith(" lines"))

    def test_lines_render_and_enter_closes(self):
        marker = object()
        screen = FakeScreen(keys=[10])
        self.assertIs(
            tui.text_viewer(screen, "Help", self.LINES, back_value=marker),
            marker)
        for line in self.LINES:
            self.assertTrue(any(text == line for _, _, text, _
                                in screen.strings), line)
        self.assert_inside_border(screen)

    def test_esc_returns_back_value(self):
        marker = object()
        screen = FakeScreen(keys=[27])
        self.assertIs(
            tui.text_viewer(screen, "Help", self.LINES, back_value=marker),
            marker)

    def test_q_returns_back_value_like_esc(self):
        marker = object()
        screen = FakeScreen(keys=[ord("q")])
        self.assertIs(
            tui.text_viewer(screen, "Help", self.LINES, back_value=marker),
            marker)

    def test_esc_aborts_without_back_value(self):
        screen = FakeScreen(keys=[27])
        with self.assertRaises(tui.WizardCancelled):
            tui.text_viewer(screen, "Help", self.LINES)

    def test_enter_aborts_without_back_value(self):
        screen = FakeScreen(keys=[10])
        with self.assertRaises(tui.WizardCancelled):
            tui.text_viewer(screen, "Help", self.LINES)

    def test_no_cursor_bar_is_drawn(self):
        # Read-only: no row is selectable, so the cyan selection bar
        # never paints, however far the text is scrolled.
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  ord("q")])
        tui.text_viewer(screen, "Help", self.LINES, back_value=object())
        bars = [s for s in screen.strings
                if s[3] == tui._THEME["bar"] and not s[2].strip()]
        self.assertEqual(bars, [])

    def test_down_scrolls_one_line_per_keypress(self):
        # The text itself scrolls immediately: two Downs put the third
        # physical line at the top of the viewport, and the border
        # reports which lines are visible.
        lines = [f"line {i}" for i in range(40)]
        screen = FakeScreen(keys=[FakeCurses.KEY_DOWN, FakeCurses.KEY_DOWN,
                                  ord("q")])
        tui.text_viewer(screen, "Help", lines, back_value=object())
        drawn = self._last_frame(screen)
        self.assertIn(" lines 3-19 of 40 ", drawn)
        self.assertEqual(self._top_line(drawn), "line 2")

    def test_up_stops_at_the_top(self):
        lines = [f"line {i}" for i in range(40)]
        screen = FakeScreen(keys=[FakeCurses.KEY_UP, FakeCurses.KEY_UP,
                                  ord("q")])
        tui.text_viewer(screen, "Help", lines, back_value=object())
        drawn = self._last_frame(screen)
        self.assertIn(" lines 1-17 of 40 ", drawn)
        self.assertEqual(self._top_line(drawn), "line 0")

    def test_down_stops_at_the_bottom(self):
        # 40 lines with 17 visible: scroll clamps at 23, so the last
        # line stays on screen and the range ends at 40.
        lines = [f"line {i}" for i in range(40)]
        keys = [FakeCurses.KEY_DOWN] * 30 + [ord("q")]
        screen = FakeScreen(keys=keys)
        tui.text_viewer(screen, "Help", lines, back_value=object())
        drawn = self._last_frame(screen)
        self.assertIn(" lines 24-40 of 40 ", drawn)
        self.assertEqual(self._top_line(drawn), "line 23")
        self.assertIn("line 39", drawn)

    def test_j_and_k_scroll_too(self):
        lines = [f"line {i}" for i in range(40)]
        # j, j (down twice), k (back up once): one line below the top.
        screen = FakeScreen(keys=[ord("j"), ord("j"), ord("k"), ord("q")])
        tui.text_viewer(screen, "Help", lines, back_value=object())
        self.assertEqual(self._top_line(self._last_frame(screen)), "line 1")

    def test_segments_indent_and_color(self):
        # Numbered rows start at the margin with their number in the
        # title color; indent=1 rows sit two columns further in.
        content = [([("1. ", "title"), ("Step one", None)], 0),
                   ([("continuation", None)], 1),
                   ""]
        screen = FakeScreen(keys=[10])
        tui.text_viewer(screen, "Help", content, back_value=object())
        x0, _ = self.dialog_box(screen)
        margin = x0 + 1 + tui.Frame.LIST_MARGIN
        number = next(entry for entry in screen.strings
                      if entry[2] == "1.")
        self.assertEqual(number[1], margin)
        self.assertEqual(number[3], tui._THEME["title"])
        step = next(entry for entry in screen.strings
                    if entry[2] == "Step")
        self.assertEqual(step[1], margin + 3)
        cont = next(entry for entry in screen.strings
                    if entry[2] == "continuation")
        self.assertEqual(cont[1], margin + 2)

    def test_segments_wrap_when_wider_than_the_dialog(self):
        # wrap=True segments rows word-wrap like text rows (colors
        # kept), never truncating mid-word at the border.
        content = [([("word " * 25, None)], 1)]  # 125 columns of text
        screen = FakeScreen(keys=[10])
        tui.text_viewer(screen, "Help", content, back_value=object())
        self.assert_inside_border(screen)
        ys = {y for y, _, text, _ in screen.strings if "word" in text}
        self.assertGreaterEqual(len(ys), 2)

    def test_segments_truncate_by_default(self):
        # Without wrap=True a segments row keeps its old behavior —
        # one physical line truncated with '~' — so menus, forms and
        # trees (wrap-less callers) never change layout.
        frame = tui.Frame(self.screen, "T", "footer")
        frame.mark_segments([("w" * 100, frame.theme["body"])],
                            selectable=True, align="left")
        frame.cursor = 0
        frame.draw()
        drawn = [text for _, _, text, _ in self.screen.strings
                 if text.startswith("w")]
        self.assertEqual(len(drawn), 1)
        self.assertTrue(drawn[0].endswith("~"))


class FitTests(TuiTestCase):
    """Column-aware fitting: East Asian Wide characters occupy 2 cells."""

    def test_disp_width_counts_wide_characters_twice(self):
        self.assertEqual(tui._disp_width(""), 0)
        self.assertEqual(tui._disp_width("hello"), 5)
        self.assertEqual(tui._disp_width("一号"), 4)
        self.assertEqual(tui._disp_width("mix語end"), 8)

    def test_fit_truncates_by_display_columns(self):
        self.assertEqual(tui._fit("hello", 3), "he~")
        self.assertEqual(tui._fit("hi", 10), "hi")
        # Exact fit keeps the wide pair; one column more would overflow.
        self.assertEqual(tui._fit("你好", 4), "你好")
        self.assertEqual(tui._fit("你好你好", 5), "你好~")
        self.assertEqual(tui._fit("こんにちは", 3), "こ~")

    def test_wrap_segments_counts_wide_characters_twice(self):
        # "語 語 語" is 8 cells, so at width 5 only two words fit per
        # line even though 5 characters would fit by count.
        lines = tui._wrap_segments([("語 語 語", None)], 5)
        self.assertEqual(["".join(t for t, _ in line) for line in lines],
                         ["語 語", "語"])


class WizardTests(unittest.TestCase):
    """The tui.Wizard screen-stack driver: Esc steps back one screen."""

    def test_advances_to_the_final_value(self):
        called = []

        def one():
            called.append("one")
            return two

        def two():
            called.append("two")
            return {"done": True}

        wizard = tui.Wizard()
        self.assertEqual(wizard.run(one), {"done": True})
        self.assertEqual(called, ["one", "two"])

    def test_back_on_first_screen_aborts(self):
        wizard = tui.Wizard()

        def first():
            return tui.Wizard.BACK

        self.assertIsNone(wizard.run(first))

    def test_back_pops_to_the_previous_screen(self):
        calls = []

        def first():
            calls.append("first")
            # Esc on the re-shown first screen finishes the wizard.
            return second if calls.count("first") == 1 else {"done": True}

        def second():
            calls.append("second")
            return tui.Wizard.BACK

        wizard = tui.Wizard()
        self.assertEqual(wizard.run(first), {"done": True})
        self.assertEqual(calls, ["first", "second", "first"])

    def test_back_goes_one_screen_at_a_time(self):
        order = []

        def a():
            order.append("a")
            return b

        def b():
            order.append("b")
            return c if order.count("b") == 1 else {"done": True}

        def c():
            order.append("c")
            return tui.Wizard.BACK

        wizard = tui.Wizard()
        self.assertEqual(wizard.run(a), {"done": True})
        # Back from c lands on b (one screen), not a.
        self.assertEqual(order, ["a", "b", "c", "b"])

    def test_screen_returning_none_aborts(self):
        wizard = tui.Wizard()

        def first():
            return None

        self.assertIsNone(wizard.run(first))


if __name__ == "__main__":
    unittest.main()