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

Returns the active window struct, or nil.

@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 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 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_frontend_reset_pending(t()) :: t()

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

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

Stores source-owned feature state.

@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 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 always use :agent scope. Buffer windows use :editor when coming from :agent scope, and preserve the current scope otherwise.

@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_dired(t(), MingaEditor.State.Dired.t()) :: t()

Replaces the dired sub-struct.

@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_highlight(t(), MingaEditor.State.Highlighting.t()) :: t()

Updates the highlighting sub-struct.

@spec set_injection_ranges(t(), %{
  required(pid()) => [Minga.Language.Highlight.InjectionRange.t()]
}) ::
  t()

Updates the injection ranges map.

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

Sets the keymap scope.

@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 switch_buffer(t(), non_neg_integer()) :: t()

Switches to the buffer at idx, making it active for the current window.

Pure workspace operation: updates Buffers and syncs the active window.

@spec sync_active_window_buffer(t()) :: t()

Syncs the active window's buffer reference with buffers.active.

Call after any operation that changes buffers.active to keep the window tree consistent. No-op when windows aren't initialized.

@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_editing(t(), (MingaEditor.VimState.t() -> MingaEditor.VimState.t())) ::
  t()

Updates the editing (VimState) sub-struct.

@spec update_feature_state(
  t(),
  MingaEditor.FeatureState.source(),
  MingaEditor.FeatureState.feature_id(),
  term(),
  (term() -> term())
) :: t()

Updates source-owned feature state. Missing values are initialized with default.

@spec update_file_tree(t(), (MingaEditor.State.FileTree.t() ->
                         MingaEditor.State.FileTree.t())) :: t()

Updates the FileTree UI state.

@spec update_highlight(t(), (MingaEditor.State.Highlighting.t() ->
                         MingaEditor.State.Highlighting.t())) ::
  t()

Updates the highlighting sub-struct via a mapper function.

@spec update_search(t(), (MingaEditor.State.Search.t() ->
                      MingaEditor.State.Search.t())) :: t()

Updates the search sub-struct via a mapper function.

@spec update_window(t(), MingaEditor.Window.id(), (MingaEditor.Window.t() ->
                                               MingaEditor.Window.t())) ::
  t()

Updates the window struct for the given window id via a mapper function.

@spec update_windows_for_buffer(t(), pid(), (MingaEditor.Window.t() ->
                                         MingaEditor.Window.t())) :: t()

Updates every window that shows the given buffer via a mapper function.