@spec accept_tab(t(), MingaEditor.State.Tab.t()) :: t()

Accepts a concrete tab only at its existing stable identity.

@spec accept_workspace(t(), MingaEditor.State.Workspace.t()) :: t()

Accepts a concrete workspace only at its existing stable identity.

@spec active(t()) :: MingaEditor.State.Tab.t() | nil

Returns the active tab.

@spec active_index(t()) :: non_neg_integer()

Returns the index of the active tab (0-based).

@spec active_workspace(t()) :: MingaEditor.State.Workspace.t() | nil

Returns the active workspace.

Derived from the active tab's group_id, not stored separately. The active workspace is always the workspace of the tab you're looking at.

@spec active_workspace_id(t()) :: non_neg_integer()

Returns the active workspace id, derived from the active tab.

@spec add(t(), MingaEditor.State.Tab.kind(), String.t()) ::
  {t(), MingaEditor.State.Tab.t()}

Adds a new tab after the active tab and makes it active.

Returns {updated_tab_bar, new_tab} so the caller can use the tab's id.

@spec add_workspace(t(), String.t(), pid() | nil) ::
  {t(), MingaEditor.State.Workspace.t()}

Adds an agent workspace and returns {updated_tab_bar, workspace}.

The workspace is appended to the workspaces list. The session pid is stored so we can track which agent owns the workspace.

@spec add_workspace_file(t(), non_neg_integer(), Minga.Project.FileRef.t()) :: t()

Adds a file identity to the identified workspace.

@spec any_attention?(t()) :: boolean()

Returns true if any tab has its attention flag set.

@spec buffer_pids(t()) :: [pid()]

Returns every live buffer pid represented by tab snapshots.

@spec clear_attention(t(), MingaEditor.State.Tab.id()) :: t()

Clears attention for the identified tab without changing tab identity or order.

@spec clear_workspace_catchup_events(t(), non_neg_integer()) :: t()

Clears replayed catch-up events for the identified workspace.

@spec clear_workspace_session(t(), non_neg_integer()) :: t()

Clears session state from the identified workspace.

@spec count(t()) :: pos_integer()

Returns the number of tabs.

@spec disclosure_tier(t()) :: 0 | 1 | 2 | 3

Returns the progressive disclosure tier (0-3) based on agent workspace count.

@spec drop_extension_feature_state_sources(t()) :: t()

Drops snapshotted extension-owned feature state from every tab context.

@spec drop_feature_state_source(t(), MingaEditor.FeatureState.source()) :: t()

Drops snapshotted feature state owned by a source from every tab context.

@spec filter_by_kind(t(), MingaEditor.State.Tab.kind()) :: [MingaEditor.State.Tab.t()]

Returns all tabs matching the given kind.

@spec find_by_kind(t(), MingaEditor.State.Tab.kind()) ::
  MingaEditor.State.Tab.t() | nil

Returns the first tab matching the given kind, or nil.

@spec find_by_remote_session(t(), String.t(), String.t()) ::
  MingaEditor.State.Tab.t() | nil

Returns the remote agent tab for a server/session id pair.

@spec find_by_session(t(), pid()) :: MingaEditor.State.Tab.t() | nil

Returns the agent tab whose session matches the given pid, or nil.

@spec find_file_tab_in_workspace(t(), non_neg_integer(), Minga.Project.FileRef.t()) ::
  MingaEditor.State.Tab.t() | nil

Finds the file tab in a workspace that represents the given file reference.

@spec find_sessionless_agent(t()) :: MingaEditor.State.Tab.t() | nil

Returns an agent tab that has no session assigned, or nil.

Used by start_agent_session to find the correct tab to bind a new session to, avoiding ambiguity when multiple agent tabs exist. Falls back to the active tab if it's an agent tab.

@spec find_workspace_by_remote_session(t(), String.t(), String.t()) ::
  MingaEditor.State.Workspace.t() | nil

Returns the workspace matching a remote server/session id pair.

@spec find_workspace_by_session(t(), pid()) :: MingaEditor.State.Workspace.t() | nil

Returns the workspace matching the given session pid, or nil.

@spec get(t(), MingaEditor.State.Tab.id()) :: MingaEditor.State.Tab.t() | nil

Returns the tab with the given id, or nil.

@spec get_workspace(t(), non_neg_integer()) :: MingaEditor.State.Workspace.t() | nil

Returns the workspace with the given id, or nil.

@spec has_agent_workspaces?(t()) :: boolean()

Returns true if any agent workspaces exist.

@spec has_tab?(t(), MingaEditor.State.Tab.id()) :: boolean()

Returns true if a tab with the given id exists.

@spec insert(t(), MingaEditor.State.Tab.kind(), String.t()) ::
  {t(), MingaEditor.State.Tab.t()}

Inserts a new tab next to the active tab without switching to it.

Returns {updated_tab_bar, new_tab}. The caller is responsible for calling switch_to/2 or EditorState.switch_tab/2 to activate it. This is the primitive that add/3 and EditorState.add_buffer/2 build on.

@spec keep_only(t(), MingaEditor.State.Tab.id()) :: t()

