"""Helpers for shaping outgoing mesh messages."""

from __future__ import annotations


def trim_to_bytes(text: str, max_bytes: int) -> str:
    """Return ``text`` truncated so its UTF-8 encoding is at most ``max_bytes`` bytes.

    Backs off if the cut lands inside a multi-byte UTF-8 sequence so we never emit
    invalid UTF-8 to the radio.
    """
    if max_bytes <= 0:
        return ""
    encoded = text.encode("utf-8")
    if len(encoded) <= max_bytes:
        return text
    cut = encoded[:max_bytes]
    # Continuation bytes start with bits 10xxxxxx; rewind past them.
    while cut and (cut[-1] & 0xC0) == 0x80:
        cut = cut[:-1]
    return cut.decode("utf-8", errors="ignore")