Research: WebAssembly (Wasm) Build Support

[kshivang]

Overview

Investigate feasibility of building BossTerm for WebAssembly (Wasm) target.

Current State

• All code is JVM-specific (desktopMain/jvmMain)
• No commonMain source sets exist
• Heavy dependencies on JVM-only libraries (pty4j, AWT, java.io)

Blockers

Critical (Cannot be resolved in Wasm)

• PTY/process spawning - Wasm sandbox prevents local shell access
• Compose Desktop - No Wasm rendering equivalent

Major (Requires significant refactoring)

• java.io dependencies throughout codebase
• ScheduledExecutorService for threading
• Blocking I/O patterns incompatible with JS async model
• ICU4J for grapheme clustering

Proposed Approach

Rather than a full Wasm port, extract terminal emulation core as a reusable library:

1. Phase 1: Create commonMain structure

   • Extract platform-agnostic terminal logic
   • Abstract I/O behind interfaces (expect/actual)

2. Phase 2: Wasm terminal library

   • BossEmulator, TerminalLine, ANSI parsing
   • Buffer management, text styling
   • Result: bossterm-core-wasm library

3. Phase 3: Web terminal client (optional)

   • Pair with xterm.js for rendering
   • WebSocket connection to SSH server
   • No local PTY (server-side only)

Use Cases for Wasm Library

• Embedded terminal widgets in web apps
• Browser-based SSH clients
• Online IDE terminal panels
• Documentation with interactive examples

Effort Estimate

• Phase 1: 2-4 weeks
• Phase 2: 8-12 weeks
• Phase 3: 4-6 weeks (optional)

Related

• Kotlin/Wasm: https://kotlinlang.org/docs/wasm-overview.html
• Compose for Web: https://www.jetbrains.com/lp/compose-multiplatform/

[kshivang]

@claude why local side pty is not possible, if possible is their any js library that can enable it

[claude]

Claude finished @kshivang's task in 1m 0s —— View job

---

PTY Support in WebAssembly - Technical Explanation

• Understand PTY requirements and browser security model
• Research existing JS/Wasm terminal solutions
• Investigate WASI and alternative approaches
• Provide comprehensive technical answer

---

Why Local PTY is Not Possible in Browser Wasm

Short Answer: Browser Wasm cannot create local PTYs due to fundamental security constraints. The browser sandbox intentionally prevents direct process spawning and OS-level resource access.

Technical Breakdown

1. What PTY Requires

A pseudo-terminal (PTY) needs:

• Process spawning: Fork/exec a shell process (bash, zsh, etc.)
• File descriptor manipulation: Create master/slave PTY pairs (/dev/ptmx, /dev/pts/N)
• Signal handling: Send SIGWINCH, SIGTERM, etc. to child processes
• Direct kernel syscalls: ioctl() for terminal control

2. Browser Security Model Prevents This

• No process spawning: spawn(), fork(), exec() don't exist in browsers
• No file system access: Cannot access /dev/ptmx or create PTY devices
• No syscalls: Wasm in browsers has no access to OS syscalls
• Sandboxed execution: All code runs in isolated sandbox with limited APIs

3. Existing JS Terminal Libraries - How They Work

xterm.js (most popular):

Browser (xterm.js) <--WebSocket--> Server (node-pty)
     ^                                    |
     |                                    v
  Rendering only                    Real PTY + Shell

• Frontend: Pure rendering (xterm.js handles display, input capture)
• Backend: Node.js server with node-pty creates real PTY
• Connection: WebSocket relays data bidirectionally

Other Libraries:

• hterm (Chrome): Same architecture - rendering only
• Terminal.js: Frontend rendering library
• ttyd: WebSocket proxy to local terminal

None of them run shells locally in the browser.

4. WASI - A Partial Solution (But Not for PTY)

WASI (WebAssembly System Interface) provides:

• File system access (virtualized)
• Environment variables
• Command-line arguments
• Networking (in some runtimes)

What WASI Still Cannot Do:

• ❌ Spawn real OS processes
• ❌ Create PTY devices
• ❌ Access /dev/ptmx
• ❌ Fork processes

WASI is designed for server-side Wasm (Wasmtime, WasmEdge), not browsers. Even with WASI, you'd need a backend server to actually run shells.

Possible Approaches for BossTerm Wasm

Option 1: Backend-Dependent Architecture (Realistic)

BossTerm-Wasm (browser) <--WebSocket--> BossTerm-Server (JVM/native)
        ^                                         |
        |                                         v
   Terminal emulation                      pty4j + real shell
   + Rendering

Pros:

• Reuses existing emulation logic
• Secure (shell runs on trusted server)
• Standard approach (same as VS Code Remote)

Cons:

• Requires backend infrastructure
• Not "local" terminal experience

Option 2: Emscripten Shell (Limited Demo)

Compile a simple shell (like busybox) to Wasm using Emscripten:

