@spec activate_buffer(t(), buffer_activation(), keyword()) :: t()

Activates a buffer selection and synchronizes every session-owned observation.

Integer selections delegate wrapping and index semantics to Buffers. A prepared Buffers value supports close, restore, and add workflows that already performed their leaf transition. By default non-buffer surfaces remain visible; replace_window_content?: true lets a shell intentionally replace one with the activated buffer.

@spec active_window_struct(t()) :: MingaEditor.Window.t() | nil

Returns the active window struct, or nil.

@spec clear_cmd_hover_link(t()) :: t()

Clears the complete transient Cmd/Ctrl-hover observation.

@spec current_viewport(t(), MingaEditor.Viewport.t()) :: MingaEditor.Viewport.t()

Returns the focused window viewport or the supplied terminal fallback.

@spec delete_lsp_pending(t(), reference()) :: t()

Removes one pending LSP request from the workspace correlation table.

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

Drops every extension-owned feature state entry.

@spec drop_feature_state(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id()
) ::
  t()

Drops one source-owned feature state entry. Missing state is treated as inactive.

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

Drops all feature state owned by a source.

@spec drop_file_tree(t()) :: t()

Resets FileTree UI state.

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

True when the workspace is showing the zero-buffers launchpad.

@spec enter_empty_state(
  t(),
  keyword()
) :: t()

