Vibe.TUI.Cast (vibe v0.2.0)

Native terminal recording and replay for Vibe TUI sessions.

Recordings store exact terminal output bytes in chunked Erlang External Term Format blocks, gzip-compressed by default. The native format keeps Vibe-only events such as keys and resizes while export_asciinema/2 produces a standard asciinema v2 .cast file from the same output stream.

Summary

Types

event()

t()

Functions

decode_block(binary, atom)

Decodes a native cast block with the configured compression.

encode_block(term, atom)

Encodes a native cast block with the configured compression.

events(path_or_cast)

Returns all decoded native events.

export_asciinema(path_or_cast, output_path)

Exports a native recording to asciinema v2 JSONL format.

find(path_or_cast, pattern, opts \\ [])

Finds times where a plain terminal snapshot contains text or a regex match.

info(path_or_cast)

Returns summary information about a cast.

magic()

Returns the native cast file magic bytes.

open(cast)

Opens a native Vibe TUI cast file.

open!(cast)

Opens a native cast file and raises on failure.

path_from_opts(opts)

Returns the path configured by CLI opts or environment variables.

reindex(path)

Rebuilds the sidecar index for a native recording.

snapshot(path_or_cast, opts \\ [])

Returns a terminal snapshot at a time or semantic point.

snapshot!(path_or_cast, opts \\ [])

Returns a terminal snapshot or raises.

start_writer(opts)

Starts a native cast writer unless recording is disabled.

version()

Returns the native cast format version.

Types

event()

@type event() ::
  {:output, non_neg_integer(), binary()}
  | {:input, non_neg_integer(), binary()}
  | {:input_redacted, non_neg_integer(), non_neg_integer()}
  | {:key, non_neg_integer(), term()}
  | {:resize, non_neg_integer(), pos_integer(), pos_integer()}
  | {:app_event, non_neg_integer(), term()}
  | {:trace_frame, non_neg_integer(), term()}
  | {:trace_snapshot, non_neg_integer(), term()}

t()

@type t() :: %Vibe.TUI.Cast{
  blocks: [map()],
  events: [event()],
  header: map(),
  path: Path.t()
}

Functions

decode_block(binary, atom)

Decodes a native cast block with the configured compression.

encode_block(term, atom)

Encodes a native cast block with the configured compression.

events(path_or_cast)

@spec events(Path.t() | t()) :: [event()]

Returns all decoded native events.

export_asciinema(path_or_cast, output_path)

@spec export_asciinema(Path.t() | t(), Path.t()) :: :ok | {:error, term()}

Exports a native recording to asciinema v2 JSONL format.

find(path_or_cast, pattern, opts \\ [])

@spec find(Path.t() | t(), binary() | Regex.t(), keyword()) :: [
  %{time_ms: non_neg_integer(), match: binary()}
]

Finds times where a plain terminal snapshot contains text or a regex match.

info(path_or_cast)

@spec info(Path.t() | t()) :: map()

Returns summary information about a cast.

magic()

Returns the native cast file magic bytes.

open(cast)

@spec open(Path.t() | t()) :: {:ok, t()} | {:error, term()}

Opens a native Vibe TUI cast file.

open!(cast)

@spec open!(Path.t() | t()) :: t()

Opens a native cast file and raises on failure.

path_from_opts(opts)

@spec path_from_opts(keyword()) :: String.t() | nil

Returns the path configured by CLI opts or environment variables.

reindex(path)

@spec reindex(Path.t()) :: :ok | {:error, term()}

Rebuilds the sidecar index for a native recording.

snapshot(path_or_cast, opts \\ [])

@spec snapshot(
  Path.t() | t(),
  keyword()
) :: {:ok, binary() | map()} | {:error, term()}

Returns a terminal snapshot at a time or semantic point.

snapshot!(path_or_cast, opts \\ [])

@spec snapshot!(
  Path.t() | t(),
  keyword()
) :: binary() | map()

Returns a terminal snapshot or raises.

start_writer(opts)

@spec start_writer(keyword()) :: {:ok, pid() | nil} | {:error, term()}

Starts a native cast writer unless recording is disabled.

version()

Returns the native cast format version.