• Runs entirely in browser
• No real OS access (virtualized FS only)
• Extremely limited - toy example at best
• Not a real terminal - cannot run native programs

Example: WebAssembly.sh uses this approach

Option 3: Browser Extension (Chrome/Firefox)

Browser extensions have native messaging APIs:

• Can communicate with native helper process
• Helper creates real PTY
• Still requires local native installation

Not portable Wasm - defeats the purpose.

Recommendation for Issue #141

For BossTerm:

1. Phase 1-2 (as described in issue) are still valuable:

   • Extract terminal emulation core as bossterm-core-wasm
   • Provide Wasm library for rendering + ANSI parsing

2. Use Case: Frontend for remote terminals

   • Pair with WebSocket backend (user-provided)
   • Similar to xterm.js but with BossTerm's features
   • Example: SSH web client, cloud IDE terminal

3. Document Clearly:

   • BossTerm-Wasm is a terminal emulator library, not a standalone terminal
   • Requires backend for actual shell execution
   • Cannot replace desktop BossTerm for local use

JS Libraries Summary

Library	Purpose	Local PTY?	Approach
xterm.js	Terminal frontend	❌	WebSocket to backend
node-pty	PTY library	✅ (Node.js only)	Native addon, not browser
hterm	Terminal frontend	❌	WebSocket to backend
ttyd	Terminal proxy	❌	WebSocket to local terminal

Bottom Line: No JS library enables local PTY in browsers. All require a backend server.

---

[kshivang]

@claude I like option 1 make detailed plan for that

[claude]

Claude finished @kshivang's task in 5m 59s —— View job

---

Detailed Plan for Option 1: Backend-Dependent Architecture

Option 1 Overview: Split BossTerm into a Wasm-based terminal emulator frontend (runs in browser) that connects to a backend server (JVM/native) for actual PTY/shell execution. Similar to VS Code Remote, xterm.js + node-pty, or cloud IDE terminals.

---

Architecture Design

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Browser (Wasm)                         │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         BossTerm Wasm Frontend                        │  │
│  │  - Terminal emulation (ANSI parsing, buffer mgmt)    │  │
│  │  - Compose HTML rendering                            │  │
│  │  - User input capture                                │  │
│  │  - WebSocket client                                  │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────────────┘
                       │ WebSocket (bidirectional)
                       │ Protocol: JSON-RPC or msgpack
                       │
┌──────────────────────┴──────────────────────────────────────┐
│                  Backend Server (JVM/Native)                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         BossTerm Backend Service                      │  │
│  │  - WebSocket server (Ktor)                           │  │
│  │  - PTY management (pty4j)                            │  │
│  │  - Shell lifecycle                                   │  │
│  │  - Session management                                │  │
│  │  - Authentication/Authorization                      │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                   │
│                          ▼                                   │
│                   Real Shell Process                         │
│                   (bash, zsh, etc.)                          │
└─────────────────────────────────────────────────────────────┘

---

Module Structure

Phase 1: Refactor Core into CommonMain (8-10 weeks)

Goal: Extract platform-agnostic terminal emulation logic into commonMain, abstract platform-specific operations.

New Module Structure

bossterm-core-mpp/
├── src/
│   ├── commonMain/kotlin/          # NEW - Platform-agnostic core
│   │   ├── ai/rever/bossterm/
│   │   │   ├── terminal/
│   │   │   │   ├── model/
│   │   │   │   │   ├── TerminalTextBuffer.kt      # Pure buffer logic
│   │   │   │   │   ├── TerminalLine.kt            # Line data structure
│   │   │   │   │   ├── CharBuffer.kt              # Char array handling
│   │   │   │   │   ├── StyleState.kt              # Text styling
│   │   │   │   │   ├── CursorShape.kt             # Cursor types
│   │   │   │   │   └── BossTerminal.kt (abstracted) # Core terminal state
│   │   │   │   ├── emulator/
│   │   │   │   │   ├── BossEmulator.kt (abstracted) # ANSI parsing
│   │   │   │   │   ├── charset/                   # Character set handling
│   │   │   │   │   └── mouse/                     # Mouse protocol parsing
│   │   │   │   └── util/
│   │   │   │       ├── CharUtils.kt (abstracted)  # String/char utilities
│   │   │   │       └── Ascii.kt                   # ASCII constants
│   │   │   └── core/
│   │   │       ├── TerminalDataStream.kt          # Abstract I/O interface
│   │   │       └── PlatformExecutor.kt            # Abstract threading
│   │
│   ├── jvmMain/kotlin/             # JVM-specific implementations
│   │   ├── ai/rever/bossterm/
│   │   │   ├── terminal/
│   │   │   │   └── model/
│   │   │   │       ├── TerminalTextBuffer.kt (impl) # Uses java.util.concurrent
│   │   │   │       └── pool/                      # Object pooling (JVM-optimized)
│   │   │   └── core/
│   │   │       ├── JvmTerminalDataStream.kt       # java.io implementation
│   │   │       └── JvmExecutorService.kt          # ScheduledExecutorService wrapper
│   │
│   ├── wasmJsMain/kotlin/          # NEW - Wasm implementations
│   │   ├── ai/rever/bossterm/
│   │   │   ├── terminal/
│   │   │   │   └── model/
│   │   │   │       └── TerminalTextBuffer.kt (impl) # Uses JS Promise/async
│   │   │   └── core/
│   │   │       ├── WasmTerminalDataStream.kt      # JS streams
│   │   │       └── WasmExecutor.kt                # JS setTimeout/setInterval
│   │
│   └── commonTest/kotlin/          # Shared tests

