retroglyph_terminal_wasm/

lib.rs

//! A WASM/browser terminal backend, driven by pushed input and pulled ANSI output.
//!
//! [`TerminalWasm`] implements [`Backend`](retroglyph_core::backend::Backend) directly (like
//! [`Headless`](retroglyph_core::backend::Headless)): there is no event loop
//! here. A browser terminal emulator (e.g. xterm.js, this crate has no
//! dependency on it and no opinion about which one is used) is driven from
//! JS, which calls into this crate once per animation frame (or on demand)
//! to pull freshly rendered ANSI bytes and push back any input it collected.
//!
//! # Usage from Rust
//!
//! ```
//! use retroglyph_core::color::Style;
//! use retroglyph_core::terminal::Terminal;
//! use retroglyph_terminal_wasm::TerminalWasm;
//!
//! let backend = TerminalWasm::new(80, 24);
//! let mut term = Terminal::new(backend);
//! term.draw(|s| s.put((0, 0), '@', Style::default())).unwrap();
//! let ansi = term.backend_mut().take_output();
//! assert!(ansi.contains('@'));
//! ```
//!
//! # Usage from JS (via `wasm-bindgen`)
//!
//! The `wasm32` build additionally exposes free functions
//! (`wasm_terminal_new`, `wasm_terminal_resize`, `wasm_terminal_push_key`,
//! `wasm_terminal_push_mouse`, `wasm_terminal_push_paste`,
//! `wasm_terminal_take_output`, in this crate's `wasm` module, only
//! compiled for `target_arch = "wasm32"`, so it won't appear in docs built
//! natively) that operate on an opaque handle, since
//! `retroglyph_core::event::Event` is not itself `wasm-bindgen`-compatible.
//!
//! The example below is a complete, working driver pairing this crate's
//! `wasm32` build with [xterm.js](https://xtermjs.org/) (any other browser
//! terminal emulator works the same way; this crate has no dependency on
//! xterm.js specifically). It assumes a `wasm-pack`/`wasm-bindgen`-generated
//! `./pkg.js` module built from a binary that re-exports this crate's `wasm`
//! module, and an `xterm.js` `<script>` already loaded on the page (see
//! [xterm.js's own quick start](https://xtermjs.org/docs/) for that half).
//!
//! It's a wiring template, not a full game: it plumbs input/output through
//! this crate's generic handle-based FFI but calls no per-frame drawing
//! logic of its own (that's the consumer's job, via their own Rust code
//! holding the `Terminal<TerminalWasm>`; see "Usage from Rust" above).
//!
//! A game driving a real [`App`](retroglyph_core::app::App) usually wants the single-instance-per-page
//! FFI [`app_entry!`] generates instead of hand-rolling a thread-local session over the
//! handle-based functions shown here: `wasm_app_init`/`wasm_app_resize`/`wasm_app_push_key`/
//! `wasm_app_push_mouse`/`wasm_app_push_paste`/`wasm_app_push_focus`/`wasm_app_tick`, with the
//! [`Terminal::resize`](retroglyph_core::terminal::Terminal::resize)-plus-`Event::Resize` bookkeeping
//! [`resize_terminal`] does and the backgrounded-tab delta clamp documented on [`app_entry!`]
//! itself. See that macro's own doc comment for a complete example. The examples crate's
//! WASM demo gallery (linked from the workspace README) uses an equivalent macro,
//! `retroglyph_examples::wasm_entry!`, generated over its own private `Example` trait instead of
//! `App` because that crate predates this one shipping a published equivalent.
//!
//! This file (kept in sync with the copy in `README.md` by a test) is
//! `crates/terminal-wasm/js/xterm-driver.js` in the source tree:
//!
//! ```js
#![doc = include_str!("../js/xterm-driver.js")]
//! ```
//!
//! # Features
//!
//! <!-- gen-features:start -->
//! This crate has no default features; every feature below is optional and off unless enabled.
//!
//! ### `dev`
//!
//! ⚪ Optional.
//!
//! Forwards `retroglyph-core`'s `dev` feature, which forces development diagnostics on in a build
//! that would otherwise compile them out (see [`retroglyph_core::dev`]).
//!
//! ### `egc`
//!
//! ⚪ Optional.
//!
//! Forwards to `retroglyph-terminal`'s (and `retroglyph-core`'s) `egc` feature for
//! grapheme-cluster-aware cell diffing.
//! <!-- gen-features:end -->
//!
//! # ANSI sequences emitted
//!
//! [`TerminalWasm`] renders through [`retroglyph_terminal::TerminalRenderer`] (see that crate's
//! docs for the full cell-diff renderer contract) and adds a handful of sequences of its own
//! ([`clear`](Output::clear), [`set_cursor_visible`](Cursor::set_cursor_visible),
//! [`set_cursor_style`](Cursor::set_cursor_style)). Every
//! sequence below is standard ANSI X3.64 (ECMA-48) CSI (the subset xterm's own control-sequence
//! reference calls plain "ANSI"/VT100-compatible), nothing proprietary or emulator-specific. The
//! bytes are the same regardless of what emulator eventually reads them; this crate makes no
//! attempt to detect or work around variance between implementations (see the quirks below for
//! the two places that matters).
//!
//! | Sequence | Name | Emitted by | Meaning |
//! | --- | --- | --- | --- |
//! | `CSI Ps;Ps H` | CUP (Cursor Position) | [`draw`](Output::draw), for a non-adjacent cell; [`set_cursor_position`](Cursor::set_cursor_position) | move the cursor, 1-indexed `row;col`, always absolute |
//! | `CSI 39 m` / `CSI 49 m` | SGR reset FG/BG | `draw`, for [`Color::Default`](retroglyph_core::color::Color::Default) | reset foreground/background to the emulator's default |
//! | `CSI 3n m` / `CSI 4n m` (`30`-`37` / `40`-`47`) | SGR ANSI FG/BG | `draw`, for the standard 8 [`Color::Ansi`](retroglyph_core::color::Color::Ansi) values | set foreground/background to a standard ANSI color |
//! | `CSI 9n m` / `CSI 10n m` (`90`-`97` / `100`-`107`) | SGR bright ANSI FG/BG | `draw`, for the bright 8 [`Color::Ansi`](retroglyph_core::color::Color::Ansi) values | set foreground/background to a bright ANSI color |
//! | `CSI 38;5;n m` / `CSI 48;5;n m` | SGR indexed FG/BG | `draw`, for [`Color::Indexed`](retroglyph_core::color::Color::Indexed) | set foreground/background from the 256-color palette |
//! | `CSI 38;2;r;g;b m` / `CSI 48;2;r;g;b m` | SGR truecolor FG/BG | `draw`, for [`Color::Rgb`](retroglyph_core::color::Color::Rgb) | set foreground/background to a 24-bit RGB color, unquantized |
//! | `CSI ?2026 h` / `CSI ?2026 l` | DEC private mode 2026 (synchronized update) | every [`draw`](Output::draw)/[`flush`](Output::flush) pair | hold rendering until the matching end marker, avoiding tearing mid-frame |
//! | `CSI ?25 h` / `CSI ?25 l` | DECTCEM (cursor visibility) | [`set_cursor_visible`](Cursor::set_cursor_visible) | show/hide the terminal cursor |
//! | `CSI Ps SP q` | DECSCUSR (cursor shape) | [`set_cursor_style`](Cursor::set_cursor_style) | set the cursor's shape/blink behavior |
//! | `CSI 2J` then `CSI H` | ED (erase display) + CUP home | [`clear`](Output::clear) | clear the screen, then move the cursor to `(1, 1)` |
//!
//! retroglyph does not model text attributes (bold, italic, underline, etc.; see
//! [`retroglyph_core::color::Style`]'s docs for why), so no SGR attribute codes (`1`, `3`, `4`,
//! ...) are ever emitted here; only the color and cursor/erase sequences above. Glyph bytes
//! themselves (see [`take_output`](TerminalWasm::take_output)) are plain UTF-8, not an escape
//! sequence.
//!
//! ## `TerminalRenderer` quirks to know before validating against a specific emulator
//!
//! - **Absolute positions only, never relative.** Every cursor move is a full CUP with both `row`
//!   and `col`, even to step one cell right or down: there is no `CSI C`/`CSI B`
//!   (cursor-relative) fallback.
//!   [`TerminalRenderer::draw`](retroglyph_terminal::TerminalRenderer::draw) does skip the move
//!   entirely when the cursor is already at the right cell from printing the previous glyph
//!   (adjacent same-row cells), but it never emits a *relative* move to get there.
//! - **No RGB-to-256/16-color quantization.** [`Color::Rgb`](retroglyph_core::color::Color::Rgb)
//!   is always written as the 24-bit `38;2;...`/`48;2;...` form, even targeting an emulator that
//!   only supports the 256-color or 16-color palette; downsampling (if any) is left entirely to
//!   the receiving emulator. See `retroglyph-terminal`'s crate-level docs ("RGB color fallback on
//!   256-color terminals") for the full rationale; use
//!   [`Color::Indexed`](retroglyph_core::color::Color::Indexed) or
//!   [`Color::Ansi`](retroglyph_core::color::Color::Ansi) instead when a specific emulator's color
//!   depth is known ahead of time.
//! - **`clear` always re-syncs tracked state.** [`clear`](Output::clear) additionally resets this
//!   renderer's tracked cursor/color state, so the *next* `draw` call re-emits a full CUP and
//!   color codes for every cell instead of (incorrectly) assuming the emulator remembers the old
//!   state through the erase.
//! - **`clear` resets SGR attributes before erasing.** [`clear`](Output::clear) emits `CSI 0 m`
//!   ahead of `CSI 2J`, because most terminals implement erase-display via background color erase
//!   (BCE) and paint the erased cells with whatever background is currently active in the pen, not
//!   the emulator's true default. Without the reset, a cell colored by the last frame leaves its
//!   tint across the whole screen after `clear`.
//! - **Every `draw` is wrapped in its own synchronized-update pair.** [`draw`](Output::draw)
//!   itself emits `CSI ?2026 h` before drawing, and the paired [`flush`](Output::flush) call
//!   emits `CSI ?2026 l` after. An emulator that doesn't recognize DEC private mode 2026 ignores
//!   both codes per the CSI spec's "unknown private mode" behavior, so this is safe to send
//!   unconditionally.
//!
//! xterm's own control-sequence reference
//! (<https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>) and ECMA-48 (the formal standard
//! behind "ANSI X3.64", <https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>)
//! are the normative references for every sequence in the table above. The synchronized-update
//! mode (`2026`) isn't part of either: it follows the de facto convention specified at
//! <https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036> and implemented by
//! xterm.js, kitty, iTerm2, and others.

