openmux 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 monotykamary
+
+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,194 @@
+# openmux
+
+A terminal multiplexer with master-stack layout (Zellij-style), built with:
+
+- **Bun** - Fast JavaScript runtime
+- **OpenTUI** - Terminal UI library with React reconciler
+- **bun-pty** - PTY support for Bun
+- **ghostty-web** - Terminal emulation via WASM
+
+## Features
+
+- Master-stack tiling layout (like Zellij)
+- i3-gaps style gaps and borders
+- Vim-style `hjkl` navigation
+- Tmux-style `Ctrl+b` prefix key
+- 9 workspaces with isolated pane layouts
+- Session persistence and management
+- Pane zoom (fullscreen focused pane)
+- Kitty Graphics and Sixel protocol support
+- Mouse tracking (click to focus, tabbed pane switching)
+- Scrollback support with mouse wheel and scrollbar
+
+## Installation
+
+### Quick Install (curl)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/monotykamary/openmux/main/scripts/install.sh | bash
+```
+
+### npm / bun
+
+```bash
+npm install -g openmux
+# or
+bun add -g openmux
+```
+
+### From Source
+
+```bash
+git clone https://github.com/monotykamary/openmux.git
+cd openmux
+bun install
+bun run build --install
+```
+
+### GitHub Releases
+
+Download prebuilt binaries from [GitHub Releases](https://github.com/monotykamary/openmux/releases).
+
+Available platforms:
+- macOS (Apple Silicon)
+- Linux (x64 / arm64)
+
+## Usage
+
+```bash
+openmux
+```
+
+For development:
+
+```bash
+bun start      # Run from source
+bun dev        # Run with watch mode
+```
+
+## Keyboard Shortcuts
+
+### Normal Mode (Alt shortcuts - no prefix needed)
+- `Alt+h/j/k/l` - Navigate panes
+- `Alt+n` - New pane
+- `Alt+1-9` - Switch to workspace 1-9
+- `Alt+[` / `Alt+]` - Cycle layout mode (vertical → horizontal → stacked)
+- `Alt+x` - Close pane
+- `Alt+z` - Toggle zoom (fullscreen focused pane)
+- `Alt+s` - Open session picker
+- `Ctrl+b` - Enter prefix mode
+
+### Mouse
+- `Click` - Focus pane
+- `Click tab` - Switch to stacked pane (in stacked mode)
+- `Scroll wheel` - Scroll through terminal history (when not in alternate screen apps like vim)
+- `Click scrollbar` - Jump to position in scrollback
+- `Drag scrollbar` - Scroll through history by dragging
+
+### Prefix Mode (Ctrl+b, 2s timeout)
+- `n` or `Enter` - New pane
+- `h/j/k/l` - Navigate panes
+- `1-9` - Switch to workspace 1-9
+- `v` - Set layout mode: vertical
+- `H` - Set layout mode: horizontal
+- `t` - Set layout mode: stacked (tabbed)
+- `x` - Close current pane
+- `z` - Toggle zoom
+- `s` - Open session picker
+- `]` - Paste from clipboard
+- `r` - Enter resize mode
+- `?` - Toggle keyboard hints
+- `Esc` - Exit prefix mode
+
+### Resize Mode
+- `h/l` - Shrink/grow width
+- `j/k` - Grow/shrink height
+- `Enter/Esc` - Exit resize mode
+
+## Concepts
+
+### Workspaces
+Like i3/sway, openmux supports multiple workspaces (1-9). Each workspace has its own layout tree of panes. The status bar shows populated workspaces dynamically - empty workspaces don't appear unless active.
+
+### Layout Modes (Zellij-style)
+Each workspace has a layout mode that determines how panes are arranged:
+- **Vertical** (`│`): Main pane on left, stack panes split vertically on right
+- **Horizontal** (`─`): Main pane on top, stack panes split horizontally on bottom
+- **Stacked** (`▣`): Main pane on left, stack panes tabbed on right (only active visible)
+
+### Sessions
+Sessions persist your workspace layouts and pane working directories. Sessions are auto-saved to `~/.config/openmux/sessions/` and can be switched via the session picker (`Alt+s` or `Ctrl+b s`).
+
+## Project Structure
+
+```
+src/
+├── core/                           # Core layout and session management
+│   ├── types.ts                    # Type definitions (Workspace, Pane, etc.)
+│   ├── config.ts                   # Configuration and defaults
+│   ├── keyboard-utils.ts           # hjkl to Direction conversion
+│   ├── operations/
+│   │   ├── index.ts                # Layout operations exports
+│   │   └── master-stack-layout.ts  # Master-stack layout calculations
+│   └── session/                    # Session persistence
+│       ├── index.ts                # Session exports
+│       ├── session-manager.ts      # High-level session operations
+│       ├── session-serializer.ts   # Serialize/deserialize sessions
+│       └── session-storage.ts      # Disk I/O for sessions
+│
+├── components/                     # OpenTUI React components
+│   ├── index.ts                    # Component exports
+│   ├── Pane.tsx                    # Individual pane with border/focus
+│   ├── PaneContainer.tsx           # Layout pane renderer
+│   ├── TerminalView.tsx            # Terminal rendering with buffer API
+│   ├── StatusBar.tsx               # Bottom status bar
+│   ├── KeyboardHints.tsx           # Keyboard shortcuts overlay
+│   └── SessionPicker.tsx           # Session selection modal
+│
+├── contexts/                       # React contexts for state
+│   ├── index.ts                    # Context exports
+│   ├── LayoutContext.tsx           # Workspace/pane layout state reducer
+│   ├── TerminalContext.tsx         # PTY management and lifecycle
+│   ├── KeyboardContext.tsx         # Prefix mode and key state
+│   ├── SessionContext.tsx          # Session management and persistence
+│   └── ThemeContext.tsx            # Theme/styling configuration
+│
+├── terminal/                       # PTY and terminal emulation
+│   ├── index.ts                    # Terminal exports
+│   ├── pty-manager.ts              # PTY session lifecycle (bun-pty)
+│   ├── ghostty-emulator.ts         # Terminal emulator (ghostty-web WASM)
+│   ├── input-handler.ts            # Key/mouse to escape sequence encoder
+│   ├── graphics-passthrough.ts     # Kitty Graphics/Sixel protocol
+│   ├── capabilities.ts             # Terminal capability detection
+│   └── terminal-colors.ts          # Color palette detection
+│
+├── utils/
+│   ├── index.ts                    # Utils exports
+│   └── clipboard.ts                # Clipboard read/write
+│
+├── App.tsx                         # Main app component with context hierarchy
+└── index.tsx                       # Entry point (Bun serve + OpenTUI renderer)
+```
+
+## Development Status
+
+Current status:
+
+- [x] Master-stack layout with gaps
+- [x] OpenTUI component layer
+- [x] Keyboard navigation system
+- [x] PTY integration
+- [x] ghostty-web WASM terminal emulation
+- [x] Workspaces (1-9)
+- [x] Layout modes (vertical/horizontal/stacked)
+- [x] Session persistence
+- [x] Pane zoom
+- [x] Mouse support
+- [x] Graphics protocol passthrough (Kitty/Sixel)
+- [x] Scrollback support
+- [ ] Session restore on startup
+- [ ] Configurable keybindings
+
+## License
+
+MIT

package/bin/openmux

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# openmux npm bin wrapper
+# Locates and executes the downloaded binary
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_DIR="$(dirname "$SCRIPT_DIR")"
+DIST_DIR="$PACKAGE_DIR/dist"
+
+# Determine library extension based on OS
+case "$(uname -s)" in
+    Darwin) LIB_EXT="dylib" ;;
+    Linux) LIB_EXT="so" ;;
+    *) echo "Unsupported OS" >&2; exit 1 ;;
+esac
+
+# Check if binary exists
+if [[ ! -x "$DIST_DIR/openmux-bin" ]]; then
+    echo "Error: openmux binary not found at $DIST_DIR/openmux-bin" >&2
+    echo "Run 'npm run build' or reinstall the package" >&2
+    exit 1
+fi
+
+# Set library path and execute
+export BUN_PTY_LIB="${BUN_PTY_LIB:-$DIST_DIR/librust_pty.$LIB_EXT}"
+exec "$DIST_DIR/openmux-bin" "$@"

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "openmux",
+  "version": "0.1.1",
+  "description": "Terminal multiplexer with master-stack tiling layout",
+  "module": "src/index.tsx",
+  "type": "module",
+  "bin": {
+    "openmux": "./bin/openmux"
+  },
+  "files": [
+    "bin",
+    "scripts/postinstall.cjs"
+  ],
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "dev": "bun run --watch src/index.tsx",
+    "typecheck": "tsc --noEmit",
+    "build": "./scripts/build.sh",
+    "build:release": "./scripts/build.sh --release",
+    "install:local": "./scripts/build.sh --install",
+    "prepare": "effect-language-service patch",
+    "postinstall": "node scripts/postinstall.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "standard-version",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major",
+    "release:patch": "standard-version --release-as patch",
+    "release:first": "standard-version --first-release",
+    "publish:npm": "./scripts/publish.sh"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/openmux.git"
+  },
+  "author": "monotykamary",
+  "license": "MIT",
+  "homepage": "https://github.com/monotykamary/openmux#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/openmux/issues"
+  },
+  "keywords": [
+    "terminal",
+    "multiplexer",
+    "tui",
+    "tmux",
+    "zellij",
+    "bun",
+    "opentui"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@effect/language-service": "^0.60.0",
+    "@effect/vitest": "^0.27.0",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "standard-version": "^9.5.0",
+    "vitest": "^4.0.15"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@effect/cli": "^0.72.1",
+    "@effect/platform": "^0.93.6",
+    "@opentui/core": "^0.1.57",
+    "@opentui/react": "^0.1.57",
+    "bun-pty": "^0.4.2",
+    "effect": "^3.19.9",
+    "ghostty-web": "^0.3.0",
+    "react": "^19.2.1"
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * openmux postinstall script
+ * Downloads prebuilt binaries from GitHub releases
+ */
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { execSync } = require("child_process");
+
+const REPO = "monotykamary/openmux";
+const PACKAGE_ROOT = path.join(__dirname, "..");
+const DIST_DIR = path.join(PACKAGE_ROOT, "dist");
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  let os;
+  switch (platform) {
+    case "darwin":
+      os = "darwin";
+      break;
+    case "linux":
+      os = "linux";
+      break;
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  let cpu;
+  switch (arch) {
+    case "x64":
+      cpu = "x64";
+      break;
+    case "arm64":
+      cpu = "arm64";
+      break;
+    default:
+      throw new Error(`Unsupported architecture: ${arch}`);
+  }
+
+  return { os, arch: cpu, target: `${os}-${cpu}` };
+}
+
+function getVersion() {
+  const packageJson = require(path.join(PACKAGE_ROOT, "package.json"));
+  return `v${packageJson.version}`;
+}
+
+function fetch(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { "User-Agent": "openmux-installer" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect
+        fetch(res.headers.location).then(resolve).catch(reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+        return;
+      }
+      resolve(res);
+    }).on("error", reject);
+  });
+}
+
+async function downloadFile(url, destPath) {
+  console.log(`Downloading ${url}...`);
+
+  const response = await fetch(url);
+  const writeStream = fs.createWriteStream(destPath);
+
+  return new Promise((resolve, reject) => {
+    response.pipe(writeStream);
+    writeStream.on("finish", () => {
+      writeStream.close();
+      resolve();
+    });
+    writeStream.on("error", reject);
+  });
+}
+
+async function main() {
+  // Skip in CI or when OPENMUX_SKIP_DOWNLOAD is set
+  if (process.env.CI || process.env.OPENMUX_SKIP_DOWNLOAD) {
+    console.log("Skipping binary download");
+    return;
+  }
+
+  try {
+    const { target } = getPlatform();
+    const version = getVersion();
+
+    console.log(`Installing openmux ${version} for ${target}...`);
+
+    const url = `https://github.com/${REPO}/releases/download/${version}/openmux-${version}-${target}.tar.gz`;
+
+    // Ensure dist directory exists
+    fs.mkdirSync(DIST_DIR, { recursive: true });
+
+    const tarballPath = path.join(DIST_DIR, "download.tar.gz");
+
+    await downloadFile(url, tarballPath);
+
+    console.log("Extracting...");
+
+    // Use native tar command to extract
+    execSync(`tar -xzf "${tarballPath}" -C "${DIST_DIR}"`, { stdio: "inherit" });
+
+    // Clean up tarball
+    fs.unlinkSync(tarballPath);
+
+    // Make binary executable
+    const binaryPath = path.join(DIST_DIR, "openmux-bin");
+    if (fs.existsSync(binaryPath)) {
+      fs.chmodSync(binaryPath, 0o755);
+    }
+
+    // Make wrapper executable
+    const wrapperPath = path.join(DIST_DIR, "openmux");
+    if (fs.existsSync(wrapperPath)) {
+      fs.chmodSync(wrapperPath, 0o755);
+    }
+
+    console.log("openmux installed successfully!");
+  } catch (error) {
+    // Don't fail the install if download fails
+    // User might be building from source
+    console.warn(`Warning: Could not download prebuilt binary: ${error.message}`);
+    console.warn("You may need to build from source: bun run build");
+  }
+}
+
+main();