@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 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_agent_chat(map()) :: binary()

Encodes a gui_agent_chat command with conversation messages.

Messages are {id, message} tuples where id is a stable BEAM-assigned uint32. Each encoded message is prefixed with its ID so the GUI frontend can use it as a persistent SwiftUI identity across updates.

@spec encode_gui_agent_context(boolean(), String.t(), DateTime.t(), atom(), boolean()) ::
  binary()

Encodes the agent context bar state when zoomed into an agent card.

Layout:

• visible(1): 1 if zoomed into a non-You agent card, 0 otherwise
• task_len(2): length of task string
• task(N): task description
• dispatch_timestamp(8): Unix timestamp when the task was dispatched
• status(1): current card status (0-5)
• can_approve(1): 1 if the user can approve the agent's work, 0 otherwise

@spec encode_gui_agent_groups(MingaEditor.State.TabBar.t()) :: binary()

Encodes a gui_agent_groups command with the current workspace state.

Wire format: opcode(1) + active_group_id(2) + workspace_count(1) + workspaces...

Per workspace: id(2) + kind(1) + agent_status(1) + color_r(1) + color_g(1) + color_b(1)

• tab_count(2) + label_len(1) + label(label_len) + icon_len(1) + icon(icon_len)

Kind: 0 = manual, 1 = agent. Agent status: 0 = idle, 1 = thinking, 2 = tool_executing, 3 = error.

@spec encode_gui_board(MingaEditor.Shell.Board.State.t()) :: binary()

Encodes a gui_board command with the card grid state.

Wire format: opcode(0x87) + visible(1) + focused_card_id(4) + card_count(2) + cards...

Per card: card_id(4) + status(1) + flags(1)

• task_len(2) + task(task_len)
• model_len(1) + model(model_len)
• elapsed_seconds(4)
• recent_file_count(1) + recent_files...

Per recent_file: path_len(2) + path(path_len)

Status bytes: 0=idle, 1=working, 2=iterating, 3=needs_you, 4=done, 5=errored Flags: bit 0 = is_you_card, bit 1 = is_focused

@spec encode_gui_bottom_panel(
  MingaEditor.BottomPanel.t(),
  MingaEditor.UI.Panel.MessageStore.t()
) :: {binary(), MingaEditor.UI.Panel.MessageStore.t()}

Encodes a gui_bottom_panel command from a BottomPanel.t().

Wire format: When visible:

opcode(1) + visible=1(1) + active_tab_index(1) + height_percent(1)
+ filter_preset(1) + tab_count(1) + tab_defs... + content_payload

Per tab_def:

tab_type(1) + name_len(1) + name(name_len)

Messages content_payload (when active tab is :messages):

entry_count(2) + entries...

Per entry:

id(4) + level(1) + subsystem(1) + timestamp_secs(4)
+ path_len(2) + path(path_len) + text_len(2) + text(text_len)

When hidden:

opcode(1) + visible=0(1)

@spec encode_gui_breadcrumb(String.t() | nil, String.t()) :: binary()

Encodes a gui_breadcrumb command.

@spec encode_gui_change_summary([map()], non_neg_integer()) :: binary()

Encodes a gui_change_summary command (0x89).

Sends the list of changed files with diff stats when zoomed into an agent card. The Swift frontend renders this as a resizable sidebar on the left.

Wire format: opcode(1) + visible(1) + selected_index(2) + entry_count(2) + entries...

Each entry: path_len(2) + path + action(1) + lines_added(4) + lines_removed(4)

Action: 0=modified, 1=added, 2=deleted, 3=renamed

@spec encode_gui_completion(
  Minga.Editing.Completion.t() | nil,
  non_neg_integer(),
  non_neg_integer()
) :: binary()

Encodes a gui_completion command.

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

Encodes a gui_cursorline command.

Sends the cursor screen row and cursorline background color to the GUI frontend so it can draw the highlight as a native Metal quad instead of a full-width space fill draw.