#![cfg_attr(docsrs, feature(doc_cfg))]

// Compile the code blocks in this crate's own README as doctests so its quick start is
// type-checked on every test run and cannot silently rot. The `cfg(doctest)` gate keeps this out
// of the rendered crate documentation: see `retroglyph-crossterm`'s matching include for the
// same pattern applied to the workspace root README.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;

// `app_entry!`'s own doc comment (on the macro, not this private module) is what shows up in
// rustdoc; `#[macro_export]` lifts it to the crate root regardless of this module's visibility,
// the same pattern `examples/src/wasm_entry.rs` uses for its own private `Example`-based macros.
mod app_entry;

use retroglyph_core::backend::DrawCell;
use retroglyph_core::backend::{Cursor, CursorStyle, Input, Output};
use retroglyph_core::event::{Event, coalesces_with};
use retroglyph_core::grid::HasSize;
use retroglyph_core::grid::{Pos, Size};
use retroglyph_core::terminal::Terminal;
use retroglyph_terminal::TerminalRenderer;
use std::collections::VecDeque;
use std::io;
use std::time::Duration;

/// A `std::io::Write` sink backed by a `String` instead of a `Vec<u8>`.
///
/// [`TerminalRenderer`] only ever writes complete, already-valid-UTF-8 fragments into its writer:
/// ASCII escape sequences from `write!`/`write_str` calls and glyphs sourced from `char`/`&str`
/// (see [`TerminalWasm::take_output`]'s doc comment for the full argument). Writing straight into
/// a `String`-backed sink instead of a `Vec<u8>` means [`take_output`](TerminalWasm::take_output)
/// never has to re-validate those bytes as UTF-8 on drain, which a `Vec<u8>`-backed sink would
/// require via `String::from_utf8` every frame: see retroglyph#288. `Write::write` still validates
/// its input as UTF-8 (returning [`io::ErrorKind::InvalidData`] on failure) rather than trusting
/// the caller, since the `std::io::Write` contract itself makes no UTF-8 guarantee about the
/// bytes it's handed; only this crate's own, always-valid-UTF-8 call sites are relied upon to
/// make that error path dead code in practice.
#[derive(Debug, Default)]
struct Utf8Sink(String);

impl io::Write for Utf8Sink {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let s =
            std::str::from_utf8(buf).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
        self.0.push_str(s);
        Ok(buf.len())
    }

    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
        self.write(buf).map(|_| ())
    }

    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}

/// A [`Backend`](retroglyph_core::backend::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`](https://docs.rs/retroglyph-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`](retroglyph_core::terminal::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`](Input::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`](Self::take_output) once per animation
///   frame to drain them.
pub struct TerminalWasm {
    renderer: TerminalRenderer<Utf8Sink>,
    size: Size,
    event_queue: VecDeque<Event>,
}

/// The maximum number of events [`TerminalWasm::push_event`] will hold at once.
///
/// There is no OS-level backpressure here the way there is on native (crossterm's underlying
/// input buffer naturally throttles a stalled reader): JS keeps calling the `wasm_terminal_push_*`
/// entry points regardless of whether the Rust game loop is still draining
/// [`poll_event`](Input::poll_event) every frame (e.g. a backgrounded tab throttling
/// `requestAnimationFrame`, or the game loop itself stalling), so an unbounded queue can grow
/// forever. `4096` is generously above any single-frame burst a real pointer/keyboard/paste stream
/// should ever produce (a 250 Hz mouse plus a full frame of dropped rendering is still only a few
/// hundred events), while staying small enough that hitting the cap and dropping the oldest event
/// is a clearly abnormal, log-worthy condition rather than routine behavior.
const EVENT_QUEUE_CAP: usize = 4096;

impl TerminalWasm {
    /// 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`](Self::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:?}");
    /// # Ok::<(), std::io::Error>(())
    /// ```
    #[must_use]
    pub const fn new(width: u16, height: u16) -> Self {
        Self {
            renderer: TerminalRenderer::new(Utf8Sink(String::new())),
            size: Size::new(width, height),
            event_queue: VecDeque::new(),
        }
    }

    /// Injects a synthetic input event into the queue, to be returned by the
    /// next [`poll_event`](Input::poll_event) call.
    ///
    /// Called from JS (via the `wasm-bindgen` entry points below) or from
    /// tests; not part of [`Backend`](retroglyph_core::backend::Backend) itself beyond the no-op default.
    ///
    /// Two mitigations guard against a stalled or throttled consumer (e.g. a backgrounded tab, or
    /// a Rust game loop that's paused) while JS keeps forwarding input: there is no OS-level
    /// backpressure here the way there is on native (crossterm's underlying input buffer
    /// naturally throttles a stalled reader):
    ///
    /// - **Pointer-move/drag coalescing.** If `event`'s queue tail
    ///   [`coalesces_with`](retroglyph_core::event::coalesces_with) it (both `Event::Mouse` with
    ///   [`MouseEventKind::Moved`], or both with [`MouseEventKind::Drag`] carrying the same
    ///   button), `event` replaces the tail in place instead of growing the queue: a consumer
    ///   that's fallen behind only ever cares about the most recent pointer position, not every
    ///   intermediate one. Any other event kind (including a `Down`/`Up`/scroll mouse event, or a
    ///   `Drag` with a different button) always pushes normally, so this never reorders or merges
    ///   anything but a `Moved` or same-button `Drag` run. The same rule is shared with the
    ///   `retroglyph-window` backend and `Headless` (retroglyph#768).
    /// - **Capacity cap.** Once the queue holds `EVENT_QUEUE_CAP` (4096) events, pushing another
    ///   silently drops the *oldest* queued event (via `pop_front`) to make room. Oldest was
    ///   chosen over dropping the new event so a consumer that's fallen behind and only pulls a
    ///   few events per frame still gets its queue trending toward current/recent input as it
    ///   catches up, rather than being stuck forever behind the exact backlog that triggered the
    ///   cap. This is silent rather than logged: this crate's non-wasm32 API surface has no
    ///   other fallible/observable operations and stays log-free (see the `wasm` module below for
    ///   where this crate *does* use `log`, at the FFI boundary specifically), and a queue that's
    ///   this far behind is already producing stale input for the consumer regardless.
    ///
    /// Crate-private: [`Input::push_event`] is the sole public way to push an event onto a
    /// `TerminalWasm`, so there is only one way for external callers to do this.
    pub(crate) fn push_event(&mut self, event: Event) {
        if let Some(back) = self.event_queue.back_mut()
            && coalesces_with(&event, back)
        {
            *back = event;
            return;
        }
        if self.event_queue.len() >= EVENT_QUEUE_CAP {
            self.event_queue.pop_front();
        }
        self.event_queue.push_back(event);
    }