Abstraction Strategy (expect/actual pattern)

Example 1: Threading/Scheduling

// commonMain/kotlin/core/PlatformExecutor.kt
expect class PlatformExecutor() {
    fun schedule(delayMs: Long, action: () -> Unit): CancellableTask
    fun scheduleRepeating(intervalMs: Long, action: () -> Unit): CancellableTask
}

expect class CancellableTask {
    fun cancel()
}

// jvmMain/kotlin/core/JvmExecutorService.kt
import java.util.concurrent.ScheduledExecutorService
import java.util.concurrent.ScheduledFuture

actual class PlatformExecutor {
    private val executor: ScheduledExecutorService = ...
    
    actual fun schedule(delayMs: Long, action: () -> Unit): CancellableTask {
        val future = executor.schedule({ action() }, delayMs, TimeUnit.MILLISECONDS)
        return JvmCancellableTask(future)
    }
}

actual class CancellableTask(private val future: ScheduledFuture<*>) {
    actual fun cancel() { future.cancel(false) }
}

// wasmJsMain/kotlin/core/WasmExecutor.kt
import kotlin.js.setTimeout

actual class PlatformExecutor {
    actual fun schedule(delayMs: Long, action: () -> Unit): CancellableTask {
        val handle = setTimeout(action, delayMs.toInt())
        return JsCancellableTask(handle)
    }
}

actual class CancellableTask(private val handle: Int) {
    actual fun cancel() { clearTimeout(handle) }
}

Example 2: I/O Streams

// commonMain/kotlin/core/TerminalDataStream.kt
interface TerminalDataStream {
    suspend fun read(buffer: ByteArray): Int
    suspend fun write(data: ByteArray)
    fun close()
}

// jvmMain - uses java.io.InputStream/OutputStream
// wasmJsMain - uses WebSocket or fetch API

Example 3: Grapheme Clustering (ICU4J)

// commonMain/kotlin/util/GraphemeUtils.kt
expect object GraphemeUtils {
    fun segmentIntoGraphemes(text: String): List<GraphemeCluster>
    fun getGraphemeWidth(cluster: GraphemeCluster): Int
}

// jvmMain - uses ICU4J BreakIterator
// wasmJsMain - uses JS Intl.Segmenter API (modern browsers)
//              or fallback to simple codepoint iteration

Critical Refactoring Tasks (Phase 1)

1. Audit Dependencies (1 week)

   • Scan all 109 .kt files in bossterm-core-mpp for JVM-specific imports
   • Create dependency matrix: file → JVM APIs used
   • Categorize: Must abstract vs Can keep in jvmMain

2. Create CommonMain Structure (2 weeks)

   • Extract pure data structures (TerminalLine, CharBuffer, StyleState)
   • Move ANSI parsing logic (BossEmulator) to commonMain
   • Create expect/actual declarations for platform APIs

3. Implement JVM Actuals (1 week)

   • Move existing JVM code to jvmMain actuals
   • Ensure 100% test coverage still passes

4. Remove java.io Dependencies (2 weeks)

   • Replace InputStream/OutputStream with suspend functions
   • Replace ScheduledExecutorService with PlatformExecutor
   • Replace java.util.concurrent.locks with kotlinx.coroutines Mutex

5. Handle ICU4J (1 week)

   • Abstract grapheme clustering APIs
   • Implement Wasm fallback (Intl.Segmenter or simple fallback)

6. Testing (1 week)

   • Run existing test suite on JVM target
   • Add commonTest for shared logic
   • Verify no regressions

---

Phase 2: Create Wasm Frontend Module (10-12 weeks)

Goal: Build browser-based terminal emulator using Compose HTML and Kotlin/Wasm.

New Module: bossterm-wasm-frontend

bossterm-wasm-frontend/
├── build.gradle.kts                # Kotlin/Wasm + Compose HTML
├── src/
│   ├── wasmJsMain/kotlin/
│   │   ├── ai/rever/bossterm/wasm/
│   │   │   ├── ui/
│   │   │   │   ├── TerminalCanvas.kt       # HTML Canvas rendering
│   │   │   │   ├── InputHandler.kt         # Keyboard/mouse capture
│   │   │   │   └── TerminalComponent.kt    # Main composable
│   │   │   ├── network/
│   │   │   │   ├── WebSocketClient.kt      # Backend connection
│   │   │   │   └── Protocol.kt             # Message serialization
│   │   │   └── WasmTerminalApp.kt          # Entry point
│   │   └── resources/
│   │       ├── index.html
│   │       └── fonts/                      # Embedded web fonts
│   └── wasmJsTest/kotlin/