Enters the zero-buffers launchpad (#2689).

Clears the active buffer, switches the active window's content to the empty-state surface, and snapshots launchpad data (session, recents). The window tree is untouched: the last window stays open.

@spec field_names() :: [MingaEditor.State.Tab.Context.field_name()]

Returns the list of field names (for snapshot/restore compatibility).

@spec file_tree_state(t()) :: MingaEditor.State.FileTree.t()

Returns FileTree UI state.

@spec find_agent_chat_window(t()) ::
  {MingaEditor.Window.id(), MingaEditor.Window.t()} | nil

Finds the semantic agent chat window, when one exists.

@spec focus_surviving_window(
  t(),
  MingaEditor.State.Windows.t(),
  MingaEditor.Window.id()
) :: t()

Commits focus to a surviving window after the active split was removed.

@spec focus_window(t(), MingaEditor.Window.id(), position() | nil) :: t()

Commits a pure window-focus transition after its required buffer calls succeed.

@spec get_feature_state(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id()
) ::
  term() | nil

Returns source-owned feature state, or nil when inactive.

@spec get_feature_state(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id(),
  default
) :: term() | default
when default: var

Returns source-owned feature state, or a caller-provided default when inactive.

@spec invalidate_all_windows(t()) :: t()

Invalidates render caches for all windows.

Call when the screen layout changes (file tree toggle, agent panel toggle) because cached draws contain baked-in absolute coordinates that become wrong when column offsets shift.

@spec mark_authoritative_scroll(t()) :: t()

Marks the active window for authoritative scroll receipt handling.

@spec mark_frontend_reset_pending(t()) :: t()

Marks all window retained-GUI render caches reset-pending after frontend state loss.

@spec observe_window(
  t(),
  MingaEditor.Window.id(),
  pid(),
  MingaEditor.Viewport.t(),
  non_neg_integer()
) ::
  t()

Records a renderer observation for one session-owned window.

@spec put_feature_state(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id(),
  term()
) :: t()

Stores source-owned feature state.

@spec put_lsp_pending(t(), reference(), atom() | tuple()) :: t()

Adds one pending LSP request to the workspace correlation table.

@spec record_feature_value(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id(),
  term()
) :: t()

Records a concrete source-owned feature value.

@spec remember_active_window_cursor(t(), position()) :: t()

Stores the active buffer cursor in its matching active window.

@spec replace_buffer_windows(t(), pid(), %{
  required(MingaEditor.Window.id()) => MingaEditor.Window.t()
}) ::
  t()

Replaces every window showing a buffer with concrete values.

@spec replace_window(t(), MingaEditor.Window.id(), MingaEditor.Window.t()) :: t()

Replaces one session-owned window with a concrete value.

@spec restore_tab_context(
  t(),
  MingaEditor.State.Tab.Context.t() | MingaEditor.State.Tab.Context.legacy()
) :: t()

Restores a tab context into a workspace. Empty contexts are ignored by this pure helper; EditorState handles brand-new tab defaults because those need editor dimensions. Dead buffer pids in the restored context are scrubbed to prevent activating a dead process.

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

Forgets a retired process when it owns the agent prompt buffer.

@spec scope_for_active_window(t()) :: atom()

Returns the appropriate keymap scope for the active window's content type.

@spec scope_for_content(
  MingaEditor.Window.Content.t(),
  Minga.Keymap.Scope.scope_name()
) ::
  Minga.Keymap.Scope.scope_name()

Derives the keymap scope from a window's content type.

Agent chat windows use :agent, launchpad windows use :editor, and buffer windows return from :agent to :editor while preserving other scopes.

@spec scroll_agent_chat_window(t(), integer()) :: t()

Scrolls the agent chat window viewport when one exists.

@spec set_agent_ui(t(), MingaEditor.Agent.UIState.t()) :: t()

Updates the agent UI state.

@spec set_buffers(t(), MingaEditor.State.Buffers.t()) :: t()

Replaces the buffers sub-struct.

@spec set_cmd_hover_cell(t(), cmd_hover_cell()) :: t()

Records the pointer cell that produced the hover observation.

@spec set_cmd_hover_link(t(), cmd_hover_link()) :: t()

Records the transient Cmd/Ctrl-hover link range.

@spec set_document_highlights(t(), [document_highlight()] | nil) :: t()

Updates the document highlights from LSP.

@spec set_editing(t(), MingaEditor.VimState.t()) :: t()

Replaces the editing (VimState) sub-struct.

@spec set_feature_state(t(), MingaEditor.FeatureState.t()) :: t()

Replaces the feature-state registry.

@spec set_file_tree(t(), MingaEditor.State.FileTree.t()) :: t()

Replaces the FileTree UI state.

@spec set_keymap_scope(t(), Minga.Keymap.Scope.scope_name()) :: t()

Sets the keymap scope.

@spec set_launchpad(t(), MingaEditor.State.Launchpad.t() | nil) :: t()

Sets or clears the launchpad (zero-buffers empty state).

@spec set_lsp_pending(t(), %{required(reference()) => atom() | tuple()}) :: t()

Updates the LSP pending requests map.

@spec set_mouse(t(), MingaEditor.State.Mouse.t()) :: t()

Updates the mouse sub-struct.

@spec set_search(t(), MingaEditor.State.Search.t()) :: t()

Updates the search sub-struct.

@spec set_viewport(t(), MingaEditor.Viewport.t()) :: t()

Sets the viewport dimensions.

@spec set_windows(t(), MingaEditor.State.Windows.t()) :: t()

Replaces the windows sub-struct.

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

Returns true if the workspace has more than one window.

@spec to_tab_context(t()) :: MingaEditor.State.Tab.Context.t()

Converts a workspace into a typed tab context suitable for storing on a MingaEditor.State.Tab and later restoring via restore_tab_context/2.

The single chokepoint for snapshots. Delegates to TabContext.from_workspace/1 which constructs the context struct directly from the session struct (no intermediate map). The vim state is normalised so the snapshotted editing state is a valid resting state, not a transient mid-transition pair where mode_state belongs to the leaving mode (see VimState.normalize/1). Use this everywhere the editor captures state.workspace into a tab context.

@spec transition_mode(t(), atom(), term()) :: t()

Transitions the editing model to a new mode.

@spec update_current_viewport(t(), MingaEditor.Viewport.t()) :: t()

Updates the active window viewport, when a window is active.