    /// 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`](Self::take_output_into) instead, which never
    /// allocates on the hot path.
    #[must_use]
    pub fn take_output(&mut self) -> String {
        let sink = &mut self.renderer.writer_mut().0;
        let replacement = String::with_capacity(sink.capacity());
        std::mem::replace(sink, replacement)
    }

    /// 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`](Self::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"));
    /// # Ok::<(), std::io::Error>(())
    /// ```
    pub fn take_output_into(&mut self, buf: &mut String) {
        buf.clear();
        let sink = &mut self.renderer.writer_mut().0;
        buf.push_str(sink);
        sink.clear();
    }
}

/// Resizes `term` to `(width, height)` cells, doing everything a correct resize needs in one call.
///
/// That's [`Terminal::resize`](retroglyph_core::terminal::Terminal::resize) (which itself resizes both grid
/// buffers and calls [`Output::resize`] on the backend), plus queuing the matching
/// [`Event::Resize`] so a driven [`App`](retroglyph_core::app::App) observes the new size through its
/// own input handling too, exactly as it would from a native backend's real resize event.
///
/// Calling `term.resize(width, height)` directly (skipping this function) leaves nothing in the
/// input queue: an app that reacts to `Event::Resize` rather than re-checking
/// `term.backend().size()` every frame silently keeps its old layout. [`app_entry!`] already
/// calls this on every `wasm_app_resize`; reach for it directly only when driving a
/// `Terminal<TerminalWasm>` by hand instead of through that macro. See retroglyph#684.
///
/// # Examples
///
/// ```
/// use retroglyph_core::terminal::Terminal;
/// use retroglyph_core::backend::Output as _;
/// use retroglyph_core::event::Event;
/// use retroglyph_terminal_wasm::{TerminalWasm, resize_terminal};
///
/// let mut term = Terminal::new(TerminalWasm::new(10, 3));
/// resize_terminal(&mut term, 20, 6);
///
/// assert_eq!(term.backend().size(), retroglyph_core::grid::Size::new(20, 6));
/// assert_eq!(term.poll(std::time::Duration::ZERO), Some(Event::Resize(20, 6)));
/// ```
///
/// [`app_entry!`]: crate::app_entry
pub fn resize_terminal(term: &mut Terminal<TerminalWasm>, width: u16, height: u16) {
    term.resize(width, height);
    Input::push_event(term.backend_mut(), Event::Resize(width, height));
}

impl Output for TerminalWasm {
    type Error = io::Error;

    fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        // Silently drop cells positioned outside the grid, the same as `Headless` and
        // `Software` already do: a caller-supplied `pos` is not trusted input, and this
        // renderer (unlike those two) has no bounds check of its own to fall back on.
        let size = self.size;
        let content =
            content.filter(move |cell| cell.pos.x < size.width() && cell.pos.y < size.height());
        self.renderer.draw_frame(content)
    }

    fn flush(&mut self) -> Result<(), Self::Error> {
        self.renderer.end_frame()
    }

    fn size(&self) -> Size {
        self.size
    }

    fn resize(&mut self, size: Size) {
        self.size = size;
        // The host's terminal emulator clears/reflows on its own resize;
        // forget our tracked cursor/color state so the next draw() re-emits
        // full escape sequences instead of (incorrectly) skipping them.
        self.renderer.reset_state();
    }

    fn clear(&mut self) -> Result<(), Self::Error> {
        // Reset SGR attributes *before* erasing: most terminals implement "erase display" via
        // background color erase (BCE), painting the erased cells with whatever background is
        // currently active in the pen, not the terminal's true default. Left un-reset, a cell
        // colored by the last frame (a themed panel, a highlighted tile) becomes the color the
        // erase paints the whole screen with. This backend has no direct handle to the emulator,
        // so both the reset and the "clear screen, cursor home" CSI sequence that follows it are
        // just more ANSI bytes for JS to forward, same as every other draw call.
        self.renderer.clear_screen()
    }
}

impl Input for TerminalWasm {
    fn poll_event(&mut self, _timeout: Duration) -> Option<Event> {
        // Never blocks: there is no runtime loop to block in. `_timeout` is
        // ignored, matching Headless's push-driven, non-blocking contract.
        self.event_queue.pop_front()
    }

    /// The sole public way to push an event onto a `TerminalWasm`; forwards to the crate-private
    /// inherent `push_event`.
    fn push_event(&mut self, event: Event) {
        Self::push_event(self, event);
    }
}

impl Cursor for TerminalWasm {
    fn set_cursor_visible(&mut self, visible: bool) {
        let _ = self.renderer.set_cursor_visible(visible);
    }

    fn set_cursor_position(&mut self, position: Pos) {
        let _ = self.renderer.move_cursor_to(position);
    }

    /// 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_style(&mut self, style: CursorStyle) {
        let _ = self.renderer.set_cursor_style(style);
    }
}

/// Decodes a `(code, mods)` pair from JS into a [`retroglyph_core::event::KeyEvent`].
///
/// `retroglyph_core::event::KeyCode`/`KeyModifiers` are not `wasm-bindgen`
/// FFI-safe types, so JS crosses the boundary with plain integers instead:
///
/// - `code`: for printable characters, the Unicode scalar value (as from
///   `event.key.codePointAt(0)` for a single-character key); for named keys,
///   one of [`key_codes`]'s constants (e.g. [`key_codes::LEFT`]).
/// - `mods`: a bitmask matching [`retroglyph_core::event::KeyModifiers`]'s
///   layout (`SHIFT = 1`, `CONTROL = 2`, `ALT = 4`, `SUPER = 8`). `SUPER` maps to the
///   JS `metaKey` (Cmd on macOS, the Windows/Super key elsewhere).
///
/// # Examples
///
/// ```
/// use retroglyph_core::event::KeyCode;
/// use retroglyph_terminal_wasm::{decode_key_event, key_codes};
///
/// // A printable character: `code` is its Unicode scalar value.
/// let key = decode_key_event(u32::from('a'), 0).unwrap();
/// assert_eq!(key.code, KeyCode::Char('a'));
///
/// // A named key, with the Control modifier bit (0b010) set.
/// let key = decode_key_event(key_codes::LEFT, 0b010).unwrap();
/// assert_eq!(key.code, KeyCode::Left);
/// assert!(key.modifiers.contains(retroglyph_core::event::KeyModifiers::CONTROL));
///
/// // A lone UTF-16 surrogate half is neither a named key nor a valid `char`.
/// assert!(decode_key_event(0xD800, 0).is_none());
/// ```
#[must_use]
pub fn decode_key_event(code: u32, mods: u8) -> Option<retroglyph_core::event::KeyEvent> {
    use key_codes as kc;
    use retroglyph_core::event::KeyCode;

    let key_code = match code {
        kc::BACKSPACE => KeyCode::Backspace,
        kc::ENTER => KeyCode::Enter,
        kc::LEFT => KeyCode::Left,
        kc::RIGHT => KeyCode::Right,
        kc::UP => KeyCode::Up,
        kc::DOWN => KeyCode::Down,
        kc::HOME => KeyCode::Home,
        kc::END => KeyCode::End,
        kc::PAGE_UP => KeyCode::PageUp,
        kc::PAGE_DOWN => KeyCode::PageDown,
        kc::TAB => KeyCode::Tab,
        kc::BACKTAB => KeyCode::BackTab,
        kc::DELETE => KeyCode::Delete,
        kc::INSERT => KeyCode::Insert,
        kc::ESCAPE => KeyCode::Escape,
        kc::F1..=kc::F24 =>
        {
            #[allow(clippy::cast_possible_truncation)]
            KeyCode::F((code - kc::F1 + 1) as u8)
        }
        _ => KeyCode::Char(char::from_u32(code)?),
    };

    Some(retroglyph_core::event::KeyEvent::new(
        key_code,
        decode_key_modifiers(mods),
    ))
}

/// Decodes the shared `mods` bitmask used by [`decode_key_event`] and
/// [`decode_mouse_event`] into a [`retroglyph_core::event::KeyModifiers`].
///
/// Bitmask layout: `SHIFT = 1`, `CONTROL = 2`, `ALT = 4`, `SUPER = 8`.
#[must_use]
const fn decode_key_modifiers(mods: u8) -> retroglyph_core::event::KeyModifiers {
    retroglyph_core::event::KeyModifiers::from_bits_truncate(mods)
}