Technology Stack (Frontend)

Component	Technology	Rationale
Language	Kotlin 2.1+	Wasm support, shared code with backend
UI Framework	Compose HTML (experimental)	Familiar Compose API, or fallback to kotlinx.html
Rendering	HTML Canvas API	High-performance text rendering
Networking	Ktor Client (JS)	WebSocket support, Kotlin-first
Serialization	kotlinx.serialization (JSON)	Efficient, type-safe
Build	Gradle + Kotlin/Wasm plugin	Official toolchain

Rendering Approach

Option A: HTML Canvas (Recommended)

• Draw terminal cells directly to <canvas>
• Full control over rendering (like current Compose Desktop)
• Supports custom fonts (via Canvas text API)
• Example: xterm.js canvas renderer

Option B: DOM-based (Fallback)

• Render cells as <div> or <span> elements
• Simpler, but performance issues with large buffers
• Used by early xterm.js versions

Compose HTML Integration:

@Composable
fun TerminalCanvas(
    terminalState: TerminalState,
    modifier: Modifier = Modifier
) {
    Canvas(attrs = {
        style {
            width(100.percent)
            height(100.percent)
        }
        onKeyDown { event -> /* Handle keyboard */ }
        onMouseDown { event -> /* Handle mouse */ }
    }) {
        // Use Canvas 2D API to draw terminal content
        val ctx = (it.target as HTMLCanvasElement).getContext("2d") as CanvasRenderingContext2D
        
        // Similar to ProperTerminal.kt rendering loop
        for (row in 0 until terminalState.height) {
            val line = terminalState.getLine(row)
            // Draw background, then text...
        }
    }
}

Input Handling

// Capture keyboard input and send to backend
fun handleKeyEvent(event: KeyboardEvent) {
    val terminalKey = when {
        event.key == "Enter" -> "\r"
        event.key == "Backspace" -> "\u007F"
        event.ctrlKey && event.key == "c" -> "\u0003"
        // ... map all keys to terminal sequences
        else -> event.key
    }
    
    websocket.send(TerminalInputMessage(terminalKey))
}

WebSocket Protocol Design

Message Types:

// Frontend → Backend
@Serializable
sealed class ClientMessage {
    @Serializable
    data class Input(val data: String) : ClientMessage()  // User typing
    
    @Serializable
    data class Resize(val cols: Int, val rows: Int) : ClientMessage()  // Window resize
    
    @Serializable
    data class Authenticate(val token: String) : ClientMessage()  // Auth
}

// Backend → Frontend
@Serializable
sealed class ServerMessage {
    @Serializable
    data class Output(val data: String) : ServerMessage()  // Shell output (raw ANSI)
    
    @Serializable
    data class Resize(val cols: Int, val rows: Int) : ServerMessage()  // Server-side resize
    
    @Serializable
    data class Exit(val code: Int) : ServerMessage()  // Shell exited
    
    @Serializable
    data class Error(val message: String) : ServerMessage()  // Error
}

WebSocket Client:

class TerminalWebSocketClient(private val url: String) {
    private val websocket: WebSocket = WebSocket(url)
    private val _messages = MutableSharedFlow<ServerMessage>()
    val messages: SharedFlow<ServerMessage> = _messages.asSharedFlow()
    
    init {
        websocket.onmessage = { event ->
            val message = Json.decodeFromString<ServerMessage>(event.data as String)
            _messages.emit(message)
        }
    }
    
    suspend fun send(message: ClientMessage) {
        val json = Json.encodeToString(message)
        websocket.send(json)
    }
}

Critical Implementation Tasks (Phase 2)

1. Setup Kotlin/Wasm Build (1 week)

   • Configure build.gradle.kts with kotlin("wasm-js") target
   • Add Compose HTML dependencies
   • Setup webpack/dev server for testing

2. Implement Canvas Renderer (3 weeks)

   • Port ProperTerminal.kt rendering logic to HTML Canvas
   • Handle font loading (web fonts)
   • Implement text measurement and positioning
   • Add cursor rendering

3. Input Handling (2 weeks)

   • Keyboard event capture and mapping
   • Mouse event handling (selection, scrolling)
   • IME support (for CJK input)

4. WebSocket Client (1 week)

   • Ktor Client setup with JS engine
   • Message serialization/deserialization
   • Reconnection logic

5. Terminal State Management (2 weeks)

   • Integrate bossterm-core-mpp (commonMain)
   • BossEmulator instance for ANSI parsing
   • Buffer updates from server messages

6. UI Features (2 weeks)

   • Search bar (port existing search UI)
   • Context menu
   • Settings panel
   • Clipboard integration (browser APIs)

