Behaviour for pluggable presentation shells.
A shell owns layout, chrome, input routing, buffer lifecycle, and tab/session queries. The editor dispatches these presentation concerns to the active shell.
Summary
Types
Why a buffer was added.
Structured GUI payload returned by a shell and encoded centrally by frontend protocol modules.
Shell-specific state. Each shell defines its own struct.
Workspace state (the editing context shared by all shells).
Callbacks
Returns the agent session pid for the user's current view.
Returns the currently active tab, or nil if the shell has no tabs.
Returns the kind of the active tab.
Runs after handle_gui_action/3 has been applied to full editor state.
Returns true when the shell can render through the asynchronous pipeline path.
Blurs shell-owned bottom-panel presentation during a window focus transition.
Returns a chrome struct with draw lists for each UI region.
Returns shell-specific data that affects chrome dirty tracking.
Returns a layout struct with named rectangles for each UI region.
Drops extension sources from feature state retained inside opaque shell state.
Drops one source from feature state retained inside opaque shell state.
Finds the file tab whose snapshotted workspace has pid as active buffer.
Returns structured GUI payload data for the active shell, or nil.
Handles an agent session going down and reports whether the shell owned it.
A managed agent session restarted and the shell should refresh pid references.
Handles a shell-specific event.
Handles a shell-specific GUI action from the native frontend.
Handles a remote session disconnect and reports whether the shell owned it.
Initializes shell state from config.
Returns the input handler stack for this shell.
An agent session emitted a background event.
Calculates shell state after a workflow has prepared inert buffer metadata.
A buffer process died.
The active buffer changed.
Returns whether this shell state owns an agent session pid. Every shell must define ownership for its own state shape.
Persists shell state outside the pure Runtime transition boundary.
Runs the full render pipeline and returns updated editor state.
Associates a session pid with a tab.
Synchronizes optional agent status held by a shell.
Tracks an agent-touched file in optional shell state.
Types
@type buffer_add_context() :: :open | :preview
Why a buffer was added.
Structured GUI payload returned by a shell and encoded centrally by frontend protocol modules.
@type shell_state() :: term()
Shell-specific state. Each shell defines its own struct.
@type workspace() :: MingaEditor.Session.State.t()
Workspace state (the editing context shared by all shells).
Callbacks
@callback active_session(shell_state()) :: pid() | nil
Returns the agent session pid for the user's current view.
@callback active_tab(shell_state()) :: MingaEditor.State.Tab.t() | nil
Returns the currently active tab, or nil if the shell has no tabs.
@callback active_tab_kind(shell_state()) :: atom()
Returns the kind of the active tab.
Runs after handle_gui_action/3 has been applied to full editor state.
Returns true when the shell can render through the asynchronous pipeline path.
@callback blur_bottom_panel(shell_state()) :: shell_state()
Blurs shell-owned bottom-panel presentation during a window focus transition.
@callback build_chrome( editor_state :: term(), layout :: MingaEditor.Layout.t(), scrolls :: map(), cursor_info :: term() ) :: MingaEditor.RenderPipeline.Chrome.t()
Returns a chrome struct with draw lists for each UI region.
Returns shell-specific data that affects chrome dirty tracking.
@callback compute_layout(editor_state :: term()) :: MingaEditor.Layout.t()
Returns a layout struct with named rectangles for each UI region.
@callback drop_extension_feature_state_sources(shell_state()) :: shell_state()
Drops extension sources from feature state retained inside opaque shell state.
@callback drop_feature_state_source( shell_state(), MingaEditor.FeatureState.source() ) :: shell_state()
Drops one source from feature state retained inside opaque shell state.
@callback find_tab_by_buffer(shell_state(), pid()) :: MingaEditor.State.Tab.t() | nil
Finds the file tab whose snapshotted workspace has pid as active buffer.
@callback gui_payload(editor_state :: term()) :: gui_payload() | nil
Returns structured GUI payload data for the active shell, or nil.
@callback handle_agent_session_down(shell_state(), session_pid :: pid(), reason :: term()) :: {shell_state(), boolean()}
Handles an agent session going down and reports whether the shell owned it.
@callback handle_agent_session_restarted( shell_state(), old_session_pid :: pid(), new_session_pid :: pid(), reason :: term() ) :: {shell_state(), boolean()}
A managed agent session restarted and the shell should refresh pid references.
@callback handle_event(shell_state(), workspace(), event :: term()) :: {shell_state(), workspace()}
Handles a shell-specific event.
@callback handle_gui_action(shell_state(), workspace(), action :: term()) :: {shell_state(), workspace()}
Handles a shell-specific GUI action from the native frontend.
@callback handle_remote_session_disconnected(shell_state(), session_pid :: pid()) :: {shell_state(), boolean()}
Handles a remote session disconnect and reports whether the shell owned it.
@callback init(opts :: keyword()) :: shell_state()
Initializes shell state from config.
@callback input_handlers(editor_state :: term()) :: %{ overlay: [MingaEditor.Input.dispatch_handler()], surface: [MingaEditor.Input.dispatch_handler()] }
Returns the input handler stack for this shell.
@callback on_agent_event( shell_state(), workspace(), session_pid :: pid(), event :: term() ) :: {shell_state(), workspace()}
An agent session emitted a background event.
@callback on_buffer_added( shell_state(), prev_workspace :: workspace(), workspace(), MingaEditor.Shell.BufferMetadata.t() ) :: {shell_state(), workspace()}
Calculates shell state after a workflow has prepared inert buffer metadata.
@callback on_buffer_died(shell_state(), workspace(), dead_pid :: pid()) :: {shell_state(), workspace()}
A buffer process died.
@callback on_buffer_switched(shell_state(), workspace()) :: {shell_state(), workspace()}
The active buffer changed.
@callback owns_agent_session?(shell_state(), session_pid :: pid()) :: boolean()
Returns whether this shell state owns an agent session pid. Every shell must define ownership for its own state shape.
@callback persist_shell_state(shell_state()) :: shell_state()
Persists shell state outside the pure Runtime transition boundary.
Runs the full render pipeline and returns updated editor state.
@callback set_tab_session(shell_state(), tab_id :: term(), pid() | nil) :: shell_state()
Associates a session pid with a tab.
@callback sync_agent_status(shell_state(), session_pid :: pid(), status :: term()) :: shell_state()
Synchronizes optional agent status held by a shell.
@callback track_agent_file(shell_state(), session_pid :: pid(), path :: String.t()) :: shell_state()
Tracks an agent-touched file in optional shell state.