Crate reovim_driver_session

Expand description

Session driver for reovim.

Provides traits and types for session management.

§Overview

This driver provides:

Session infrastructure: Shared state (SessionShared) and runtime (SessionRuntime)
Client identification: ClientId for explicit client binding
Window management: Window, WindowLayout, CursorPosition
Mode lifecycle: Runtime mode hooks (SessionMode, ModeError)
Extension system: Module per-session state (SessionExtension, ExtensionMap)
Empty session handling: Startup behavior (EmptySessionHandler)

§Architecture (#471, #491)

┌─────────────────────────────────────────────────────────────────┐
│ SESSION DRIVER (server/lib/drivers/session/) - PURE MECHANISM   │
│                                                                 │
│ SHARED INFRASTRUCTURE:                                          │
│   Session { id, shared: SessionShared }                         │
│   SessionShared { compositor, home_mode }                       │
│                                                                 │
│ RUNTIME (borrows shared + per-client state):                    │
│   SessionRuntime::new(&session, &mode_stack, &windows, ...)     │
│                                                                 │
│ PER-CLIENT TYPES (defined here, owned by server::EditingState): │
│   ModeStack, WindowLayout, KeySequence, ExtensionMap, Viewport  │
│                                                                 │
│ LIFECYCLE TRAITS:                                               │
│   SessionMode: id(), on_enter(), on_exit()                      │
│   SessionExtension: create() - module state factory             │
│   EmptySessionHandler: handle() - startup behavior              │
└─────────────────────────────────────────────────────────────────┘

§Per-Client State (#471 Phase 0)

Per-client state (mode, cursor, selection) lives in server::EditingState, not in this driver. The driver provides shared infrastructure only. Use SessionRuntime::new with per-client state, or SessionRuntime::with_owner for explicit client binding. Per-client state is now REQUIRED (no Option wrappers).

§Empty Session Handling

The EmptySessionHandler trait defines how to handle sessions with no buffers. Modules implement this to define policy (e.g., create a scratch buffer, show a welcome screen).

use reovim_driver_session::{
    EmptySessionHandler, EmptySessionContext, EmptySessionAction
};

struct MyHandler;

impl EmptySessionHandler for MyHandler {
    fn handle(&self, ctx: &EmptySessionContext) -> EmptySessionAction {
        EmptySessionAction::CreateBuffer {
            name: None,
            content: String::new(),
        }
    }
    fn id(&self) -> &'static str { "my-module:handler" }
    fn description(&self) -> &'static str { "My handler" }
}

§Session Extension

Modules store per-session policy state via SessionExtension:

use reovim_driver_session::{SessionExtension, ExtensionMap};

#[derive(Default)]
pub struct VimSessionState {
    pub pending_count: Option<usize>,
}

impl SessionExtension for VimSessionState {
    fn create() -> Self { Self::default() }
}

// Access in resolver
let vim = session.extensions.get_or_insert::<VimSessionState>();
vim.pending_count = Some(5);

Re-exports§

pub use api::BufferApi;
pub use api::BufferError;
pub use api::ChangeTracker;
pub use api::ClipboardApi;
pub use api::CommandApi;
pub use api::CommandExecutor;
pub use api::CommandHandle;
pub use api::CompositorApi;
pub use api::CompositorError;
pub use api::ExtensionApi;
pub use api::FindCharRecord;
pub use api::FindCharState;
pub use api::ModeApi;
pub use api::ModeError as ApiModeError;
pub use api::RegisterApi;
pub use api::Selection;
pub use api::SelectionMode;
pub use api::SessionApi;
pub use api::SessionApiDyn;
pub use api::StateChanges;
pub use api::WindowApi;
pub use api::WindowError;
pub use tab::TabPage;
pub use tab::TabPageSet;
pub use tick::TickScheduler;
pub use tick::TickSchedulerHandle;

Modules§

api: Session API traits for resolvers and commands.
bridges: Extension state bridge system for server-to-client state streaming.
tab: Tab page management for session driver.
testing: Test utilities for session-based command testing.
tick: Tick scheduler trait for periodic extension state advancement (#546).

Structs§

BootstrapState: Bootstrap state for creating a new session with initial per-client data.
BufferReadAccess: Read-only buffer access for bridge tick functions.
ClientContext: Borrowed per-client state bundle for session operations.
ClientId: Unique client connection identifier.
CursorPosition: Cursor position within a window.
CursorSnapshot: Per-client cursor position snapshot for bridge tick consumption.
EmptySessionContext: Context provided to empty session handlers.
ExtensionMap: Type-erased extension storage using TypeId.
InitialModeProvider: Provider for the initial editor mode.
KeySequence: Pending key sequence.
LeaderKeyProvider: Provider for the leader key notation.
ModeError: Error from mode lifecycle hooks.
NotificationDrainRegistry: Registry for notification drain implementations.
OperatorPendingState: Session extension for operator-pending state.
PendingEntry: A pending notification entry with optional source attribution.
PendingNotification: A pending notification to be flushed to display state.
PendingNotificationQueue: Thread-safe queue for notifications from background threads.
RegisterContent: Content stored in a register.
Session: Driver-layer session containing shared infrastructure.
SessionRuntime: Runtime that implements all session API traits.
SessionShared: Shared session infrastructure.
SnippetExpanderRegistry: Registry for snippet expander implementations.
TextObjRange: Range computed by a text object command.
TransitionContext: Context passed when entering a new mode.
Viewport: Viewport for a client session.
Window: Window within a session.
WindowLayout: Window layout for a session.

Enums§

EmptySessionAction: Action to take when session is empty.
PendingLevel: Notification level for pending notifications.
PendingOp: Operation type for the pending notification queue.
PopResult: Result returned when popping from a mode.
SessionHandlerKey: Typed key for session handler lookup.
YankType: Type of yank operation.

Traits§

EmptySessionHandler: Handler for empty session state.
NotificationDrain: Trait for draining pending notifications into session state.
SessionExtension: Trait for module-provided per-session state.
SessionExtensionDyn: Object-safe trait for runtime access to session extensions.
SessionMode: Mode with lifecycle hooks.
SnippetExpander: Trait for expanding snippet bodies during completion confirm.
TextInputSink: Trait for extensions that can receive text input.

Functions§

expand_leader: Expand all <leader> tokens in a key string with the given notation.

Type Aliases§

SessionHandlerRegistry: Registry for session handlers, keyed by purpose.