DOCSEARCHbyAlgolia
Submit Docs

Rio Terminal Documentation

repository·main·Indexed 27 days ago

https://github.com/raphamorim/rio

A modern, cross-platform terminal emulator designed for high performance and visual flexibility. The project includes rio-vt, an embeddable terminal core with a VT state machine and ANSI parser; librio, a C ABI wrapper for non-Rust consumers; and supporting libraries such as rio-window (a Winit fork), teletypewriter for TTY emulation, and corcovado, a non-blocking IO library based on mio 0.6.x.

Tokens
24.9K
Snippets
41
Records
172
Agent score
92%

What's inside Rio

  4. Overview of librio

    main

    librio is an embeddable terminal core extracted from the Rio project. It provides PTY spawning, VT (Virtual Terminal) parsing, terminal state management, and a host-pulled render-state API with per-row dirty tracking.

    Key characteristics:

    • No drawing or windowing code: It is designed for developers to bring their own renderer.
    • C ABI Wrapper: It wraps rio-vt as a C ABI, making it suitable for non-Rust consumers like Swift or C.
    • Distribution: It is not published to crates.io. It is distributed as the RioKit.xcframework static library in Rio's GitHub releases.
    • Rust Users: If you are writing in Rust, you should depend on rio-vt directly instead of using librio.

  5. Overview of Corcovado

    main
    Corcovado is a maintained fork of mio 0.6.x. It is designed to work with Windows 11 by utilizing the Windows API and includes integrations with mio-signal-hook and mio-extras. Unlike the original mio 0.6.x, Corcovado uses Rust edition 2021 and leverages the Rust standard library for networking (net) and I/O operations instead of relying on mio 0.6.x for those specific tasks.

  6. Security and Constraints of Glyph Protocol

    main

    The Glyph Protocol is designed to allow applications to register custom glyphs without altering the semantic meaning of existing text. Key security and operational constraints include:

    • PUA Restriction: Registration is strictly limited to the three Unicode Private Use Areas (PUA). Any attempt to register a non-PUA codepoint must be rejected with reason=out_of_namespace.
    • Cell Buffer Authority: Text extraction tools (selection, copy, search, hyperlinks, shell history) must return the original emitted codepoint, not the rendered glyph.
    • Resource Limits: There is a 1024-slot cap for simultaneous registrations per session and a 64 KiB cap per payload, limiting the memory footprint to approximately 64 MiB per session.
    • No Code Execution: The glyf subset excludes executable hinting instructions; the protocol is purely declarative.
    • Session Isolation: Glossaries are not shared between terminal tabs, windows, or PTY sessions.

  7. Understand the Glyph Protocol Overview

    main

    Glyph Protocol is a terminal protocol that allows applications to ship custom vector glyphs (monochrome or full-color) to the terminal at runtime. This eliminates the need for users to install patched fonts like Nerd Fonts.

    Key features:

    • Vector-based: Glyphs are resolution-independent and scale to any cell size.
    • Safe: Registrations are restricted to Unicode Private Use Areas (PUA) to avoid modifying standard text.
    • Graceful Degradation: Terminals that do not support the protocol simply ignore the messages. Applications can detect support via a protocol-detection ping.
    • Payload Formats: Supports monochrome via OpenType glyf, and color via OpenType COLR v0 (layered) or COLR v1 (paint graph).

  8. Use librio for embeddable terminal functionality

    main

    librio is an embeddable terminal library that provides PTY and VT (Virtual Terminal) state management. It is designed to be used from Swift, C, or any language that can interface with a C ABI, without requiring a windowing stack.

    Key characteristics:

    • VT-only: It manages the PTY, VT state, and provides a render-state API, but it does not include a renderer. The host application is responsible for pulling the render state and drawing it (e.g., via a CPU renderer, WASM canvas, or TUI).
    • Pull Model: The host pulls a snapshot of the terminal state with per-row dirty flags. The host is responsible for resetting these flags after rendering.
    • Threading: A Surface owns a dedicated PTY IO thread. Callbacks like wakeup_cb and action_cb may fire on this IO thread and should only be used to flag or schedule work on the host thread.

  9. Setup and run WASM tests for Sugarloaf

    main

    To run tests targeting WebAssembly (WASM), you must first install the wasm-bindgen-cli tool globally to provide the necessary test runner harness.

    1. Install wasm-bindgen-cli

    cargo install wasm-bindgen-cli

    2. Run WASM tests

    Execute the following command from the root sugarloaf directory:

    CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner cargo test --target wasm32-unknown-unknown -p sugarloaf --tests

    Flag details:

    • CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner: Instructs Cargo to use the wasm-bindgen-cli test harness.
    • -p sugarloaf: Limits the test execution to the sugarloaf package.
    • --tests: Runs only the tests and skips building examples (which may fail to compile to WASM due to networking dependencies).
    cargo install wasm-bindgen-cli

CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner cargo test --target wasm32-unknown-unknown -p sugarloaf --tests

  10. Pipeline for generating `glyf` data

    main

    Since most applications do not hand-author glyf bytes, use the following pipeline to extract glyphs from existing fonts (like Nerd Fonts):

    1. Open the source TTF (e.g., a Nerd Font) using fontTools.
    2. Extract the glyph record for the desired codepoint.
    3. If the glyph is composite, flatten it using fontTools.pens.ttGlyphPen.TTGlyphPen.
    4. Strip hinting instructions (set instructionLength := 0) to comply with the glyf subset.
    5. Compile the result to bytes, base64-encode it, and register it at a chosen PUA codepoint (ideally in the Supplementary PUA-B range U+100000+).

  11. Distribute and integrate librio

    main

    librio is not published to crates.io. It is distributed as static artifacts via Rio's GitHub releases.

    • For Swift/C users: Use the RioKit.xcframework provided in the releases. This includes the static library, curated headers, and a module.modulemap for easy integration in Xcode.
    • For Rust users: Do not use librio. Instead, depend on the rio-vt crate directly, which is the idiomatic, published Rust crate.

  12. Author `COLR` glyph payloads

    main

    To create colored glyphs for the Glyph Protocol, do not hand-author COLR bytes. Use one of the following workflows:

    1. From an existing colour font: Use fontTools to extract the COLR/CPAL tables for specific glyphs, then pack them with the referenced outlines into the protocol container.
    2. From SVG: Use tools like nanoemoji or maximum-color (from the Skia team) to compile a directory of SVGs into a COLR v1 font, then use the output in your packer.