/// Decodes an `(x, y, action, button, mods)` tuple from JS into a
/// [`retroglyph_core::event::MouseEvent`].
///
/// Same pattern as [`decode_key_event`]: `retroglyph_core::event::MouseEvent`
/// (and its `MouseEventKind`/`MouseButton` fields) are not `wasm-bindgen`
/// FFI-safe types, so JS crosses the boundary with plain integers instead:
///
/// - `x`, `y`: the cell-grid column/row the pointer is over, matching
///   [`retroglyph_core::grid::Pos`]. JS is responsible for converting a raw
///   pixel position (e.g. from a DOM `MouseEvent`) into cell coordinates
///   using the terminal emulator's own cell size, the same way it already
///   tracks `cols`/`rows` for the `wasm32`-only `wasm::wasm_terminal_resize`.
///   This backend has no sub-cell precision to report, so the returned
///   event's [`pixel_position`](retroglyph_core::event::MouseEvent::pixel_position)
///   is always `None`: the same convention `retroglyph-crossterm` uses for
///   its own character-mode backend.
/// - `action`: one of [`mouse_actions`]'s constants (`DOWN`, `UP`, `MOVED`,
///   `SCROLL_UP`, `SCROLL_DOWN`).
/// - `button`: which button the event applies to, one of [`mouse_buttons`]'s
///   constants (`LEFT`, `MIDDLE`, `RIGHT`), matching the DOM
///   `MouseEvent.button` convention JS already has on hand. Only consulted
///   when `action` is `DOWN` or `UP`; ignored otherwise.
/// - `mods`: the same bitmask layout as [`decode_key_event`]'s `mods`
///   (`SHIFT = 1`, `CONTROL = 2`, `ALT = 4`, `SUPER = 8`).
///
/// Returns `None` if `action` doesn't match a known [`mouse_actions`]
/// constant, or if `action` is `DOWN`/`UP` and `button` doesn't match a known
/// [`mouse_buttons`] constant.
///
/// # Examples
///
/// ```
/// use retroglyph_core::event::{MouseButton, MouseEventKind};
/// use retroglyph_terminal_wasm::{decode_mouse_event, mouse_actions, mouse_buttons};
///
/// let mouse = decode_mouse_event(3, 4, mouse_actions::DOWN, mouse_buttons::LEFT, 0).unwrap();
/// assert_eq!(mouse.kind, MouseEventKind::Down(MouseButton::Left));
/// assert_eq!(mouse.position, retroglyph_core::grid::Pos { x: 3, y: 4 });
///
/// // `button` is ignored for `MOVED`; an out-of-range value doesn't fail decoding.
/// let mouse = decode_mouse_event(1, 1, mouse_actions::MOVED, 0xFF, 0).unwrap();
/// assert_eq!(mouse.kind, MouseEventKind::Moved);
///
/// // An unknown `action` fails to decode.
/// assert!(decode_mouse_event(0, 0, 0xFF, mouse_buttons::LEFT, 0).is_none());
/// ```
#[must_use]
pub fn decode_mouse_event(
    x: u16,
    y: u16,
    action: u8,
    button: u8,
    mods: u8,
) -> Option<retroglyph_core::event::MouseEvent> {
    use mouse_actions as ma;
    use retroglyph_core::event::MouseEventKind;

    let kind = match action {
        ma::DOWN => MouseEventKind::Down(decode_mouse_button(button)?),
        ma::UP => MouseEventKind::Up(decode_mouse_button(button)?),
        ma::MOVED => MouseEventKind::Moved,
        // Wire protocol has no scroll magnitude; synthesize a unit-magnitude `Scroll` matching
        // the sign convention documented on `MouseEventKind::Scroll`.
        ma::SCROLL_UP => MouseEventKind::Scroll { dx: 0.0, dy: 1.0 },
        ma::SCROLL_DOWN => MouseEventKind::Scroll { dx: 0.0, dy: -1.0 },
        _ => return None,
    };

    Some(retroglyph_core::event::MouseEvent::new(
        kind,
        Pos { x, y },
        decode_key_modifiers(mods),
    ))
}

const fn decode_mouse_button(button: u8) -> Option<retroglyph_core::event::MouseButton> {
    use mouse_buttons as mb;
    use retroglyph_core::event::MouseButton;

    match button {
        mb::LEFT => Some(MouseButton::Left),
        mb::MIDDLE => Some(MouseButton::Middle),
        mb::RIGHT => Some(MouseButton::Right),
        _ => None,
    }
}

/// `action` values for [`decode_mouse_event`].
pub mod mouse_actions {
    /// A mouse button was pressed. `button` selects which one.
    pub const DOWN: u8 = 0;
    /// A mouse button was released. `button` selects which one.
    pub const UP: u8 = 1;
    /// The mouse moved. `button` is ignored.
    pub const MOVED: u8 = 2;
    /// The mouse wheel scrolled up (away from the user). `button` is ignored.
    pub const SCROLL_UP: u8 = 3;
    /// The mouse wheel scrolled down (toward the user). `button` is ignored.
    pub const SCROLL_DOWN: u8 = 4;
}

/// `button` values for [`decode_mouse_event`], matching the DOM
/// `MouseEvent.button` convention (`0` = left, `1` = middle, `2` = right) so
/// JS can forward its own `event.button` unchanged.
pub mod mouse_buttons {
    /// Left (primary) mouse button.
    pub const LEFT: u8 = 0;
    /// Middle (auxiliary) mouse button.
    pub const MIDDLE: u8 = 1;
    /// Right (secondary) mouse button.
    pub const RIGHT: u8 = 2;
}

/// `code` values for [`decode_key_event`]'s named (non-printable) keys.
///
/// Values start at `0x0011_0000`, above the Unicode scalar value space
/// (`0x0..=0x10FFFF`), so a single `u32` can carry either a codepoint or a
/// named key without ambiguity.
pub mod key_codes {
    const BASE: u32 = 0x0011_0000;

    /// Backspace.
    pub const BACKSPACE: u32 = BASE;
    /// Enter.
    pub const ENTER: u32 = BASE + 1;
    /// Left arrow.
    pub const LEFT: u32 = BASE + 2;
    /// Right arrow.
    pub const RIGHT: u32 = BASE + 3;
    /// Up arrow.
    pub const UP: u32 = BASE + 4;
    /// Down arrow.
    pub const DOWN: u32 = BASE + 5;
    /// Home.
    pub const HOME: u32 = BASE + 6;
    /// End.
    pub const END: u32 = BASE + 7;
    /// Page Up.
    pub const PAGE_UP: u32 = BASE + 8;
    /// Page Down.
    pub const PAGE_DOWN: u32 = BASE + 9;
    /// Tab.
    pub const TAB: u32 = BASE + 10;
    /// Backtab (Shift+Tab).
    pub const BACKTAB: u32 = BASE + 11;
    /// Delete.
    pub const DELETE: u32 = BASE + 12;
    /// Insert.
    pub const INSERT: u32 = BASE + 13;
    /// Escape.
    pub const ESCAPE: u32 = BASE + 14;
    /// F1. F2-F24 follow contiguously up to [`F24`].
    pub const F1: u32 = BASE + 100;
    /// F24, the last of the contiguous F1-F24 range.
    pub const F24: u32 = F1 + 23;
}

/// The `wasm-bindgen`-exported FFI surface, compiled only for `wasm32`.
///
/// A thin, stateful wrapper around [`TerminalWasm`] keyed by opaque handles,
/// since `wasm-bindgen` cannot export a type generic enough to hand a
/// `TerminalWasm` (or a `Terminal<TerminalWasm>`) directly to arbitrary game
/// code the way `retroglyph_examples::rg_run!` does for the software
/// backend. Each example that wants a WASM/xterm.js demo drives its own
/// per-example `#[wasm_bindgen]` entry point (see
/// `crates/examples/src/util/mod.rs`'s `rg_run!` for the software
/// equivalent); this module only owns the terminal instance registry and
/// event decoding that every such entry point would otherwise duplicate.
///
/// Every `wasm_terminal_*` function taking a `handle` logs a warning (via the `log` crate) and
/// otherwise does nothing if `handle` is unknown, e.g. because the terminal was already freed via
/// [`wasm_terminal_free`].
#[cfg(target_arch = "wasm32")]
pub mod wasm {
    use super::{TerminalWasm, decode_key_event, decode_mouse_event};
    use std::cell::RefCell;
    use std::collections::HashMap;
    use wasm_bindgen::prelude::wasm_bindgen;

