@spec config_state(Minga.Config.Options.server(), Minga.Keymap.server()) ::
  config_state()

Builds a full settings state payload from the current config and keymap servers.

@spec decode_gui_action(non_neg_integer(), binary()) :: {:ok, gui_action()} | :error

Decodes a GUI action sub-opcode and its payload into a gui_action() tuple.

Called from Protocol.decode_event/1 when the outer opcode is 0x07 (gui_action).

@spec decode_search_flags(non_neg_integer()) :: [
  replace_mode: boolean(),
  case_sensitive: boolean(),
  whole_word: boolean(),
  regex: boolean()
]

Unpacks a search flags byte into a keyword list of booleans.

@spec encode_clipboard_write(String.t(), clipboard_target()) :: binary()

Encodes a clipboard_write command.

Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload. Payload: target(1) + text_length(2) + text(text_length).

Target: 0 = general pasteboard (Cmd+C), 1 = find pasteboard (Cmd+E).

@spec encode_gui_config_state(config_state()) :: binary()

Encodes the current settings panel state for native GUI frontends.

Parity oracle (#2119): production no longer pushes config_state through this function. config_state is emitted in-frame by Minga.Frontend.Adapter.GUI.ConfigStateEncoder from the cached snapshot the builder projects via MingaEditor.RenderModel.UI.ConfigStateBuilder. The projection helpers below (config_state/2, settings_option?/1) are still live: the builder and the GUI action handler use them. This encoder is retained only as the byte-for-byte oracle for the GUI protocol tests.

@spec encode_gui_cursor_animation(boolean()) :: binary()

Encodes a gui_cursor_animation command.

Parity oracle (#2119): production no longer pushes cursor animation through this function. cursor_animation is emitted in-frame by Minga.Frontend.Adapter.GUI.CursorAnimationEncoder; this encoder is retained only as the byte-for-byte oracle for the GUI protocol tests.

Sends whether the GUI renderer should animate cursor movement. Reduce Motion can still disable animation on the frontend. Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + enabled(1).

@spec encode_gui_extension_overlays([extension_overlay_entry()]) :: binary()

Encodes a gui_extension_overlay command (0x9C).

Sends all active extension overlays for the current frame. Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload.

Payload: count(1) + per overlay: extension_name_len(1) + extension_name(utf8) + overlay_id_len(1) + overlay_id(utf8) + window_id(2) + row(2) + col(2) + shape(1) + fg_r(1) + fg_g(1) + fg_b(1) + opacity(1) + content_len(2) + content(utf8).

@spec encode_gui_extension_panels([Minga.Extension.Panel.entry()]) :: binary()

Encodes a gui_extension_panel command (0x9D).

Sends all visible extension panels with their structured content. Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload.

Payload: panel_count(1) + per panel: ext_name_len(1) + ext_name + panel_id_len(1) + panel_id + title_len(1) + title + position(1) + size_type(1) + size_value(1) + visible(1) + block_count(1) + content blocks.

Each content block: type(1) + type-specific payload.

@spec encode_gui_extension_runtime(String.t(), String.t(), binary()) :: binary()

Encodes a generic frontend-extension runtime message.

Shared protocol owns only the envelope. The named frontend extension owns the payload schema and decoder.

Format: opcode(1) + payload_length(4) + extension_id_len(2) + extension_id + channel_len(2) + channel + payload.

@spec encode_gui_file_tree(
  String.t() | nil,
  non_neg_integer(),
  file_tree_status(),
  boolean(),
  [
    MingaEditor.FileTree.Row.t()
  ]
) :: binary()

Encodes the semantic GUI file-tree command.

Wire format uses a 32-bit length-prefixed envelope:

opcode(1) + payload_len(4) + payload(payload_len)

Payload v2:

version(1) + tree_flags(1) + tree_state(1) + selected_id_len(2) + selected_id + root_len(2) + root + tree_width(2) + row_count(2) + error_reason_len(2) + error_reason + rows...

Per row:

stable_hash(4) + row_flags(2) + depth(1) + git_status(1) + diagnostics(8) + guide_count(1) + guides + id + path + rel_path + name + icon + editing_type(1) + editing_text + icon_color(3)

String fields use uint16 byte lengths except icon, which uses a uint8 byte length. icon_color is three bytes (R, G, B), following the editing payload.

@spec encode_gui_file_tree_selection(String.t(), boolean()) :: binary()

Encodes a lightweight file-tree selection update.

@spec encode_gui_float_popup(float_popup_data()) :: binary()

Encodes a gui_float_popup command (0x83).

Wire format: opcode(1) + visible(1) + width(2) + height(2) + title_len(2) + title(title_len) + line_count(2) + lines...

Each line: text_len(2) + text(text_len)

When visible=0, no further fields are sent.

@spec encode_gui_hover_action(MingaEditor.HoverPopup.t() | nil) :: binary()

Encodes optional hover popup action metadata as a forward-compatible sidecar command.

@spec encode_gui_hover_popup(MingaEditor.HoverPopup.t() | nil) :: binary()

Encodes a gui_hover_popup command (0x81).

Wire format: opcode(1) + visible(1) + anchor_row(2) + anchor_col(2) + focused(1) + scroll_offset(2) + line_count(2) + lines...

Each line: line_type(1) + segment_count(2) + segments...

Each segment: standard: style(1) + text_len(2) + text(text_len) syntaxHighlighted: style(1=13) + fg_r(1) + fg_g(1) + fg_b(1) + flags(1) + text_len(2) + text(text_len)

Line types: 0=text, 1=code, 2=code_header, 3=header, 4=blockquote, 5=list_item, 6=rule, 7=empty

Segment styles: 0=plain, 1=bold, 2=italic, 3=bold_italic, 4=code, 5=code_block, 6=code_content, 7=header1, 8=header2, 9=header3, 10=blockquote, 11=list_bullet, 12=rule, 13=syntaxHighlighted

@spec encode_gui_line_spacing(number()) :: binary()

Encodes a gui_line_spacing command.

Parity oracle (#2119): production no longer pushes line spacing through this function. line_spacing is emitted in-frame by Minga.Frontend.Adapter.GUI.LineSpacingEncoder; this encoder is retained only as the byte-for-byte oracle for the GUI protocol tests.

Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload. Payload: spacing_x100(2) — the spacing multiplier times 100 as a 16-bit unsigned integer. For example, 1.2 is encoded as 120, 1.0 as 100.

@spec encode_gui_minibuffer(MingaEditor.MinibufferData.t()) :: binary()

Encodes a gui_minibuffer command (0x7F).

Sends structured minibuffer state to the GUI frontend for native rendering. Includes mode, prompt, input text, cursor position, context string, and completion candidates.

When visible is false, sends a single hide byte. When visible, encodes the full payload including any completion candidates.

@spec encode_gui_notifications(MingaEditor.UI.NotificationCenter.t()) :: binary()

Encodes the full GUI notification center snapshot.

Wire format (opcode 0x99): opcode(1) + payload_len(2) + version(1) + count(2) + notifications...

Each notification: id + level(1) + flags(1) + created_at(8) + updated_at(8) + auto_dismiss_ms(4) + title + body + source + action_count(1) + actions...

Strings are u16 length-prefixed. auto_dismiss_ms uses 0xFFFFFFFF for nil.

@spec encode_gui_observatory(observatory_data()) :: binary()

Encodes the BEAM Observatory sidebar state for native GUI frontends using a 32-bit payload length envelope.

@spec encode_gui_search_state(
  boolean(),
  non_neg_integer(),
  non_neg_integer(),
  MingaEditor.State.Search.gui_search() | %{}
) :: binary()

Encodes the GUI search toolbar state.

Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload. Payload: active(1) + match_count(2) + current_index(2) + flags(1).

Flags bits: bit 0 = replace_mode, bit 1 = case_sensitive, bit 2 = whole_word, bit 3 = regex.

@spec encode_gui_sidebars([sidebar_metadata()], String.t() | nil) :: binary()

Encodes semantic sidebar metadata for native GUI frontend hosts.

@spec encode_gui_signature_help(MingaEditor.SignatureHelp.t() | nil) :: binary()

Encodes a gui_signature_help command (0x82).

Wire format: opcode(1) + visible(1) + anchor_row(2) + anchor_col(2) + active_signature(1) + active_parameter(1) + signature_count(1) + signatures...

Each signature: label_len(2) + label + doc_len(2) + doc + param_count(1) + params...

Each parameter: label_len(2) + label + doc_len(2) + doc

@spec encode_gui_status_bar(MingaEditor.StatusBar.Data.t()) :: binary()

Encodes a gui_status_bar command from a StatusBar.Data.t() tagged union.

Wire format (opcode 0x76, sectioned):

[opcode:1][section_count:1][section_id:1][section_len:2][payload:N]...

Sections are self-describing: each starts with a 1-byte ID and 2-byte length. Unknown sections are skipped by the frontend. New fields can be added without changing the decoder for existing sections.

Section IDs: 0x01 - Identity: content_kind, mode, flags 0x02 - Cursor: cursor_line, cursor_col, line_count 0x03 - Diagnostics: error/warning/info/hint counts, diagnostic_hint 0x04 - Language: lsp_status, parser_status 0x05 - Git: branch, added, modified, deleted 0x06 - File: icon, icon_color, filename, filetype 0x07 - Message: status message 0x08 - Recording: macro_recording 0x09 - Agent: model_name, message_count, session_status, agent_status, background_count, background_label, active_tool_name 0x0A - Indent: indent_type, indent_size 0x0B - ModelineSegments: named configured left/right styled modeline segments 0x0C - Selection: selection_mode, selection_size 0x0D - Workspace: active workspace summary

@spec encode_gui_tab_bar(
  MingaEditor.State.TabBar.t() | MingaEditor.Session.ChromeState.t(),
  pid() | nil
) :: binary()

Encodes a gui_tab_bar command with the current tab bar state.

Each tab entry includes: flags byte (is_active, is_dirty, is_agent, has_attention, agent_status in upper bits), tab id, group_id for workspace grouping, Nerd Font icon, and display label. When the active tab is omitted from ChromeState.visible_tabs, active_index is 255 to signal that no visible tab is active.

@spec encode_gui_theme(MingaEditor.UI.Theme.t()) :: binary()

Encodes a gui_theme command from a Theme.t().

Takes a Theme.t() and produces a binary with {slot_id:u8, r:u8, g:u8, b:u8} entries for every color slot the GUI needs. Colors that are nil are skipped.

@spec encode_gui_tool_manager(map() | nil) :: binary()

Encodes the tool manager panel state.

Parity oracle / future wiring (#2119): this opcode has no live BEAM emitter. The macOS frontend has a fully wired decode -> ToolManagerState -> ToolManagerView path designed to be BEAM-driven, but the BEAM half (a semantic tool-manager model and emission) was never built, and building it is out of scope here and blocked by the semantic-surface freeze. Rather than orphan the frontend decoder and break the GUI protocol round-trip tests, this encoder is retained as the byte-for-byte parity oracle until a tool-manager feature is built on the semantic path. The gui_protocol_test.exs round-trip suite exercises it.

Sends a rich structured view of all available tools with their install status, versions, categories, and progress info. The GUI frontend renders this as a native management panel.

Wire format

When visible:
  opcode(1) + 1(1) + filter(1) + selected_index(2) + tool_count(2) + tools...

Per tool:
  name_len(1) + name(name_len) + label_len(1) + label(label_len)
  + desc_len(2) + desc(desc_len) + category(1) + status(1)
  + method(1) + language_count(1) + languages...
  + version_len(1) + version(version_len)
  + homepage_len(2) + homepage(homepage_len)
  + provides_count(1) + provides...
  + error_reason_len(2) + error_reason(error_reason_len)

Per language:
  lang_len(1) + lang(lang_len)

Per provides:
  cmd_len(1) + cmd(cmd_len)

When hidden:
  opcode(1) + 0(1)

Status values

Category values

Method values

Filter values

@spec encode_gui_which_key(MingaEditor.State.WhichKey.t()) :: binary()

Encodes a gui_which_key command.

@spec encode_gui_workspaces(MingaEditor.Session.ChromeState.t()) :: binary()

Encodes the canonical gui_workspaces command.

Wire format: opcode(1) + payload_len(2) + payload

Payload: version(1) + active_workspace_id(2) + mode(1) + flags(1) + workspace_count(1)

• workspaces... + visible_tab_count(2) + visible_tabs...

@spec encode_hidden_gui_file_tree(String.t() | nil) :: binary()

Encodes a hidden semantic GUI file-tree command while preserving the project root.