Module hyperlink

Expand description

OSC 8 terminal hyperlinks.

Like crate::term::progress (OSC 9;4), this is an out-of-band terminal capability that ratatui’s cell buffer cannot carry: a Cell holds one grapheme + style, with nowhere to attach a link target, and embedding the escape in a cell’s symbol breaks width accounting. So hyperlinks are emitted by writing styled spans directly to the terminal, wrapping link runs in the OSC 8 sequence:

ESC ] 8 ; ; <url> ST   <visible text>   ESC ] 8 ; ; ST

where ST is the string terminator (ESC \). Terminals that support OSC 8 (Ghostty, iTerm2, WezTerm, Kitty, recent VTE) make the run clickable; others ignore the unknown OSC and render the text unchanged.

encode is the pure encoder (validated + sanitized, unit-testable with no I/O). write_line serializes a ratatui Line — colors, common modifiers, and OSC 8 links — to any Write sink, so a host can push a transcript line to scrollback with real hyperlinks instead of going through the cell buffer.

Structs§

BufferLink: A hyperlink run in a rendered buffer: columns [start_col, end_col) on line (0-based within the rendered lines, not screen coordinates) point at url. Produced by markdown when a [label](url) (or bare URL) survives wrapping; applied with apply_buffer_links.
HyperlinkBackend: A ratatui Backend that wraps CrosstermBackend and makes http(s) URLs in rendered output real OSC 8 hyperlinks.
LinkPolicy: Which URL schemes tuika turns into OSC 8 hyperlinks.

Functions§

apply_buffer_links: Embed OSC 8 hyperlinks for each BufferLink into buf.
ctrl_click_url: Return the visible HTTP(S) URL under a Ctrl+left-button release.
ctrl_click_url_with: ctrl_click_url with an explicit LinkPolicy for the bare-URL fallback.
encode: encode_with under the default (LinkPolicy::WEB) policy: wrap text in a link to url when url is a safe http(s) URL, else return text.
encode_with: Wrap text in an OSC 8 hyperlink to url under policy, or return text unchanged when url is not a valid, safe target for that policy. Pure and allocation-only — no I/O.
is_web_url: Whether s is a bare http(s):// URL with no interior whitespace — the shape a host can hand to write_line as a link run.
write_line: Serialize a ratatui Line to out with SGR styling and OSC 8 links, then reset styling. A span whose visible text is a bare web URL (see is_web_url) is emitted as a hyperlink to itself; every other span is printed as plain styled text. Does not emit a trailing newline — the caller controls line breaks.
write_line_with: write_line with an explicit LinkPolicy, so a host can decide which schemes (e.g. mailto:) become hyperlinks when it pushes a line to scrollback.