row is the screen row (0-indexed). bg_rgb is a 24-bit RGB color value. Pass row = 0xFFFF and bg_rgb = 0 to indicate no cursorline (inactive window or cursorline disabled).

@spec encode_gui_file_tree(
  Minga.Project.FileTree.t() | nil,
  MingaEditor.State.FileTree.editing() | nil
) :: binary()

Encodes a gui_file_tree command with the visible file tree entries.

Sends: selected_index, tree_width, entry_count, root_len, root, then per entry: path_hash, flags (is_dir, is_expanded), depth, git_status, icon, name, rel_path.

@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_git_status(git_status_data()) :: binary()

Encodes a gui_git_status command (0x85) for the native GUI frontend.

Wire format: opcode:1, repo_state:1, ahead:2, behind:2, branch_len:2, branch, entry_count:2, then per entry:

path_hash:4, section:1, status:1, path_len:2, path

@spec encode_gui_gutter(gutter_data()) :: binary()

Encodes a gui_gutter command for one window.

One message is sent per window (not batched). Each message includes the window's screen position so the GUI knows where to render.

Wire format: opcode(1) + window_id(2) + content_row(2) + content_col(2) + content_height(2)

• is_active(1) + cursor_line(4) + line_number_style(1)
• line_number_width(1) + sign_col_width(1) + line_count(2) + entries...

Per entry: buf_line(4) + display_type(1) + sign_type(1)

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

Encodes a gui_gutter_separator command.

Sends the gutter column position and separator color to the GUI frontend. col is the cell column at the right edge of the gutter (0 = no separator). color_rgb is a 24-bit RGB color value.

@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: style(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

@spec encode_gui_indent_guides(indent_guide_data()) :: binary()

Encodes a gui_indent_guides command for one window.

Uses the forward-compatible 0x90+ format: opcode(1) + payload_length(2) + payload. Payload: window_id(2) + tab_width(1) + active_guide_col(2) + guide_count(1) + guide_cols(2 each).

active_guide_col of 0xFFFF means no active guide. Guide columns are character-unit offsets from the content start (not screen left).

@spec encode_gui_indent_guides_empty(non_neg_integer()) :: binary()

Encodes a gui_indent_guides command with no guides (empty).

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

Encodes a gui_line_spacing command.

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_picker(
  MingaEditor.UI.Picker.t() | nil,
  boolean(),
  action_menu_state(),
  non_neg_integer()
) :: binary()

Encodes a gui_picker command.

Wire format (v2, extended):

opcode(1) + visible(1) + selected_index(2) + filtered_count(2) + total_count(2)
+ title_len(2) + title + query_len(2) + query + has_preview(1) + item_count(2) + items...

Per item:
  icon_color(3) + flags(1) + label_len(2) + label + desc_len(2) + desc
  + annotation_len(2) + annotation + match_pos_count(1) + match_positions(each 2 bytes)

Flags bits:
  bit 0: two_line (file-style two-line layout)
  bit 1: marked (multi-select checkmark)

@spec encode_gui_picker_preview([[preview_segment()]] | nil) :: binary()

Encodes a gui_picker_preview command.

Wire format:

opcode(1) + visible(1)

When visible:
  opcode(1) + 1(1) + line_count(2) + lines...

Per line:
  segment_count(1) + segments...

Per segment:
  fg_color(3) + flags(1) + text_len(2) + text

Flags bits:
  bit 0: bold

@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_split_separators(non_neg_integer(), [vertical_separator()], [
  horizontal_separator()
]) ::
  binary()

Encodes a gui_split_separators command (0x84).

Wire format: opcode(1) + border_color_rgb(3) + vertical_count(1) + verticals... + horizontal_count(1) + horizontals...

Each vertical: col(2) + start_row(2) + end_row(2) Each horizontal: row(2) + col(2) + width(2) + filename_len(2) + filename

@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

@spec encode_gui_tab_bar(MingaEditor.State.TabBar.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.

@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.

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.