7. Testing (1 week)

   • Unit tests for Wasm target
   • Browser-based integration tests

---

Phase 3: Create Backend Server Module (6-8 weeks)

Goal: Build JVM/native server that handles PTY, shell lifecycle, and WebSocket communication.

New Module: bossterm-backend-server

bossterm-backend-server/
├── build.gradle.kts                # JVM target, Ktor server
├── src/
│   ├── jvmMain/kotlin/
│   │   ├── ai/rever/bossterm/backend/
│   │   │   ├── server/
│   │   │   │   ├── TerminalServer.kt       # Ktor application
│   │   │   │   ├── WebSocketHandler.kt     # WS endpoint
│   │   │   │   └── AuthMiddleware.kt       # Security
│   │   │   ├── session/
│   │   │   │   ├── TerminalSession.kt      # Per-connection state
│   │   │   │   ├── SessionManager.kt       # Multi-session handling
│   │   │   │   └── PtyProcess.kt           # pty4j wrapper
│   │   │   └── config/
│   │   │       └── ServerConfig.kt         # Settings
│   │   └── Main.kt                         # Entry point
│   └── jvmTest/kotlin/

Technology Stack (Backend)

Component	Technology	Rationale
Server Framework	Ktor Server	Kotlin-first, WebSocket support, lightweight
PTY Library	pty4j	Existing dependency, cross-platform
Serialization	kotlinx.serialization	Matches frontend
Concurrency	Coroutines	Kotlin async/await
Authentication	JWT or sessions	Secure multi-user support
Deployment	Docker + JVM 17+	Portable, easy deployment

Server Architecture

// Main server setup
fun main() {
    embeddedServer(Netty, port = 8080) {
        install(WebSockets)
        install(Authentication) {
            jwt { /* ... */ }
        }
        
        routing {
            authenticate {
                webSocket("/terminal") {
                    val session = TerminalSession(this)
                    session.start()
                }
            }
        }
    }.start(wait = true)
}

TerminalSession Implementation

class TerminalSession(private val websocket: DefaultWebSocketServerSession) {
    private val ptyProcess: PtyProcess = PtyProcess.create("/bin/bash")  // or $SHELL
    private val emulator: BossEmulator = BossEmulator(...)  // Not needed on backend!
    
    suspend fun start() {
        // Launch two coroutines:
        
        // 1. Read from PTY, send to frontend
        launch {
            ptyProcess.outputStream.reader().use { reader ->
                val buffer = CharArray(4096)
                while (true) {
                    val n = reader.read(buffer)
                    if (n <= 0) break
                    
                    val output = String(buffer, 0, n)
                    websocket.send(Json.encodeToString(ServerMessage.Output(output)))
                }
            }
            websocket.send(Json.encodeToString(ServerMessage.Exit(ptyProcess.exitCode)))
        }
        
        // 2. Receive from frontend, write to PTY
        for (frame in websocket.incoming) {
            if (frame is Frame.Text) {
                val message = Json.decodeFromString<ClientMessage>(frame.readText())
                when (message) {
                    is ClientMessage.Input -> {
                        ptyProcess.inputStream.write(message.data.toByteArray())
                        ptyProcess.inputStream.flush()
                    }
                    is ClientMessage.Resize -> {
                        ptyProcess.setWindowSize(message.cols, message.rows)
                    }
                }
            }
        }
    }
}

Key Insight: Backend does NOT need BossEmulator! It just forwards raw PTY output to frontend. Frontend handles ANSI parsing.

PTY Process Wrapper

class PtyProcess(private val process: Process, private val pty: PtyProcessTtyConnector) {
    val inputStream: OutputStream get() = process.outputStream
    val outputStream: InputStream get() = process.inputStream
    val exitCode: Int get() = process.waitFor()
    
    fun setWindowSize(cols: Int, rows: Int) {
        pty.resize(Dimension(cols, rows))
    }
    
    companion object {
        fun create(shell: String, env: Map<String, String> = emptyMap()): PtyProcess {
            val ptyProcess = PtyProcessBuilder()
                .setCommand(arrayOf(shell))
                .setEnvironment(env)
                .start()
            return PtyProcess(ptyProcess.process, ptyProcess)
        }
    }
}

Session Management (Multi-User)

class SessionManager {
    private val sessions = ConcurrentHashMap<String, TerminalSession>()
    
    fun createSession(userId: String): TerminalSession {
        val session = TerminalSession(...)
        sessions[userId] = session
        return session
    }
    
    fun getSession(userId: String): TerminalSession? = sessions[userId]
    
    fun closeSession(userId: String) {
        sessions.remove(userId)?.close()
    }
}

Critical Implementation Tasks (Phase 3)

1. Ktor Server Setup (1 week)

   • Configure Ktor with WebSockets plugin
   • Setup authentication (JWT)
   • CORS configuration for browser access