    thread_local! {
        static INSTANCES: RefCell<HashMap<u32, TerminalWasm>> = RefCell::new(HashMap::new());
        static NEXT_HANDLE: RefCell<u32> = const { RefCell::new(1) };
    }

    /// Creates a new [`TerminalWasm`] of the given size and returns an opaque
    /// handle for use with the other `wasm_terminal_*` functions.
    #[wasm_bindgen]
    #[must_use]
    pub fn wasm_terminal_new(width: u16, height: u16) -> u32 {
        let handle = NEXT_HANDLE.with_borrow_mut(|next| {
            let handle = *next;
            *next += 1;
            handle
        });
        INSTANCES.with_borrow_mut(|instances| {
            instances.insert(handle, TerminalWasm::new(width, height));
        });
        handle
    }

    /// Destroys the [`TerminalWasm`] identified by `handle`, freeing its
    /// memory. Further calls with `handle` are no-ops.
    #[wasm_bindgen]
    pub fn wasm_terminal_free(handle: u32) {
        INSTANCES.with_borrow_mut(|instances| {
            instances.remove(&handle);
        });
    }

    /// Reports a new size (in cells) for the terminal identified by
    /// `handle`, e.g. after xterm.js's `fit` addon recomputes `cols`/`rows`.
    #[wasm_bindgen]
    pub fn wasm_terminal_resize(handle: u32, width: u16, height: u16) {
        use retroglyph_core::backend::Output;
        use retroglyph_core::grid::Size;
        INSTANCES.with_borrow_mut(|instances| {
            if let Some(term) = instances.get_mut(&handle) {
                term.resize(Size::new(width, height));
            } else {
                log::warn!("wasm_terminal_resize: unknown handle {handle}");
            }
        });
    }

    /// Pushes a key event into the terminal identified by `handle`. See
    /// [`decode_key_event`] for the `code`/`mods` encoding.
    ///
    /// Silently ignores codes that don't decode to a known key (e.g. a lone
    /// Unicode combining mark with no assigned scalar meaning here).
    #[wasm_bindgen]
    pub fn wasm_terminal_push_key(handle: u32, code: u32, mods: u8) {
        use retroglyph_core::event::Event;
        let Some(key_event) = decode_key_event(code, mods) else {
            return;
        };
        INSTANCES.with_borrow_mut(|instances| {
            if let Some(term) = instances.get_mut(&handle) {
                term.push_event(Event::Key(key_event));
            } else {
                log::warn!("wasm_terminal_push_key: unknown handle {handle}");
            }
        });
    }

    /// Pushes a mouse event into the terminal identified by `handle`. See
    /// [`decode_mouse_event`] for the `x`/`y`/`action`/`button`/`mods`
    /// encoding.
    ///
    /// Silently ignores an `action`/`button` combination that doesn't decode
    /// to a known mouse event.
    #[wasm_bindgen]
    pub fn wasm_terminal_push_mouse(handle: u32, x: u16, y: u16, action: u8, button: u8, mods: u8) {
        use retroglyph_core::event::Event;
        let Some(mouse_event) = decode_mouse_event(x, y, action, button, mods) else {
            return;
        };
        INSTANCES.with_borrow_mut(|instances| {
            if let Some(term) = instances.get_mut(&handle) {
                term.push_event(Event::Mouse(mouse_event));
            } else {
                log::warn!("wasm_terminal_push_mouse: unknown handle {handle}");
            }
        });
    }

    /// Pushes pasted text into the terminal identified by `handle`, delivered
    /// as a single [`retroglyph_core::event::Event::Paste`] rather than
    /// synthesized key events.
    ///
    /// Unlike [`wasm_terminal_push_key`], this takes a plain JS string
    /// directly: `String` is already `wasm-bindgen`-FFI-safe, so there's no
    /// `decode_*` step to pair with it, and no risk of a paste of `N`
    /// characters being misread as `N` individual keystrokes (which would let
    /// pasted text trigger single-key game commands one character at a
    /// time).
    ///
    /// The driver is responsible for sourcing `text`: e.g. a native browser
    /// `paste` event's `event.clipboardData.getData('text/plain')`, read
    /// synchronously and without an Async Clipboard API permission prompt.
    /// This crate has no opinion on *how* JS obtains the text, only that it
    /// arrives here as one call per paste.
    #[wasm_bindgen]
    pub fn wasm_terminal_push_paste(handle: u32, text: String) {
        use retroglyph_core::event::Event;
        INSTANCES.with_borrow_mut(|instances| {
            if let Some(term) = instances.get_mut(&handle) {
                term.push_event(Event::Paste(text));
            } else {
                log::warn!("wasm_terminal_push_paste: unknown handle {handle}");
            }
        });
    }

    /// Pushes a focus-change event into the terminal identified by `handle`.
    ///
    /// `focused: true` delivers [`Event::FocusGained`](retroglyph_core::event::Event::FocusGained),
    /// `focused: false` delivers
    /// [`Event::FocusLost`](retroglyph_core::event::Event::FocusLost). Mirrors the crossterm
    /// backend's `EnableFocusChange`-driven focus-event mapping, so a browser terminal element's
    /// native `focus`/`blur` DOM events can drive the same "pause when unfocused" pattern.
    #[wasm_bindgen]
    pub fn wasm_terminal_push_focus(handle: u32, focused: bool) {
        use retroglyph_core::event::Event;
        let event = if focused {
            Event::FocusGained
        } else {
            Event::FocusLost
        };
        INSTANCES.with_borrow_mut(|instances| {
            if let Some(term) = instances.get_mut(&handle) {
                term.push_event(event);
            } else {
                log::warn!("wasm_terminal_push_focus: unknown handle {handle}");
            }
        });
    }

