xnano.terminal

@classmethod
def offscreen(
    cls,
    *,
    cols: int = 40,
    rows: int = 12,
    state: StateT | None = None,
    title: str | None = None,
) -> "Terminal[StateT]":
    """Create a terminal backed by an in-memory cell buffer."""
    terminal = cls(state=state, title=title)
    terminal._runtime = Runtime.offscreen(
        cols,
        rows,
        state=state,
        title=title,
    )
    terminal.surface = "offscreen"
    return terminal

@staticmethod
def supports_live_terminal() -> bool:
    """Return whether interactive terminal sessions are available."""
    return Runtime.supports_live_terminal()

def attach_grid(self, grid: Any) -> None:
    """Set the grid used by subsequent renders and dispatch."""
    self.runtime.set_root(grid)

def render(
    self,
    *renderables: Any,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    border: Border | None = None,
    border_sides: Sequence[Side] | None = None,
    border_color: ColorLike | None = None,
    title: str | None = None,
    title_position: FrameTitlePosition | None = None,
    padding: PaddingLike | None = None,
    gap: int = 0,
    direction: Direction = "vertical",
    color: ColorLike | None = None,
    align: Alignment | None = None,
) -> Frame:
    """Paint one frame and return its immutable snapshot.

    Args:
        *renderables: Grids, components, content primitives, or plain
            values to paint.
        foreground: Foreground color applied to plain values.
        background: Background color for the rendered area.
        modifiers: Character modifiers applied to plain values.
        horizontal_align: Horizontal alignment applied to plain values.
    vertical_align: Vertical alignment applied to plain values.
        border: Border style around the rendered area.
        border_sides: Border sides to draw.
        border_color: Border foreground color.
        title: Optional border title.
        title_position: Border edge that holds the title.
        padding: Space between the border and content.
        gap: Cells between multiple renderables.
        direction: Direction used to lay out multiple renderables.

    Returns:
        A snapshot of the rendered terminal frame.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    horizontal_align = resolve_renamed_alias(
        horizontal_align,
        align,
        old="align",
        new="horizontal_align",
        stacklevel=3,
    )
    runtime = self._ensure_runtime()
    if renderables:
        runtime.set_root(renderables[0] if len(renderables) == 1 else None)
    return runtime.render(
        *renderables,
        foreground=foreground,
        background=background,
        modifiers=modifiers,
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        border=border,
        border_sides=border_sides,
        border_color=border_color,
        title=title,
        title_position=title_position,
        padding=padding,
        gap=gap,
        direction=direction,
    )

def run(
    self,
    *renderables: Any,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    border: Border | None = None,
    border_sides: Sequence[Side] | None = None,
    border_color: ColorLike | None = None,
    title: str | None = None,
    title_position: FrameTitlePosition | None = None,
    padding: PaddingLike | None = None,
    gap: int = 0,
    direction: Direction = "vertical",
    color: ColorLike | None = None,
    align: Alignment | None = None,
) -> None:
    """Render and dispatch events until an exit is requested.

    Args:
        *renderables: Grids, components, content primitives, or plain
            values to paint.
        foreground: Foreground color applied to plain values.
        background: Background color for the rendered area.
        modifiers: Character modifiers applied to plain values.
        horizontal_align: Horizontal alignment applied to plain values.
    vertical_align: Vertical alignment applied to plain values.
        border: Border style around the rendered area.
        border_sides: Border sides to draw.
        border_color: Border foreground color.
        title: Optional border title.
        title_position: Border edge that holds the title.
        padding: Space between the border and content.
        gap: Cells between multiple renderables.
        direction: Direction used to lay out multiple renderables.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    horizontal_align = resolve_renamed_alias(
        horizontal_align,
        align,
        old="align",
        new="horizontal_align",
        stacklevel=3,
    )
    runtime = self._ensure_runtime(live=True)
    if renderables:
        runtime.set_root(renderables[0] if len(renderables) == 1 else None)
    live = runtime.is_live
    render_frame = runtime._render if live else runtime.render
    try:
        while True:
            render_frame(
                *renderables,
                foreground=foreground,
                background=background,
                modifiers=modifiers,
                horizontal_align=horizontal_align,
                vertical_align=vertical_align,
                border=border,
                border_sides=border_sides,
                border_color=border_color,
                title=title,
                title_position=title_position,
                padding=padding,
                gap=gap,
                direction=direction,
            )
            if live:
                runtime._frame_commands.clear()
            if not runtime.pump():
                break
    finally:
        self.close()

def request_exit(self) -> None:
    """Stop the active run loop."""
    if self._runtime is not None:
        self._runtime.request_exit()

def focus(self, group: str) -> bool:
    """Focus a named field group."""
    return self.runtime.focus(group)

def blur(self) -> None:
    """Clear field focus."""
    self.runtime.blur()

def focus_next(self) -> bool:
    """Move focus forward."""
    return self.runtime.focus_next()

def focus_previous(self) -> bool:
    """Move focus backward."""
    return self.runtime.focus_previous()

def get_output(self) -> str:
    """Return the current cell buffer as plain text."""
    return self.runtime.get_output()

def get_output_as_ansi(self) -> str:
    """Return the current cell buffer with ANSI styling."""
    return self.runtime.get_output_as_ansi()

def copy_to_clipboard(self, text: str) -> bool:
    """Copy text when the active platform supports clipboard writes."""
    return self.runtime.device.copy_to_clipboard(text)

def close(self) -> None:
    """Restore and release the owned runtime."""
    if self._runtime is not None:
        self._runtime.close()
        self._runtime = None