2. PTY Management (2 weeks)

   • Wrap pty4j for session lifecycle
   • Handle shell spawning (bash, zsh, configurable)
   • Window resize handling
   • Graceful shutdown

3. WebSocket Handler (1 week)

   • Implement bidirectional message handling
   • Error handling and reconnection
   • Protocol implementation (matches frontend)

4. Session Management (1 week)

   • Multi-session support
   • Session persistence (optional, for reconnect)
   • Resource cleanup

5. Authentication & Security (1 week)

   • JWT token validation
   • User isolation (prevent cross-session access)
   • Rate limiting

6. Configuration (1 week)

   • Server settings (port, shell, env vars)
   • Logging setup
   • Docker packaging

7. Testing (1 week)

   • Unit tests for session management
   • Integration tests with mock WebSocket client
   • Load testing (simulate 100+ concurrent sessions)

---

Technology Stack Summary

Frontend (Wasm)

• Kotlin 2.1+ with Wasm target
• Compose HTML (or kotlinx.html fallback)
• Ktor Client (JS engine) for WebSocket
• kotlinx.serialization for messages
• HTML Canvas API for rendering
• Browser APIs: Clipboard, Intl.Segmenter

Backend (JVM)

• Kotlin 2.1+ with JVM target
• Ktor Server (Netty engine)
• pty4j for PTY/shell management
• kotlinx.coroutines for async I/O
• kotlinx.serialization for messages
• JWT for authentication
• Docker for deployment

Shared (Core)

• bossterm-core-mpp (commonMain)
• ANSI parsing (BossEmulator)
• Buffer management (TerminalTextBuffer)
• Terminal state (BossTerminal)
• Protocols (mouse, keyboard, OSC sequences)

---

Migration Strategy

From Current JVM-Only to Wasm + Backend

Stage 1: Parallel Development (Phases 1-3 above)

• Keep existing desktop app working
• Build new Wasm + backend stack in separate modules
• No breaking changes to existing API

Stage 2: Alpha Release

• Deploy backend server (Docker image)
• Host Wasm frontend (static site)
• Invite early testers
• Collect feedback on latency, UX

Stage 3: Production Hardening

• Performance optimization (reduce latency)
• Security audit
• Add monitoring/logging
• Documentation

Stage 4: Maintenance

• Keep both desktop and web versions
• Share core emulation logic (commonMain)
• Platform-specific features as needed

---

Deployment Architecture

Backend Deployment Options

Option A: Single-Server (Simple)

User's Browser → Backend Server (same machine/VM)
                 - Ktor + PTY
                 - Serves Wasm frontend as static files

Option B: Multi-Tenant Cloud (Scalable)

User's Browser → Load Balancer → Backend Cluster (Kubernetes)
                                  - Multiple Ktor instances
                                  - Session affinity (sticky sessions)
                                  - Shared auth service (JWT)

Option C: Embedded (Library Use Case)

Web App (React/Vue) → BossTerm Wasm Component (embedded)
                       ↓
                     Custom Backend (user-provided)

Example: Docker Compose Setup

version: '3.8'
services:
  backend:
    image: bossterm-backend:latest
    ports:
      - "8080:8080"
    environment:
      - SHELL=/bin/bash
      - JWT_SECRET=${JWT_SECRET}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # For Docker-in-Docker
  
  frontend:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./frontend-dist:/usr/share/nginx/html  # Wasm artifacts

---

Testing Strategy

Unit Tests

• Core (commonTest): ANSI parsing, buffer operations
• Frontend (wasmJsTest): Input handling, WebSocket client
• Backend (jvmTest): Session management, PTY lifecycle

Integration Tests

• End-to-End: Browser (Playwright) → Backend → PTY
• Load Testing: Simulate 100+ concurrent sessions (K6 or Gatling)
• Latency Testing: Measure roundtrip time (input → output)

Compatibility Tests

• Browsers: Chrome, Firefox, Safari, Edge
• Shells: bash, zsh, fish, sh
• Platforms: Linux, macOS, Windows (backend)

---

Performance Considerations

Frontend (Wasm)

• Rendering: Target 60fps (16ms frame budget)
• Memory: Limit buffer size (e.g., 10K lines scrollback)
• Network: Compress WebSocket messages (gzip or brotli)

Backend

• Latency: <20ms P95 for input → output
• Throughput: Handle 500+ concurrent sessions per server
• Resource Limits: CPU/memory isolation per session (cgroups)

Network Protocol Optimization

• Binary Protocol: Consider msgpack instead of JSON (smaller payload)
• Batching: Send multiple output chunks in single WebSocket frame
• Compression: Enable permessage-deflate WebSocket extension

---

Security Considerations

Authentication

• JWT tokens with expiration
• HTTPS only (TLS 1.3)
• CORS properly configured

Isolation

• Per-user sessions: No cross-session access
• Resource limits: Prevent runaway processes (ulimit)
• Sandboxing: Consider Docker/containerization per session

