@spec decode_command(binary()) ::
  {:ok,
   :clear
   | :batch_end
   | {:draw_text, map()}
   | {:draw_styled_text, map()}
   | {:set_cursor, non_neg_integer(), non_neg_integer()}
   | {:set_cursor_shape, cursor_shape()}}
  | {:error, :unknown_opcode | :malformed}

Decodes a render command from a binary payload (primarily for testing).

@spec decode_event(binary()) ::
  {:ok, input_event()} | {:error, :unknown_opcode | :malformed}

Decodes an input event from a binary payload.

@spec encode_batch_end() :: binary()

Encodes a batch_end command (triggers render flush).

@spec encode_clear() :: binary()

Encodes a clear screen command.

@spec encode_clear_region(non_neg_integer()) :: binary()

Encodes a clear_region command.

See Minga.Parser.Protocol.encode_close_buffer/1.

@spec encode_cursor(non_neg_integer(), non_neg_integer()) :: binary()

Encodes a set_cursor command.

@spec encode_cursor_shape(cursor_shape()) :: binary()

Encodes a set_cursor_shape command.

@spec encode_define_region(
  non_neg_integer(),
  non_neg_integer(),
  region_role(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: binary()

Encodes a define_region command.

@spec encode_destroy_region(non_neg_integer()) :: binary()

Encodes a destroy_region command.

@spec encode_draw(non_neg_integer(), non_neg_integer(), String.t(), style()) ::
  binary()

Encodes a draw_text command.

@spec encode_draw_smart(non_neg_integer(), non_neg_integer(), String.t(), style()) ::
  binary()

Smart encoder: uses draw_styled_text if the style contains extended attributes, otherwise falls back to the more compact draw_text.

@spec encode_draw_styled(non_neg_integer(), non_neg_integer(), String.t(), style()) ::
  binary()

Encodes a draw_styled_text command with extended attributes.

Extended over draw_text with:

• attrs expanded to 16 bits (adds strikethrough 0x10, underline_style 3 bits at 0xE0)
• underline_color as a separate 24-bit RGB field (0x000000 = use fg)
• blend as an 8-bit opacity value (0-100, 100 = fully opaque)
• font_weight as an 8-bit weight index (0-7, maps to thin through black)

Use this for text that needs underline styles, strikethrough, underline color, blend, or per-span font weight. For simple text (fg/bg/bold/italic/underline/reverse), encode_draw/4 is more compact.

See Minga.Parser.Protocol.encode_edit_buffer/3.

See Minga.Parser.Protocol.encode_load_grammar/2.

See Minga.Parser.Protocol.encode_parse_buffer/3.

See Minga.Parser.Protocol.encode_query_language_at/3.

@spec encode_register_font(non_neg_integer(), String.t()) :: binary()

Encodes a register_font command to associate a font_id with a font family.

Font ID 0 is the primary font (set via set_font). IDs 1-255 are secondary fonts that can be referenced by font_id in draw_styled_text. The GUI creates a FontFace for each registered font at the same size as the primary. If the secondary font's cell metrics differ from the primary, the GUI logs a warning and falls back to the primary for those glyphs.

Format: opcode:8, font_id:8, name_len:16, name:bytes

See Minga.Parser.Protocol.encode_request_indent/3.

See Minga.Parser.Protocol.encode_request_textobject/5.

@spec encode_scroll_region(non_neg_integer(), non_neg_integer(), integer()) ::
  binary()

Encodes a scroll_region command for terminal scroll optimization.

Tells the Zig renderer to use ANSI scroll region sequences to shift content within the given screen row range by delta lines, avoiding a full redraw.

• top_row / bottom_row — screen row range (inclusive) for the scroll region.
• delta — positive = scroll up (content moves up, new lines at bottom),

        negative = scroll down (content moves down, new lines at top).

Wire format: opcode(1) + top_row(2) + bottom_row(2) + delta(2, signed) = 7 bytes.

@spec encode_set_active_region(non_neg_integer()) :: binary()

Encodes a set_active_region command. Pass 0 to reset to root.

See Minga.Parser.Protocol.encode_set_fold_query/2.

@spec encode_set_font(String.t(), pos_integer(), boolean(), atom()) :: binary()

Encodes a set_font command to configure the GUI frontend's font.

The font family is resolved by the frontend using NSFontManager (macOS) so both display names ("JetBrains Mono") and PostScript names ("JetBrainsMonoNF-Regular") work. The TUI ignores this command.

Format: opcode:8, size:16, weight:8, ligatures:8, name_len:16, name:bytes

Fields are ordered by category: font identity (size, weight, name) then rendering features (ligatures). The variable-length name stays at the end.

@spec encode_set_font_fallback([String.t()]) :: binary()

Encodes a set_font_fallback command to configure the GUI's font fallback chain.

The fallback chain is tried in order when the primary font (set via set_font) doesn't have a glyph. Each entry is a font family name resolved by the frontend via NSFontManager. After the configured fallbacks, the system fallback (CTFontCreateForString) is used as a last resort.

Format: opcode:8, count:8, [name_len:16, name:bytes]*

See Minga.Parser.Protocol.encode_set_highlight_query/2.

See Minga.Parser.Protocol.encode_set_indent_query/2.

See Minga.Parser.Protocol.encode_set_injection_query/2.

See Minga.Parser.Protocol.encode_set_language/2.

See Minga.Parser.Protocol.encode_set_textobject_query/2.

@spec encode_set_title(String.t()) :: binary()

Encodes a set_title command to update the terminal window title.

@spec encode_set_window_bg(non_neg_integer()) :: binary()

Encodes a set_window_bg command to set the default background color.

The Zig renderer uses this as the fallback background for any cell that doesn't specify an explicit bg: value. This prevents cells from falling back to the terminal's default background, which may not match the editor theme.

@spec has_modifier?(modifiers(), modifiers()) :: boolean()

Checks if a modifier flag is set.

@spec mod_alt() :: modifiers()

Returns the ALT modifier flag.

@spec mod_ctrl() :: modifiers()

Returns the CTRL modifier flag.

@spec mod_shift() :: modifiers()

Returns the SHIFT modifier flag.

@spec mod_super() :: modifiers()

Returns the SUPER modifier flag.