tui: typed cell colors, handle-owned i/o, and spawn-time sizing

Core crate:
- replace stringly StyledCell.fgcolor/bgcolor ("idx:5", "rgb:1,2,3") with a
  typed Color enum (Default/Indexed/Rgb) and rename to fg/bg.
- move all read/write methods onto the self-sufficient TuiInstance handle and
  drop the unused_self-forced TuiManager static async fns; the manager now just
  spawns, tracks, and shares its runtime into each handle.
- collapse the duplicated send/await boilerplate into one generic reader::request.
- add SpawnConfig for spawn-time rows/cols/scrollback (size was hardcoded).
- take Duration instead of u64 ms in the blocking API; give ArrayConversion a
  real ndarray::ShapeError source.
- delete the dead Cache module (exported but never used).

Python bindings:
- expose color as the pythonic int | tuple[int,int,int] | None (None=default).
- collapse the three redundant StyledCell reprs into the native class and drop
  the redundant native FullOutput pyclass (read_full returns a tuple).
- add rows/cols to the constructor; defaults flow from core SpawnConfig.

Fix stale READMEs (scrollback was claimed unimplemented; TuiInfo and runtime
ioctl resize never existed).

Author: andrewgazelka

packages/tui-py/README.md

@@ -47,6 +47,13 @@ with Tui("python", "-q") as tui:
 `tui.snapshot()` returns a frozen `Snapshot` (viewport, scrollback, size). It
 supports `str(snap)`, `"needle" in snap`, and `.text` / `.full_text`.
 
+The terminal opens at 80x24 with 10,000 lines of scrollback. Override per
+instance with keyword args:
+
+```python
+Tui("bash", "--norc", "-i", rows=40, cols=120, scrollback_lines=50_000)
+```
+
 ## Examples
 
 ### Drive a REPL and read its output
@@ -121,7 +128,10 @@ with Tui("bash", "--norc", "-i") as t:
 
 `tui.chars()` returns a `numpy.uint32` array of Unicode codepoints, shape
 `(rows, cols)`. `tui.styled_cells()` returns a nested list of `StyledCell`
-dataclasses (`char`, `fg`, `bg`, `bold`, `italic`, `underline`, `inverse`).
+objects (`char`, `fg`, `bg`, `bold`, `italic`, `underline`, `inverse`).
+
+`fg` and `bg` are `Color` values: `None` for the terminal default, an `int` in
+`0..=255` for a palette index, or an `(r, g, b)` tuple for truecolor.
 
 ```python
 import numpy as np
@@ -136,6 +146,7 @@ with Tui("bash", "--norc", "-i") as t:
     styled = t.styled_cells()
     bolds = [(r, c) for r, row in enumerate(styled)
                     for c, cell in enumerate(row) if cell.bold]
+    reds = [cell.char for row in styled for cell in row if cell.fg == 1]
 ```
 
 ### Handle timeouts
@@ -170,7 +181,8 @@ print(len(Tui.list_all()))   # 2
 | `Snapshot`     | Frozen viewport + scrollback + size.                   |
 | `Size`         | `(rows, cols)` dataclass.                              |
 | `Key`          | ANSI keystroke constants + `Key.ctrl`/`Key.alt`.       |
-| `StyledCell`   | One cell with VT100 attributes.                        |
+| `StyledCell`   | One cell: `char`, `fg`/`bg`, and VT100 attributes.     |
+| `Color`        | `None` (default), `int` (palette), or `(r, g, b)`.     |
 | `WaitTimeout`  | Raised by `wait_for` / `await_for` on deadline expiry. |
 
 [maturin]: https://www.maturin.rs/

packages/tui-py/python/tui/__init__.py

@@ -8,6 +8,7 @@
     Size            (rows, cols) terminal size
     Key             common keystrokes as ANSI byte strings, with .ctrl/.alt
     StyledCell      one viewport cell: character + VT100 attributes
+    Color           a cell color: None (default), int (palette), or (r, g, b)
     WaitTimeout     raised by `Tui.wait_for(...)` when nothing matched in time
 
 Every blocking I/O method has an `a`-prefixed coroutine variant that returns a