Input Validation

• Sanitize inputs: Prevent command injection
• Rate limiting: Prevent DoS attacks
• Audit logging: Track user actions

---

Estimated Timeline

Phase	Tasks	Duration	Deliverable
Phase 1	Refactor to commonMain	8-10 weeks	bossterm-core-mpp with commonMain/jvmMain/wasmJsMain
Phase 2	Wasm frontend	10-12 weeks	bossterm-wasm-frontend (browser terminal)
Phase 3	Backend server	6-8 weeks	bossterm-backend-server (Ktor + pty4j)
Phase 4	Integration & testing	4-6 weeks	End-to-end working system
Phase 5	Production hardening	4-6 weeks	Security audit, performance tuning, docs

Total: 32-42 weeks (~8-10 months)

---

Success Metrics

Technical

• ✅ Core emulation logic runs on both JVM and Wasm
• ✅ <20ms P95 latency for user input → shell output
• ✅ 60fps rendering in browser
• ✅ Support 500+ concurrent sessions per server

User Experience

• ✅ Feature parity with desktop app (search, selection, clipboard, mouse)
• ✅ Works on all major browsers (Chrome, Firefox, Safari, Edge)
• ✅ Mobile-responsive (touch input on tablets)

Developer Experience

• ✅ Clear API for embedding Wasm terminal in web apps
• ✅ Comprehensive documentation
• ✅ Example projects (React integration, Vue integration)

---

Risks & Mitigations

Risk	Impact	Mitigation
Kotlin/Wasm instability	High	Use stable Kotlin version (2.1+), fallback to JS target
Compose HTML limitations	Medium	Fallback to kotlinx.html + Canvas API directly
ICU4J unavailable on Wasm	Medium	Use JS Intl.Segmenter or simple codepoint iteration
Network latency	High	Optimize protocol, add local echo, type-ahead prediction
Browser compatibility	Medium	Polyfills for older browsers, progressive enhancement
Security vulnerabilities	High	Security audit, penetration testing, rate limiting

---

Next Steps

1. Validate Assumptions

   • Prototype Kotlin/Wasm Canvas rendering (1 week spike)
   • Test Ktor WebSocket performance (concurrent sessions)
   • Measure latency in realistic network conditions

2. Create Proof of Concept (4 weeks)

   • Minimal Wasm frontend (hardcoded buffer, no backend)
   • Minimal backend (echo server, no PTY)
   • WebSocket connection between them
   • Demonstrate end-to-end flow

3. Get Stakeholder Buy-In

   • Present this plan to team/community
   • Gather feedback on priorities
   • Decide on timeline and resources

4. Start Phase 1

   • Begin refactoring bossterm-core-mpp to commonMain
   • Create initial expect/actual structure
   • Set up CI/CD for multi-target builds

---

Alternative Considerations

Why Not Just Use xterm.js?

Pros of BossTerm Wasm:

• ✅ Full Kotlin codebase (type safety, null safety)
• ✅ Share core logic with desktop app (no code duplication)
• ✅ Compose-based UI (consistent with desktop)
• ✅ Kotlin ecosystem (Ktor, kotlinx.serialization)

Cons:

• ❌ More work than using existing xterm.js
• ❌ Kotlin/Wasm is less mature than JavaScript
• ❌ Smaller community/ecosystem

Recommendation: If goal is to ship web terminal quickly, use xterm.js. If goal is unified Kotlin codebase and learning Kotlin/Wasm, proceed with this plan.

---

References

• Kotlin/Wasm Overview
• Compose Multiplatform Web
• Ktor Server Documentation
• xterm.js Architecture (for reference)
• WebSocket RFC 6455
• PTY4J Documentation

---

Summary: This comprehensive plan outlines a complete roadmap for transforming BossTerm into a WebAssembly-based terminal emulator with backend server architecture. The approach preserves BossTerm's existing features while enabling browser-based deployment through three main phases: (1) refactoring core logic to Kotlin Multiplatform commonMain (8-10 weeks), (2) building a Wasm frontend with Compose HTML and Canvas rendering (10-12 weeks), and (3) creating a Ktor-based backend server for PTY management (6-8 weeks). Total estimated effort is 8-10 months with clear deliverables at each phase. The architecture enables both standalone web deployment and embedded use cases while maintaining the desktop version.

---

[kshivang]

@claude how jypyter notebook use terminal browser

[claude]

Claude finished @kshivang's task in 1m 2s —— View job

---

How Jupyter Notebooks Use Browser Terminals

• Research Jupyter's terminal architecture
• Explain frontend components
• Explain backend components
• Compare with BossTerm Wasm approach
• Provide technical details and references

---

Jupyter's Terminal Architecture

Jupyter notebooks use a client-server architecture for browser-based terminals - exactly the same approach as Option 1 in the detailed plan above. Here's how it works:

Architecture Overview

