xnano_core.rust.engine

xnano_core.rust.engine ¶

Runtime shim for the Rust-implemented engine submodule. Importing :mod:xnano_core.rust.native registers the real module object on sys.modules under this name.

Classes:

IrLine –

A pre-built ratatui Line<'static> constructed in a single boundary crossing.
CoreRenderIR –

IR node that carries all widget data for a single widget.
CoreKeyBinding –

Parsed form of an xnano keyboard binding string such as "ctrl+q".
CoreTerminalEventKind –

Discriminator for :class:CoreEvent.
CoreTickEvent –

Synthetic clock tick emitted by :class:CoreSession.
CoreEvent –

Unified event delivered by the session event loop.
CoreRenderContent –

Tagged payload that a :class:CoreRenderNode paints into its rect.
CoreRenderNode –

A single node in the render tree.
CoreTerminalRef –

Scope-guarded handle to the live ratatui DefaultTerminal.
CoreSession –

Owner of the terminal, event loop, effects, and device state.
CoreTextEditor –

Stateful multi-line text editor backing editable Text fields.

CoreDrawableCallback `module-attribute` ¶

CoreDrawableCallback = collections.abc.Callable[
    [Buffer, Rect], None
]

Signature for :meth:CoreRenderContent.drawable callbacks.

The callback receives a mutable :class:~xnano_core.rust.native.Buffer view scoped to the node's rect plus the rect itself. The buffer view is valid only for the duration of the callback; the engine invalidates it on return.

Any exception raised inside the callback is captured by the engine, propagated back to the outer :meth:CoreSession.render call, and re-raised as a Python exception without leaving the terminal in a broken state.

IrLine ¶

A pre-built ratatui Line<'static> constructed in a single boundary crossing.

Methods:

raw –

Build an unstyled line from a plain string.
styled –

Build a uniformly styled line.
from_spans –

Build a line from a list of (content, fg, bg, modifiers) tuples.

raw `staticmethod` ¶

raw(content: str) -> IrLine

Build an unstyled line from a plain string.

styled `staticmethod` ¶

styled(
    content: str,
    fg: Any | None = None,
    bg: Any | None = None,
    modifiers: List[Any] = ...,
) -> IrLine

Build a uniformly styled line.

from_spans `staticmethod` ¶

from_spans(
    spans: List[Tuple[str, Any, Any, List[Any]]],
) -> IrLine

Build a line from a list of (content, fg, bg, modifiers) tuples.

CoreRenderIR ¶

IR node that carries all widget data for a single widget.

The entire data needed to build and render a ratatui widget is passed in one Python→Rust boundary crossing instead of 3-4. measure() returns the natural size without rendering; CoreRenderContent.ir(ir) schedules rendering entirely on the Rust side.

Methods:

measure –

Return the natural (width, height) of this IR node in character cells.

measure ¶

measure() -> Tuple[int, int]

Return the natural (width, height) of this IR node in character cells.

CoreKeyBinding ¶

Parsed form of an xnano keyboard binding string such as "ctrl+q".

Matching is performed entirely in Rust — no Python string manipulation per event. Instances should be cached and reused across multiple events.

Methods:

parse –

Parse a binding string into a CoreKeyBinding.
matches –

Return True if event matches this binding.

parse `staticmethod` ¶

parse(binding: str) -> CoreKeyBinding

Parse a binding string into a CoreKeyBinding.

Parameters:

binding (str) –

An xnano-style binding string such as "ctrl+q", "shift+up", "f5", or "enter".

Returns:

CoreKeyBinding –

A CoreKeyBinding ready for :meth:matches calls.

Raises:

ValueError –

If the binding string is empty, contains an unknown modifier, or names an unrecognised key.

matches ¶

matches(event: KeyEvent) -> bool

Return True if event matches this binding.

Parameters:

event (KeyEvent) –

A native :class:~xnano_core.rust.native.KeyEvent.

Returns:

bool –

True when the key code and modifier flags all match.

CoreTerminalEventKind ¶

Discriminator for :class:CoreEvent.

Attributes:

Key (CoreTerminalEventKind) –

The event carries a keyboard :class:~xnano_core.rust.native.KeyEvent.
Resize (CoreTerminalEventKind) –

The terminal reports a new size. width and height on the event are populated.
Paste (CoreTerminalEventKind) –

The terminal reports bracketed-paste content. paste on the event is populated.
Mouse (CoreTerminalEventKind) –

The event carries a :class:~xnano_core.rust.native.MouseEvent.
FocusGained (CoreTerminalEventKind) –

The terminal window received focus. No payload.
FocusLost (CoreTerminalEventKind) –

The terminal window lost focus. No payload.
Tick (CoreTerminalEventKind) –

The event was synthesized by the session tick clock. tick on the event is populated with a :class:CoreTickEvent.

CoreTickEvent ¶

Synthetic clock tick emitted by :class:CoreSession.

Ticks are only produced when the session was constructed with tick_rate_ms set. They are opt-in: a session with no configured tick interval never yields Tick events, so downstream consumers can rely on poll_event blocking purely on real input.

Attributes:

