ok-serial-terminal 0.1__tar.gz

ok_serial_terminal-0.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.3
+Name: ok-serial-terminal
+Version: 0.1
+Summary: Interactive serial port terminal (based on ok-serial)
+Author: Dan Egnor
+Author-email: Dan Egnor <egnor@ofb.net>
+Requires-Dist: click>=8.3.1
+Requires-Dist: ok-logging-setup>=0.17
+Requires-Dist: ok-serial>=0.4
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/egnor/ok-serial-terminal#readme
+Project-URL: Repository, https://github.com/egnor/ok-serial-terminal.git
+Description-Content-Type: text/markdown
+
+# OK serial terminal &nbsp; 🔌〡〇〡〇〡💻
+
+An interactive [serial port](https://en.wikipedia.org/wiki/Serial_port) terminal, built on [ok-serial](https://github.com/egnor/ok-py-serial#readme).
+
+Think twice before using this! Consider something more established:
+
+- [tio](https://github.com/tio/tio) - not Python, but a great serial terminal utility
+- [picocom](https://github.com/npat-efault/picocom) - the classic minimal serial terminal
+- [screen](https://www.gnu.org/software/screen/) - the terminal multiplexer is also a serial terminal
+- [minicom](https://salsa.debian.org/minicom-team/minicom) - if you're nostalgic for the DOS era
+- [pyserial's miniterm](https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm) - `python -m serial.tools.miniterm`, already installed if you have pyserial
+
+## Installation and Usage
+
+Install the Python package, which installs the `okterm` utility:
+
+```sh
+pip install ok-serial-terminal
+# or 'uv add ok-serial-terminal', 'uv tool install ok-serial-terminal', etc.
+okterm <port> [baud]
+```
+
+OR, skip the package install and run it directly with [uvx](https://docs.astral.sh/uv/guides/tools/) or [pipx](https://pipx.pypa.io/stable/):
+
+```sh
+uvx ok-serial-terminal <port> [baud]
+# or `pipx run ok-serial-terminal <port> [baud]`
+```
+
+The baud rate defaults to 115200 if omitted. The port is an [ok-serial match expression](https://github.com/egnor/ok-py-serial#port-matching), so `okterm RP2040`, `okterm 2e8a:0005`, and `okterm /dev/ttyACM0` all work. Run [`okserial`](https://github.com/egnor/ok-py-serial#readme) (or `uvx ok-py-serial`) to list visible ports and their attributes.
+
+On a terminal (unless `--plain` is given), `okterm` decorates the display with connection status, control signal state, and an indicator for unechoed typed characters. In this mode, ctrl-`]` opens a menu and ctrl-`\` quits.
+
+In plain mode (I/O redirected or `--plain` given), data is pass-through and ^C quits.
+
+See `okterm --help` for more options (locking mode, etc).
+
+## Socat for testing and profit
+
+On Unix-ish systems, [socat](http://www.dest-unreach.org/socat/) is handy for connecting serial-port apps (`okterm` or otherwise) to non-serial endpoints (like a Unix program or a TCP socket). Install it with your favorite package manager (eg. `sudo apt install socat`), and run something like this in one window:
+
+```sh
+socat pty,raw,echo=0,link=socat.tmp exec:$SHELL,pty,stderr,setsid,ctty
+```
+
+The first socat argument `pty,raw,echo=0,link=socat.tmp` allocates a pseudoterminal (pty) that looks like a serial port, and creates a `./socat.tmp` symlink to the device. The `,raw,echo=0` suppresses default pty echo behavior to avoid the shell looping on its own output.
+
+The second socat argument starts a shell on its own pty, but this could be any socat endpoint (`exec:cat`, `tcp:localhost:8000`, etc).
+
+Socat will then shuffle data between the two points. Try this in another window (in the same directory):
+
+```sh
+okterm socat.tmp
+```
+
+You should get a terminal connected to the pty socat allocated; hit enter and you should see a shell prompt.
+
+(None of this is `okterm`-specific — as far as [ok-serial](https://github.com/egnor/ok-py-serial#readme) is concerned `./socat.tmp` is just another serial port, so `ok_serial.SerialConnection(match="socat.tmp", baud=115200)` works the same way from your own code.)

ok_serial_terminal-0.1/README.md

@@ -0,0 +1,58 @@
+# OK serial terminal   🔌〡〇〡〇〡💻
+
+An interactive [serial port](https://en.wikipedia.org/wiki/Serial_port) terminal, built on [ok-serial](https://github.com/egnor/ok-py-serial#readme).
+
+Think twice before using this! Consider something more established:
+
+- [tio](https://github.com/tio/tio) - not Python, but a great serial terminal utility
+- [picocom](https://github.com/npat-efault/picocom) - the classic minimal serial terminal
+- [screen](https://www.gnu.org/software/screen/) - the terminal multiplexer is also a serial terminal
+- [minicom](https://salsa.debian.org/minicom-team/minicom) - if you're nostalgic for the DOS era
+- [pyserial's miniterm](https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm) - `python -m serial.tools.miniterm`, already installed if you have pyserial
+
+## Installation and Usage
+
+Install the Python package, which installs the `okterm` utility:
+
+```sh
+pip install ok-serial-terminal
+# or 'uv add ok-serial-terminal', 'uv tool install ok-serial-terminal', etc.
+okterm <port> [baud]
+```
+
+OR, skip the package install and run it directly with [uvx](https://docs.astral.sh/uv/guides/tools/) or [pipx](https://pipx.pypa.io/stable/):
+
+```sh
+uvx ok-serial-terminal <port> [baud]
+# or `pipx run ok-serial-terminal <port> [baud]`
+```
+
+The baud rate defaults to 115200 if omitted. The port is an [ok-serial match expression](https://github.com/egnor/ok-py-serial#port-matching), so `okterm RP2040`, `okterm 2e8a:0005`, and `okterm /dev/ttyACM0` all work. Run [`okserial`](https://github.com/egnor/ok-py-serial#readme) (or `uvx ok-py-serial`) to list visible ports and their attributes.
+
+On a terminal (unless `--plain` is given), `okterm` decorates the display with connection status, control signal state, and an indicator for unechoed typed characters. In this mode, ctrl-`]` opens a menu and ctrl-`\` quits.
+
+In plain mode (I/O redirected or `--plain` given), data is pass-through and ^C quits.
+
+See `okterm --help` for more options (locking mode, etc).
+
+## Socat for testing and profit
+
+On Unix-ish systems, [socat](http://www.dest-unreach.org/socat/) is handy for connecting serial-port apps (`okterm` or otherwise) to non-serial endpoints (like a Unix program or a TCP socket). Install it with your favorite package manager (eg. `sudo apt install socat`), and run something like this in one window:
+
+```sh
+socat pty,raw,echo=0,link=socat.tmp exec:$SHELL,pty,stderr,setsid,ctty
+```
+
+The first socat argument `pty,raw,echo=0,link=socat.tmp` allocates a pseudoterminal (pty) that looks like a serial port, and creates a `./socat.tmp` symlink to the device. The `,raw,echo=0` suppresses default pty echo behavior to avoid the shell looping on its own output.
+
+The second socat argument starts a shell on its own pty, but this could be any socat endpoint (`exec:cat`, `tcp:localhost:8000`, etc).
+
+Socat will then shuffle data between the two points. Try this in another window (in the same directory):
+
+```sh
+okterm socat.tmp
+```
+
+You should get a terminal connected to the pty socat allocated; hit enter and you should see a shell prompt.
+
+(None of this is `okterm`-specific — as far as [ok-serial](https://github.com/egnor/ok-py-serial#readme) is concerned `./socat.tmp` is just another serial port, so `ok_serial.SerialConnection(match="socat.tmp", baud=115200)` works the same way from your own code.)

ok_serial_terminal-0.1/ok_serial_terminal/__init__.py

@@ -0,0 +1,9 @@
+"""
+An interactive serial port terminal built on
+[ok-serial](https://github.com/egnor/ok-py-serial#readme).
+This package is a CLI utility (`okterm`), not a library.
+"""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__)

ok_serial_terminal-0.1/ok_serial_terminal/async_stdio.py

@@ -0,0 +1,107 @@
+import asyncio
+import contextlib
+import logging
+import os
+import select
+import termios
+import typing
+
+log = logging.getLogger(__name__)
+
+# Approach: Both reads and writes *attempt* to use the event loop; if
+# loop.add_reader/writer rejects the fd (file, /dev/null, etc), proceed anyway.
+#
+# Other approaches considered
+# - asyncio.streams.StreamReader/Writer: don't work on files, /dev/null, etc
+# - asyncio.run_in_executor (or similar threading): cancellation is difficult
+# - O_NONBLOCK: breaks other users of the file (eg. stderr writes to same tty)
+
+
+class AsyncReader:
+    """Wraps an OS-level I/O stream with an async read() function.
+    Designed for stdio: pipes, files, ttys/ptys, and /dev/null.
+    """
+
+    def __init__(self, stream: typing.IO) -> None:
+        self._fd = stream.fileno()
+        self._lock = asyncio.Lock()
+        self._loop = asyncio.get_running_loop()
+        self._pollable = True
+
+    async def read(self, size: int) -> bytes:
+        async with self._lock:
+            while True:
+                if self._pollable:
+                    future = self._loop.create_future()
+                    try:
+                        self._loop.add_reader(self._fd, future.set_result, None)
+                        await future
+                    except OSError:
+                        log.debug("FD %d isn't pollable (reading)", self._fd)
+                        self._pollable = False
+                    finally:
+                        self._loop.remove_reader(self._fd)
+
+                with contextlib.suppress(BlockingIOError):
+                    return os.read(self._fd, size)
+
+
+class AsyncWriter:
+    """Wraps an OS-level I/O stream with an async write() function.
+    Designed for stdio: pipes, files, ttys/ptys, and /dev/null.
+    """
+
+    def __init__(self, stream: typing.IO) -> None:
+        self._fd = stream.fileno()
+        self._lock = asyncio.Lock()
+        self._loop = asyncio.get_running_loop()
+        self._pollable = True
+
+    async def write(self, data: bytes) -> None:
+        view = memoryview(data)
+        async with self._lock:
+            while view:
+                if self._pollable:
+                    future = self._loop.create_future()
+                    try:
+                        self._loop.add_writer(self._fd, future.set_result, None)
+                        await future
+                    except OSError:
+                        log.debug("FD %d isn't pollable (writing)", self._fd)
+                        self._pollable = False
+                    finally:
+                        self._loop.remove_writer(self._fd)
+
+                # cap write size to bound blocking (the fd is not O_NONBLOCK);
+                # for pipes/FIFOs, writable poll guarantees PIPE_BUF space
+                # TODO: for ttys/ptys, reopen it by name and use O_NONBLOCK?
+                # TODO: for sockets (eg. systemd logging), use a small write?
+                with contextlib.suppress(BlockingIOError):
+                    view = view[os.write(self._fd, view[: select.PIPE_BUF]) :]
+
+
+@contextlib.contextmanager
+def raw_tty_context(fd: typing.Literal[0, 1, 2]) -> typing.Iterator[bool]:
+    """Returns a context manager that, on entry, if the stdio fd (0, 1, 2)
+    is a terminal, sets it to raw mode and restores original mode on exit."""
+
+    try:
+        old_attr = termios.tcgetattr(fd)
+    except termios.error:
+        logging.debug("FD %d is not a terminal, skipping raw mode", fd)
+        yield False  # not a tty
+        return
+
+    if fd == 0:
+        raw_cc = [int(i == termios.VMIN) for i in range(len(old_attr[6]))]
+        raw_attr = [0, old_attr[1], 0, 0, *old_attr[4:6], raw_cc]
+    else:
+        raw_attr = [old_attr[0], 0, *old_attr[2:]]
+
+    logging.debug("Setting tty fd=%d to raw mode", fd)
+    try:
+        termios.tcsetattr(fd, termios.TCSADRAIN, raw_attr)
+        yield True  # is a tty
+    finally:
+        logging.debug("Restoring tty fd=%d to original mode", fd)
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_attr)

ok_serial_terminal-0.1/ok_serial_terminal/chunker.py

@@ -0,0 +1,121 @@
+import re
+from threading import TIMEOUT_MAX
+
+# TODO: maybe optimize TerminalChunker (and de-chunking); start with a
+# chunker-focused profiling pass. Colorized `xxd` output (SGR codes every few
+# bytes -> ~4-byte chunks) is a good stress test. Ideas: single-pass finditer
+# instead of per-chunk match() calls, batch runs of small text/escape chunks,
+# and accumulate chunk output into a bytearray rather than b"".join() of
+# millions of pieces
+
+_CHUNK_RX = re.compile(
+    # group 1: well-formed UTF-8 code points -- what str.decode() accepts
+    # Grammar: https://datatracker.ietf.org/doc/html/rfc3629#section-4
+    b"((?:"
+    b"[\x20-\x7e]|"  # printable ASCII (other 1-byte are controls, group 5)
+    b"[\xc2-\xdf][\x80-\xbf]|"  # 2-byte
+    # 3-byte, no overlong, no UTF-16 surrogates (U+D800..U+DFFF)
+    b"\xe0[\xa0-\xbf][\x80-\xbf]|[\xe1-\xec][\x80-\xbf]{2}|"
+    b"\xed[\x80-\x9f][\x80-\xbf]|[\xee-\xef][\x80-\xbf]{2}|"
+    # 4-byte, no overlong, no code points > U+10FFFF
+    b"\xf0[\x90-\xbf][\x80-\xbf]{2}|[\xf1-\xf3][\x80-\xbf]{3}|"
+    b"\xf4[\x80-\x8f][\x80-\xbf]{2}"
+    b")+)|"
+    # group 2: incomplete-but-valid UTF-8 prefix at end of data
+    b"("
+    b"[\xc2-\xf4]|"
+    b"\xe0[\xa0-\xbf]|[\xe1-\xec][\x80-\xbf]|"
+    b"\xed[\x80-\x9f]|[\xee-\xef][\x80-\xbf]|"
+    b"\xf0[\x90-\xbf][\x80-\xbf]?|[\xf1-\xf3][\x80-\xbf]{1,2}|"
+    b"\xf4[\x80-\x8f][\x80-\xbf]?"
+    b")\\Z|"
+    # group 3: one complete VTxxx control sequence
+    # https://vt100.net/emu/dec_ansi_parser
+    b"("
+    b"(?:\x1b\\[|\x9b)[\x20-\x3f]*[\x40-\x7e]|"  # CSI
+    b"(?:\x1b[\x50\x58\\]-\x5f]|[\x90\x98\x9d-\x9f])"  # DCS/SOS/OSC/PM/APC
+    b"[\x20-\x7f]*(?:\x07|\x9c|\x1b\\\\)|"  # ...end DCS/SOS/OSC/PM/APC
+    b"(?:\x1b[\x4e\x4f]|[\x8e\x8f])[\x20-\x7e]|"  # SS2/SS3 + char
+    b"\x1b[\x20-\x2f]+[\x30-\x7e]|"  # ESC + intermediates + final (charset)
+    b"\x1b[\x30-\x4d\x51-\x57\x59\x5a\x60-\x7e]"  # ESC-char controls
+    b")|"
+    # group 4: *partial* VTxxx control sequence at end of data
+    b"("
+    b"\x1b\\Z|"  # ESC by itself
+    b"(?:\x1b[\x4e\x4f]|[\x8e\x8f])\\Z|"  # SS2/SS3 awaiting char
+    b"\x1b[\x20-\x2f]+\\Z|"  # ESC + intermediates awaiting final
+    b"(?:\x1b\\[|\x9b)[\x20-\x3f]*\\Z|"  # CSI
+    b"(?:\x1b[\x50\x58\\]-\x5f]|[\x90\x98\x9d-\x9f])[\x20-\x7f]*\x1b?\\Z"
+    b")|"
+    # group 5: any other byte (control char, invalid, etc)
+    b"([\x00-\xff])"
+)
+
+_CHUNK_TIMEOUT = 0.1  # seconds to pause before giving up on partial data
+
+_VALID_TEXT_RX = re.compile("[^\x00-\x1f]+")  # non-control text
+
+
+class TerminalChunker:
+    """Breaks VTxxx data into output characters and control sequences.
+
+    Output attributes:
+    - chunks: received escape codes (bytes) or text (str); caller removes
+    - data_deadline: when to call add_data(b"", now) if nothing received
+    """
+
+    def __init__(self) -> None:
+        self.chunks: list[str | bytes] = []
+        self.data_deadline = TIMEOUT_MAX
+        self._buffer = bytearray()
+
+    def add_data(self, data: bytes, data_time: float) -> None:
+        """Accepts terminal data to be chunked:
+        - data: bytes to process; use b"" if nothing received
+        - data_time: data timestamp in seconds (arbitrary epoch)
+        Appends output to .chunks and updates .data_deadline.
+        """
+
+        if data:
+            self.data_deadline = data_time + _CHUNK_TIMEOUT
+            self._buffer.extend(data)
+            self._process_buffer()
+
+        while self.data_deadline and data_time > self.data_deadline:
+            self.chunks.append(bytes(self._buffer[:1]))
+            del self._buffer[:1]
+            self._process_buffer()
+
+    def _process_buffer(self) -> None:
+        pos = 0
+        while pos < len(self._buffer):
+            match = _CHUNK_RX.match(self._buffer, pos)
+            assert match, self._buffer[pos:]
+            chars, char_part, esc, esc_part, other = match.groups()
+            if chars:
+                self.chunks.append(chars.decode())  # regexp enforces validity
+                pos += len(chars)
+            elif esc:
+                self.chunks.append(esc)
+                pos += len(esc)
+            elif other:
+                self.chunks.append(other)
+                assert len(other) == 1, other
+                pos += 1
+            else:
+                assert self._buffer[pos:] in (char_part, esc_part)
+                break
+
+        del self._buffer[:pos]
+        if not self._buffer:
+            self.data_deadline = TIMEOUT_MAX
+
+
+def chunk_to_bytes(chunk: str | bytes):
+    """Returns the data-stream bytes for a TerminalChunker-type chunk."""
+    assert isinstance(chunk, (str, bytes)), chunk
+    if isinstance(chunk, bytes):
+        return chunk
+    else:
+        assert _VALID_TEXT_RX.fullmatch(chunk), chunk
+        return chunk.encode()

ok_serial_terminal-0.1/ok_serial_terminal/decorator.py

@@ -0,0 +1,243 @@
+import re
+from typing import Literal
+
+from ok_serial_terminal.mode_tracker import TerminalModeTracker
+
+QUERY_PASSTHRU_TIMEOUT = 1.0  # seconds
+CURSOR_QUERY_RX = re.compile(b"(?:\x1b\\[|\x9b)6n")
+CURSOR_REPLY_RX = re.compile(b"(?:\x1b\\[|\x9b)(\\d+);(\\d+)R")
+
+
+class TerminalDecorator:
+    """Modifies terminal output to show extra text around the cursor (for
+    status messages, alerts, etc) without disrupting base rendering too much.
+    Does not perform I/O directly, but processes chunks (per TerminalChunker)
+    on their way to/from the terminal, via these properties:
+
+    Input *queues* (caller should append, culled by .update() as processed):
+    - .add_base (chunk list) - base terminal data from serial port
+    - .add_above (chunk lists) - message lines to insert above the cursor and
+        leave in place (eg. important status messages/logs)
+    - .add_from_terminal (chunk list) - input chunks received from the terminal
+
+    Input *values* (caller should set/update, .update() observes changes):
+    - .set_right - message (chunk list) to show immediately after the cursor,
+        moving with the cursor until removed or replaced
+    - .set_below - message lines (chunk lists) to insert below the cursor,
+        moving with the cursor until removed or replaced
+
+    *Output* queues (appended by .update(), caller should cull once handled):
+    - .out_to_terminal (chunk list) - to send directly to the terminal
+    - .out_from_terminal (chunk list) - filtered terminal input to handle
+
+    "Decorations" (.add_above/.set_below lines, .set_right) can include
+    SGR-type directives (starting from reset each time) but must be a single
+    line without cursor shenanigans. Auto-wrap is disabled so they will cut off.
+
+    Caveats: base rendering isn't disrupted "too much", but...
+    - adding decorations above/below moves lines around and can change the row
+    - adding and removing decorations to the right can erase existing content
+    - decorations get disrupted if base content switches primary/alt screens
+    - if the cursor is outside the scrolling margins, line display is glitchy
+    """
+
+    def __init__(self) -> None:
+        self.add_base: list[bytes | str] = []
+        self.add_above: list[list[bytes | str]] = []
+        self.set_right: list[bytes | str] = []
+        self.set_below: list[list[bytes | str]] = []
+        self.out_to_terminal: list[bytes | str] = []
+
+        self.add_from_terminal: list[bytes | str] = []
+        self.out_from_terminal: list[bytes | str] = []
+        self.pending_query_time: float | None = None  # if query is outstanding
+
+        # terminal mode tracking: the mode set by base content, the mode
+        # to use for decorations, and what the terminal is actually doing
+        self._base_mode = TerminalModeTracker()
+        self._active_mode = self._base_mode
+
+        # cursor tracking: the base cursor column, and cursor excursion status
+        # (between cols, the cursor *row* remains aligned with the base cursor)
+        self._base_col: int | Literal["unknown", "querying"] = 1
+        self._cursor_pos: Literal["base", "roam"] = "base"
+        self._query_passthru: list[float] = []  # expiration times
+
+        # currently displayed right/below decorations for comparison
+        # (above decorations are inserted and left in place forever)
+        self._now_below: list[list[bytes | str]] = []
+        self._now_right: list[bytes | str] = []
+
+    def update(self, time: float) -> None:
+        """Processes input properties and updates output properties.
+        - time: clock time in seconds (with any consistent epoch)
+        """
+
+        # process input from terminal; match against pending passthru queries,
+        # then our own. (note, this assumes no passthru once in "querying")
+        for chunk in self.add_from_terminal:
+            if isinstance(chunk, bytes) and (m := CURSOR_REPLY_RX.match(chunk)):
+                if self._query_passthru:
+                    del self._query_passthru[:1]
+                elif self.pending_query_time is not None:
+                    self.pending_query_time = None
+                    if self._base_col == "querying":
+                        self._base_col = int(m.group(2))
+                    continue  # we issued the query; consume the result
+            self.out_from_terminal.append(chunk)
+        self.add_from_terminal.clear()
+
+        # expire pending passthru queries if we never saw a response
+        while self._query_passthru and time > self._query_passthru[0]:
+            del self._query_passthru[0]
+
+        # strategize - trim decorations right/below of cursor if:
+        # - base content is pending *and* reachable after trimming right/below
+        # - OR right/below decoration content changed and needs updating
+        if self.add_base and (
+            isinstance(self._base_col, int)
+            or (self._can_move_cursor_to_base() and not self._now_below)
+        ):
+            clear_right, keep_below = bool(self._now_right), 0
+        else:
+            clear_right, keep_below = (self.set_right != self._now_right), 0
+            while (
+                keep_below < len(self.set_below)
+                and keep_below < len(self._now_below)
+                and self.set_below[keep_below] == self._now_below[keep_below]
+            ):
+                keep_below += 1
+
+        # clear right of cursor if requested and possible
+        if clear_right and self._can_move_cursor_to_base():
+            self._switch_terminal_mode(self._new_decoration_mode())
+            self._move_cursor_to_base()
+            self._emit(b"\x1b[K")  # caveat: leaves a hole right of cursor
+            self._now_right.clear()
+
+        # delete below decoration rows if requested
+        if del_below := len(self._now_below) - keep_below:
+            assert del_below > 0, (self._now_below, keep_below)
+            self._switch_terminal_mode(self._new_decoration_mode())
+            self._prepare_cursor_to_roam(time)  # deleting rows moves left
+            self._emit(
+                b"\x1b[%dB" % (keep_below + 1),  # move down
+                b"\x1b[%dM" % del_below,  # delete rows
+                b"\x1b[%dA" % (keep_below + 1),  # move back up
+            )
+            del self._now_below[-del_below:]
+
+        # add base content if provided, reachable, and clear of decorations
+        if self.add_base and (
+            self._can_move_cursor_to_base()
+            and not (self._now_right or self._now_below)
+        ):
+            assert self._base_col != "querying", self._base_col
+            self._move_cursor_to_base()
+            self._switch_terminal_mode(self._base_mode)
+            self._emit(*self.add_base)
+            for chunk in self.add_base:
+                self._base_col = 1 if chunk == b"\n" else "unknown"
+                if isinstance(chunk, bytes) and CURSOR_QUERY_RX.match(chunk):
+                    self._query_passthru.append(time + QUERY_PASSTHRU_TIMEOUT)
+            self.add_base.clear()
+
+        # add/replace right decoration if provided and reachable
+        if self.set_right and (
+            self._can_move_cursor_to_base() and not self._now_right
+        ):
+            self._switch_terminal_mode(self._new_decoration_mode())
+            self._move_cursor_to_base()
+            self._prepare_cursor_to_roam(time)  # adding content moves cursor
+            self._emit(*self.set_right)
+            self._now_right[:] = self.set_right
+
+        # insert lines above if requested
+        if self.add_above:
+            self._switch_terminal_mode(self._new_decoration_mode())
+            self._prepare_cursor_to_roam(time)  # adding content moves cursor
+            self._emit(
+                *[b"\n"] * len(self.add_above),  # scroll down to make room
+                b"\x1b[%dA" % len(self.add_above),  # move back up
+                b"\x1b[%dL" % len(self.add_above),  # insert rows
+            )
+            self._emit(b"\r", *self.add_above[0], b"\n")
+            for next_line in self.add_above[1:]:
+                self._switch_terminal_mode(self._new_decoration_mode())
+                self._emit(b"\r", *next_line, b"\n")  # ends at base row
+            self.add_above.clear()
+
+        # insert lines below if requested
+        assert len(self.set_below) >= len(self._now_below)
+        if len(self.set_below) > len(self._now_below):
+            skip_lines = len(self._now_below)
+            assert self.set_below[:skip_lines] == self._now_below
+            self._switch_terminal_mode(self._new_decoration_mode())
+            self._prepare_cursor_to_roam(time)  # adding content moves cursor
+            self._emit(*([b"\n"] * skip_lines))
+            for next_line in self.set_below[skip_lines:]:
+                self._switch_terminal_mode(self._new_decoration_mode())
+                self._emit(b"\r", b"\n", *next_line)
+                self._now_below.append(next_line[:])
+            self._emit(b"\x1b[%dA" % len(self.set_below))  # ends at base row
+
+        if self._can_move_cursor_to_base():
+            self._move_cursor_to_base()  # leave the cursor there if possible
+
+    def reset(self) -> None:
+        """Adds cleanup to .out_to_terminal (*without* an update cycle):
+        - resets terminal mode to default state
+        - clears the screen after & below the cursor
+        - moves to a new line if we're not positioned at start of line
+        - (for possible restart) updates mode tracking
+        - (for possible restart) clears right & below decoration setting
+        """
+
+        self._base_mode = TerminalModeTracker()  # reset to default state
+        self._switch_terminal_mode(self._base_mode)
+        self._emit(b"\x1b7", b"\x1b[r", b"\x1b8")  # reset DECSTBM margins
+        self._emit(b"\x1b[J")  # clear from cursor to end of display
+        if (self._cursor_pos, self._base_col) != ("base", 1):
+            self._cursor_pos, self._base_col = "base", 1  # in case of restart
+            self._emit(b"\r", b"\n")  # newline to move past the base line
+        self.set_right.clear()
+        self.set_below.clear()
+
+    def _can_move_cursor_to_base(self) -> bool:
+        return self._cursor_pos == "base" or isinstance(self._base_col, int)
+
+    def _move_cursor_to_base(self) -> None:
+        assert self._can_move_cursor_to_base()
+        if self._cursor_pos != "base":
+            assert isinstance(self._base_col, int), self._base_col
+            self.out_to_terminal.append(b"\x1b[%dG" % self._base_col)
+            self._cursor_pos = "base"
+
+    def _prepare_cursor_to_roam(self, time: float) -> None:
+        if (self._cursor_pos, self._base_col) == ("base", "unknown"):
+            self.out_to_terminal.append(b"\x1b[6n")
+            self.pending_query_time = time
+            self._base_col = "querying"
+        self._cursor_pos = "roam"
+
+    def _switch_terminal_mode(self, mode: TerminalModeTracker) -> None:
+        if mode is not self._active_mode:
+            mode_chunks = mode.mode_chunks(base=self._active_mode)
+            self.out_to_terminal.extend(mode_chunks)
+            self._active_mode = mode
+
+    def _new_decoration_mode(self) -> TerminalModeTracker:
+        mode = self._base_mode.copy()
+        mode.add_chunk(b"\x0f")  # use G0
+        mode.add_chunk(b"\x1b(B")  # G0 = US-ASCII
+        mode.add_chunk(b'\x1b[0"q')  # character protection off
+        mode.add_chunk(b"\x1b[m")  # reset SGR
+        mode.add_chunk(b"\x1b[4l")  # reset IRM - no insert mode
+        mode.add_chunk(b"\x1b[20l")  # reset LNM - normal newline mode
+        mode.add_chunk(b"\x1b[?7l")  # reset DECAWM - do not wrap at EOL
+        return mode
+
+    def _emit(self, *chunks: bytes | str) -> None:
+        self.out_to_terminal.extend(chunks)
+        for chunk in chunks:
+            self._active_mode.add_chunk(chunk)