Struct Client 

pub struct Client {
    pub id: ClientId,
    pub relation: Option<ClientRelation>,
    pub state: EditingState,
    pub metadata: ClientMetadata,
    pub ring_buffer: ClientRingBuffer,
}

A client in a session.

All clients have EditingState for local viewport, smooth transitions, and pending keys buffer. The relation field controls input routing.

Property Invariants

1. relation = None implies client is independent (input → self)
2. relation = Some(Following{target}) implies input is ignored
3. relation = Some(Sharing{with}) implies input routes to with
4. All clients ALWAYS have state: EditingState (non-optional)
5. No cycles allowed: if A → B, then B cannot → A (directly or transitively)

Fields

id: ClientId

Unique client identifier.

relation: Option<ClientRelation>

Relation to another client. None = independent.

state: EditingState

Editing state (mode, cursor, windows, etc.). ALWAYS present.

metadata: ClientMetadata

Client metadata (type, display name, join time).

ring_buffer: ClientRingBuffer

Per-client debug ring buffer (Phase #478/#481).

Implementations

impl Client

pub fn new(id: ClientId, metadata: ClientMetadata) -> Self

Create a new independent client with default editing state.

pub fn with_mode_stack( id: ClientId, metadata: ClientMetadata, mode_stack: ModeStack, ) -> Self

Create client with specific mode stack.

pub fn with_mode_stack_and_window( id: ClientId, metadata: ClientMetadata, mode_stack: ModeStack, window: Window, ) -> Self

Create client with mode stack and initial window.

pub const fn ring_buffer(&self) -> &ClientRingBuffer

Get the ring buffer for this client.

pub const fn is_independent(&self) -> bool

Check if client is independent (no relation).

pub const fn is_following(&self) -> bool

Check if client is following another.

pub const fn is_sharing(&self) -> bool

Check if client is sharing with another.

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

Get the target client ID (for Following/Sharing), or None if independent.

pub fn validate_relation_change( client: &Self, new_relation: Option<ClientRelation>, clients: &HashMap<ClientId, Self>, ) -> TransitionResult

Validate a relation change without applying it.

This is a static method that checks if a relation change is valid without mutating the client. Used by Session::set_client_relation().

Validation Rules

1. Cannot target self (returns CannotTargetSelf)
2. Target must exist (returns TargetNotFound)
3. Cannot create cycles (returns WouldCreateCycle)
4. Following → Sharing with same target may require cursor sync

pub fn try_set_relation( &mut self, new_relation: Option<ClientRelation>, clients: &HashMap<ClientId, Self>, ) -> TransitionResult

Attempt to change relation with validation.

Returns TransitionResult indicating success or required preconditions.

Validation Rules

1. Cannot target self (returns CannotTargetSelf)
2. Target must exist (returns TargetNotFound)
3. Cannot create cycles (returns WouldCreateCycle)
4. Following → Sharing with same target may require cursor sync

Examples

// Independent to Following
let result = client.try_set_relation(
    Some(ClientRelation::Following { target: other_id }),
    &clients,
);
assert!(result.is_ok());

// Back to independent
let result = client.try_set_relation(None, &clients);
assert!(result.is_ok());

pub fn sync_cursor_to(&mut self, target: &Self)

Sync cursor to target client’s position.

Used for Following → Sharing transitions that require cursor alignment.

pub const fn set_relation_unchecked(&mut self, relation: Option<ClientRelation>)

Force set relation without validation.

Use sparingly - prefer try_set_relation() for safety. This is useful for initialization or internal operations where validation has already been performed.

pub fn effective_state<'a>( &'a self, clients: &'a HashMap<ClientId, Self>, ) -> Option<&'a EditingState>

Get the effective state for display.

• Independent: own state
• Following: target’s state (with depth limit)
• Sharing: target’s state (with depth limit)

Returns None if the target/chain doesn’t exist or if there’s a cycle.

pub fn effective_state_mut<'a>( &'a self, clients: &'a mut HashMap<ClientId, Self>, ) -> Option<&'a mut EditingState>

Get mutable reference to the effective state for input routing.

• Independent: Returns None (caller should use self.state directly)
• Following: Returns None (input is ignored)
• Sharing: Returns target’s state (recursively)

Note: For independent clients, the caller must handle self.state specially due to Rust borrow rules (can’t borrow self and return reference to self.state).

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.