Raxol.UI.Components.Harness.AxolFace (Raxol v2.6.1)

View Source

The axol face ≡··≡ — the harness identity/status layer.

A fixed four-display-column glyph: the gills (≡) are constant, the two eyes carry the agent's state. The face swaps in place, no width jitter, so it can sit in a status strip and never disturb layout.

States

StateCycleMotif
:boot≡--≡ → ≡··≡ → ≡oo≡ → ≡··≡wake blink
:idle≡··≡ … ≡--≡neutral, slow blink
:thinking≡··≡ → ≡''≡ → ≡..≡eyes drift
:working≡oo≡ → ≡OO≡pupils pulse
:done≡^^≡happy squint
:error≡xx≡knocked-out eyes

The state maps directly from harness contract events (see Raxol.UI.Components.Harness.AxolFace usage in the mix raxol.code surface): turn_started → :thinking, tool activity → :working, turn_completed{final} → :done, error → :error, otherwise :idle. Frame advance is event-driven (bump on each item_delta) or a subscription tick.

Single source of truth

glyph/3 is a pure function of (state, frame, ascii?) so every surface — the CLI boot beat, this TUI component, an SSE status line — renders the identical face. ascii?: true selects an ASCII-only fallback (gills =, ASCII eyes) for terminals without a UTF-8 font; the branded ≡ face is the default (it is single display-width and renders in modern terminals).

Summary

Types

face_state()
t()

Functions

broadcast(msg)
color(atom)

Foreground color for a state's face (nil = terminal default).

command(cmd)
glyph(state, frame, ascii? \\ false)

The face glyph for state at frame, ASCII if ascii?.

handle_event(event, state, context)

Callback implementation for Raxol.UI.Components.Base.Component.handle_event/3.

mount(state)

Callback implementation for Raxol.UI.Components.Base.Component.mount/1.

schedule(msg, delay)
states()

The face states, in canonical order.

unmount(state)

Callback implementation for Raxol.UI.Components.Base.Component.unmount/1.

update(props, state)

Callback implementation for Raxol.UI.Components.Base.Component.update/2.

Types

face_state()

@type face_state() :: :boot | :idle | :thinking | :working | :done | :error

t()

@type t() :: %{
  id: String.t() | atom(),
  state: face_state(),
  frame: non_neg_integer(),
  ascii: boolean(),
  style: map(),
  theme: map()
}

Functions

broadcast(msg)

color(atom)

@spec color(face_state()) :: atom() | nil

Foreground color for a state's face (nil = terminal default).

command(cmd)

glyph(state, frame, ascii? \\ false)

@spec glyph(face_state(), non_neg_integer(), boolean()) :: String.t()

The face glyph for state at frame, ASCII if ascii?.

Pure: the single source of truth shared by every surface. frame wraps over the state's cycle length, so any non-negative integer is valid.

handle_event(event, state, context)

Callback implementation for Raxol.UI.Components.Base.Component.handle_event/3.

mount(state)

Callback implementation for Raxol.UI.Components.Base.Component.mount/1.

schedule(msg, delay)

states()

@spec states() :: [face_state()]

The face states, in canonical order.

unmount(state)

Callback implementation for Raxol.UI.Components.Base.Component.unmount/1.

update(props, state)

Callback implementation for Raxol.UI.Components.Base.Component.update/2.