Skip to content

Host & Viewer

ShareManager

codemol/app/share_manager.py manages the client side of shared sessions. It connects to the relay server and handles both hosting and viewing.

Hosting a Session

/share create       # Start hosting

Flow:

  1. ShareManager connects to relay server via WebSocket
  2. Sends create message → receives room code
  3. Displays code in console: "Session created: ABC123"
  4. From this point, every command the host executes is broadcast to viewers

Command Broadcasting

After _handle_command() processes a command, ShareManager intercepts and broadcasts:

# In ShareManager
def broadcast_command(self, command_text: str):
    """Send command to all viewers via relay."""
    self._ws.send(json.dumps({
        "type": "command",
        "data": command_text
    }))

Structure Activation Broadcasting

When the host switches active structures, an activate message is sent so viewers see the same structure:

def broadcast_activate(self, structure_name: str):
    self._ws.send(json.dumps({
        "type": "activate",
        "data": structure_name
    }))

Joining a Session

/share join ABC123   # Join with room code

Flow:

  1. ShareManager connects to relay server
  2. Sends join message with code
  3. Requests history replay → receives list of past commands
  4. Replays commands sequentially to catch up with host's state
  5. Starts receiving live commands

History Replay

When a viewer joins mid-session, they need to see everything the host has done:

sequenceDiagram
    participant Viewer
    participant Server
    participant Host

    Viewer->>Server: join + history_request
    Server->>Host: history_request
    Host-->>Server: history (all commands since session start)
    Server-->>Viewer: history
    Viewer->>Viewer: Replay each command sequentially
    Note over Viewer: Now caught up — live commands arrive

View Sync

Viewers receive commands and execute them locally:

def _on_message(self, message):
    data = json.loads(message)
    if data["type"] == "command":
        self._ctx.handle_command(data["data"])
    elif data["type"] == "activate":
        self._ctx.session.activate(data["data"], cmd)

Session Management Commands

Command Description
/share create Start hosting a session
/share join CODE Join an existing session
/share status Show current session state
/share list List connected viewers
/share stop End the session
/share tutorial Interactive tutorial

Architecture Summary

graph LR
    subgraph Host Machine
        H[MolbotWindow] --> SM1[ShareManager]
    end

    SM1 -->|WebSocket| RS[Relay Server]

    subgraph Viewer Machine
        SM2[ShareManager] --> V[MolbotWindow]
    end

    RS -->|WebSocket| SM2