elapsed_ms (int) –

Milliseconds elapsed since the previous tick was emitted (or since :meth:CoreSession.init for the first tick).

CoreEvent ¶

Unified event delivered by the session event loop.

Exactly one of key, paste, mouse, or tick is populated for each kind; on Resize events both width and height are set; FocusGained / FocusLost carry no payload. Consumers should dispatch on kind and read only the associated payload field.

Attributes:

kind (CoreTerminalEventKind) –

Which of the seven event kinds this event represents.
key (Optional[KeyEvent]) –

Populated when kind == CoreTerminalEventKind.Key.
width (Optional[int]) –

Populated when kind == CoreTerminalEventKind.Resize.
height (Optional[int]) –

Populated when kind == CoreTerminalEventKind.Resize.
paste (Optional[str]) –

Populated when kind == CoreTerminalEventKind.Paste.
mouse (Optional[MouseEvent]) –

Populated when kind == CoreTerminalEventKind.Mouse.
tick (Optional[CoreTickEvent]) –

Populated when kind == CoreTerminalEventKind.Tick.

Methods:

kind_str –

Return the event kind as a lowercase string.

kind_str ¶

kind_str() -> Literal[
    "key",
    "resize",
    "paste",
    "mouse",
    "focus_gained",
    "focus_lost",
    "tick",
]

Return the event kind as a lowercase string.

CoreRenderContent ¶

Tagged payload that a :class:CoreRenderNode paints into its rect.

Instances are opaque — construct via the four static constructors and inspect via the is_* predicates. Content values are cheaply cloneable (widget/state/callback references are Py<PyAny> handles, not deep copies).

Attributes:

__module__ –

Always "xnano_core.rust.engine".

Methods:

empty –

Create a content variant that paints nothing.
widget –

Wrap a stateless widget for rendering.
stateful –

Wrap a stateful widget together with its mutable state.
drawable –

Wrap a Python callback that draws directly into the buffer.
ir –

Wrap a :class:CoreRenderIR for rendering entirely in Rust.
is_empty –

Whether this content variant is :meth:empty.
is_stateful –

Whether this content variant is :meth:stateful.
is_drawable –

Whether this content variant is :meth:drawable.
is_ir –

Whether this content variant is an :meth:ir node.

empty `staticmethod` ¶

empty() -> CoreRenderContent

Create a content variant that paints nothing.

Empty content is the default when a node is used purely for layout or grouping — the engine skips the paint step entirely for these nodes.

Returns:

CoreRenderContent –

A CoreRenderContent whose :meth:is_empty returns True.

widget `staticmethod` ¶

widget(widget: Any) -> CoreRenderContent

Wrap a stateless widget for rendering.

The engine will attempt, in order:

If widget has a _to_core method, call it and use the result.
Otherwise if widget has an _inner attribute, use that.
Otherwise treat widget as one of the built-in native widget types (Paragraph, Block, List, Table, Gauge, Tabs, Sparkline, LineGauge, BarChart, Chart, Canvas, Clear, Span, Line, Text).
Otherwise call widget.render(area) and recurse on the result.

Parameters:

widget (Any) –

A native widget instance, a duck-typed object exposing _to_core or _inner, or a callable Python object whose render(area) returns something in one of the above forms.

Returns:

CoreRenderContent –

A CoreRenderContent whose :meth:is_empty returns False
CoreRenderContent –

and whose :meth:is_stateful and :meth:is_drawable return
CoreRenderContent –

False.

stateful `staticmethod` ¶

stateful(widget: Any, state: Any) -> CoreRenderContent

Wrap a stateful widget together with its mutable state.

Supports the three ratatui stateful widgets currently bridged: List+ListState, Table+TableState, Scrollbar+ScrollbarState. Any other pairing raises TypeError at render time.

Parameters:

widget (Any) –

A stateful native widget instance.
state (Any) –

The corresponding state instance. The engine borrows it mutably during render; do not mutate it from another thread during a render call.

Returns:

CoreRenderContent –

A CoreRenderContent whose :meth:is_stateful returns True.

drawable `staticmethod` ¶

drawable(
    callback: CoreDrawableCallback,
) -> CoreRenderContent

Wrap a Python callback that draws directly into the buffer.

The callback receives a scope-guarded mutable view onto the live buffer and the rect it should draw into. Use this for custom rendering that doesn't fit the built-in widget catalog.

Parameters:

callback (CoreDrawableCallback) –

A callable (buffer, rect) -> None. The buffer argument is a scope-guarded view (see :class:~xnano_core.rust.native.BufferMutView) that becomes invalid the instant the callback returns.

Returns:

CoreRenderContent –

A CoreRenderContent whose :meth:is_drawable returns True.

ir `staticmethod` ¶

ir(ir: CoreRenderIR) -> CoreRenderContent

Wrap a :class:CoreRenderIR for rendering entirely in Rust.

No Python widget construction occurs during :meth:CoreSession.render; the IR is lowered to a ratatui widget and painted in a single Rust call.

Parameters:

ir (CoreRenderIR) –

A :class:CoreRenderIR produced by one of its factory methods.

Returns:

