Struct SessionRuntime 

pub struct SessionRuntime<'a> { /* private fields */ }

Runtime that implements all session API traits.

Bundles Session + KernelContext + CommandExecutor. Changes accumulate internally; runner takes at end via take_changes.

Compositor Integration

The compositor is accessed via session.compositor. When present, CompositorApi methods delegate to it. When absent, they return errors.

Per-Client State (#471, #477)

SessionRuntime ALWAYS operates on per-client state. The per-client fields are required (no Option wrappers, no fallback to shared state):

• mode_stack (#471): Per-client mode (INSERT, NORMAL, etc.)
• windows (#471): Per-client cursor positions
• extensions (#477): Per-client module state (VimSessionState, etc.)

This enforces multi-client isolation at compile time - you cannot create a SessionRuntime without providing per-client state.

Client Binding (#471)

The owner field tracks which client this runtime is bound to. When present, it makes explicit which client’s state we’re operating on. This is useful for:

• Debugging and logging
• Assertions in tests
• Future multi-client coordination

Implementations

impl<'a> SessionRuntime<'a>

pub fn new( session: &'a mut Session, client: ClientContext<'a>, kernel: &'a KernelContext, executor: &'a dyn CommandExecutor, ) -> Self

Create a new runtime with per-client state (#471, #477).

All per-client state is required. There are no fallbacks to shared session state. This enforces multi-client isolation at compile time.

Arguments

• session - Shared session state (compositor, home mode)
• mode_stack - Per-client mode stack (source of truth for mode)
• windows - Per-client window layout with cursors
• extensions - Per-client module extensions
• kernel - Kernel context (buffers, registers, marks)
• executor - Command executor

Multi-Client Isolation

Each client has independent:

• Mode state (Client A in INSERT while Client B in NORMAL)
• Cursor positions (Client A at line 5, Client B at line 10)
• Module state (Client A’s pending_count doesn’t affect Client B)

Example

// From server level, get per-client EditingState
let editing_state = session.client_state_mut(client_id)?;

// Create runtime with per-client state bundle
let client = editing_state.client_context();
let mut runtime = SessionRuntime::new(
    &mut driver_session,
    client,
    &kernel,
    &executor,
);

// All operations use per-client state
runtime.push_mode(insert_mode, ctx);     // Only affects this client
runtime.windows().active();              // This client's active window
runtime.ext_mut::<VimSessionState>();    // This client's vim state

pub fn with_owner( owner: ClientId, session: &'a mut Session, client: ClientContext<'a>, kernel: &'a KernelContext, executor: &'a dyn CommandExecutor, ) -> Self

Create a runtime with explicit client binding (#471).

Like new, but also records which client this runtime is bound to. The owner field can be retrieved via owner().

Arguments

• owner - The ClientId this runtime is bound to
• session - Shared session infrastructure
• client - Per-client state bundle (mode, windows, extensions, registers, etc.)
• kernel - Kernel context (buffers, global marks)
• executor - Command executor

Example

let client = editing_state.client_context();
let mut runtime = SessionRuntime::with_owner(
    client_id,
    &mut driver_session,
    client,
    &kernel,
    &executor,
);

// Query which client owns this runtime
assert_eq!(runtime.owner(), Some(client_id));

pub const fn owner(&self) -> Option<ClientId>

Get the client ID this runtime is bound to (#471).

Returns Some(ClientId) if created with with_owner, None otherwise. Use this for debugging, logging, or assertions about which client owns this runtime.

Example

let runtime = SessionRuntime::with_owner(client_id, ...);
assert_eq!(runtime.owner(), Some(client_id));

let shared_runtime = SessionRuntime::new(...);
assert_eq!(shared_runtime.owner(), None);

pub const fn with_shared_extensions( self, extensions: &'a mut ExtensionMap, ) -> Self

Set shared extensions for session-wide state access (#543).

Called by server code that has access to AppState.extensions. Enables shared_ext() / shared_ext_mut() in commands.

pub fn signal(&mut self, signal: RuntimeSignal)

Push a lifecycle signal onto the queue (#547).

Commands call this during execution. The server drains the queue after the command returns and acts on the signals. Same pattern as StateChanges — accumulate during execution, drain after.

pub fn take_signals(&mut self) -> Vec<RuntimeSignal>

Drain the signal queue, returning all accumulated signals (#547).

Called by the server after command execution completes. Returns the signals and empties the queue.

pub fn has_compositor(&self) -> bool

Check if compositor is available.

pub const fn session(&self) -> &Session

Get direct access to the session.

pub const fn session_mut(&mut self) -> &mut Session

Get mutable access to the session.

pub const fn kernel(&self) -> &KernelContext

Get direct access to the kernel context.

pub fn with_buffer_read<F, R>(&self, buffer: BufferId, f: F) -> Option<R>

where F: FnOnce(&Buffer) -> R,

Execute a read-only operation on a buffer.

This method provides temporary read access to a buffer for complex calculations that need the full buffer interface (e.g., motion calculations, text object matching).

Arguments

• buffer - The buffer ID to access
• f - A function that receives a read guard to the buffer

Returns

Some(R) with the function’s return value if the buffer exists, None if the buffer doesn’t exist.

Example

let target = runtime.with_buffer_read(buffer_id, |buffer| {
    MotionEngine::calculate(buffer, &cursor, motion, count)
});

pub fn record_global_option_change( &mut self, name: impl Into<String>, value: OptionValue, )

Record a global option change for notification emission.

Call this after setting a global option via kernel.options.set(). The change will be emitted as an OPTION_CHANGED notification.

pub fn record_window_option_change( &mut self, name: impl Into<String>, value: OptionValue, window_id: WindowId, )

Record a window-scoped option change for notification emission.

Call this after setting a window option via kernel.options.set(). The change will be emitted as an OPTION_CHANGED notification.

pub fn record_buffer_modified(&mut self, buffer: BufferId)

Record that a buffer was modified for notification emission.

Call this after modifying buffer content directly (e.g., via OperatorContext which bypasses SessionRuntime’s BufferApi methods like delete_range()).

pub const fn windows(&self) -> &WindowLayout

Get the per-client windows.

Phase #471: Direct access to per-client windows. No fallback, no Option. Commands use this to access the active window’s cursor position.

Example

let Some(window) = runtime.windows().active() else {
    return CommandResult::error("No active window");
};
let pos = Position::new(window.cursor.line, window.cursor.column);

pub fn windows_mut(&mut self) -> &mut WindowLayout

Get the per-client windows mutably.

Phase #471: Direct access to per-client windows for cursor/selection updates.

Example

if let Some(window) = runtime.windows_mut().active_mut() {
    window.cursor = new_pos.into();
    window.selection = Some(Selection::new(start, end, mode));
}

pub const fn registers(&self) -> &RegisterBank

Get per-client registers (#515).

pub fn registers_mut(&mut self) -> &mut RegisterBank

Get per-client registers mutably (#515).

pub const fn clipboard_history(&self) -> &HistoryRing

Get per-client clipboard history (#515).

pub fn clipboard_history_mut(&mut self) -> &mut HistoryRing

Get per-client clipboard history mutably (#515).

pub const fn kernel_and_registers( &mut self, ) -> (&KernelContext, &mut RegisterBank, &mut HistoryRing)

Get kernel, registers, and clipboard history together (#515).

Splits the borrow so the caller can hold &KernelContext and &mut RegisterBank / &mut HistoryRing simultaneously, which isn’t possible through separate accessor calls.

pub const fn local_marks(&self) -> &MarkBank

Get per-client local marks (#515).

pub fn local_marks_mut(&mut self) -> &mut MarkBank

Get per-client local marks mutably (#515).

pub const fn jumplist(&self) -> &Jumplist

Get per-client jump list (#654).

pub fn jumplist_mut(&mut self) -> &mut Jumplist

Get per-client jump list mutably (#654).

impl SessionRuntime<'_>

pub fn push_to_clipboard_history(&mut self, content: RegisterContent)

Push content to the per-client clipboard history (#515).

Should be called after every yank/delete operation to populate numbered registers (0-9). This is an inherent method because history is per-client state, not a shared service.

pub fn store_register_with_sync( &mut self, register: Option<char>, content: RegisterContent, )

Store content to register with clipboard sync (#515 Phase 4).

Coordinates RegisterApi and ClipboardApi:

1. Stores content in per-client register via RegisterApi
2. Syncs to OS clipboard for +/* registers via ClipboardApi
3. Pushes to clipboard history for numbered register rotation

Use this from commands that operate on SessionRuntime directly (visual mode operators, editor commands). Vim operators that hold separate borrows via OperatorContext use registers::store_and_sync instead.

pub fn get_register_with_clipboard( &self, register: Option<char>, ) -> Option<RegisterContent>

Get register content with clipboard fallback for +/* (#515 Phase 4).

For system clipboard registers:

• +: reads from OS clipboard, falls back to per-client register
• *: reads from OS selection, falls back to per-client register
• All others: reads directly from per-client RegisterBank

Trait Implementations

impl BufferApi for SessionRuntime<'_>

fn active_buffer(&self) -> Option<BufferId>

Get the active buffer ID.

fn set_active_buffer(&mut self, id: Option<BufferId>)

Set the active buffer ID.

fn buffer_line(&self, buffer: BufferId, line: usize) -> Option<String>

Get a line from a buffer.

fn buffer_line_count(&self, buffer: BufferId) -> Option<usize>

Get the line count of a buffer.

fn buffer_line_len(&self, buffer: BufferId, line: usize) -> Option<usize>

Get the length of a line in characters.

fn buffer_text_range( &self, buffer: BufferId, start: Position, end: Position, ) -> Option<String>

Extract text from a range in the buffer.

fn buffer_content(&self, buffer: BufferId) -> Option<String>

Get full buffer content as a string.

fn buffer_file_path(&self, buffer: BufferId) -> Option<String>

Get buffer’s file path.

fn is_buffer_modified(&self, buffer: BufferId) -> Option<bool>

Check if buffer has been modified since last save.

fn set_buffer_modified(&mut self, buffer: BufferId, modified: bool)

Set buffer’s modified flag.

fn insert_text(&mut self, buffer: BufferId, pos: Position, text: &str)

Insert text at a position.

fn delete_range(&mut self, buffer: BufferId, start: Position, end: Position)

Delete a range.

fn replace_content(&mut self, buffer: BufferId, content: &str)

Replace entire buffer content.

fn create_buffer(&mut self, name: Option<&str>, content: &str) -> BufferId

Create a new buffer.

fn delete_buffer(&mut self, buffer: BufferId) -> Result<(), BufferError>

Delete a buffer.

fn rename_buffer(&mut self, buffer: BufferId, new_name: &str)

Rename a buffer.

impl ChangeTracker for SessionRuntime<'_>

fn take_changes(&mut self) -> StateChanges

Take all accumulated changes, resetting internal state.

fn record_cursor_move(&mut self, buffer: BufferId)

Record that the cursor moved in a buffer.

fn record_selection_change(&mut self, buffer: BufferId)

Record that the selection changed in a buffer (#474).

impl ClipboardApi for SessionRuntime<'_>

fn copy_to_clipboard(&self, text: &str) -> bool

Copy text to the system clipboard (+ register).

fn paste_from_clipboard(&self) -> Option<String>

Paste text from the system clipboard (+ register).

fn copy_to_selection(&self, text: &str) -> bool

Copy text to the selection clipboard (* register).

fn paste_from_selection(&self) -> Option<String>

Paste text from the selection clipboard (* register).

impl CommandApi for SessionRuntime<'_>

fn execute_command( &mut self, cmd: CommandId, ctx: CommandContext, ) -> CommandResult

Execute a command directly.

impl CompositorApi for SessionRuntime<'_>

fn navigate( &self, direction: NavigateDirection, ) -> Result<WindowId, CompositorError>

Navigate in direction from the current window.

fn split( &mut self, direction: SplitDirection, ) -> Result<WindowId, CompositorError>

Split the current window.

fn close_current_window(&mut self) -> Result<WindowId, CompositorError>

Close the current window.

fn close_others(&mut self) -> Result<(), CompositorError>

Close all windows except the current one.

fn resize( &mut self, direction: NavigateDirection, delta: i16, ) -> Result<(), CompositorError>

Resize the current window.

fn equalize(&mut self) -> Result<(), CompositorError>

Equalize all windows in the current layer.

fn cycle(&self, forward: bool) -> Result<WindowId, CompositorError>

Cycle to next/previous window.

fn focus(&mut self, window: WindowId) -> Result<(), CompositorError>

Set focus to a specific window.

fn focused_window(&self) -> Option<WindowId>

Get the currently focused window.

fn compositor_window_count(&self) -> usize

Get window count in the active layer.

fn arrange(&self, screen: Rect) -> Vec<WindowPlacement>

Get all window placements (for rendering).

fn active_layer(&self) -> Option<LayerId>

Get the active layer ID.

fn set_screen(&mut self, screen: Rect)

Update screen size (on terminal resize).

fn toggle_float(&mut self) -> Result<(), CompositorError>

Toggle the current window between tiled and float zones.

fn raise_float(&mut self) -> Result<(), CompositorError>

Raise the current float window to the front.

fn lower_float(&mut self) -> Result<(), CompositorError>

Lower the current float window to the back.

fn show_overlay( &mut self, constraints: OverlayConstraints, ) -> Result<WindowId, CompositorError>

Show an overlay with constraints.

fn hide_overlay(&mut self, window: WindowId) -> Result<(), CompositorError>

Hide (remove) an overlay.

fn resize_overlay( &mut self, window: WindowId, width: u16, height: u16, ) -> Result<(), CompositorError>

Resize an overlay.

fn hide_all_overlays(&mut self) -> Result<(), CompositorError>

Hide all overlays in the active layer.

fn set_active_layer_opacity( &mut self, opacity: f32, ) -> Result<(), CompositorError>

Set the opacity of the active layer.

fn active_layer_opacity(&self) -> Result<f32, CompositorError>

Get the opacity of the active layer.

fn adjust_active_layer_opacity( &mut self, delta: f32, ) -> Result<f32, CompositorError>

Adjust the active layer’s opacity by a delta.

fn tab_new(&mut self) -> Result<TabId, CompositorError>

Create a new tab page after the active tab.

fn tab_close(&mut self) -> Result<(), CompositorError>

Close the active tab page.

fn tab_next(&mut self) -> Result<TabId, CompositorError>

Switch to the next tab page (wraps around).

fn tab_prev(&mut self) -> Result<TabId, CompositorError>

Switch to the previous tab page (wraps around).

fn tab_goto(&mut self, index: usize) -> Result<TabId, CompositorError>

Switch to a tab page by 0-based index.

fn tab_count(&self) -> usize

Get the number of tab pages.

fn active_tab_id(&self) -> Option<TabId>

Get the active tab page’s ID.

impl ExtensionApi for SessionRuntime<'_>

Per-client extensions (#477, #471 Phase 0).

Extensions are now ALWAYS per-client (no fallback to shared session). This enforces complete module state isolation between clients. For example, VimSessionState.pending_count is per-client, so Client A pressing 5 doesn’t affect Client B’s motions.

fn ext<T: SessionExtension>(&self) -> Option<&T>

Get per-client extension by type (immutable).

fn ext_mut<T: SessionExtension>(&mut self) -> &mut T

Get per-client extension by type (mutable), creating if needed.

fn shared_ext<T: SessionExtension>(&self) -> Option<&T>

Get shared (session-wide) extension by type (immutable).

fn shared_ext_mut<T: SessionExtension>(&mut self) -> Option<&mut T>

Get shared (session-wide) extension by type (mutable), creating if needed.

impl ModeApi for SessionRuntime<'_>

Per-client state (#471): Mode operations use the per-client mode stack directly.

Since per-client state is now required (no Option), all mode operations directly access self.mode_stack without fallback to session.

fn current_mode(&self) -> &ModeId

Get the current mode (top of stack).

fn home_mode(&self) -> &ModeId

Get the home mode (bottom of stack, cannot be popped).

fn mode_depth(&self) -> usize

Get the mode stack depth.

fn is_mode_active(&self, mode: &ModeId) -> bool

Check if a mode is anywhere on the stack.

fn mode_stack(&self) -> Vec<ModeId>

Get the full mode stack as a snapshot (bottom to top).

fn push_mode(&mut self, mode: ModeId, _ctx: TransitionContext)

Push a mode onto the stack.

fn pop_mode(&mut self, _result: Option<PopResult>) -> Result<(), ModeError>

Pop the current mode from the stack.

fn set_mode(&mut self, mode: ModeId, _ctx: TransitionContext)

Replace the current mode (pop + push atomically).

impl RegisterApi for SessionRuntime<'_>

fn get_register(&self, name: Option<char>) -> Option<RegisterContent>

Get register contents.

fn set_register(&mut self, name: Option<char>, content: RegisterContent)

Set register contents.

impl UndoApi for SessionRuntime<'_>

fn undo(&mut self, buffer: BufferId) -> Option<UndoResult>

Undo the last change for a buffer.

fn redo(&mut self, buffer: BufferId) -> Option<UndoResult>

Redo the last undone change for a buffer.

fn record_edit( &mut self, buffer: BufferId, edits: Vec<Edit>, cursor_before: Position, cursor_after: Position, )

Record edits for undo history.

fn can_undo(&self, buffer: BufferId) -> bool

Check if undo is available for a buffer.

fn can_redo(&self, buffer: BufferId) -> bool

Check if redo is available for a buffer.

fn undo_mine(&mut self, buffer: BufferId) -> Option<UndoResult>

Undo the last change made by the current client.

fn redo_mine(&mut self, buffer: BufferId) -> Option<UndoResult>

Redo the last undone change made by the current client.

fn record_edit_mine( &mut self, buffer: BufferId, edits: Vec<Edit>, cursor_before: Position, cursor_after: Position, )

Record edits for undo history with client origin tagging.

impl WindowApi for SessionRuntime<'_>

fn active_window(&self) -> Option<WindowId>

Get the active window ID.

fn cursor_position(&self) -> Option<Position>

Get cursor position from the active window.

fn window_count(&self) -> usize

Get the window count.

fn window_buffer(&self, window: WindowId) -> Option<BufferId>

Get the buffer displayed in a window.

fn create_window(&mut self, buffer: Option<BufferId>) -> WindowId

Create a new window.

fn close_window(&mut self, window: WindowId) -> Result<(), WindowError>

Close a window.

fn focus_window(&mut self, window: WindowId) -> Result<(), WindowError>

Focus a window.

fn set_window_buffer( &mut self, window: WindowId, buffer: BufferId, ) -> Result<(), WindowError>

Set the buffer displayed in a window.

fn set_active_selection(&mut self, selection: Option<Selection>)

Set or clear the selection on the active window.

fn active_selection(&self) -> Option<&Selection>

Get the selection on the active window, if any.