Raxol.LiveView.Renderer (Raxol v2.0.1)

View Source

Core buffer-to-HTML rendering engine for Raxol web terminals.

This module handles the conversion of terminal buffers (grid of cells) into optimized HTML suitable for web rendering with character-perfect monospace grid alignment.

Features

  • Virtual DOM-style diffing to minimize DOM updates
  • Smart caching for common characters and styles
  • Efficient iodata-based string building
  • Dirty checking to skip unnecessary renders
  • Graceful error handling with fallback rendering

Usage

buffer = %{
  lines: [%{cells: [%{char: "H", style: %{bold: true}}]}],
  width: 80,
  height: 24
}

renderer = Raxol.LiveView.Renderer.new()
{html, new_renderer} = Raxol.LiveView.Renderer.render(renderer, buffer)

Summary

Types

buffer()
cell()
line()
t()

Functions

invalidate_cache(renderer)

Invalidates all caches, forcing a full re-render on next call.

new()

Creates a new renderer with empty caches.

render(renderer, buffer)

Renders a buffer to HTML, using diffing and caching for performance.

stats(renderer)

Returns statistics about cache performance.

validate_buffer(arg1)

Validates a buffer structure.

Types

buffer()

@type buffer() :: %{lines: [line()], width: integer(), height: integer()}

cell()

@type cell() :: %{char: String.t(), style: map()}

line()

@type line() :: %{cells: [cell()]}

t()

@type t() :: %Raxol.LiveView.Renderer{
  cache_hits: term(),
  cache_misses: term(),
  html_char_cache: term(),
  previous_buffer: term(),
  previous_html: term(),
  render_count: term(),
  style_class_cache: term()
}

Functions

invalidate_cache(renderer)

@spec invalidate_cache(t()) :: t()

Invalidates all caches, forcing a full re-render on next call.

new()

@spec new() :: t()

Creates a new renderer with empty caches.

render(renderer, buffer)

@spec render(t(), buffer() | nil) :: {String.t(), t()}

Renders a buffer to HTML, using diffing and caching for performance.

Returns {html_string, updated_renderer}. On error, returns a fallback empty terminal HTML and logs the error.

Examples

renderer = Renderer.new()
{html, new_renderer} = Renderer.render(renderer, buffer)

# With invalid buffer - returns empty terminal, logs error
{html, renderer} = Renderer.render(renderer, nil)

stats(renderer)

@spec stats(t()) :: map()

Returns statistics about cache performance.

validate_buffer(arg1)

@spec validate_buffer(any()) :: :ok | {:error, atom()}

Validates a buffer structure.

Returns :ok if valid, or {:error, reason} if invalid.