"""Compact human-readable duration formatting for the TUI.

Shared by the live elapsed-timer widget (next to the activity indicator) and
the turn-metadata renderer (the dim ``⏱ 2m 16s`` line under an answer), so both
show the same compact form: ``16s``, ``2m 16s``, ``1h 2m``.
"""

from __future__ import annotations


def format_duration(seconds: float | None) -> str:
    """Format a duration as ``Ns`` / ``Mm Ss`` / ``Hh Mm``.

    ``None`` (the backend did not report a value) renders as ``—``.
    """
    if seconds is None:
        return "—"
    total = int(round(seconds))
    if total < 60:
        return f"{total}s"
    if total < 3600:
        return f"{total // 60}m {total % 60}s"
    return f"{total // 3600}h {(total % 3600) // 60}m"