    /// Drains and returns the ANSI bytes rendered since the last call for the
    /// terminal identified by `handle`. Returns an empty string if `handle`
    /// is unknown or nothing has been drawn since the last call.
    #[wasm_bindgen]
    #[must_use]
    pub fn wasm_terminal_take_output(handle: u32) -> String {
        INSTANCES.with_borrow_mut(|instances| {
            let Some(term) = instances.get_mut(&handle) else {
                log::warn!("wasm_terminal_take_output: unknown handle {handle}");
                return String::new();
            };
            term.take_output()
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use retroglyph_core::color::Style;
    use retroglyph_core::event::{Event, KeyCode, KeyModifiers};
    use retroglyph_core::terminal::Terminal;

    #[test]
    fn renders_into_pullable_buffer() {
        let backend = TerminalWasm::new(10, 3);
        let mut term = Terminal::new(backend);
        term.draw(|s| s.put((1, 1), 'H', Style::default())).unwrap();
        let out = term.backend_mut().take_output();
        assert!(out.contains('H'), "output: {out:?}");
        // Draining again returns nothing new until the next present().
        assert_eq!(term.backend_mut().take_output(), "");
    }

    #[test]
    fn resize_terminal_resizes_grid_backend_and_queues_resize_event() {
        // retroglyph#684: `term.resize(..)` alone (or just `Output::resize` on the backend)
        // leaves nothing in the input queue, so an app that reacts to `Event::Resize` rather than
        // re-checking `term.backend().size()` every frame would silently keep its old layout.
        let mut term = Terminal::new(TerminalWasm::new(10, 3));
        resize_terminal(&mut term, 20, 6);

        assert_eq!(term.backend().size(), Size::new(20, 6));
        assert_eq!(term.grid().width(), 20);
        assert_eq!(term.grid().height(), 6);
        assert_eq!(
            term.poll(Duration::ZERO),
            Some(Event::Resize(20, 6)),
            "resize_terminal must queue the matching Event::Resize"
        );
    }

    #[test]
    fn take_output_retains_capacity_across_frames() {
        // retroglyph#287: the replacement buffer left behind after a drain should be pre-sized
        // to the outgoing buffer's capacity, not restart from zero every frame.
        let backend = TerminalWasm::new(40, 12);
        let mut term = Terminal::new(backend);
        term.draw(|s| {
            for y in 0..12 {
                for x in 0..40 {
                    s.put((x, y), 'X', Style::default());
                }
            }
        })
        .unwrap();
        let first = term.backend_mut().take_output();
        assert!(!first.is_empty());

        // The internal sink left behind should already be sized to hold another frame of
        // similar size without regrowing from an empty allocation.
        let internal_capacity = term.backend_mut().renderer.writer().0.capacity();
        assert!(
            internal_capacity >= first.len(),
            "expected the replacement buffer to retain the previous frame's capacity \
             ({internal_capacity} < {})",
            first.len()
        );
    }

    #[test]
    fn take_output_into_clears_and_fills_caller_buffer() {
        let backend = TerminalWasm::new(10, 3);
        let mut term = Terminal::new(backend);
        term.draw(|s| s.put((1, 1), 'H', Style::default())).unwrap();

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

        // Draining again with nothing new pending clears the caller's buffer to empty.
        term.backend_mut().take_output_into(&mut buf);
        assert_eq!(buf, "");
    }

    #[test]
    fn clear_resets_sgr_attributes_before_erasing() {
        // Regression test: `Output::clear` used to issue `CSI 2J` without resetting the SGR pen
        // first. Terminals that implement erase-display via background color erase (BCE) paint
        // erased cells with whatever background is currently active, not the terminal's true
        // default, so a colored cell drawn just before a `clear()` left a stale tint across the
        // whole screen. `clear` must emit a full SGR reset ahead of the erase so BCE always
        // paints with the terminal's real default background. See retroglyph#715.
        use retroglyph_core::color::Color;

        let backend = TerminalWasm::new(10, 3);
        let mut term = Terminal::new(backend);
        let style = Style::default().bg(Color::Rgb { r: 200, g: 0, b: 0 });
        term.draw(|s| s.put((0, 0), 'X', style)).unwrap();
        let _ = term.backend_mut().take_output();

        Output::clear(term.backend_mut()).unwrap();

        let out = term.backend_mut().take_output();
        let clear_pos = out
            .rfind("\x1b[2J")
            .unwrap_or_else(|| panic!("clear() must emit CSI 2J, got: {out:?}"));
        let reset_pos = out
            .rfind("\x1b[0m")
            .unwrap_or_else(|| panic!("clear() must emit a full SGR reset, got: {out:?}"));
        assert!(
            reset_pos < clear_pos,
            "SGR reset must precede the erase so background color erase paints with the \
             terminal's true default, not the last frame's color; output: {out:?}"
        );
    }

    #[test]
    fn push_event_then_poll_roundtrips() {
        let mut backend = TerminalWasm::new(10, 3);
        backend.push_event(Event::Key(retroglyph_core::event::KeyEvent::new(
            KeyCode::Left,
            KeyModifiers::NONE,
        )));
        assert_eq!(
            Input::poll_event(&mut backend, Duration::ZERO),
            Some(Event::Key(retroglyph_core::event::KeyEvent::new(
                KeyCode::Left,
                KeyModifiers::NONE
            )))
        );
        assert_eq!(Input::poll_event(&mut backend, Duration::ZERO), None);
    }

    #[test]
    fn push_event_supports_paste_as_a_single_event() {
        // A paste is delivered as one `Event::Paste`, not one `Event::Key` per character; see
        // `wasm::wasm_terminal_push_paste`'s doc comment for why that distinction matters (pasted
        // text must not be misread as individual keystrokes triggering single-key commands).
        let mut backend = TerminalWasm::new(10, 3);
        backend.push_event(Event::Paste("hello, world".to_string()));
        assert_eq!(
            Input::poll_event(&mut backend, Duration::ZERO),
            Some(Event::Paste("hello, world".to_string()))
        );
        assert_eq!(Input::poll_event(&mut backend, Duration::ZERO), None);
    }

    #[test]
    fn push_event_supports_focus_gained_and_lost() {
        let mut backend = TerminalWasm::new(10, 3);
        backend.push_event(Event::FocusGained);
        backend.push_event(Event::FocusLost);
        assert_eq!(
            Input::poll_event(&mut backend, Duration::ZERO),
            Some(Event::FocusGained)
        );
        assert_eq!(
            Input::poll_event(&mut backend, Duration::ZERO),
            Some(Event::FocusLost)
        );
        assert_eq!(Input::poll_event(&mut backend, Duration::ZERO), None);
    }

    #[test]
    fn cursor_position_uses_1_indexed_cup_sequence() {
        // CSI row;col H (CUP), 1-indexed and absolute: verified against xterm.js and
        // hterm/Terminalemulator (see `TerminalRenderer::move_cursor_to`'s doc comment). Both use
        // the same format, so no dual-emission or 0-indexed fallback is needed.
        let mut backend = TerminalWasm::new(10, 3);
        Cursor::set_cursor_position(&mut backend, Pos { x: 0, y: 0 });
        assert_eq!(backend.take_output(), "\x1b[1;1H");

        Cursor::set_cursor_position(&mut backend, Pos { x: 4, y: 2 });
        assert_eq!(backend.take_output(), "\x1b[3;5H");
    }

    #[test]
    fn set_cursor_position_desyncs_the_renderers_tracked_cursor() {
        // Regression test for retroglyph#713: `set_cursor_position` wrote its CUP escape
        // straight into the writer without telling the shared `TerminalRenderer` the cursor had
        // moved, so `cursor_x`/`cursor_y` kept whatever position the last *drawn glyph* left them
        // at. A subsequent `draw()` whose first changed cell happened to match that stale tracked
        // position then skipped its own CUP entirely, painting wherever the real cursor was
        // actually left (by `set_cursor_position`) instead of the intended cell.
        use retroglyph_core::backend::DrawCell;
        use retroglyph_core::backend::Output;

        let mut backend = TerminalWasm::new(10, 3);
        let tile_a = retroglyph_core::tile::Tile::new('A', Style::default());
        let tile_b = retroglyph_core::tile::Tile::new('B', Style::default());

        // Drawing at (0, 0) leaves the renderer tracking the cursor at (1, 0), right after the
        // glyph it just wrote.
        Output::draw_layers(
            &mut backend,
            core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile_a)),
        )
        .unwrap();
        Output::flush(&mut backend).unwrap();

        // The app parks the caret elsewhere, e.g. a text field or status line, once per frame: a
        // common pattern that must not corrupt the next frame's diff.
        Cursor::set_cursor_position(&mut backend, Pos { x: 7, y: 3 });
        Output::flush(&mut backend).unwrap();

        // The first (and only) changed cell in this frame is exactly (1, 0): the position
        // `set_cursor_position` desynced the tracked cursor from.
        Output::draw_layers(
            &mut backend,
            core::iter::once(DrawCell::new(Pos { x: 1, y: 0 }, &tile_b)),
        )
        .unwrap();
        Output::flush(&mut backend).unwrap();

        let written = backend.take_output();
        let cup_1_0 = "\x1b[1;2H"; // 1-indexed CUP for (x=1, y=0)
        let b_pos = written
            .rfind('B')
            .unwrap_or_else(|| panic!("expected 'B' in output: {written:?}"));
        let cup_pos = written.rfind(cup_1_0).unwrap_or_else(|| {
            panic!("expected a CUP back to (1, 0) before drawing 'B', got: {written:?}")
        });
        assert!(
            cup_pos < b_pos,
            "CUP to (1, 0) must precede 'B': {written:?}"
        );
    }

    #[test]
    fn set_cursor_style_writes_the_matching_decscusr_escape() {
        // retroglyph#767: `terminal-wasm` previously had no `Cursor::set_cursor_style`
        // implementation at all; it now delegates to the same `TerminalRenderer::set_cursor_style`
        // that `retroglyph-crossterm` uses, verified against the same DECSCUSR codes there.
        use retroglyph_core::backend::CursorStyle;

        let mut backend = TerminalWasm::new(10, 3);
        Cursor::set_cursor_style(&mut backend, CursorStyle::BlinkingBar);
        assert_eq!(backend.take_output(), "\x1b[5 q");
    }

    #[test]
    fn size_is_set_externally_not_queried() {
        let mut backend = TerminalWasm::new(80, 24);
        assert_eq!(backend.size(), Size::new(80, 24));
        backend.resize(Size::new(40, 12));
        assert_eq!(backend.size(), Size::new(40, 12));
    }

    #[test]
    fn decode_key_event_maps_printable_char() {
        let key = decode_key_event(u32::from('a'), 0).unwrap();
        assert_eq!(key.code, KeyCode::Char('a'));
        assert!(key.modifiers.is_empty());
    }

    #[test]
    fn decode_key_event_maps_named_keys() {
        let key = decode_key_event(key_codes::LEFT, 0b010).unwrap();
        assert_eq!(key.code, KeyCode::Left);
        assert!(key.modifiers.contains(KeyModifiers::CONTROL));
    }

    #[test]
    fn decode_key_event_maps_super_modifier() {
        let key = decode_key_event(u32::from('x'), 0b1000).unwrap();
        assert_eq!(key.code, KeyCode::Char('x'));
        assert!(key.modifiers.contains(KeyModifiers::SUPER));
    }

    #[test]
    fn decode_key_event_maps_super_combined_with_other_modifiers() {
        let key = decode_key_event(u32::from('x'), 0b1011).unwrap();
        assert!(key.modifiers.contains(KeyModifiers::SHIFT));
        assert!(key.modifiers.contains(KeyModifiers::CONTROL));
        assert!(key.modifiers.contains(KeyModifiers::SUPER));
        assert!(!key.modifiers.contains(KeyModifiers::ALT));
    }

    #[test]
    fn decode_key_event_maps_function_keys() {
        let key = decode_key_event(key_codes::F1, 0).unwrap();
        assert_eq!(key.code, KeyCode::F(1));

        let key = decode_key_event(key_codes::F1 + 11, 0).unwrap();
        assert_eq!(key.code, KeyCode::F(12));
    }

    #[test]
    fn decode_key_event_maps_f24_the_last_of_the_contiguous_range() {
        let key = decode_key_event(key_codes::F24, 0).unwrap();
        assert_eq!(key.code, KeyCode::F(24));
    }

    #[test]
    fn decode_key_event_one_past_f24_falls_through_to_char_decode_and_fails() {
        // `F24 + 1` is `BASE + 124`, past `char::MAX` (0x10FFFF): not a named key and not a
        // valid `char` either, so this must decode to `None`, not panic or wrap into a bogus
        // `KeyCode::F(25)`.
        assert!(decode_key_event(key_codes::F24 + 1, 0).is_none());
    }

    #[test]
    fn decode_key_event_maps_every_named_key_constant() {
        use key_codes::{
            BACKSPACE, BACKTAB, DELETE, DOWN, END, ENTER, ESCAPE, HOME, INSERT, LEFT, PAGE_DOWN,
            PAGE_UP, RIGHT, TAB, UP,
        };

        for &(code, expected) in &[
            (BACKSPACE, KeyCode::Backspace),
            (ENTER, KeyCode::Enter),
            (LEFT, KeyCode::Left),
            (RIGHT, KeyCode::Right),
            (UP, KeyCode::Up),
            (DOWN, KeyCode::Down),
            (HOME, KeyCode::Home),
            (END, KeyCode::End),
            (PAGE_UP, KeyCode::PageUp),
            (PAGE_DOWN, KeyCode::PageDown),
            (TAB, KeyCode::Tab),
            (BACKTAB, KeyCode::BackTab),
            (DELETE, KeyCode::Delete),
            (INSERT, KeyCode::Insert),
            (ESCAPE, KeyCode::Escape),
        ] {
            assert_eq!(decode_key_event(code, 0).unwrap().code, expected);
        }
    }

    #[test]
    fn decode_key_event_accepts_the_null_char() {
        // 0x00 is a valid (if unusual) Unicode scalar value, and not a named key code.
        let key = decode_key_event(0x00, 0).unwrap();
        assert_eq!(key.code, KeyCode::Char('\0'));
    }

    #[test]
    fn decode_key_event_rejects_lone_surrogate_half_code_points() {
        // 0xD800..=0xDFFF are lone UTF-16 surrogate halves: never a valid `char`, and outside
        // every named-key range, so this must decode to `None`, not panic.
        assert!(decode_key_event(0xD800, 0).is_none());
        assert!(decode_key_event(0xDFFF, 0).is_none());
    }

    #[test]
    fn decode_key_event_rejects_out_of_range_code_points() {
        assert!(decode_key_event(u32::MAX, 0).is_none());
        // In the gap between the named control-key block (`BASE..=BASE+14`) and the F-key block
        // (`BASE+100..=BASE+123`): not a named key, and (like every named-key code, since
        // `BASE` (`0x0011_0000`) sits one past `char::MAX` (0x10FFFF)) not a valid `char`
        // either. `BASE` itself is *not* an out-of-range example: it's `KeyCode::Backspace`.
        assert!(decode_key_event(key_codes::ESCAPE + 1, 0).is_none());
    }

    #[test]
    fn decode_mouse_event_maps_button_down() {
        use retroglyph_core::event::{MouseButton, MouseEventKind};

        let mouse = decode_mouse_event(3, 4, mouse_actions::DOWN, mouse_buttons::LEFT, 0).unwrap();
        assert_eq!(mouse.kind, MouseEventKind::Down(MouseButton::Left));
        assert_eq!(mouse.position, Pos { x: 3, y: 4 });
        assert_eq!(mouse.pixel_position, None);
        assert!(mouse.modifiers.is_empty());
    }

    #[test]
    fn decode_mouse_event_maps_button_up() {
        use retroglyph_core::event::{MouseButton, MouseEventKind};

        let mouse = decode_mouse_event(0, 0, mouse_actions::UP, mouse_buttons::RIGHT, 0).unwrap();
        assert_eq!(mouse.kind, MouseEventKind::Up(MouseButton::Right));
    }

    #[test]
    fn decode_mouse_event_maps_moved_ignoring_button() {
        use retroglyph_core::event::MouseEventKind;

        // `button` is ignored for `MOVED`; an out-of-range value must not fail decoding.
        let mouse = decode_mouse_event(1, 1, mouse_actions::MOVED, 0xFF, 0).unwrap();
        assert_eq!(mouse.kind, MouseEventKind::Moved);
    }

    #[test]
    fn decode_mouse_event_maps_scroll() {
        use retroglyph_core::event::MouseEventKind;

        let up = decode_mouse_event(0, 0, mouse_actions::SCROLL_UP, 0, 0).unwrap();
        assert_eq!(up.kind, MouseEventKind::Scroll { dx: 0.0, dy: 1.0 });

        let down = decode_mouse_event(0, 0, mouse_actions::SCROLL_DOWN, 0, 0).unwrap();
        assert_eq!(down.kind, MouseEventKind::Scroll { dx: 0.0, dy: -1.0 });
    }

    #[test]
    fn decode_mouse_event_maps_modifiers() {
        let mouse =
            decode_mouse_event(0, 0, mouse_actions::DOWN, mouse_buttons::MIDDLE, 0b1101).unwrap();
        assert!(mouse.modifiers.contains(KeyModifiers::SHIFT));
        assert!(mouse.modifiers.contains(KeyModifiers::ALT));
        assert!(mouse.modifiers.contains(KeyModifiers::SUPER));
        assert!(!mouse.modifiers.contains(KeyModifiers::CONTROL));
    }

    #[test]
    fn decode_mouse_event_rejects_unknown_action() {
        assert!(decode_mouse_event(0, 0, 0xFF, mouse_buttons::LEFT, 0).is_none());
    }

    #[test]
    fn decode_mouse_event_rejects_unknown_button_for_down_and_up() {
        assert!(decode_mouse_event(0, 0, mouse_actions::DOWN, 0xFF, 0).is_none());
        assert!(decode_mouse_event(0, 0, mouse_actions::UP, 0xFF, 0).is_none());
    }

    #[test]
    fn push_event_caps_queue_and_drops_oldest_under_burst() {
        // A burst well past `EVENT_QUEUE_CAP`, of non-coalescing events (alternating key codes,
        // so nothing here hits the `Moved` coalescing path) must never grow the queue past the
        // cap, and the oldest entries are the ones dropped: the earliest surviving key should
        // be from partway through the burst, not from the very start.
        let mut backend = TerminalWasm::new(10, 3);
        let total = EVENT_QUEUE_CAP + 500;
        for i in 0..total {
            #[allow(clippy::cast_possible_truncation)]
            let code = u32::from(b'a') + (i % 26) as u32;
            backend.push_event(Event::Key(retroglyph_core::event::KeyEvent::new(
                KeyCode::Char(char::from_u32(code).unwrap()),
                KeyModifiers::NONE,
            )));
        }
        assert_eq!(backend.event_queue.len(), EVENT_QUEUE_CAP);

        // Drain and count: still exactly the cap's worth of events, none created out of thin air.
        let mut drained = 0usize;
        while Input::poll_event(&mut backend, Duration::ZERO).is_some() {
            drained += 1;
        }
        assert_eq!(drained, EVENT_QUEUE_CAP);
    }

    #[test]
    fn push_event_coalesces_consecutive_moved_events() {
        use retroglyph_core::event::{MouseButton, MouseEvent, MouseEventKind};

        let mut backend = TerminalWasm::new(80, 24);
        for x in 0..200u16 {
            backend.push_event(Event::Mouse(MouseEvent::new(
                MouseEventKind::Moved,
                Pos { x, y: 0 },
                KeyModifiers::NONE,
            )));
        }

        // All 200 `Moved` pushes collapsed into a single queued event, holding only the latest
        // position.
        assert_eq!(backend.event_queue.len(), 1);
        assert_eq!(
            Input::poll_event(&mut backend, Duration::ZERO),
            Some(Event::Mouse(MouseEvent::new(
                MouseEventKind::Moved,
                Pos { x: 199, y: 0 },
                KeyModifiers::NONE,
            )))
        );
        assert_eq!(Input::poll_event(&mut backend, Duration::ZERO), None);

        // A non-`Moved` mouse event breaks the coalescing run: it queues alongside, not merged
        // into, a preceding `Moved`.
        backend.push_event(Event::Mouse(MouseEvent::new(
            MouseEventKind::Moved,
            Pos { x: 1, y: 1 },
            KeyModifiers::NONE,
        )));
        backend.push_event(Event::Mouse(MouseEvent::new(
            MouseEventKind::Down(MouseButton::Left),
            Pos { x: 1, y: 1 },
            KeyModifiers::NONE,
        )));
        assert_eq!(backend.event_queue.len(), 2);
    }

    #[test]
    fn push_event_never_drops_or_coalesces_non_moved_events_under_burst() {
        use retroglyph_core::event::{MouseButton, MouseEvent, MouseEventKind};

        // A burst of distinct key presses, mouse clicks, and pastes (well under the cap, and
        // none of them `Moved`) must all survive untouched: no coalescing (they're not `Moved`)
        // and no dropping (the burst never reaches `EVENT_QUEUE_CAP`).
        let mut backend = TerminalWasm::new(80, 24);
        let mut expected = Vec::new();

        for i in 0..50u16 {
            let key = Event::Key(retroglyph_core::event::KeyEvent::new(
                KeyCode::Char('a'),
                KeyModifiers::NONE,
            ));
            backend.push_event(key.clone());
            expected.push(key);

            let click = Event::Mouse(MouseEvent::new(
                MouseEventKind::Down(MouseButton::Left),
                Pos { x: i, y: i },
                KeyModifiers::NONE,
            ));
            backend.push_event(click.clone());
            expected.push(click);

            let paste = Event::Paste(format!("paste-{i}"));
            backend.push_event(paste.clone());
            expected.push(paste);
        }

        assert_eq!(backend.event_queue.len(), expected.len());
        for expected_event in expected {
            assert_eq!(
                Input::poll_event(&mut backend, Duration::ZERO),
                Some(expected_event)
            );
        }
        assert_eq!(Input::poll_event(&mut backend, Duration::ZERO), None);
    }

    // Guards against the JS driver example silently forking into two different (and eventually
    // contradictory) versions: one embedded in this crate's own doc comment (via `include_str!`
    // of `js/xterm-driver.js`, see the module doc above) and one hand-copied into README.md's
    // "Usage from JS" section, since crates.io/GitHub render README.md as plain markdown and
    // can't `include_str!` it the way rustdoc can. `js/xterm-driver.js` is the source of truth;
    // if this test fails, README.md's fenced ```js block fell out of sync with it.
    #[test]
    fn readme_js_example_matches_canonical_driver() {
        let canonical = include_str!("../js/xterm-driver.js");
        let readme = include_str!("../README.md");

        let fence_start = readme
            .find("```js\n")
            .expect("README.md should have a ```js fenced code block")
            + "```js\n".len();
        let fence_end = readme[fence_start..]
            .find("```")
            .expect("README.md's ```js fence should be closed")
            + fence_start;
        let readme_js = &readme[fence_start..fence_end];

        assert_eq!(
            readme_js, canonical,
            "README.md's JS driver example has drifted from js/xterm-driver.js: update \
             README.md's fenced ```js block to match the canonical file"
        );
    }

    // ── Output/Cursor conformance (retroglyph#763) ──────────────────────────────────────────

    /// [`Observable::snapshot`] hashes only the bytes appended since the previous call, per that
    /// trait's docs: `TerminalWasm`'s observable state is an append-only ANSI byte buffer, and
    /// [`TerminalWasm::take_output`] already drains exactly that (nothing new to build here).
    impl retroglyph_core::testing::conformance::Observable for TerminalWasm {
        fn snapshot(&mut self) -> u64 {
            retroglyph_core::testing::conformance::fnv1a(self.take_output().as_bytes())
        }
    }

    #[test]
    fn satisfies_the_output_contract() {
        retroglyph_core::testing::conformance::assert_output_contract(|size| {
            TerminalWasm::new(size.width(), size.height())
        });
    }

    #[test]
    fn satisfies_the_input_contract() {
        retroglyph_core::testing::conformance::assert_input_contract(|| TerminalWasm::new(10, 10));
    }

    #[test]
    fn satisfies_the_cursor_contract() {
        retroglyph_core::testing::conformance::assert_cursor_contract(|size| {
            TerminalWasm::new(size.width(), size.height())
        });
    }

    #[test]
    fn satisfies_the_cursor_style_contract() {
        retroglyph_core::testing::conformance::assert_cursor_style_contract(|size| {
            TerminalWasm::new(size.width(), size.height())
        });
    }
}

/// Fuzzes [`decode_key_event`] over arbitrary `(code, mods)` pairs: no `(u32, u8)` input may
/// panic, produce invalid Unicode, or produce an out-of-bounds F-key index. See
/// `crates/core/src/grid.rs`'s `egc_proptests` module for the same pattern applied elsewhere in
/// the workspace.
///
/// Not compiled for `wasm32`: `proptest` pulls in `rand`/`getrandom`, and `getrandom` does not
/// build for `wasm32-unknown-unknown` without extra feature wiring that `just test-wasm`'s
/// `wasm-pack` build doesn't do (see the matching `proptest` dev-dependency's cfg gate in
/// `Cargo.toml`). `decode_key_event` itself has no wasm-specific behavior, so host-only coverage
/// is sufficient.
#[cfg(all(test, not(target_arch = "wasm32")))]
mod decode_key_event_proptests {
    use super::*;
    use proptest::prelude::*;
    use retroglyph_core::event::{KeyCode, KeyModifiers};