@@ -31,11 +32,13 @@
 from numpy.typing import NDArray
 
 from ._tui import (
+    StyledCell as StyledCell,
     TuiInstance as _RawTuiInstance,
     __version__,
 )
 
 __all__ = [
+    "Color",
     "Key",
     "Pattern",
     "Size",
@@ -52,6 +55,12 @@
 # --------------------------------------------------------------------------- #
 
 
+#: A VT100 cell color: `None` is the terminal default, an `int` in `0..=255` is
+#: a palette index, and an `(r, g, b)` tuple is 24-bit truecolor. Read off a
+#: `StyledCell` via `cell.fg` / `cell.bg`.
+Color: TypeAlias = int | tuple[int, int, int] | None
+
+
 @dataclass(frozen=True, slots=True)
 class Size:
     """Terminal dimensions, in cells."""
@@ -64,22 +73,6 @@ def __iter__(self) -> Iterator[int]:
         yield self.cols
 
 
-@dataclass(frozen=True, slots=True)
-class StyledCell:
-    """One viewport cell with its VT100 attributes.
-
-    `fg`/`bg` are vt100-formatted color strings or `None` for the default.
-    """
-
-    char: str
-    fg: str | None
-    bg: str | None
-    bold: bool
-    italic: bool
-    underline: bool
-    inverse: bool
-
-
 @dataclass(frozen=True, slots=True)
 class Snapshot:
     """An immutable view of a Tui at a single point in time."""
@@ -191,21 +184,6 @@ def _build_predicate(pattern: Pattern) -> Callable[[Snapshot], bool]:
     return pattern
 
 
-def _wrap_styled(raw_row: list) -> list[StyledCell]:
-    return [
-        StyledCell(
-            char=c.character,
-            fg=c.fgcolor,
-            bg=c.bgcolor,
-            bold=c.bold,
-            italic=c.italic,
-            underline=c.underline,
-            inverse=c.inverse,
-        )
-        for c in raw_row
-    ]
-
-
 # --------------------------------------------------------------------------- #
 # Tui
 # --------------------------------------------------------------------------- #
@@ -220,10 +198,11 @@ class Tui:
             tui.enter("1 + 2")
             snap = tui.wait_for("3", timeout=2.0)
 
-    A single process-wide tokio runtime drives every spawned PTY. Sync methods
-    release the GIL on the underlying Rust call; async methods return native
-    asyncio coroutines bridged through pyo3-async-runtimes — no thread-pool
-    hop.
+    The terminal opens at `rows` x `cols` (default 80x24) with `scrollback_lines`
+    of history (default 10,000). A single process-wide tokio runtime drives
+    every spawned PTY. Sync methods release the GIL on the underlying Rust call;
+    async methods return native asyncio coroutines bridged through
+    pyo3-async-runtimes, with no thread-pool hop.
 
     There is no force-kill path today. `interrupt()` sends Ctrl+C, which most
     cooperative programs respect; `with` blocks will interrupt on exit.
@@ -235,9 +214,11 @@ def __init__(
         self,
         command: str,
         *args: str,
-        scrollback_lines: int = 10_000,
+        rows: int | None = None,
+        cols: int | None = None,
+        scrollback_lines: int | None = None,
     ) -> None:
-        self._raw = _RawTuiInstance(command, list(args), scrollback_lines)
+        self._raw = _RawTuiInstance(command, list(args), rows, cols, scrollback_lines)
 
     @classmethod
     def _from_raw(cls, raw: _RawTuiInstance) -> Self:
@@ -311,10 +292,10 @@ def text(self) -> str:
 
     def snapshot(self) -> Snapshot:
         """Immutable point-in-time view of viewport + scrollback."""
-        full = self._raw.read_full()
+        scrollback, viewport = self._raw.read_full()
         return Snapshot(
-            viewport=tuple(full.viewport),
-            scrollback=tuple(full.scrollback),
+            viewport=tuple(viewport),
+            scrollback=tuple(scrollback),
             size=self.size,
         )
 
@@ -334,7 +315,7 @@ def chars(self) -> NDArray[np.uint32]:
 
     def styled_cells(self) -> list[list[StyledCell]]:
         """Per-cell styling for the viewport, indexed as `[row][col]`."""
-        return [_wrap_styled(row) for row in self._raw.read_styled_cells()]
+        return self._raw.read_styled_cells()
 
     # -- waits --------------------------------------------------------------
 
@@ -384,19 +365,18 @@ async def aread(self, *, timeout: float | None = None) -> list[str]:
 
     async def asnapshot(self) -> Snapshot:
         """Native asyncio-awaitable snapshot."""
-        full = await self._raw.read_full_async()
+        scrollback, viewport = await self._raw.read_full_async()
         return Snapshot(
-            viewport=tuple(full.viewport),
-            scrollback=tuple(full.scrollback),
+            viewport=tuple(viewport),
+            scrollback=tuple(scrollback),
             size=self.size,
         )
 
     async def achars(self) -> NDArray[np.uint32]:
         return await self._raw.read_chars_array_async()
 
     async def astyled_cells(self) -> list[list[StyledCell]]:
-        rows = await self._raw.read_styled_cells_async()
-        return [_wrap_styled(row) for row in rows]
+        return await self._raw.read_styled_cells_async()
 
     async def await_for(
         self,

packages/tui-py/python/tui/_tui.pyi

@@ -9,21 +9,26 @@ pyo3-async-runtimes; awaiting them drives the underlying tokio future.
 from __future__ import annotations
 
 from collections.abc import Awaitable
+from typing import TypeAlias
 
 import numpy as np
 from numpy.typing import NDArray
 
 __version__: str
 
+#: A cell color: `None` is the terminal default, an `int` is a palette index,
+#: an `(r, g, b)` tuple is truecolor.
+_Color: TypeAlias = int | tuple[int, int, int] | None
+
 class StyledCell:
     """A single terminal cell: character plus VT100 styling."""
 
     @property
-    def character(self) -> str: ...
+    def char(self) -> str: ...
     @property
-    def fgcolor(self) -> str | None: ...
+    def fg(self) -> _Color: ...
     @property
-    def bgcolor(self) -> str | None: ...
+    def bg(self) -> _Color: ...
     @property
     def bold(self) -> bool: ...
     @property
@@ -34,28 +39,19 @@ class StyledCell:
     def inverse(self) -> bool: ...
     def __repr__(self) -> str: ...
 
-class FullOutput:
-    """Snapshot of both scrollback history and the current viewport."""
-
-    @property
-    def scrollback(self) -> list[str]: ...
-    @property
-    def viewport(self) -> list[str]: ...
-    def __repr__(self) -> str: ...
-
 class TuiInstance:
     """A handle to a single spawned TUI process. Spawning is the constructor."""
 
     def __init__(
         self,
         command: str,
         args: list[str] | None = ...,
-        scrollback_lines: int = ...,
+        rows: int | None = ...,
+        cols: int | None = ...,
+        scrollback_lines: int | None = ...,
     ) -> None: ...
-
     @staticmethod
     def list_all() -> list[TuiInstance]: ...
-
     @property
     def id(self) -> str: ...
     @property
@@ -73,7 +69,7 @@ class TuiInstance:
     def write(self, data: str) -> None: ...
     def read_viewport(self) -> list[str]: ...
     def read_scrollback(self) -> list[str]: ...
-    def read_full(self) -> FullOutput: ...
+    def read_full(self) -> tuple[list[str], list[str]]: ...
     def read_blocking(self, timeout_ms: int) -> list[str]: ...
     def read_chars_array(self) -> NDArray[np.uint32]: ...
     def read_styled_cells(self) -> list[list[StyledCell]]: ...
@@ -82,9 +78,8 @@ class TuiInstance:
     def write_async(self, data: str) -> Awaitable[None]: ...
     def read_viewport_async(self) -> Awaitable[list[str]]: ...
     def read_scrollback_async(self) -> Awaitable[list[str]]: ...
-    def read_full_async(self) -> Awaitable[FullOutput]: ...
+    def read_full_async(self) -> Awaitable[tuple[list[str], list[str]]]: ...
     def read_blocking_async(self, timeout_ms: int) -> Awaitable[list[str]]: ...
     def read_chars_array_async(self) -> Awaitable[NDArray[np.uint32]]: ...
     def read_styled_cells_async(self) -> Awaitable[list[list[StyledCell]]]: ...
-
     def __repr__(self) -> str: ...

packages/tui-py/src/lib.rs

@@ -1,16 +1,14 @@
 //! Python bindings for the `tui` PTY-backed terminal management library.
 //!
 //! All blocking calls release the GIL via `Python::detach`, so multiple
-//! Python threads can drive the same manager concurrently.
+//! Python threads can drive the same manager concurrently. Async methods
+//! return native asyncio-awaitable coroutines bridged through
+//! pyo3-async-runtimes.
 
 #![allow(
     clippy::missing_const_for_fn,
     reason = "pyo3 getter methods cannot be const because they are dispatched through the pymethod vtable"
 )]
-#![allow(
-    clippy::struct_excessive_bools,
-    reason = "VT100 cell attributes are intrinsically four parallel booleans"
-)]
 
 mod manager;
 mod types;
@@ -20,7 +18,6 @@ use pyo3::prelude::*;
 #[pymodule]
 fn _tui(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_class::<manager::TuiInstance>()?;
-    module.add_class::<types::FullOutput>()?;
     module.add_class::<types::StyledCell>()?;
     module.add("__version__", env!("CARGO_PKG_VERSION"))?;
     Ok(())