CoreRenderContent –

A CoreRenderContent whose :meth:is_ir returns True.

is_empty ¶

is_empty() -> bool

Whether this content variant is :meth:empty.

Returns:

bool –

True if the variant is Empty, False otherwise.

is_stateful ¶

is_stateful() -> bool

Whether this content variant is :meth:stateful.

Returns:

bool –

True if the variant is Stateful, False otherwise.

is_drawable ¶

is_drawable() -> bool

Whether this content variant is :meth:drawable.

Returns:

bool –

True if the variant is Drawable, False otherwise.

is_ir ¶

is_ir() -> bool

Whether this content variant is an :meth:ir node.

Returns:

bool –

True if the variant is Ir, False otherwise.

CoreRenderNode ¶

CoreRenderNode(
    *,
    x: Optional[int] = None,
    y: Optional[int] = None,
    width: Optional[int] = None,
    height: Optional[int] = None,
    direction: Optional[Direction] = None,
    gap: int = 0,
    constraints: Optional[Sequence[Constraint]] = None,
    margin: Optional[Margin] = None,
    content: Optional[CoreRenderContent] = None,
    cursor_hint: Optional[tuple[int, int]] = None,
    effect_key: Optional[str] = None,
    z: int = 0,
    visible: bool = True,
    children: Optional[Sequence[CoreRenderNode]] = None
)

A single node in the render tree.

Every node contributes to the frame in three ways:

Geometry: either absolute (x/y/width/height all set, which the tree walk treats as a stacking context anchor) or constraint-derived from the parent's direction+constraints.
Paint: a :class:CoreRenderContent painted into the resolved rect.
Children: laid out under this node's direction/constraints/gap, optionally with a margin applied to the parent rect first.

The engine walks children in ascending z order (stable sort). Nodes with matching z paint in declaration order — later siblings paint over earlier ones, exactly like the pre-z behavior. Nodes with visible=False are skipped entirely: neither they nor their descendants are laid out, painted, or considered for cursor placement or effect-area tracking. A hidden subtree still occupies the layout slot the parent reserved for it (matching CSS visibility: hidden semantics rather than display: none); if the framework needs true collapse it should omit the node from the tree entirely.

z is sibling-local: it orders paint among children of the same parent only. To promote content above unrelated subtrees, place it under a shared absolute-geometry ancestor (see :meth:stack). This mirrors CSS stacking contexts and keeps z from fighting containment.

Attributes:

__module__ –

Always "xnano_core.rust.engine".

Construct a render node.

All arguments are keyword-only.

Parameters:

x (Optional[int], default: None ) –

Absolute X of the node's top-left in cells. If all four of x/y/width/height are supplied the node has absolute geometry and is treated as a stacking-context anchor; otherwise the parent's layout allocates its rect.
y (Optional[int], default: None ) –

Absolute Y of the node's top-left in cells.
width (Optional[int], default: None ) –

Absolute width in cells.
height (Optional[int], default: None ) –

Absolute height in cells.
direction (Optional[Direction], default: None ) –

How this node's children should flow when laid out by constraint. None defaults to Direction.Vertical.
gap (int, default: 0 ) –

Cells of spacing inserted between adjacent children by the layout solver. Ignored if all children have absolute geometry.
constraints (Optional[Sequence[Constraint]], default: None ) –

Layout constraints applied to children in declaration order. Length should match len(children).
margin (Optional[Margin], default: None ) –

Inner margin applied to this node's rect before it is subdivided for children. Does not affect this node's own paint region.
content (Optional[CoreRenderContent], default: None ) –

What this node paints into its own rect. Defaults to :meth:CoreRenderContent.empty.
cursor_hint (Optional[tuple[int, int]], default: None ) –

If set, the terminal cursor is positioned at (rect.x + dx, rect.y + dy) after this subtree renders, subject to the cursor being visible. Later cursor hints encountered during traversal override earlier ones.
effect_key (Optional[str], default: None ) –

If set, the resolved rect for this node is recorded under this key so :meth:CoreSession.effect_area_for can look it up after the frame.
z (int, default: 0 ) –

Sibling-local paint order. Higher values paint later (on top). Defaults to 0. Sibling ties break in declaration order.
visible (bool, default: True ) –

If False, this node and its entire subtree are skipped during traversal — no layout, no paint, no cursor or effect-area contributions. The layout slot the parent reserved is still consumed by the (invisible) node. Defaults to True.
children (Optional[Sequence[CoreRenderNode]], default: None ) –

Child nodes. Each child's rect is derived from the parent's direction+constraints+gap unless the child itself has absolute geometry.

Methods:

leaf –

Construct a leaf node with no children and default styling.
row –

Construct a horizontal container.
column –

Construct a vertical container.
stack –

Construct an absolute-geometry stacking context.
get_children –

Return a shallow copy of this node's children.
get_content –

Return a clone of this node's content.
get_effect_key –

Return this node's effect-area key, if any.
get_z –

Return this node's paint-order hint.
is_visible –

Return this node's visibility flag.
has_absolute_geometry –

Whether all four geometry fields are set.