Browser (Frontend)              Backend Server
┌─────────────────┐            ┌──────────────────┐
│   xterm.js      │<-WebSocket->│   Terminado      │
│  (Rendering +   │            │  (PTY Manager)   │
│   Input)        │            │                  │
└─────────────────┘            └────────┬─────────┘
                                        │
                                        ▼
                                  Real Shell Process
                                  (bash, zsh, etc.)

Frontend: xterm.js

Technology: xterm.js - JavaScript/TypeScript terminal emulator

Responsibilities:

• Renders terminal content in HTML Canvas or DOM
• Captures keyboard input
• Handles mouse events (selection, right-click, scrolling)
• ANSI escape sequence parsing and rendering
• Does NOT run any shell locally

Integration:

// Simplified Jupyter terminal frontend
import { Terminal } from 'xterm';

const term = new Terminal();
term.open(document.getElementById('terminal'));

const ws = new WebSocket('ws://localhost:8888/terminals/1');
ws.onmessage = (event) => {
  term.write(event.data);  // Display shell output
};

term.onData((data) => {
  ws.send(JSON.stringify(['stdin', data]));  // Send user input
});

Backend: Terminado

Technology: Terminado - Python library for PTY management

Responsibilities:

• Creates real PTY (pseudo-terminal) using pty module
• Spawns shell process (bash, zsh, etc.)
• Manages WebSocket connections
• Forwards data bidirectionally (browser ↔ PTY)
• Handles terminal resize events

Implementation:

# Simplified Terminado architecture
import pty
import tornado.web
import tornado.websocket

class TerminalWebSocket(tornado.websocket.WebSocketHandler):
    def open(self, term_name):
        # Create PTY and spawn shell
        self.pty_fd, self.child_pid = pty.fork()
        if self.child_pid == 0:
            # Child process - exec shell
            os.execvp('/bin/bash', ['/bin/bash'])
        
        # Parent - read from PTY, send to browser
        self.start_reading()
    
    def on_message(self, message):
        # Write user input to PTY
        os.write(self.pty_fd, message.encode())
    
    def start_reading(self):
        # Read from PTY, send to browser
        data = os.read(self.pty_fd, 1024)
        self.write_message(data)

Protocol: WebSocket with JSON Messages

Jupyter uses a simple message protocol over WebSocket:

Browser → Server:

["stdin", "ls -la\n"]              # User typed command
["set_size", 80, 24]               # Terminal resized

Server → Browser:

["stdout", "\u001b[32mhello\u001b[0m"]  # Shell output (raw ANSI)

Technology Stack Summary

Component	Technology	Purpose
Frontend Rendering	xterm.js (JS/TS)	ANSI parsing, display, input capture
Backend Server	Tornado (Python)	WebSocket server
PTY Management	Terminado (Python)	Wraps pty module
Shell Execution	System shell (bash/zsh)	Actual command execution
Communication	WebSocket	Bidirectional data stream

Why This Approach?

Security: Browser sandbox prevents direct PTY access (as discussed earlier)

Cross-Platform: Works on any device with a browser

Lightweight Frontend: Browser only handles rendering (no shell execution)

Familiar UX: Looks and feels like a native terminal

Comparison with BossTerm Wasm (Option 1)

The proposed BossTerm Wasm architecture is nearly identical to Jupyter's approach:

Component	Jupyter	BossTerm Wasm (Proposed)
Frontend	xterm.js (JS)	BossTerm-Wasm (Kotlin/Wasm) + Canvas
Backend	Terminado (Python) + Tornado	Ktor (Kotlin) + pty4j
PTY Library	pty module (Python stdlib)	pty4j (JVM)
Protocol	WebSocket + JSON	WebSocket + JSON (or msgpack)
Shell	System shell	System shell

Key Difference: BossTerm would use Kotlin end-to-end instead of JavaScript + Python, enabling code sharing between desktop and web versions.

Real-World Deployment

JupyterHub (multi-user Jupyter) uses this architecture at scale:

• Spawns separate backend server per user
• Proxy routes WebSocket connections
• Supports 100+ concurrent users
• Same architecture works for local (JupyterLab) and cloud deployments

References

• Terminado GitHub: https://github.com/jupyter/terminado
• xterm.js GitHub: https://github.com/xtermjs/xterm.js
• Jupyter Terminal Documentation: https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Running%20Code.html#Terminal
• JupyterHub Architecture: https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html

Key Takeaway

Jupyter's terminal implementation validates the proposed BossTerm Wasm approach (Option 1) from the detailed plan. It's a proven, scalable architecture used by millions of developers worldwide. The main difference would be using Kotlin/Compose instead of JavaScript/Python, which offers:

✅ Type safety across frontend and backend
✅ Code sharing with desktop BossTerm
✅ Unified Kotlin ecosystem
✅ Performance benefits of Wasm (vs interpreted JavaScript)

This architecture is the industry-standard approach for browser-based terminals and should be the foundation for BossTerm Wasm.

---