Struct TerminalWasm 

pub struct TerminalWasm { /* private fields */ }

A Backend that renders into an in-memory ANSI byte buffer and accepts pushed input, for driving a browser terminal emulator from WASM.

Unlike retroglyph_crossterm::Crossterm, this backend:

• never queries a TTY for its size: call resize_terminal (or, if the input side doesn’t matter for the caller, Terminal::resize directly) whenever the host reports a new size (e.g. from xterm.js’s fit addon);
• never polls for input: input only ever arrives via push_event, called from a wasm-bindgen entry point in response to a JS event;
• buffers rendered ANSI bytes in memory rather than writing to a descriptor; call take_output once per animation frame to drain them.

Implementations

impl TerminalWasm

pub const fn new(width: u16, height: u16) -> Self

Creates a new backend with the given initial size in cells.

Examples

The push-input/pull-ANSI cycle this backend is built around: push a synthetic key event via Input::push_event, draw a frame, then pull the rendered ANSI bytes back out with take_output.

use retroglyph_core::backend::Input;
use retroglyph_core::event::{Event, KeyCode, KeyEvent, KeyModifiers};
use retroglyph_core::color::Style;
use retroglyph_core::terminal::Terminal;
use retroglyph_terminal_wasm::TerminalWasm;

let mut backend = TerminalWasm::new(10, 3);
backend.push_event(Event::Key(KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE)));

let mut term = Terminal::new(backend);
assert_eq!(
    term.poll(std::time::Duration::ZERO),
    Some(Event::Key(KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE)))
);

term.draw(|s| s.put((0, 0), '@', Style::default()))?;
let ansi = term.backend_mut().take_output();
assert!(ansi.contains('@'), "output: {ansi:?}");

pub fn take_output(&mut self) -> String

Drains and returns the ANSI bytes rendered since the last call, as a UTF-8 string.

Returns an empty string if nothing has been drawn since the last call. Call this once per animation frame from JS and write the result into the terminal emulator.

This allocates a fresh String every call (the replacement buffer left behind is pre-sized to the outgoing one’s capacity, so a steady frame rate converges to one right-sized allocation per frame instead of regrowing from empty each time; see retroglyph#287). Callers that can reuse a long-lived, JS-side buffer across frames should prefer take_output_into instead, which never allocates on the hot path.

pub fn take_output_into(&mut self, buf: &mut String)

Drains the ANSI bytes rendered since the last call into buf, clearing buf first.

Equivalent to *buf = self.take_output() but reuses buf’s existing allocation instead of returning a new String each call, and leaves this backend’s own internal buffer capacity untouched (just cleared) for the next frame, so neither side allocates once buf has grown to its steady-state size. Intended for callers holding a long-lived buffer across frames (e.g. a JS-side driver reusing the same String every animation frame) instead of receiving a fresh allocation from take_output each time.

Examples

use retroglyph_core::color::Style;
use retroglyph_core::terminal::Terminal;
use retroglyph_terminal_wasm::TerminalWasm;

let mut term = Terminal::new(TerminalWasm::new(10, 3));
term.draw(|s| s.put((0, 0), '@', Style::default()))?;

let mut buf = String::from("stale contents");
term.backend_mut().take_output_into(&mut buf);
assert!(buf.contains('@'), "buf: {buf:?}");
assert!(!buf.contains("stale"));

Trait Implementations

impl Cursor for TerminalWasm

fn set_cursor_style(&mut self, style: CursorStyle)

Writes the DECSCUSR cursor-shape escape.

This is the standard VT100/ANSI (DEC private mode) cursor-shape sequence and is not one of the areas where browser terminal emulators diverge: both xterm.js (https://xtermjs.org/docs/api/vtfeatures/) and hterm/Terminalemulator (https://chromium.googlesource.com/apps/libapps/+/HEAD/hterm/docs/ControlSequences.md) implement CSI Ps SP q identically.

fn set_cursor_visible(&mut self, visible: bool)

Show or hide the cursor.

fn set_cursor_position(&mut self, position: Pos)

Move the cursor to a position.

impl Input for TerminalWasm

fn push_event(&mut self, event: Event)

The sole public way to push an event onto a TerminalWasm; forwards to the crate-private inherent push_event.

fn poll_event(&mut self, _timeout: Duration) -> Option<Event>

Poll for an input event, waiting up to timeout.

impl Output for TerminalWasm

type Error = Error

Error type returned by fallible operations.

fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>

where I: Iterator<Item = DrawCell<'a>>,

Draw changed cells across all layers.

fn flush(&mut self) -> Result<(), Self::Error>

Flush buffered output to the display.

fn size(&self) -> Size

Return current display dimensions.

fn resize(&mut self, size: Size)

Notify the backend of a resize to size, updating what size reports.

fn clear(&mut self) -> Result<(), Self::Error>

Clear the entire display.

fn draw<'a, I>(&mut self, content: I) -> Result<(), Self::Error>

where I: Iterator<Item = DrawCell<'a>>,

Draw changed cells to the output surface, layer 0 only.

fn needs_full_frame(&self) -> bool

Returns true if the backend needs the entire frame (all cells on all layers) on every call to draw_layers, rather than just the changed cells.

fn composites_layers(&self) -> bool

Whether this backend composites layers itself (per pixel or quad), receiving the raw layered stream from draw_layers.