Keeps only the tab with the given id. Returns unchanged when the tab is not present.

@spec most_recent_of_kind(t(), MingaEditor.State.Tab.kind()) ::
  MingaEditor.State.Tab.t() | nil

Returns the most recently used tab of the given kind that is NOT the active tab. Useful for "switch back to previous file/agent" commands.

Tabs are searched right-to-left from the active position (wrapping), so the nearest neighbor of the requested kind is returned.

@spec move_active_tab_left(t()) :: t()

Moves the active tab one visible slot left within its workspace.

@spec move_active_tab_right(t()) :: t()

Moves the active tab one visible slot right within its workspace.

@spec move_tab_left(t(), MingaEditor.State.Tab.id()) :: t()

Moves the tab with the given id one visible slot left within its workspace.

@spec move_tab_right(t(), MingaEditor.State.Tab.id()) :: t()

Moves the tab with the given id one visible slot right within its workspace.

@spec move_tab_to_workspace(t(), MingaEditor.State.Tab.id(), non_neg_integer()) :: t()

Moves a tab to a different workspace.

@spec new(MingaEditor.State.Tab.t(), String.t() | nil) :: t()

Creates a tab bar with a single initial tab and the manual workspace.

@spec new_empty(String.t() | nil) :: t()

Creates a tab bar with no tabs, for a zero-buffers launchpad startup (#2689).

active_id keeps its dangling default (1) — active/1 returns nil for an empty bar — so next_id starts at 2 to guarantee no restored or added tab ever collides with the dangling active id.

@spec next(t()) :: t()

Switches to the next visible file tab in the active workspace, wrapping around.

@spec next_agent_workspace(t()) :: t()

Switches to the next agent workspace, wrapping around. No-op if no agent workspaces exist.

@spec next_of_kind(t(), MingaEditor.State.Tab.kind()) :: t()

Cycles to the next tab of the given kind, wrapping around. If the active tab is already of that kind, jumps to the next one. If the active tab is a different kind, jumps to the first of the requested kind. Returns unchanged if no tabs of that kind exist.

@spec pin_tab(t(), MingaEditor.State.Tab.id()) :: t()

Pins the tab with the given id. Returns unchanged when the tab is missing.

@spec prev(t()) :: t()

Switches to the previous visible file tab in the active workspace, wrapping around.

@spec prev_agent_workspace(t()) :: t()

Switches to the previous agent workspace, wrapping around. No-op if no agent workspaces exist.

@spec rebind_buffer_file(t(), pid(), Minga.Project.FileRef.t()) :: t()

Rebinds every matching file tab and workspace reference to one logical file identity.

@spec refresh_tab_session(
  t(),
  MingaEditor.State.Tab.id(),
  pid(),
  pid(),
  MingaEditor.State.Tab.agent_status()
) :: t()

Refreshes a restarted session identity and status on the identified tab.

@spec remote_workspaces_for_server(t(), String.t()) :: [
  MingaEditor.State.Workspace.t()
]

Returns remote workspaces for a server.

@spec remove(t(), MingaEditor.State.Tab.id()) :: {:ok, t()} | :last_tab

Removes the tab with the given id.

If the removed tab was active, switches to the nearest neighbor (prefer right, then left). Returns {:ok, updated_tab_bar} or :last_tab if this is the only tab (can't remove the last one).

@spec remove_file_tabs(t()) :: t()

Removes every file tab, leaving agent tabs (if any) in place.

Used when the workspace enters the zero-buffers launchpad (#2689): the file tab strip collapses instead of keeping phantom tabs. remove/2 keeps its can't-remove-last contract for every other caller. When the active tab was removed, the first remaining tab becomes active; active/1 tolerates an empty bar (returns nil).

@spec remove_workspace(t(), non_neg_integer()) :: t()

Removes a workspace and migrates its tabs to the manual workspace (group_id 0).

Cannot remove the manual workspace.

@spec remove_workspace_file(t(), non_neg_integer(), Minga.Project.FileRef.t()) :: t()

Removes a file identity from the identified workspace.

@spec rename_workspace(t(), non_neg_integer(), String.t()) :: t()

Renames the identified workspace.

@spec reorder_tab(t(), MingaEditor.State.Tab.id(), non_neg_integer()) :: t()

Reorders a visible file tab within its workspace by zero-based visible index.

@spec restore_workspaces(t(), [MingaEditor.State.Workspace.t()], String.t() | nil) ::
  t()

Replaces restored workspaces and recalculates the next workspace id.

@spec retarget_tab_file(
  t(),
  MingaEditor.State.Tab.id(),
  Minga.Project.FileRef.t(),
  boolean()
) :: t()

Retargets one tab and its workspace to a concrete file identity.

@spec retarget_workspace_file(
  t(),
  non_neg_integer(),
  Minga.Project.FileRef.t() | nil,
  Minga.Project.FileRef.t(),
  boolean()
) :: t()

Retargets one file identity in the identified workspace.

@spec scrub_dead_buffer(t(), pid()) :: t()

Removes a dead buffer pid from every tab and workspace projection.

@spec set_attention_by_session(t(), pid(), boolean()) :: t()

Sets the attention flag on the tab matching the given session pid.

@spec set_remote_connection_status(
  t(),
  String.t(),
  MingaEditor.State.Tab.connection_status()
) :: t()

Updates all workspaces and projected tabs for a remote server to the given connection status.

@spec set_tab_agent_status(
  t(),
  MingaEditor.State.Tab.id(),
  MingaEditor.State.Tab.agent_status()
) :: t()

Records an agent status on the identified tab.

@spec set_tab_attention(t(), MingaEditor.State.Tab.id(), boolean()) :: t()

Records attention for the identified tab without changing tab identity or order.

@spec set_tab_connection_status(
  t(),
  MingaEditor.State.Tab.id(),
  MingaEditor.State.Tab.connection_status()
) :: t()

Records remote connection status on the identified tab.

@spec set_tab_remote_session(
  t(),
  MingaEditor.State.Tab.id(),
  String.t(),
  String.t(),
  pid()
) :: t()

Records a remote session identity on the identified tab.

@spec set_tab_session(t(), MingaEditor.State.Tab.id(), pid() | nil) :: t()

Binds or clears the session owned by the identified tab.

@spec set_workspace_active_file(
  t(),
  non_neg_integer(),
  Minga.Project.FileRef.t() | nil
) :: t()

Selects the active file identity in the identified workspace.

@spec set_workspace_agent_status(
  t(),
  non_neg_integer(),
  MingaEditor.State.Tab.agent_status()
) :: t()

Records agent status on the identified workspace.

@spec set_workspace_agent_ui(t(), non_neg_integer(), MingaEditor.Agent.UIState.t()) ::
  t()

Records the agent UI projection on the identified workspace.

@spec set_workspace_icon(t(), non_neg_integer(), String.t()) :: t()

Sets the icon of the identified workspace.

@spec set_workspace_pending_catchup_events(t(), non_neg_integer(), [term()]) :: t()

Records pending durable catch-up events on the identified workspace.

@spec set_workspace_project_view(t(), non_neg_integer(), term()) :: t()

Records project-view state on the identified workspace.

@spec set_workspace_remote_connection_status(
  t(),
  non_neg_integer(),
  MingaEditor.State.Tab.connection_status()
) :: t()

Records remote connection status on the identified workspace.

@spec set_workspace_review(
  t(),
  non_neg_integer(),
  MingaEditor.State.WorkspaceReview.t()
) :: t()

Records review state on the identified workspace.

@spec set_workspace_session(t(), non_neg_integer(), pid() | nil) :: t()

Binds or clears the identified workspace session.

@spec snapshot_and_switch(
  t(),
  MingaEditor.State.Tab.id(),
  MingaEditor.State.Tab.context(),
  MingaEditor.State.Tab.id()
) :: t()

Snapshots the outgoing tab and activates an existing target tab atomically.

@spec switch_to(t(), MingaEditor.State.Tab.id()) :: t()

Switches the active tab to the one with the given id.

@spec switch_to_workspace(t(), non_neg_integer()) :: t()

Switches to the given workspace by activating its first visible tab.

Returns unchanged if the workspace doesn't exist or has no visible tabs.

@spec sync_workspace_agent_tab_projection(t(), non_neg_integer()) :: t()

@spec sync_workspace_agent_tab_projection(t(), MingaEditor.State.Workspace.t()) :: t()

Synchronizes any agent-tab projection from workspace-owned lifecycle and remote metadata.

@spec tab_at(t(), pos_integer()) :: MingaEditor.State.Tab.t() | nil

Returns the tab at the given 1-based position index, or nil.

@spec tabs_in_workspace(t(), non_neg_integer()) :: [MingaEditor.State.Tab.t()]

Returns all tabs belonging to the given workspace.

@spec toggle_active_pin(t()) :: t()

Toggles the pinned state of the active tab.

@spec unpin_tab(t(), MingaEditor.State.Tab.id()) :: t()

Unpins the tab with the given id. Returns unchanged when the tab is missing.

@spec update_context(
  t(),
  MingaEditor.State.Tab.id(),
  MingaEditor.State.Tab.context() | MingaEditor.State.Tab.legacy_context()
) :: t()

Updates the context of the tab with the given id.

@spec update_label(t(), MingaEditor.State.Tab.id(), String.t()) :: t()

Updates the label of the tab with the given id.

@spec visible_file_tabs(t()) :: [MingaEditor.State.Tab.t()]

Returns visible file tabs for the active workspace.

@spec visible_file_tabs(t(), non_neg_integer()) :: [MingaEditor.State.Tab.t()]

Returns visible file tabs for the given workspace id. Agent chat tabs are excluded.

@spec visible_workspace_tabs(t()) :: [MingaEditor.State.Tab.t()]

Returns visible content tabs for the active workspace.

@spec visible_workspace_tabs(t(), non_neg_integer()) :: [MingaEditor.State.Tab.t()]

Returns visible content tabs for the given workspace id. Agent workspaces show their agent tab first, followed by file tabs.