leaf `staticmethod` ¶

leaf(content: CoreRenderContent) -> CoreRenderNode

Construct a leaf node with no children and default styling.

Parameters:

content (CoreRenderContent) –

The content painted into this node's rect.

Returns:

CoreRenderNode –

A node with z=0, visible=True, no children, no absolute
CoreRenderNode –

geometry, and the given content.

row `staticmethod` ¶

row(
    children: Sequence[CoreRenderNode],
    *,
    constraints: Optional[Sequence[Constraint]] = None,
    gap: int = 0,
    margin: Optional[Margin] = None
) -> CoreRenderNode

Construct a horizontal container.

Parameters:

children (Sequence[CoreRenderNode]) –

Child nodes laid out left-to-right.
constraints (Optional[Sequence[Constraint]], default: None ) –

Layout constraints per child.
gap (int, default: 0 ) –

Cells of horizontal spacing between children.
margin (Optional[Margin], default: None ) –

Inner margin applied to the parent rect before children are laid out.

Returns:

CoreRenderNode –

A container node with direction=Direction.Horizontal,
CoreRenderNode –

z=0, visible=True.

column `staticmethod` ¶

column(
    children: Sequence[CoreRenderNode],
    *,
    constraints: Optional[Sequence[Constraint]] = None,
    gap: int = 0,
    margin: Optional[Margin] = None
) -> CoreRenderNode

Construct a vertical container.

Parameters:

children (Sequence[CoreRenderNode]) –

Child nodes laid out top-to-bottom.
constraints (Optional[Sequence[Constraint]], default: None ) –

Layout constraints per child.
gap (int, default: 0 ) –

Cells of vertical spacing between children.
margin (Optional[Margin], default: None ) –

Inner margin applied to the parent rect before children are laid out.

Returns:

CoreRenderNode –

A container node with direction=Direction.Vertical,
CoreRenderNode –

z=0, visible=True.

stack `staticmethod` ¶

stack(
    x: int,
    y: int,
    width: int,
    height: int,
    children: Sequence[CoreRenderNode],
) -> CoreRenderNode

Construct an absolute-geometry stacking context.

Every child inherits this anchor's rect unless it has its own absolute geometry. Children paint in ascending z order, so modals, dropdowns, and overlays should live under a stack parent to escape their surrounding container's clip.

Parameters:

x (int) –

Absolute X of the stack's top-left in cells.
y (int) –

Absolute Y of the stack's top-left in cells.
width (int) –

Absolute width in cells.
height (int) –

Absolute height in cells.
children (Sequence[CoreRenderNode]) –

Child nodes that share the stack's rect.

Returns:

CoreRenderNode –

A node with all four geometry fields set, z=0,
CoreRenderNode –

visible=True, and the given children.

get_children ¶

get_children() -> list[CoreRenderNode]

Return a shallow copy of this node's children.

The returned list may be freely mutated; the underlying node's children are not affected.

Returns:

list[CoreRenderNode] –

A new list of the child nodes in declaration order.

get_content ¶

get_content() -> CoreRenderContent

Return a clone of this node's content.

Returns:

The ( CoreRenderContent ) –

class:CoreRenderContent variant carried by this node.

get_effect_key ¶

get_effect_key() -> Optional[str]

Return this node's effect-area key, if any.

Returns:

Optional[str] –

The string key registered via the effect_key constructor
Optional[str] –

argument, or None if the node has no key.

get_z ¶

get_z() -> int

Return this node's paint-order hint.

Returns:

int –

The z value passed at construction time, or 0 if none
int –

was supplied.

is_visible ¶

is_visible() -> bool

Return this node's visibility flag.

Returns:

bool –

True if the node participates in rendering, False if
bool –

the engine will skip its subtree entirely.

has_absolute_geometry ¶

has_absolute_geometry() -> bool

Whether all four geometry fields are set.

A node with absolute geometry ignores the parent-supplied rect and uses its own x/y/width/height instead.

Returns:

bool –

True if all of x, y, width, and height are
bool –

set, False otherwise.

CoreTerminalRef ¶

Scope-guarded handle to the live ratatui DefaultTerminal.

Yielded by :meth:CoreSession.get_terminal. The reference is valid only while the parent :class:CoreSession is alive and has not been restored. Calling any method after the parent session has been restored raises RuntimeError.

Attributes:

__module__ –

Always "xnano_core.rust.engine".

Methods:

draw –

Run a direct-draw callback against a fresh terminal frame.
try_draw –

Run a direct-draw callback and return frame metadata on success.
flush –

Flush pending output to the underlying terminal.
clear –

Clear the terminal's back buffer.
size –

Return the current terminal size in cells.

draw ¶

draw(callback: Callable[[Any], Any]) -> None

Run a direct-draw callback against a fresh terminal frame.