    /// The contiguous `BASE..=BASE+14` block of named, non-`char`, non-F control keys
    /// ([`key_codes::BACKSPACE`] through [`key_codes::ESCAPE`]).
    fn is_named_control_key(code: u32) -> bool {
        (key_codes::BACKSPACE..=key_codes::ESCAPE).contains(&code)
    }

    proptest! {
        /// Every `(code, mods)` pair must be explainable by exactly one of three cases (a
        /// named control key, the contiguous F1-F24 range, or a valid printable `char`) and
        /// must never panic getting there.
        #[test]
        fn never_panics_and_result_matches_one_of_three_cases(code: u32, mods: u8) {
            let result = decode_key_event(code, mods);

            if is_named_control_key(code) {
                let key = result.expect("named control key code decoded to None");
                assert!(
                    !matches!(key.code, KeyCode::Char(_) | KeyCode::F(_)),
                    "named control key code {code:#x} decoded to {:?}",
                    key.code
                );
            } else if (key_codes::F1..=key_codes::F24).contains(&code) {
                let key = result.expect("F1..=F24 range code decoded to None");
                let KeyCode::F(n) = key.code else {
                    panic!("F-key range code {code:#x} decoded to {:?}, not KeyCode::F", key.code);
                };
                assert!((1..=24).contains(&n), "F-key index {n} out of the documented 1..=24 range");
                assert_eq!(u32::from(n), code - key_codes::F1 + 1);
            } else if let Some(c) = char::from_u32(code) {
                let key = result.expect("valid, non-named char code decoded to None");
                assert_eq!(key.code, KeyCode::Char(c));
            } else {
                // Not a named key, not an F-key, and not a valid Unicode scalar value (a lone
                // UTF-16 surrogate half, or anything past `char::MAX`): must decode to `None`,
                // not panic or fabricate a `KeyCode`.
                assert!(
                    result.is_none(),
                    "invalid Unicode code point {code:#x} decoded to {:?} instead of None",
                    result.map(|k| k.code)
                );
            }
        }

        /// Modifier decoding is independent of `code`: every bit of `mods` maps to exactly one
        /// `KeyModifiers` flag, for every key that successfully decodes.
        #[test]
        fn modifiers_decode_independently_of_code(code: u32, mods: u8) {
            if let Some(key) = decode_key_event(code, mods) {
                assert_eq!(key.modifiers.contains(KeyModifiers::SHIFT), mods & 0b0001 != 0);
                assert_eq!(key.modifiers.contains(KeyModifiers::CONTROL), mods & 0b0010 != 0);
                assert_eq!(key.modifiers.contains(KeyModifiers::ALT), mods & 0b0100 != 0);
                assert_eq!(key.modifiers.contains(KeyModifiers::SUPER), mods & 0b1000 != 0);
            }
        }
    }
}