# `Raxol.Terminal.Capabilities`
[🔗](https://github.com/DROOdotFOO/raxol/blob/v2.7.0/lib/raxol/terminal/capabilities/capabilities_record.ex#L1)

Session-immutable terminal capability record (F0 §5, T1 slice).

Filled once at startup by the probe pass
(`Raxol.Terminal.Capabilities.Probe` -> `Classifier`), cached in
`:persistent_term`, and never mutated for the rest of the session.

Provenance discipline: every detected capability records *where* the
answer came from in `source` (`:decrqm`, `:xtversion`, `:xtgettcap`,
`:env`, `:tmux_clamp`, `:default`). Env sniffing (`$TERM_PROGRAM` et
al.) is only ever a free first-pass seed -- it can never claim a
probe-able capability like mode 2026 (the fail-first anchor of the T1
unit).

`sync_output?/0` is the single public emit-gate for mode-2026 framing;
render paths consult it and nothing else.

# `color_depth`

```elixir
@type color_depth() :: :truecolor | :ansi256 | :ansi16 | :none
```

# `grapheme_width`

```elixir
@type grapheme_width() :: :mode_2027 | :measured | :assumed
```

# `identity`

```elixir
@type identity() :: {String.t(), String.t() | nil} | nil
```

# `multiplexer`

```elixir
@type multiplexer() :: :none | :tmux | :screen
```

# `polarity`

```elixir
@type polarity() :: :dark | :light
```

# `provenance`

```elixir
@type provenance() ::
  :decrqm
  | :xtversion
  | :da1
  | :da2
  | :xtgettcap
  | :env
  | :tmux_clamp
  | :platform
  | :osc11
  | :osc10
  | :colorterm
  | :no_color
  | :term
  | :colorfgbg
  | :default
```

# `rgb`

```elixir
@type rgb() :: {0..255, 0..255, 0..255}
```

# `t`

```elixir
@type t() :: %Raxol.Terminal.Capabilities{
  background: rgb() | nil,
  cell_px: {pos_integer(), pos_integer()} | nil,
  color_depth: color_depth(),
  foreground: rgb() | nil,
  grapheme_width: grapheme_width(),
  identity: identity(),
  in_band_resize: boolean(),
  kitty_graphics: boolean(),
  kitty_keyboard: non_neg_integer() | nil,
  lr_margins: boolean(),
  multiplexer: multiplexer(),
  polarity_seed: polarity() | nil,
  quirks: [atom()],
  sixel: boolean(),
  sixel_regs: non_neg_integer() | nil,
  source: %{optional(atom()) => provenance()},
  styled_underline: boolean(),
  sync_output: boolean(),
  theme_events: boolean(),
  tier: tier(),
  truecolor: boolean(),
  unicode: unicode_axis()
}
```

# `tier`

```elixir
@type tier() :: :core_minus | :core | :modern | :rich
```

# `unicode_axis`

```elixir
@type unicode_axis() :: :none | :wide | :grapheme
```

# `background`

```elixir
@spec background() :: rgb() | nil
```

Detected native background color (`OSC 11`), if any.

# `cache`

```elixir
@spec cache(t()) :: :ok
```

Caches the classified record for the session. Write-once: the first
cached record wins; later calls are no-ops (session immutability,
CAP-P-13).

# `cached`

```elixir
@spec cached() :: {:ok, t()} | :error
```

Returns the cached session record, if any.

# `color_depth`

```elixir
@spec color_depth() :: color_depth()
```

The classified color depth. Defaults to `:ansi16` (the Core floor) when
no record has been cached, mirroring the struct default.

# `foreground`

```elixir
@spec foreground() :: rgb() | nil
```

Detected native foreground color (`OSC 10`), if any.

# `polarity_seed`

```elixir
@spec polarity_seed() :: polarity() | nil
```

The `$COLORFGBG` polarity SEED (`:dark` | `:light` | `nil`). A seed
only -- used downstream iff OSC 11 is silent (native-palette-riding §2
rung 2).

# `sync_output?`

```elixir
@spec sync_output?() :: boolean()
```

THE mode-2026 emit gate. Render paths consult this one function before
emitting `CSI ? 2026 h/l` sync frames.

Truth order: cached session record -> raw DECRQM mode replies noted by
the driver's reply scan -> `false`. Env is never consulted.

---

*Consult [api-reference.md](api-reference.md) for complete listing*