The callback receives a native Frame handle. Errors raised inside the callback are printed but not propagated (matching ratatui's Terminal::draw contract).

Parameters:

callback (Callable[[Any], Any]) –

A callable receiving a Frame. Its return value is discarded.

try_draw ¶

try_draw(callback: Callable[[Any], Any]) -> CompletedFrame

Run a direct-draw callback and return frame metadata on success.

Errors raised inside the callback are propagated as Python exceptions after the draw is aborted.

Parameters:

callback (Callable[[Any], Any]) –

A callable receiving a Frame. Its return value is discarded.

Returns:

A ( CompletedFrame ) –

class:~xnano_core.rust.native.CompletedFrame describing the
CompletedFrame –

frame that was written.

flush ¶

flush() -> None

Flush pending output to the underlying terminal.

clear ¶

clear() -> None

Clear the terminal's back buffer.

size ¶

size() -> Size

Return the current terminal size in cells.

Returns:

A ( Size ) –

class:~xnano_core.rust.native.Size.

CoreSession ¶

Owner of the terminal, event loop, effects, and device state.

A CoreSession is the singleton runtime handle for one live xnano application. It is the only type in xnano_core allowed to call ratatui::init / ratatui::restore — every other primitive is stateless or state-owning-but-scoped.

A session can be constructed in one of two modes:

Live (:meth:init): claims the real terminal, installs a panic hook that restores the terminal on abnormal exit, and drives the full event loop. Only available when :meth:supports_live_terminal is True (native builds with the terminal cargo feature).
Offscreen (:meth:offscreen): allocates an in-memory buffer of fixed size and skips all crossterm I/O. Used for tests, snapshot rendering, wasm / Pyodide single-frame rendering, and running effects without a terminal. Always available.

On Emscripten/WebAssembly wheels (built with --no-default-features) the layout/render engine still ships and :meth:offscreen paints through the real constraint solver into a buffer. Only live terminal I/O and interactive event polling are unavailable — :meth:supports_live_terminal returns False.

Sessions are context managers: with CoreSession.init() as session: guarantees the terminal is restored on both normal exit and exception propagation. Dropping the session without calling restore / __exit__ also restores the terminal via a Drop implementation, but relying on that is discouraged.

Attributes:

__module__ –

Always "xnano_core.rust.engine".

Methods:

supports_live_terminal –

Return whether this build can claim a live crossterm terminal.
is_buffer_backed –

Return whether this session paints into an in-memory buffer.
init –

Claim the terminal and construct a live session.
offscreen –

Construct an offscreen session backed by an in-memory buffer.
render –

Render one frame from a render tree.
poll_event –

Wait up to timeout_ms for the next event, then return.
read_event –

Block until the next event arrives.
buffer_snapshot –

Clone the current frame buffer.
add_effect –

Register a non-keyed effect on the session's effect manager.
add_unique_effect –

Register or replace a keyed effect.
cancel_effect –

Cancel a previously added keyed effect.
is_animating –

Whether at least one effect is still running.
effect_area_for –

Look up the last-frame rect for a render node's effect_key.
get_terminal –

Yield a scope-guarded reference to the live terminal.
enable_raw_mode –

Enable crossterm raw mode.
disable_raw_mode –

Disable crossterm raw mode.
enable_mouse_capture –

Enable mouse event capture.
disable_mouse_capture –

Disable mouse event capture.
enable_bracketed_paste –

Enable bracketed-paste event delivery.
disable_bracketed_paste –

Disable bracketed-paste event delivery.
enable_focus_change –

Enable focus-gained/focus-lost event delivery.
disable_focus_change –

Disable focus-gained/focus-lost event delivery.
enter_alternate_screen –

Switch the terminal to its alternate screen buffer.
leave_alternate_screen –

Return the terminal to its primary screen buffer.
push_keyboard_enhancement_flags –

Push kitty-protocol keyboard enhancement flags on the stack.
pop_keyboard_enhancement_flags –

Pop the most recent keyboard enhancement flag frame.
show_cursor –

Show the terminal cursor.
hide_cursor –

Hide the terminal cursor.
set_cursor_style –

Set the terminal cursor shape.
get_cursor_style –

Return the currently applied cursor style.
move_cursor_to –

Move the terminal cursor to absolute coordinates.
save_cursor_position –

Save the cursor position on the terminal's cursor stack.
restore_cursor_position –

Restore the previously saved cursor position.
get_cursor_position –

Return the current cursor position.
get_size –

Return the terminal's cell size.
get_window_size –

Return the terminal's pixel window size.
get_last_frame_area –

Return the rect of the most recently rendered frame.
get_viewport_area –

Return the terminal's current viewport rect.
is_raw_mode_enabled –

Return the session's mirror of raw-mode state.
is_mouse_capture_enabled –

Return the session's mirror of mouse-capture state.
is_bracketed_paste_enabled –

Return the session's mirror of bracketed-paste state.
is_focus_change_enabled –

Return the session's mirror of focus-change state.
is_alternate_screen_enabled –

Return the session's mirror of alternate-screen state.
is_inline –

Return whether the session uses an inline viewport.
get_inline_height –

Return the inline viewport height, if any.
is_cursor_visible –

Return the session's mirror of cursor visibility.
clear –

Clear part or all of the terminal.
set_title –

Set the terminal window title.
get_title –

Return the last title set via :meth:set_title.
scroll_up –

Scroll the terminal viewport up.
scroll_down –

Scroll the terminal viewport down.
begin_synchronized_update –

Begin a terminal synchronized-output region.
end_synchronized_update –

End a terminal synchronized-output region.
restore –

Restore the terminal and release engine resources.
__enter__ –

Context-manager entry.
__exit__ –

Context-manager exit; always calls :meth:restore.

supports_live_terminal `staticmethod` ¶

supports_live_terminal() -> bool

Return whether this build can claim a live crossterm terminal.

Returns:

bool –

True on native wheels built with the terminal feature.
bool –

False on Emscripten/WebAssembly (--no-default-features)
bool –

builds, where only :meth:offscreen buffer-backed sessions
bool –

work.

is_buffer_backed ¶

is_buffer_backed() -> bool

Return whether this session paints into an in-memory buffer.

:meth:render uses the buffer path (full layout solver, no crossterm I/O) when this is True. Live :meth:init sessions return False; :meth:offscreen sessions (and all wasm sessions) return True.

Returns:

bool –

True for buffer-backed sessions, False for live ones.

init `staticmethod` ¶

init(
    *,
    tick_rate_ms: Optional[int] = None,
    inline_height: Optional[int] = None
) -> CoreSession

Claim the terminal and construct a live session.

Installs a panic hook that restores the terminal on abnormal exit. Enables raw mode. When inline_height is None the session enters the alternate screen and claims the full viewport; when it is set the session uses an inline viewport of that many rows in the main screen buffer (no alternate screen), leaving prior terminal output intact.

Parameters:

tick_rate_ms (Optional[int], default: None ) –

If set, the session's event loop emits :class:CoreTerminalEventKind.Tick events at this cadence. If None or 0, ticks are disabled and :meth:poll_event / :meth:read_event never yield Tick.
inline_height (Optional[int], default: None ) –

If set, reserve this many rows for an inline viewport instead of entering the alternate screen. Values are clamped to a minimum of 1.

Returns:

CoreSession –

A live CoreSession.

offscreen `staticmethod` ¶

offscreen(width: int, height: int) -> CoreSession

Construct an offscreen session backed by an in-memory buffer.

No terminal is claimed. No panic hook is installed. No crossterm I/O is performed. :meth:poll_event and :meth:read_event are still callable but will never yield real terminal events; use the offscreen mode only for tests and snapshot rendering.

Parameters:

width (int) –

Buffer width in cells.
height (int) –

Buffer height in cells.

Returns:

CoreSession –

An offscreen CoreSession.

render ¶

render(node: CoreRenderNode) -> None

Render one frame from a render tree.

Walks node, laying out children under each node's direction and constraints, painting content in ascending z order per sibling group, skipping subtrees with visible=False, running any registered effects over the resulting buffer, and finally positioning the cursor (or hiding it) according to the last-seen cursor hint.

When :meth:is_buffer_backed is True (offscreen sessions, and all sessions on wasm builds) this paints into the in-memory buffer via the full layout solver with zero crossterm I/O; read the result back with :meth:buffer_snapshot. On a live session this writes to the real terminal via Terminal::draw.

Parameters:

node (CoreRenderNode) –

The root of the render tree for this frame.

poll_event ¶

poll_event(timeout_ms: int = 16) -> Optional[CoreEvent]

Wait up to timeout_ms for the next event, then return.

Blocks releasing the GIL so Python threads run during the wait. Checks Python signals on wake so Ctrl+C interrupts cleanly.

Parameters:

timeout_ms (int, default: 16 ) –

Maximum milliseconds to block. Capped internally by the session's tick budget when ticks are enabled.

Returns:

Optional[CoreEvent] –

The next :class:CoreEvent, or None if the poll timed out
Optional[CoreEvent] –

with no event and no tick was due.

read_event ¶

read_event() -> CoreEvent

Block until the next event arrives.

Equivalent to calling :meth:poll_event in a loop with a large timeout. Releases the GIL while blocking and checks signals on each iteration so Ctrl+C interrupts cleanly.

Returns:

CoreEvent –

The next :class:CoreEvent.

buffer_snapshot ¶

buffer_snapshot() -> Buffer

Clone the current frame buffer.

Works in both live and offscreen modes. On a live session this clones the terminal's current frame buffer; on an offscreen session it clones the internal buffer.

Returns:

Buffer –

A fresh :class:~xnano_core.rust.native.Buffer.

add_effect ¶

add_effect(effect: Effect) -> None

Register a non-keyed effect on the session's effect manager.

The effect runs on every subsequent :meth:render until it finishes on its own timeline.

Parameters:

effect (Effect) –

A :class:~xnano_core.rust.native.Effect to run.

add_unique_effect ¶

add_unique_effect(key: str, effect: Effect) -> None

Register or replace a keyed effect.

Any prior effect with the same key is cancelled first, so a hot path can call this every frame without piling up duplicates.

Parameters:

key (str) –

Identifier for this effect. Also usable with :meth:effect_area_for when a render node ties its effect_key to the same string.
effect (Effect) –

A :class:~xnano_core.rust.native.Effect to run.

cancel_effect ¶

cancel_effect(key: str) -> None

Cancel a previously added keyed effect.

No-op if the key is not registered.

Parameters:

key (str) –

The identifier passed to :meth:add_unique_effect.

is_animating ¶

is_animating() -> bool

Whether at least one effect is still running.

Returns:

bool –

True if any registered effect is unfinished, False
bool –

otherwise.

effect_area_for ¶

effect_area_for(key: str) -> Optional[Rect]

Look up the last-frame rect for a render node's effect_key.

A node's effect_key is recorded during traversal even for nodes that don't have absolute geometry, so effects can target a rect that was resolved by the layout solver.

Parameters:

key (str) –

The string set on a :class:CoreRenderNode's effect_key.

Returns:

Optional[Rect] –

The rect recorded on the most recent frame, or None if
Optional[Rect] –

no node with that key rendered.

get_terminal ¶

get_terminal() -> CoreTerminalRef

Yield a scope-guarded reference to the live terminal.

Returns:

A ( CoreTerminalRef ) –

class:CoreTerminalRef valid while this session is alive.

Raises:

RuntimeError –

If this is an offscreen session.

enable_raw_mode ¶

enable_raw_mode() -> None

Enable crossterm raw mode.

disable_raw_mode ¶

disable_raw_mode() -> None

Disable crossterm raw mode.

enable_mouse_capture ¶

enable_mouse_capture() -> None

Enable mouse event capture.

disable_mouse_capture ¶

disable_mouse_capture() -> None

Disable mouse event capture.

enable_bracketed_paste ¶

enable_bracketed_paste() -> None

Enable bracketed-paste event delivery.

disable_bracketed_paste ¶

disable_bracketed_paste() -> None

Disable bracketed-paste event delivery.

enable_focus_change ¶

enable_focus_change() -> None

Enable focus-gained/focus-lost event delivery.

disable_focus_change ¶

disable_focus_change() -> None

Disable focus-gained/focus-lost event delivery.

enter_alternate_screen ¶

enter_alternate_screen() -> None

Switch the terminal to its alternate screen buffer.

leave_alternate_screen ¶

leave_alternate_screen() -> None

Return the terminal to its primary screen buffer.

push_keyboard_enhancement_flags ¶

push_keyboard_enhancement_flags(
    flags: KeyboardEnhancementFlags,
) -> None

Push kitty-protocol keyboard enhancement flags on the stack.

Parameters:

flags (KeyboardEnhancementFlags) –

Enhancement flags to enable while pushed.

pop_keyboard_enhancement_flags ¶

pop_keyboard_enhancement_flags() -> None

Pop the most recent keyboard enhancement flag frame.

show_cursor ¶

show_cursor() -> None

Show the terminal cursor.

hide_cursor ¶

hide_cursor() -> None

Hide the terminal cursor.

set_cursor_style ¶

set_cursor_style(style: CursorStyle) -> None

Set the terminal cursor shape.

Parameters:

style (CursorStyle) –

The cursor shape to apply.

get_cursor_style ¶

get_cursor_style() -> CursorStyle

Return the currently applied cursor style.

Returns:

CursorStyle –

The last :class:~xnano_core.rust.native.CursorStyle set via
CursorStyle –

meth:set_cursor_style, or the default shape if none was set.

move_cursor_to ¶

move_cursor_to(x: int, y: int) -> None

Move the terminal cursor to absolute coordinates.

Parameters:

x (int) –

Column, in cells.
y (int) –

Row, in cells.

save_cursor_position ¶

save_cursor_position() -> None

Save the cursor position on the terminal's cursor stack.

restore_cursor_position ¶

restore_cursor_position() -> None

Restore the previously saved cursor position.

get_cursor_position ¶

get_cursor_position() -> Position

Return the current cursor position.

Returns:

A ( Position ) –

class:~xnano_core.rust.native.Position.

get_size ¶

get_size() -> Size

Return the terminal's cell size.

Returns:

A ( Size ) –

class:~xnano_core.rust.native.Size.

get_window_size ¶

get_window_size() -> Size

Return the terminal's pixel window size.

Returns:

A ( Size ) –

class:~xnano_core.rust.native.Size giving the terminal
Size –

window in pixels, not cells.

get_last_frame_area ¶

get_last_frame_area() -> Optional[Rect]

Return the rect of the most recently rendered frame.

Returns:

The ( Optional[Rect] ) –

class:~xnano_core.rust.native.Rect used on the last
Optional[Rect] –

meth:render call, or None if no frame has rendered yet.

get_viewport_area ¶

get_viewport_area() -> Rect

Return the terminal's current viewport rect.

Unlike :meth:get_last_frame_area, this is available before the first render. For inline sessions the rect is offset from the screen origin (positioned at the reserved viewport rows), so render geometry must be built relative to it.

Returns:

The ( Rect ) –

class:~xnano_core.rust.native.Rect of the live viewport, or
Rect –

the offscreen buffer area for offscreen sessions.

Raises:

RuntimeError –

If the session has been closed.

is_raw_mode_enabled ¶

is_raw_mode_enabled() -> bool

Return the session's mirror of raw-mode state.

Returns:

bool –

True if raw mode is enabled.

is_mouse_capture_enabled ¶

is_mouse_capture_enabled() -> bool

Return the session's mirror of mouse-capture state.

Returns:

bool –

True if mouse capture is enabled.

is_bracketed_paste_enabled ¶

is_bracketed_paste_enabled() -> bool

Return the session's mirror of bracketed-paste state.

Returns:

bool –

True if bracketed paste is enabled.

is_focus_change_enabled ¶

is_focus_change_enabled() -> bool

Return the session's mirror of focus-change state.

Returns:

bool –

True if focus-change events are enabled.

is_alternate_screen_enabled ¶

is_alternate_screen_enabled() -> bool

Return the session's mirror of alternate-screen state.

Returns:

bool –

True if the alternate screen is active.

is_inline ¶

is_inline() -> bool

Return whether the session uses an inline viewport.

Returns:

bool –

True if the session was created with an inline viewport.

get_inline_height ¶

get_inline_height() -> Optional[int]

Return the inline viewport height, if any.

Returns:

Optional[int] –

The reserved inline row count, or None for full-screen or
Optional[int] –

offscreen sessions.

is_cursor_visible ¶

is_cursor_visible() -> bool

Return the session's mirror of cursor visibility.

Returns:

bool –

True if the cursor is currently shown.

clear ¶

clear(clear_type: ClearType) -> None

Clear part or all of the terminal.

Parameters:

clear_type (ClearType) –

What portion of the terminal to clear.

set_title ¶

set_title(title: str) -> None

Set the terminal window title.

Parameters:

title (str) –

The title to apply.

get_title ¶

get_title() -> Optional[str]

Return the last title set via :meth:set_title.

Returns:

Optional[str] –

The title string, or None if none was set.

scroll_up ¶

scroll_up(count: int = 1) -> None

Scroll the terminal viewport up.

Parameters:

count (int, default: 1 ) –

Number of rows to scroll.

scroll_down ¶

scroll_down(count: int = 1) -> None

Scroll the terminal viewport down.

Parameters:

count (int, default: 1 ) –

Number of rows to scroll.

begin_synchronized_update ¶

begin_synchronized_update() -> None

Begin a terminal synchronized-output region.

end_synchronized_update ¶

end_synchronized_update() -> None

End a terminal synchronized-output region.

restore ¶

restore() -> None

Restore the terminal and release engine resources.

Idempotent: safe to call multiple times. Called automatically by :meth:__exit__ and by the Drop implementation on the underlying Rust type.

enter ¶

__enter__() -> CoreSession

Context-manager entry.

Returns:

CoreSession –

This session.

exit ¶

__exit__(
    exc_type: object, exc_value: object, traceback: object
) -> bool

Context-manager exit; always calls :meth:restore.

Parameters:

exc_type (object) –

The exception type, if propagating.
exc_value (object) –

The exception instance, if propagating.
traceback (object) –

The exception traceback, if propagating.

Returns:

bool –

False so any in-flight exception continues to propagate.

CoreTextEditor ¶

CoreTextEditor(
    text: str = "", *, single_line: bool = False
)

Stateful multi-line text editor backing editable Text fields.

Editing state (lines, cursor, undo history) lives entirely in Rust; Python forwards one key event per keystroke and reads the result. Instances render directly as native widget content.

Create an editor seeded with text, cursor at the end.

Parameters:

text (str, default: '' ) –

Initial content; newlines split it into lines.
single_line (bool, default: False ) –

When True, Enter is not consumed and inserted newlines are replaced with spaces.

Methods:

input –

Apply a key event.
insert_text –

Insert text at the cursor (paste path).
text –

Return the full content as a newline-joined string.
set_text –

Replace the full content, keeping the cursor at the end.
lines –

Return the content as one string per line.
cursor –

Return the cursor position as (row, column).
undo –

Undo the last edit; returns whether anything changed.
redo –

Redo the last undone edit; returns whether anything changed.
set_placeholder_text –

Set the dim placeholder shown while the editor is empty.

input ¶

input(key: KeyEvent) -> bool

Apply a key event.

Tab, BackTab, and Esc always fall through unconsumed (focus navigation and hooks own them); Enter falls through in single-line mode.

Parameters:

key (KeyEvent) –

A native :class:~xnano_core.rust.native.KeyEvent.

Returns:

bool –

True when the editor consumed the event.

insert_text ¶

insert_text(text: str) -> None

Insert text at the cursor (paste path).

text ¶

text() -> str

Return the full content as a newline-joined string.

set_text ¶

set_text(text: str) -> None

Replace the full content, keeping the cursor at the end.

lines ¶

lines() -> list[str]

Return the content as one string per line.

cursor ¶

cursor() -> Tuple[int, int]

Return the cursor position as (row, column).

undo ¶

undo() -> bool

Undo the last edit; returns whether anything changed.

redo ¶

redo() -> bool

Redo the last undone edit; returns whether anything changed.

set_placeholder_text ¶

set_placeholder_text(text: str) -> None

Set the dim placeholder shown while the editor is empty.

xnano_core.rust.engine