@jacksontian/mwt 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jackson Tian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# mwt - Multi-Window Terminal
+
+A lightweight web-based multi-window terminal for **local development**. Run multiple shell sessions in the browser with side-by-side, grid, and tab layouts.
+
+> **Note:** mwt is designed for local use on your development machine. It does not provide authentication, encryption, or any access control — do not expose it to the network.
+
+[![npm version](https://img.shields.io/npm/v/@jacksontian/mwt)](https://www.npmjs.com/package/@jacksontian/mwt)
+[![npm downloads](https://img.shields.io/npm/dm/@jacksontian/mwt)](https://www.npmjs.com/package/@jacksontian/mwt)
+[![Node.js](https://img.shields.io/node/v/@jacksontian/mwt)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/@jacksontian/mwt)](LICENSE)
+
+### Side by Side
+
+![Side by Side](./figures/sidebyside.png)
+
+### Grid
+
+![Grid](./figures/grid.png)
+
+### Tabs
+
+![Tabs](./figures/tabs.png)
+
+## Why mwt?
+
+### 设计动机
+
+日常开发中，我们经常需要同时运行多个终端会话：一个跑开发服务器，一个跑测试，一个执行 git 操作，还有一个用来查看日志。现有的方案要么太重，要么上手成本不低：
+
+- **tmux / screen** — 功能强大，但快捷键体系需要专门学习，配置门槛较高，对新手不够友好
+- **VS Code 内置终端** — 使用方便，但你不得不启动一个完整的 IDE，仅仅为了开几个终端窗口
+- **iTerm2 / Windows Terminal** — 依赖特定操作系统，无法跨平台统一体验
+- **ttyd / Wetty / code-server** — 面向远程场景设计，功能和配置远超本地开发所需
+
+mwt 想解决的问题很简单：**给本地开发提供一个轻量、直觉化、开箱即用的多窗口终端**。
+
+在 AI 时代，这个需求变得更加迫切。真正发挥生产力的方式不是盯着一个 AI 等它输出，而是**同时指挥多个 AI 工具并行干活**——一个窗口让 Claude Code 重构后端，一个窗口让另一个 Agent 写测试，一个窗口盯着构建日志，一个窗口查文档。mwt 天然适合这种「一人指挥，多路并发」的工作模式：轻量启动、多窗口并排、一眼掌控全局。
+
+### 设计原则
+
+**极简依赖** — 后端仅依赖 node-pty 和 ws 两个包，前端使用原生 ES Modules + xterm.js，没有框架、没有构建工具、没有打包步骤。`npx @jacksontian/mwt` 一行命令即可启动。
+
+**浏览器即界面** — 选择浏览器作为 UI 层，天然跨平台，不需要安装桌面应用。布局切换、主题跟随、快捷键操作都在浏览器中完成，所见即所得。
+
+**会话不丢失** — 每个终端保留 100KB 的输出缓冲区，刷新页面或网络断开后可以恢复现场。断线 30 分钟内自动重连，开发流程不被打断。
+
+**够用就好** — 不做 SSH、不做认证、不做插件系统。mwt 只专注于一件事：在本地高效地管理多个终端窗口。功能边界清晰，代码量控制在 2000 行左右，任何人都可以快速理解和修改。
+
+## Features
+
+- **Multi-terminal** - Create and manage multiple terminal sessions simultaneously
+- **Three layouts** - Side-by-side, grid, and tabs, switch anytime
+- **Session persistence** - Reconnect without losing terminal output (100KB buffer per terminal)
+- **Auto-reconnect** - WebSocket disconnection recovery with exponential backoff
+- **Dark / Light theme** - Manual toggle or follow system preference
+- **Keyboard-driven** - Full keyboard shortcut support
+- **Zero build step** - No webpack, no bundler, just run
+
+## Quick Start
+
+```bash
+npx @jacksontian/mwt
+```
+
+Or install globally:
+
+```bash
+npm install -g @jacksontian/mwt
+mwt
+```
+
+Then open http://localhost:1987 in your browser.
+
+## Usage
+
+```
+mwt [options]
+
+Options:
+  -p, --port <port>  Port to listen on (default: 1987)
+  -h, --help         Show this help message
+```
+
+Example:
+
+```bash
+mwt -p 8080
+```
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Shift+T` | New terminal |
+| `Ctrl+Shift+W` | Close active terminal |
+| `Ctrl+Shift+]` | Next terminal |
+| `Ctrl+Shift+[` | Previous terminal |
+| `Alt+1-9` | Switch to terminal N |
+| `Ctrl+Shift+M` | Maximize / restore active terminal |
+| `F11` | Toggle fullscreen |
+
+## Architecture
+
+```
+Browser                          Server (Node.js)
+┌──────────────┐    WebSocket    ┌──────────────┐
+│  xterm.js    │◄──────────────►│  node-pty     │
+│  App.js      │                │  RingBuffer   │
+│  LayoutMgr   │                │  Session Mgr  │
+│  ThemeMgr    │                └──────────────┘
+└──────────────┘
+```
+
+- **Frontend** - Vanilla JS + xterm.js, no framework
+- **Backend** - Node.js HTTP server + WebSocket (ws)
+- **PTY** - node-pty spawns real shell processes
+- **Buffer** - RingBuffer keeps last 100KB output per terminal for session restore
+
+## Dependencies
+
+Only two runtime backend dependencies:
+
+- [node-pty](https://github.com/microsoft/node-pty) - Pseudo-terminal management
+- [ws](https://github.com/websockets/ws) - WebSocket server
+
+Frontend uses [xterm.js](https://xtermjs.org/) with fit and web-links addons, served from node_modules.
+
+## Comparison
+
+| | mwt | tmux / screen | iTerm2 / Windows Terminal | VS Code 终端 | ttyd | Wetty | code-server |
+|---|---|---|---|---|---|---|---|
+| **多终端管理** | ✅ 并排 / 网格 / 标签页 | ✅ 窗格 / 窗口 | ✅ 标签页 / 分屏 | ✅ 分屏 / 标签页 | ❌ 单终端 | ❌ 单终端 | ✅ 内嵌终端 |
+| **运行环境** | 浏览器 | 终端 | macOS 专属 | 桌面应用 | 浏览器 | 浏览器 | 浏览器 |
+| **跨平台** | ✅ 任意有浏览器的系统 | ✅ Unix/Linux/macOS | ❌ macOS only | ✅ | ✅ | ✅ | ✅ |
+| **上手成本** | 零配置，开箱即用 | 高，需学习快捷键体系 | 低 | 低（需安装 IDE） | 低 | 中等 | 中等 |
+| **安装体积** | ~2MB（2 个运行时依赖） | 系统包管理器安装 | ~30MB | ~300MB+ | ~1MB（C 编译） | ~50MB | ~200MB+ |
+| **构建步骤** | 无 | 无 | N/A | N/A | 需编译 C | 需 npm install | 需编译 |
+| **会话持久化** | ✅ 100KB 缓冲 + 自动重连 | ✅ detach/attach | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **布局切换** | ✅ 三种布局一键切换 | ✅ 手动分屏 | ✅ | ✅ | ❌ | ❌ | ✅ |
+| **主题切换** | ✅ 深色/浅色 + 跟随系统 | 需手动配置 | ✅ | ✅ | ❌ | ❌ | ✅ |
+| **远程/SSH** | ❌ 仅本地 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **认证/权限** | ❌ 不需要 | N/A | N/A | N/A | 可选 | ✅ | ✅ |
+| **适用场景** | 本地开发多终端 | 服务器运维/本地开发 | macOS 日常使用 | 编码 + 终端一体化 | 远程单终端 | 远程终端 | 远程开发 |
+
+**mwt 的定位**：如果你只是想在本地开发时开几个终端窗口，不想为此启动一个 IDE，也不想花时间学 tmux，mwt 是最轻量的选择。它不试图替代任何一个竞品，而是填补了「本地轻量多终端」这个细分场景的空白。
+
+## Limitations
+
+mwt is intentionally simple. It does **not** support:
+
+- SSH or remote server connections — local shell only
+- Authentication / HTTPS — not needed for localhost
+- File editing — use your own editor
+- Plugin system — keep it minimal
+
+If you need remote access or multi-user support, consider [ttyd](https://github.com/tsl0922/ttyd), [Wetty](https://github.com/butlerx/wetty), or [code-server](https://github.com/coder/code-server).
+
+## License
+
+MIT

package/bin/mwt.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+  options: {
+    port: { type: 'string', short: 'p', default: '1987' },
+    host: { type: 'string', default: '127.0.0.1' },
+    open: { type: 'boolean', default: true },
+    help: { type: 'boolean', short: 'h', default: false },
+  },
+  allowNegative: true,
+});
+
+if (values.help) {
+  console.log(`
+  mwt - Multi-Window Terminal
+
+  Usage:
+    mwt [options]
+
+  Options:
+    -p, --port <port>  Port to listen on (default: 1987)
+    --host <host>      Host to bind to (default: 127.0.0.1)
+    --no-open          Do not open the browser automatically
+    -h, --help         Show this help message
+`);
+  process.exit(0);
+}
+
+import {start} from '../lib/server.js';
+
+start(Number(values.port), values.host, { open: values.open });

package/lib/ring-buffer.js

@@ -0,0 +1,53 @@
+export class RingBuffer {
+  constructor(capacity = 100 * 1024) {
+    this.capacity = capacity;
+    this.buffer = Buffer.alloc(capacity);
+    this.length = 0;   // bytes currently stored
+    this.offset = 0;   // next write position (wraps around)
+  }
+
+  write(chunk) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+
+    if (buf.length >= this.capacity) {
+      // Chunk alone fills the entire buffer — keep only the tail
+      buf.copy(this.buffer, 0, buf.length - this.capacity);
+      this.offset = 0;
+      this.length = this.capacity;
+      return;
+    }
+
+    const spaceAtEnd = this.capacity - this.offset;
+
+    if (buf.length <= spaceAtEnd) {
+      buf.copy(this.buffer, this.offset);
+    } else {
+      // Wrap around
+      buf.copy(this.buffer, this.offset, 0, spaceAtEnd);
+      buf.copy(this.buffer, 0, spaceAtEnd);
+    }
+
+    this.offset = (this.offset + buf.length) % this.capacity;
+    this.length = Math.min(this.length + buf.length, this.capacity);
+  }
+
+  read() {
+    if (this.length === 0) return '';
+
+    if (this.length < this.capacity) {
+      // Haven't wrapped yet — data starts at 0
+      return this.buffer.toString('utf8', 0, this.length);
+    }
+
+    // Buffer is full — data starts at this.offset (oldest byte)
+    const start = this.offset; // oldest byte position
+    const head = this.buffer.subarray(start, this.capacity);
+    const tail = this.buffer.subarray(0, start);
+    return Buffer.concat([head, tail]).toString('utf8');
+  }
+
+  clear() {
+    this.length = 0;
+    this.offset = 0;
+  }
+}

package/lib/server.js

@@ -0,0 +1,212 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exec } from 'node:child_process';
+import { WebSocketServer } from 'ws';
+import pty from 'node-pty';
+import { RingBuffer } from './ring-buffer.js';
+
+const __dirname = fileURLToPath(new URL('..', import.meta.url));
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.map': 'application/json',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+};
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 60 * 1000;     // check every minute
+const OUTPUT_BUFFER_SIZE = 100 * 1024;      // 100KB per terminal
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open';
+  exec(`${cmd} ${url}`);
+}
+
+export function start(port = 1987, host = '127.0.0.1', options = {}) {
+
+const startCwd = process.cwd();
+const sessions = new Map(); // sessionId -> { terminals, ws, disconnectedAt }
+
+// HTTP server for static files
+const server = createServer(async (req, res) => {
+  let filePath;
+  const url = req.url.split('?')[0];
+
+  if (url === '/') {
+    filePath = join(__dirname, 'public', 'index.html');
+  } else {
+    filePath = join(__dirname, 'public', url);
+  }
+
+  try {
+    const data = await readFile(filePath);
+    const ext = extname(filePath);
+    res.writeHead(200, { 'Content-Type': MIME_TYPES[ext] || 'application/octet-stream' });
+    res.end(data);
+  } catch {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  }
+});
+
+// WebSocket server
+const wss = new WebSocketServer({ server });
+
+wss.on('connection', (ws, req) => {
+  const url = new URL(req.url, 'http://localhost');
+  const sessionId = url.searchParams.get('sessionId');
+  if (!sessionId) {
+    ws.close(4001, 'Missing sessionId');
+    return;
+  }
+
+  let session = sessions.get(sessionId);
+  if (!session) {
+    session = { terminals: new Map(), ws: null, disconnectedAt: null };
+    sessions.set(sessionId, session);
+  }
+
+  // Detach old WS if still open
+  if (session.ws && session.ws !== ws && session.ws.readyState === 1) {
+    session.ws.close();
+  }
+
+  session.ws = ws;
+  session.disconnectedAt = null;
+
+  // Send session-restore with existing terminal IDs
+  const terminalIds = [...session.terminals.keys()];
+  ws.send(JSON.stringify({ type: 'session-restore', terminals: terminalIds }));
+
+  // Send buffered output for each existing terminal
+  for (const [id, entry] of session.terminals) {
+    const buffered = entry.outputBuffer.read();
+    if (buffered) {
+      ws.send(JSON.stringify({ type: 'buffer', id, data: buffered }));
+    }
+  }
+
+  // Signal that all buffer messages have been sent
+  if (terminalIds.length > 0) {
+    ws.send(JSON.stringify({ type: 'restore-complete' }));
+  }
+
+  ws.on('message', async (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+
+    switch (msg.type) {
+      case 'create': {
+        const shell = process.env.SHELL || '/bin/bash';
+        let ptyProcess;
+        try {
+          ptyProcess = pty.spawn(shell, [], {
+            name: 'xterm-256color',
+            cols: msg.cols || 80,
+            rows: msg.rows || 24,
+            cwd: startCwd,
+            env: process.env,
+          });
+        } catch (err) {
+          console.error(`Failed to spawn shell "${shell}":`, err.message);
+          if (ws.readyState === 1) {
+            ws.send(JSON.stringify({ type: 'exit', id: msg.id, exitCode: 1 }));
+          }
+          break;
+        }
+
+        const outputBuffer = new RingBuffer(OUTPUT_BUFFER_SIZE);
+        session.terminals.set(msg.id, { pty: ptyProcess, outputBuffer });
+
+        ptyProcess.onData((data) => {
+          outputBuffer.write(data);
+          if (session.ws && session.ws.readyState === 1) {
+            session.ws.send(JSON.stringify({ type: 'data', id: msg.id, data }));
+          }
+        });
+
+        ptyProcess.onExit(({ exitCode }) => {
+          session.terminals.delete(msg.id);
+          if (session.ws && session.ws.readyState === 1) {
+            session.ws.send(JSON.stringify({ type: 'exit', id: msg.id, exitCode }));
+          }
+        });
+        break;
+      }
+
+      case 'data': {
+        const entry = session.terminals.get(msg.id);
+        if (entry) entry.pty.write(msg.data);
+        break;
+      }
+
+      case 'resize': {
+        const entry = session.terminals.get(msg.id);
+        if (entry) {
+          try {
+            entry.pty.resize(msg.cols, msg.rows);
+          } catch {
+            // ignore invalid resize
+          }
+        }
+        break;
+      }
+
+      case 'close': {
+        const entry = session.terminals.get(msg.id);
+        if (entry) {
+          entry.pty.kill();
+          session.terminals.delete(msg.id);
+        }
+        break;
+      }
+
+    }
+  });
+
+  ws.on('close', () => {
+    if (session.ws === ws) {
+      session.ws = null;
+      session.disconnectedAt = Date.now();
+    }
+  });
+});
+
+server.listen(port, host, () => {
+  const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
+  console.log(`mwt running at ${url}`);
+  if (options.open !== false) {
+    openBrowser(url);
+  }
+});
+
+// Clean up sessions that have been disconnected too long
+const cleanupTimer = setInterval(() => {
+  const now = Date.now();
+  for (const [sessionId, session] of sessions) {
+    if (session.disconnectedAt && (now - session.disconnectedAt) > SESSION_TIMEOUT_MS) {
+      for (const [, entry] of session.terminals) {
+        entry.pty.kill();
+      }
+      session.terminals.clear();
+      sessions.delete(sessionId);
+    }
+  }
+}, CLEANUP_INTERVAL_MS);
+cleanupTimer.unref();
+
+} // end start

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@jacksontian/mwt",
+  "version": "1.0.0",
+  "description": "Multi-window terminal with side-by-side, grid, and tab layouts",
+  "type": "module",
+  "bin": {
+    "mwt": "bin/mwt.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "public/"
+  ],
+  "keywords": [
+    "terminal",
+    "xterm",
+    "multi-window",
+    "web-terminal"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "mocha",
+    "cov": "c8 mocha",
+    "cov:report": "c8 report --reporter=text --reporter=html"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "node-pty": "^1.2.0-beta.12",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "mocha": "^11.7.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}