\n\n---\n\n# psmux\n\n**The real tmux for Windows.** Not a port, not a wrapper, not a workaround.\n\npsmux is a **native Windows terminal multiplexer** built from the ground up in Rust. It uses Windows ConPTY directly, speaks the tmux command language, reads your `.tmux.conf`, and supports tmux themes. All without WSL, Cygwin, or MSYS2.\n\n> 💡 **Tip:** psmux ships with `tmux` and `pmux` aliases. Just type `tmux` and it works!\n\n👀 On Windows 👇\n\n\n\n## Installation\n\n### Using WinGet\n\n```powershell\nwinget install psmux\n```\n\n### Using Cargo\n\n```powershell\ncargo install psmux\n```\n\nThis installs `psmux`, `pmux`, and `tmux` binaries to your Cargo bin directory.\n\n### Using Scoop\n\n```powershell\nscoop bucket add psmux https://github.com/psmux/scoop-psmux\nscoop install psmux\n```\n\n### Using Chocolatey\n\n```powershell\nchoco install psmux\n```\n\n### From GitHub Releases\n\nDownload the latest `.zip` from [GitHub Releases](https://github.com/psmux/psmux/releases) and add to your PATH.\n\n### From Source\n\n```powershell\ngit clone https://github.com/psmux/psmux.git\ncd psmux\ncargo build --release\n```\n\nBuilt binaries:\n\n```text\ntarget\\release\\psmux.exe\ntarget\\release\\pmux.exe\ntarget\\release\\tmux.exe\n```\n\n### Docker (build environment)\n\nA ready-made Windows container with Rust + MSVC + SSH for building psmux:\n\n```powershell\ncd docker\ndocker build -t psmux-dev .\ndocker run -d --name psmux-dev -p 127.0.0.1:2222:22 -e ADMIN_PASSWORD=YourPass123! psmux-dev\nssh ContainerAdministrator@localhost -p 2222\n```\n\nSee [docker/README.md](docker/README.md) for full details.\n\n### Requirements\n\n- Windows 10 or Windows 11\n- **PowerShell 7+** (recommended) or cmd.exe\n - Download PowerShell: `winget install --id Microsoft.PowerShell`\n - Or visit: https://aka.ms/powershell\n\n## Why psmux?\n\nIf you've used tmux on Linux/macOS and wished you had something like it on Windows, **this is it**. Split panes, multiple windows, session persistence, full mouse support, tmux themes, 83 commands, 140+ format variables, 53 vim copy-mode keys. Your existing `.tmux.conf` works. Full details: **[docs/features.md](docs/features.md)** · **[docs/compatibility.md](docs/compatibility.md)**\n\n## Usage\n\nUse `psmux`, `pmux`, or `tmux` — they're identical:\n\n```powershell\npsmux # Start a new session\npsmux new-session -s work # Named session\npsmux ls # List sessions\npsmux attach -t work # Attach to a session\npsmux --help # Show help\n```\n\n## Claude Code Agent Teams\n\npsmux has first-class support for Claude Code agent teams. When Claude Code runs inside a psmux session, teammate agents automatically spawn in separate tmux panes instead of running in-process.\n\n```powershell\npsmux new-session -s work # Start a psmux session\nclaude # Run Claude Code — agent teams just work\n```\n\nNo extra configuration needed. Full guide: **[docs/claude-code.md](docs/claude-code.md)**\n\n## Documentation\n\n| Topic | Description |\n|-------|-------------|\n| **[Features](docs/features.md)** | Full feature list — mouse, copy mode, layouts, format engine |\n| **[Compatibility](docs/compatibility.md)** | tmux command/config compatibility matrix |\n| **[Performance](docs/performance.md)** | Benchmarks and optimization details |\n| **[Key Bindings](docs/keybindings.md)** | Default keys and customization |\n| **[Scripting](docs/scripting.md)** | 83 commands, hooks, targets, pipe-pane |\n| **[Configuration](docs/configuration.md)** | Config files, options, environment variables |\n| **[Plugins & Themes](docs/plugins.md)** | Plugin ecosystem — Catppuccin, Dracula, Nord, and more |\n| **[Mouse Over SSH](docs/mouse-ssh.md)** | SSH mouse support and Windows version requirements |\n| **[Claude Code](docs/claude-code.md)** | Agent teams integration guide |\n| **[FAQ](docs/faq.md)** | Common questions and answers |\n\n## Related Projects\n\n
\n
\n
\n \n \n pstop\n \n htop for Windows — real-time system monitor with per-core CPU bars, tree view, 7 color schemes \n cargo install pstop\n
\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome — bug reports, PRs, docs, and test scripts via [GitHub Issues](https://github.com/psmux/psmux/issues).\n\nIf psmux helps your Windows workflow, consider giving it a ⭐ on GitHub!\n\n## Star History\n\n[](https://www.star-history.com/?repos=psmux%2Fpsmux&type=date&legend=top-left)\n\n---\n\n
\n Made with ❤️ for PowerShell using Rust 🦀\n
\n"
},
{
"path": "choco-pkg/psmux.nuspec",
"content": "\n\n \n psmux\n 3.3.3\n psmux - Terminal Multiplexer for Windows\n Josh\n Josh\n https://github.com/psmux/psmux/blob/master/LICENSE\n https://github.com/psmux/psmux\n false\n Terminal multiplexer for Windows - tmux alternative for PowerShell and Windows Terminal. Includes psmux, pmux, and tmux commands.\n Terminal multiplexer for Windows (tmux alternative)\n https://github.com/psmux/psmux/releases\n terminal multiplexer tmux powershell cli windows psmux pmux\n https://github.com/psmux/psmux\n https://github.com/psmux/psmux#readme\n https://github.com/psmux/psmux/issues\n \n \n \n \n"
},
{
"path": "choco-pkg/tools/chocolateyinstall.ps1",
"content": "$ErrorActionPreference = 'Stop'\n\n$toolsDir = \"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\"\n$url64 = 'https://github.com/psmux/psmux/releases/download/v3.3.3/psmux-v3.3.3-windows-x64.zip'\n\n$packageArgs = @{\n packageName = $env:ChocolateyPackageName\n unzipLocation = $toolsDir\n url64bit = $url64\n checksum64 = 'E6FE103A776ED453647F82254445CBD4BA851E1A14BCBB959FDF858DE16CE5DD'\n checksumType64 = 'sha256'\n}\n\nInstall-ChocolateyZipPackage @packageArgs\n\n$psmuxPath = Join-Path $toolsDir \"psmux.exe\"\n$pmuxPath = Join-Path $toolsDir \"pmux.exe\"\n$tmuxPath = Join-Path $toolsDir \"tmux.exe\"\n\nInstall-BinFile -Name \"psmux\" -Path $psmuxPath\nInstall-BinFile -Name \"pmux\" -Path $pmuxPath\nInstall-BinFile -Name \"tmux\" -Path $tmuxPath"
},
{
"path": "choco-pkg/tools/chocolateyuninstall.ps1",
"content": "Uninstall-BinFile -Name \"psmux\"\nUninstall-BinFile -Name \"pmux\"\nUninstall-BinFile -Name \"tmux\""
},
{
"path": "crates/portable-pty-psmux/.cargo-ok",
"content": "{\"v\":1}"
},
{
"path": "crates/portable-pty-psmux/.cargo_vcs_info.json",
"content": "{\n \"git\": {\n \"sha1\": \"d389cf717cdb7702c9a732d1d9bc0b6f08603b4a\"\n },\n \"path_in_vcs\": \"\"\n}"
},
{
"path": "crates/portable-pty-psmux/Cargo.toml",
"content": "# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO\n#\n# When uploading crates to the registry Cargo will automatically\n# \"normalize\" Cargo.toml files for maximal compatibility\n# with all versions of Cargo and also rewrite `path` dependencies\n# to registry (e.g., crates.io) dependencies.\n#\n# If you are reading this file be aware that the original Cargo.toml\n# will likely look very different (and much more reasonable).\n# See Cargo.toml.orig for the original contents.\n\n[package]\nedition = \"2018\"\nname = \"portable-pty-psmux\"\nversion = \"0.9.3\"\nauthors = [\"Wez Furlong\"]\nbuild = false\ninclude = [\n \"src/**/*\",\n \"LICENSE.md\",\n \"README.md\",\n \"Cargo.toml\",\n \"examples/**/*\",\n]\nautolib = false\nautobins = false\nautoexamples = false\nautotests = false\nautobenches = false\ndescription = \"Cross platform pty interface (psmux fork with ConPTY PASSTHROUGH_MODE + WIN32_INPUT_MODE + RESIZE_QUIRK patches)\"\ndocumentation = \"https://docs.rs/portable-pty\"\nreadme = false\nlicense = \"MIT\"\nrepository = \"https://github.com/psmux/portable-pty-patched\"\nresolver = \"2\"\n\n[features]\ndefault = []\nserde_support = [\n \"serde\",\n \"serde_derive\",\n]\n\n[lib]\nname = \"portable_pty\"\npath = \"src/lib.rs\"\n\n[[example]]\nname = \"bash\"\npath = \"examples/bash.rs\"\n\n[[example]]\nname = \"narrow\"\npath = \"examples/narrow.rs\"\n\n[[example]]\nname = \"whoami\"\npath = \"examples/whoami.rs\"\n\n[[example]]\nname = \"whoami_async\"\npath = \"examples/whoami_async.rs\"\n\n[dependencies.anyhow]\nversion = \"1.0\"\n\n[dependencies.downcast-rs]\nversion = \"2.0\"\n\n[dependencies.filedescriptor]\nversion = \"0.8.3\"\n\n[dependencies.libc]\nversion = \"0.2\"\n\n[dependencies.log]\nversion = \"0.4\"\n\n[dependencies.nix]\nversion = \"0.31\"\nfeatures = [\n \"term\",\n \"fs\",\n]\n\n[dependencies.serde]\nversion = \"1.0\"\noptional = true\n\n[dependencies.serde_derive]\nversion = \"1.0\"\noptional = true\n\n[dependencies.serial2]\nversion = \"0.2\"\n\n[dependencies.shell-words]\nversion = \"1.1\"\n\n[dev-dependencies.futures]\nversion = \"0.3\"\n\n[dev-dependencies.smol]\nversion = \"2.0\"\n\n[target.\"cfg(windows)\".dependencies.lazy_static]\nversion = \"1.4\"\n\n[target.\"cfg(windows)\".dependencies.shared_library]\nversion = \"0.1\"\n\n[target.\"cfg(windows)\".dependencies.winapi]\nversion = \"0.3\"\nfeatures = [\n \"winuser\",\n \"consoleapi\",\n \"handleapi\",\n \"fileapi\",\n \"namedpipeapi\",\n \"synchapi\",\n \"libloaderapi\",\n \"winnt\",\n]\n\n[target.\"cfg(windows)\".dependencies.winreg]\nversion = \"0.56\"\n"
},
{
"path": "crates/portable-pty-psmux/Cargo.toml.orig",
"content": "# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO\n#\n# When uploading crates to the registry Cargo will automatically\n# \"normalize\" Cargo.toml files for maximal compatibility\n# with all versions of Cargo and also rewrite `path` dependencies\n# to registry (e.g., crates.io) dependencies.\n#\n# If you are reading this file be aware that the original Cargo.toml\n# will likely look very different (and much more reasonable).\n# See Cargo.toml.orig for the original contents.\n\n[package]\nedition = \"2018\"\nname = \"portable-pty-psmux\"\nversion = \"0.9.1\"\nauthors = [\"Wez Furlong\"]\nbuild = false\nautolib = false\nautobins = false\nautoexamples = false\nautotests = false\nautobenches = false\ndescription = \"Cross platform pty interface (psmux fork with ConPTY PASSTHROUGH_MODE + WIN32_INPUT_MODE + RESIZE_QUIRK patches)\"\ndocumentation = \"https://docs.rs/portable-pty\"\nreadme = false\nlicense = \"MIT\"\nrepository = \"https://github.com/marlocarlo/portable-pty-patched\"\ninclude = [\"src/**/*\", \"LICENSE.md\", \"README.md\", \"Cargo.toml\", \"examples/**/*\"]\nresolver = \"2\"\n\n[lib]\nname = \"portable_pty\"\npath = \"src/lib.rs\"\n\n[[example]]\nname = \"bash\"\npath = \"examples/bash.rs\"\n\n[[example]]\nname = \"narrow\"\npath = \"examples/narrow.rs\"\n\n[[example]]\nname = \"whoami\"\npath = \"examples/whoami.rs\"\n\n[[example]]\nname = \"whoami_async\"\npath = \"examples/whoami_async.rs\"\n\n[dependencies.anyhow]\nversion = \"1.0\"\n\n[dependencies.downcast-rs]\nversion = \"1.0\"\n\n[dependencies.filedescriptor]\nversion = \"0.8.3\"\n\n[dependencies.libc]\nversion = \"0.2\"\n\n[dependencies.log]\nversion = \"0.4\"\n\n[dependencies.nix]\nversion = \"0.28\"\nfeatures = [\n \"term\",\n \"fs\",\n]\n\n[dependencies.serde]\nversion = \"1.0\"\noptional = true\n\n[dependencies.serde_derive]\nversion = \"1.0\"\noptional = true\n\n[dependencies.serial2]\nversion = \"0.2\"\n\n[dependencies.shell-words]\nversion = \"1.1\"\n\n[dev-dependencies.futures]\nversion = \"0.3\"\n\n[dev-dependencies.smol]\nversion = \"2.0\"\n\n[features]\ndefault = []\nserde_support = [\n \"serde\",\n \"serde_derive\",\n]\n\n[target.\"cfg(windows)\".dependencies.bitflags]\nversion = \"1.3\"\n\n[target.\"cfg(windows)\".dependencies.lazy_static]\nversion = \"1.4\"\n\n[target.\"cfg(windows)\".dependencies.shared_library]\nversion = \"0.1\"\n\n[target.\"cfg(windows)\".dependencies.winapi]\nversion = \"0.3\"\nfeatures = [\n \"winuser\",\n \"consoleapi\",\n \"handleapi\",\n \"fileapi\",\n \"namedpipeapi\",\n \"synchapi\",\n \"libloaderapi\",\n \"winnt\",\n]\n\n[target.\"cfg(windows)\".dependencies.winreg]\nversion = \"0.10\"\n"
},
{
"path": "crates/portable-pty-psmux/LICENSE.md",
"content": "MIT License\n\nCopyright (c) 2018 Wez Furlong\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "crates/portable-pty-psmux/README.md",
"content": "# portable-pty-patched\n\nPatched version of [portable-pty](https://crates.io/crates/portable-pty) v0.9.0 (originally from [wez/wezterm](https://github.com/wez/wezterm)) with ConPTY flag support required by [psmux](https://github.com/psmux/psmux).\n\n## Why this exists\n\n`portable-pty` is not published as a standalone repo — it lives inside the wezterm monorepo, making a proper GitHub fork impractical (we'd be forking an entire terminal emulator project just for one file change).\n\nThe upstream crate does not pass modern ConPTY creation flags that psmux needs for correct terminal behavior on Windows 10/11.\n\n## Patches (`src/win/psuedocon.rs`)\n\n### New ConPTY flags\n- **`PSEUDOCONSOLE_RESIZE_QUIRK`** (0x2) — fixes resize artifacts\n- **`PSEUDOCONSOLE_WIN32_INPUT_MODE`** (0x4) — enables Win32 input mode for proper key handling\n- **`PSEUDOCONSOLE_PASSTHROUGH_MODE`** (0x8) — relays VT sequences directly from child processes (Windows 11 22H2+ only), enabling cursor shape forwarding, DECSCUSR, etc.\n\n### Build detection (`supports_passthrough_mode()`)\nUses `RtlGetVersion` to detect Windows build >= 22621 (Windows 11 22H2). On older builds, passthrough mode is skipped to avoid broken ConPTY output.\n\n### Two-tier `PsuedoCon::new()`\n1. Attempts `CreatePseudoConsole` with all flags including `PASSTHROUGH_MODE` on supported builds\n2. Falls back to base flags (without passthrough) if the call fails or on older Windows\n\n### Cargo.toml\nAdded `libloaderapi` and `winnt` features to `winapi` dependency for `GetModuleHandleW`/`GetProcAddress`/`RtlGetVersion`.\n\n## Usage\n\nIn your `Cargo.toml`:\n```toml\nportable-pty = { git = \"https://github.com/psmux/portable-pty-patched.git\", branch = \"main\" }\n```\n\n## Keeping up to date\n\nThis is **not** a GitHub fork (upstream lives inside wezterm monorepo). To sync with a new upstream release:\n1. Download the new version from [crates.io](https://crates.io/crates/portable-pty)\n2. Re-apply the patches to `src/win/psuedocon.rs` and `Cargo.toml`\n"
},
{
"path": "crates/portable-pty-psmux/examples/bash.rs",
"content": "//! This example demonstrates how to spawn a Bash shell using the `portable_pty` crate.\n//! based on pty/examples/whoami.rs\n\nuse portable_pty::{CommandBuilder, NativePtySystem, PtySize, PtySystem};\nuse std::io::{Read, Write};\nuse std::sync::mpsc::channel;\nuse std::thread;\n\nfn main() {\n let pty_system = NativePtySystem::default();\n\n // Open the PTY with specified size.\n let pair = pty_system\n .openpty(PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n })\n .unwrap();\n\n // Set up the command to launch Bash.\n let cmd = CommandBuilder::new(\"bash\");\n let mut child = pair.slave.spawn_command(cmd).unwrap();\n\n drop(pair.slave);\n\n // Set up channels for reading and writing.\n let (tx, rx) = channel::();\n let mut reader = pair.master.try_clone_reader().unwrap();\n let master_writer = pair.master.take_writer().unwrap();\n\n // Thread to read from the PTY and send data to the main thread.\n thread::spawn(move || {\n let mut buffer = [0u8; 1024];\n loop {\n match reader.read(&mut buffer) {\n Ok(0) => break, // EOF\n Ok(n) => {\n let output = String::from_utf8_lossy(&buffer[..n]);\n println!(\"{}\", output); // Print to stdout for visibility.\n }\n Err(e) => {\n eprintln!(\"Error reading from PTY: {}\", e);\n break;\n }\n }\n }\n });\n\n // Thread to write input into the PTY.\n let tx_writer = thread::spawn(move || {\n handle_input_stream(rx, master_writer);\n });\n\n println!(\"You can now type commands for Bash (type 'exit' to quit):\");\n\n // Main thread sends user input to the writer thread.\n loop {\n let mut input = String::new();\n std::io::stdin().read_line(&mut input).unwrap();\n\n if input.trim() == \"exit\" {\n break;\n }\n\n tx.send(input).unwrap();\n }\n\n drop(tx);\n tx_writer.join().unwrap();\n\n println!(\"Waiting for Bash to exit...\");\n let status = child.wait().unwrap();\n println!(\"Bash exited with status: {:?}\", status);\n}\n\nfn handle_input_stream(rx: std::sync::mpsc::Receiver, mut writer: Box) {\n for input in rx.iter() {\n if writer.write_all(input.as_bytes()).is_err() {\n eprintln!(\"Error writing to PTY\");\n break;\n }\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/examples/narrow.rs",
"content": "//! Runs a command with a fixed terminal size.\n//! This is used by wezterm's doc building automation to keep\n//! the --help output within a reasonable width\nuse portable_pty::{CommandBuilder, NativePtySystem, PtySize, PtySystem};\nuse std::sync::mpsc::channel;\n\nfn main() {\n let pty_system = NativePtySystem::default();\n\n let pair = pty_system\n .openpty(PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n })\n .unwrap();\n\n let mut args = std::env::args_os().skip(1);\n\n let mut cmd = CommandBuilder::new(args.next().unwrap());\n cmd.args(args);\n\n let mut child = pair.slave.spawn_command(cmd).unwrap();\n\n // Release any handles owned by the slave: we don't need it now\n // that we've spawned the child.\n drop(pair.slave);\n\n // Read the output in another thread.\n // This is important because it is easy to encounter a situation\n // where read/write buffers fill and block either your process\n // or the spawned process.\n let (tx, rx) = channel();\n let mut reader = pair.master.try_clone_reader().unwrap();\n std::thread::spawn(move || {\n // Consume the output from the child\n let mut s = String::new();\n reader.read_to_string(&mut s).unwrap();\n tx.send(s).unwrap();\n });\n\n {\n // Obtain the writer.\n // When the writer is dropped, EOF will be sent to\n // the program that was spawned.\n // It is important to take the writer even if you don't\n // send anything to its stdin so that EOF can be\n // generated, otherwise you risk deadlocking yourself.\n let mut writer = pair.master.take_writer().unwrap();\n\n if cfg!(target_os = \"macos\") {\n // macOS quirk: the child and reader must be started and\n // allowed a brief grace period to run before we allow\n // the writer to drop. Otherwise, the data we send to\n // the kernel to trigger EOF is interleaved with the\n // data read by the reader! WTF!?\n // This appears to be a race condition for very short\n // lived processes on macOS.\n // I'd love to find a more deterministic solution to\n // this than sleeping.\n std::thread::sleep(std::time::Duration::from_millis(20));\n }\n\n // This example doesn't need to write anything, but if you\n // want to send data to the child, you'd set `to_write` to\n // that data and do it like this:\n let to_write = \"\";\n if !to_write.is_empty() {\n // To avoid deadlock, wrt. reading and waiting, we send\n // data to the stdin of the child in a different thread.\n std::thread::spawn(move || {\n writer.write_all(to_write.as_bytes()).unwrap();\n });\n }\n }\n\n // Wait for the child to complete\n eprintln!(\"child status: {:?}\", child.wait().unwrap());\n\n // Take care to drop the master after our processes are\n // done, as some platforms get unhappy if it is dropped\n // sooner than that.\n drop(pair.master);\n\n // Now wait for the output to be read by our reader thread\n let output = rx.recv().unwrap();\n\n let output = output.replace(\"\\r\\n\", \"\\n\");\n\n print!(\"{output}\");\n}\n"
},
{
"path": "crates/portable-pty-psmux/examples/whoami.rs",
"content": "//! This is a conceptually simple example that spawns the `whoami` program\n//! to print your username. It is made more complex because there are multiple\n//! pipes involved and it is easy to get blocked/deadlocked if care and attention\n//! is not paid to those pipes!\nuse portable_pty::{CommandBuilder, NativePtySystem, PtySize, PtySystem};\nuse std::sync::mpsc::channel;\n\nfn main() {\n let pty_system = NativePtySystem::default();\n\n let pair = pty_system\n .openpty(PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n })\n .unwrap();\n\n let cmd = CommandBuilder::new(\"whoami\");\n let mut child = pair.slave.spawn_command(cmd).unwrap();\n\n // Release any handles owned by the slave: we don't need it now\n // that we've spawned the child.\n drop(pair.slave);\n\n // Read the output in another thread.\n // This is important because it is easy to encounter a situation\n // where read/write buffers fill and block either your process\n // or the spawned process.\n let (tx, rx) = channel();\n let mut reader = pair.master.try_clone_reader().unwrap();\n std::thread::spawn(move || {\n // Consume the output from the child\n let mut s = String::new();\n reader.read_to_string(&mut s).unwrap();\n tx.send(s).unwrap();\n });\n\n {\n // Obtain the writer.\n // When the writer is dropped, EOF will be sent to\n // the program that was spawned.\n // It is important to take the writer even if you don't\n // send anything to its stdin so that EOF can be\n // generated, otherwise you risk deadlocking yourself.\n let mut writer = pair.master.take_writer().unwrap();\n\n if cfg!(target_os = \"macos\") {\n // macOS quirk: the child and reader must be started and\n // allowed a brief grace period to run before we allow\n // the writer to drop. Otherwise, the data we send to\n // the kernel to trigger EOF is interleaved with the\n // data read by the reader! WTF!?\n // This appears to be a race condition for very short\n // lived processes on macOS.\n // I'd love to find a more deterministic solution to\n // this than sleeping.\n std::thread::sleep(std::time::Duration::from_millis(20));\n }\n\n // This example doesn't need to write anything, but if you\n // want to send data to the child, you'd set `to_write` to\n // that data and do it like this:\n let to_write = \"\";\n if !to_write.is_empty() {\n // To avoid deadlock, wrt. reading and waiting, we send\n // data to the stdin of the child in a different thread.\n std::thread::spawn(move || {\n writer.write_all(to_write.as_bytes()).unwrap();\n });\n }\n }\n\n // Wait for the child to complete\n println!(\"child status: {:?}\", child.wait().unwrap());\n\n // Take care to drop the master after our processes are\n // done, as some platforms get unhappy if it is dropped\n // sooner than that.\n drop(pair.master);\n\n // Now wait for the output to be read by our reader thread\n let output = rx.recv().unwrap();\n\n // We print with escapes escaped because the windows conpty\n // implementation synthesizes title change escape sequences\n // in the output stream and it can be confusing to see those\n // printed out raw in another terminal.\n print!(\"output: \");\n for c in output.escape_debug() {\n print!(\"{}\", c);\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/examples/whoami_async.rs",
"content": "use anyhow::anyhow;\nuse futures::prelude::*;\nuse portable_pty::{native_pty_system, CommandBuilder, PtySize};\n\n// This example shows how to use the `smol` crate to use portable_pty\n// in an asynchronous application.\n\nfn main() -> anyhow::Result<()> {\n smol::block_on(async {\n let pty_system = native_pty_system();\n\n let pair = pty_system.openpty(PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n })?;\n\n let cmd = CommandBuilder::new(\"whoami\");\n\n // Move the slave to another thread to block and spawn a\n // command.\n // Note that this implicitly drops slave and closes out\n // file handles which is important to avoid deadlock\n // when waiting for the child process!\n let slave = pair.slave;\n let mut child = smol::unblock(move || slave.spawn_command(cmd)).await?;\n\n {\n // Obtain the writer.\n // When the writer is dropped, EOF will be sent to\n // the program that was spawned.\n // It is important to take the writer even if you don't\n // send anything to its stdin so that EOF can be\n // generated, otherwise you risk deadlocking yourself.\n let writer = pair.master.take_writer()?;\n\n // Explicitly generate EOF\n drop(writer);\n }\n\n println!(\n \"child status: {:?}\",\n smol::unblock(move || child\n .wait()\n .map_err(|e| anyhow!(\"waiting for child: {}\", e)))\n .await?\n );\n\n let reader = pair.master.try_clone_reader()?;\n\n // Take care to drop the master after our processes are\n // done, as some platforms get unhappy if it is dropped\n // sooner than that.\n drop(pair.master);\n\n let mut lines = smol::io::BufReader::new(smol::Unblock::new(reader)).lines();\n while let Some(line) = lines.next().await {\n let line = line.map_err(|e| anyhow!(\"problem reading line: {}\", e))?;\n // We print with escapes escaped because the windows conpty\n // implementation synthesizes title change escape sequences\n // in the output stream and it can be confusing to see those\n // printed out raw in another terminal.\n print!(\"output: len={} \", line.len());\n for c in line.escape_debug() {\n print!(\"{}\", c);\n }\n println!();\n }\n\n Ok(())\n })\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/cmdbuilder.rs",
"content": "#[cfg(unix)]\nuse anyhow::Context;\n#[cfg(feature = \"serde_support\")]\nuse serde_derive::*;\nuse std::collections::BTreeMap;\nuse std::ffi::{OsStr, OsString};\n#[cfg(windows)]\nuse std::os::windows::ffi::OsStrExt;\n#[cfg(unix)]\nuse std::path::Component;\nuse std::path::Path;\n\n/// Used to deal with Windows having case-insensitive environment variables.\n#[derive(Clone, Debug, PartialEq, PartialOrd)]\n#[cfg_attr(feature = \"serde_support\", derive(Serialize, Deserialize))]\nstruct EnvEntry {\n /// Whether or not this environment variable came from the base environment,\n /// as opposed to having been explicitly set by the caller.\n is_from_base_env: bool,\n\n /// For case-insensitive platforms, the environment variable key in its preferred casing.\n preferred_key: OsString,\n\n /// The environment variable value.\n value: OsString,\n}\n\nimpl EnvEntry {\n fn map_key(k: OsString) -> OsString {\n if cfg!(windows) {\n // Best-effort lowercase transformation of an os string\n match k.to_str() {\n Some(s) => s.to_lowercase().into(),\n None => k,\n }\n } else {\n k\n }\n }\n}\n\n#[cfg(unix)]\nfn get_shell() -> String {\n use nix::unistd::{access, AccessFlags};\n use std::ffi::CStr;\n use std::str;\n\n let ent = unsafe { libc::getpwuid(libc::getuid()) };\n if !ent.is_null() {\n let shell = unsafe { CStr::from_ptr((*ent).pw_shell) };\n match shell.to_str().map(str::to_owned) {\n Err(err) => {\n log::warn!(\n \"passwd database shell could not be \\\n represented as utf-8: {err:#}, \\\n falling back to /bin/sh\"\n );\n }\n Ok(shell) => {\n if let Err(err) = access(Path::new(&shell), AccessFlags::X_OK) {\n log::warn!(\n \"passwd database shell={shell:?} which is \\\n not executable ({err:#}), falling back to /bin/sh\"\n );\n } else {\n return shell;\n }\n }\n }\n }\n \"/bin/sh\".into()\n}\n\nfn get_base_env() -> BTreeMap {\n let mut env: BTreeMap = std::env::vars_os()\n .map(|(key, value)| {\n (\n EnvEntry::map_key(key.clone()),\n EnvEntry {\n is_from_base_env: true,\n preferred_key: key,\n value,\n },\n )\n })\n .collect();\n\n #[cfg(unix)]\n {\n let key = EnvEntry::map_key(\"SHELL\".into());\n // Only set the value of SHELL if it isn't already set\n if !env.contains_key(&key) {\n env.insert(\n EnvEntry::map_key(\"SHELL\".into()),\n EnvEntry {\n is_from_base_env: true,\n preferred_key: \"SHELL\".into(),\n value: get_shell().into(),\n },\n );\n }\n }\n\n #[cfg(windows)]\n {\n use std::os::windows::ffi::OsStringExt;\n use winapi::um::processenv::ExpandEnvironmentStringsW;\n use winreg::enums::{RegType, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE};\n use winreg::types::FromRegValue;\n use winreg::{RegKey, RegValue};\n\n fn reg_value_to_string(value: &RegValue) -> anyhow::Result {\n match value.vtype {\n RegType::REG_EXPAND_SZ => {\n let src = unsafe {\n std::slice::from_raw_parts(\n value.bytes.as_ptr() as *const u16,\n value.bytes.len() / 2,\n )\n };\n let size =\n unsafe { ExpandEnvironmentStringsW(src.as_ptr(), std::ptr::null_mut(), 0) };\n let mut buf = vec![0u16; size as usize + 1];\n unsafe {\n ExpandEnvironmentStringsW(src.as_ptr(), buf.as_mut_ptr(), buf.len() as u32)\n };\n\n let mut buf = buf.as_slice();\n while let Some(0) = buf.last() {\n buf = &buf[0..buf.len() - 1];\n }\n Ok(OsString::from_wide(buf))\n }\n _ => Ok(OsString::from_reg_value(value)?),\n }\n }\n\n if let Ok(sys_env) = RegKey::predef(HKEY_LOCAL_MACHINE)\n .open_subkey(\"System\\\\CurrentControlSet\\\\Control\\\\Session Manager\\\\Environment\")\n {\n for res in sys_env.enum_values() {\n if let Ok((name, value)) = res {\n if name.eq_ignore_ascii_case(\"username\") {\n continue;\n }\n if let Ok(value) = reg_value_to_string(&value) {\n log::trace!(\"adding SYS env: {:?} {:?}\", name, value);\n env.insert(\n EnvEntry::map_key(name.clone().into()),\n EnvEntry {\n is_from_base_env: true,\n preferred_key: name.into(),\n value,\n },\n );\n }\n }\n }\n }\n\n if let Ok(sys_env) = RegKey::predef(HKEY_CURRENT_USER).open_subkey(\"Environment\") {\n for res in sys_env.enum_values() {\n if let Ok((name, value)) = res {\n if let Ok(value) = reg_value_to_string(&value) {\n // Merge the system and user paths together\n let value = if name.eq_ignore_ascii_case(\"path\") {\n match env.get(&EnvEntry::map_key(name.clone().into())) {\n Some(entry) => {\n let mut result = OsString::new();\n result.push(&entry.value);\n result.push(\";\");\n result.push(&value);\n result\n }\n None => value,\n }\n } else {\n value\n };\n\n log::trace!(\"adding USER env: {:?} {:?}\", name, value);\n env.insert(\n EnvEntry::map_key(name.clone().into()),\n EnvEntry {\n is_from_base_env: true,\n preferred_key: name.into(),\n value,\n },\n );\n }\n }\n }\n }\n }\n\n env\n}\n\n/// `CommandBuilder` is used to prepare a command to be spawned into a pty.\n/// The interface is intentionally similar to that of `std::process::Command`.\n#[derive(Clone, Debug, PartialEq)]\n#[cfg_attr(feature = \"serde_support\", derive(Serialize, Deserialize))]\npub struct CommandBuilder {\n args: Vec,\n envs: BTreeMap,\n cwd: Option,\n #[cfg(unix)]\n pub(crate) umask: Option,\n controlling_tty: bool,\n}\n\nimpl CommandBuilder {\n /// Create a new builder instance with argv\\[0\\] set to the specified\n /// program.\n pub fn new>(program: S) -> Self {\n Self {\n args: vec![program.as_ref().to_owned()],\n envs: get_base_env(),\n cwd: None,\n #[cfg(unix)]\n umask: None,\n controlling_tty: true,\n }\n }\n\n /// Create a new builder instance from a pre-built argument vector\n pub fn from_argv(args: Vec) -> Self {\n Self {\n args,\n envs: get_base_env(),\n cwd: None,\n #[cfg(unix)]\n umask: None,\n controlling_tty: true,\n }\n }\n\n /// Set whether we should set the pty as the controlling terminal.\n /// The default is true, which is usually what you want, but you\n /// may need to set this to false if you are crossing container\n /// boundaries (eg: flatpak) to workaround issues like:\n /// \n /// \n pub fn set_controlling_tty(&mut self, controlling_tty: bool) {\n self.controlling_tty = controlling_tty;\n }\n\n pub fn get_controlling_tty(&self) -> bool {\n self.controlling_tty\n }\n\n /// Create a new builder instance that will run some idea of a default\n /// program. Such a builder will panic if `arg` is called on it.\n pub fn new_default_prog() -> Self {\n Self {\n args: vec![],\n envs: get_base_env(),\n cwd: None,\n #[cfg(unix)]\n umask: None,\n controlling_tty: true,\n }\n }\n\n /// Returns true if this builder was created via `new_default_prog`\n pub fn is_default_prog(&self) -> bool {\n self.args.is_empty()\n }\n\n /// Append an argument to the current command line.\n /// Will panic if called on a builder created via `new_default_prog`.\n pub fn arg>(&mut self, arg: S) {\n if self.is_default_prog() {\n panic!(\"attempted to add args to a default_prog builder\");\n }\n self.args.push(arg.as_ref().to_owned());\n }\n\n /// Append a sequence of arguments to the current command line\n pub fn args(&mut self, args: I)\n where\n I: IntoIterator,\n S: AsRef,\n {\n for arg in args {\n self.arg(arg);\n }\n }\n\n pub fn get_argv(&self) -> &Vec {\n &self.args\n }\n\n pub fn get_argv_mut(&mut self) -> &mut Vec {\n &mut self.args\n }\n\n /// Override the value of an environmental variable\n pub fn env(&mut self, key: K, value: V)\n where\n K: AsRef,\n V: AsRef,\n {\n let key: OsString = key.as_ref().into();\n let value: OsString = value.as_ref().into();\n self.envs.insert(\n EnvEntry::map_key(key.clone()),\n EnvEntry {\n is_from_base_env: false,\n preferred_key: key,\n value: value,\n },\n );\n }\n\n pub fn env_remove(&mut self, key: K)\n where\n K: AsRef,\n {\n let key = key.as_ref().into();\n self.envs.remove(&EnvEntry::map_key(key));\n }\n\n pub fn env_clear(&mut self) {\n self.envs.clear();\n }\n\n pub fn get_env(&self, key: K) -> Option<&OsStr>\n where\n K: AsRef,\n {\n let key = key.as_ref().into();\n self.envs.get(&EnvEntry::map_key(key)).map(\n |EnvEntry {\n is_from_base_env: _,\n preferred_key: _,\n value,\n }| value.as_os_str(),\n )\n }\n\n pub fn cwd(&mut self, dir: D)\n where\n D: AsRef,\n {\n self.cwd = Some(dir.as_ref().to_owned());\n }\n\n pub fn clear_cwd(&mut self) {\n self.cwd.take();\n }\n\n pub fn get_cwd(&self) -> Option<&OsString> {\n self.cwd.as_ref()\n }\n\n /// Iterate over the configured environment. Only includes environment\n /// variables set by the caller via `env`, not variables set in the base\n /// environment.\n pub fn iter_extra_env_as_str(&self) -> impl Iterator {\n self.envs.values().filter_map(\n |EnvEntry {\n is_from_base_env,\n preferred_key,\n value,\n }| {\n if *is_from_base_env {\n None\n } else {\n let key = preferred_key.to_str()?;\n let value = value.to_str()?;\n Some((key, value))\n }\n },\n )\n }\n\n pub fn iter_full_env_as_str(&self) -> impl Iterator {\n self.envs.values().filter_map(\n |EnvEntry {\n preferred_key,\n value,\n ..\n }| {\n let key = preferred_key.to_str()?;\n let value = value.to_str()?;\n Some((key, value))\n },\n )\n }\n\n /// Return the configured command and arguments as a single string,\n /// quoted per the unix shell conventions.\n pub fn as_unix_command_line(&self) -> anyhow::Result {\n let mut strs = vec![];\n for arg in &self.args {\n let s = arg\n .to_str()\n .ok_or_else(|| anyhow::anyhow!(\"argument cannot be represented as utf8\"))?;\n strs.push(s);\n }\n Ok(shell_words::join(strs))\n }\n}\n\n#[cfg(unix)]\nimpl CommandBuilder {\n pub fn umask(&mut self, mask: Option) {\n self.umask = mask;\n }\n\n fn resolve_path(&self) -> Option<&OsStr> {\n self.get_env(\"PATH\")\n }\n\n fn search_path(&self, exe: &OsStr, cwd: &OsStr) -> anyhow::Result {\n use nix::unistd::{access, AccessFlags};\n\n let exe_path: &Path = exe.as_ref();\n if exe_path.is_relative() {\n let cwd: &Path = cwd.as_ref();\n let mut errors = vec![];\n\n // If the requested executable is explicitly relative to cwd,\n // then check only there.\n if is_cwd_relative_path(exe_path) {\n let abs_path = cwd.join(exe_path);\n\n if abs_path.is_dir() {\n anyhow::bail!(\n \"Unable to spawn {} because it is a directory\",\n abs_path.display()\n );\n } else if access(&abs_path, AccessFlags::X_OK).is_ok() {\n return Ok(abs_path.into_os_string());\n } else if access(&abs_path, AccessFlags::F_OK).is_ok() {\n anyhow::bail!(\n \"Unable to spawn {} because it is not executable\",\n abs_path.display()\n );\n }\n\n anyhow::bail!(\n \"Unable to spawn {} because it does not exist\",\n abs_path.display()\n );\n }\n\n if let Some(path) = self.resolve_path() {\n for path in std::env::split_paths(&path) {\n let candidate = cwd.join(&path).join(&exe);\n\n if candidate.is_dir() {\n errors.push(format!(\"{} exists but is a directory\", candidate.display()));\n } else if access(&candidate, AccessFlags::X_OK).is_ok() {\n return Ok(candidate.into_os_string());\n } else if access(&candidate, AccessFlags::F_OK).is_ok() {\n errors.push(format!(\n \"{} exists but is not executable\",\n candidate.display()\n ));\n }\n }\n errors.push(format!(\"No viable candidates found in PATH {path:?}\"));\n } else {\n errors.push(\"Unable to resolve the PATH\".to_string());\n }\n anyhow::bail!(\n \"Unable to spawn {} because:\\n{}\",\n exe_path.display(),\n errors.join(\".\\n\")\n );\n } else if exe_path.is_dir() {\n anyhow::bail!(\n \"Unable to spawn {} because it is a directory\",\n exe_path.display()\n );\n } else {\n if let Err(err) = access(exe_path, AccessFlags::X_OK) {\n if access(exe_path, AccessFlags::F_OK).is_ok() {\n anyhow::bail!(\n \"Unable to spawn {} because it is not executable ({err:#})\",\n exe_path.display()\n );\n } else {\n anyhow::bail!(\n \"Unable to spawn {} because it doesn't exist on the filesystem ({err:#})\",\n exe_path.display()\n );\n }\n }\n\n Ok(exe.to_owned())\n }\n }\n\n /// Convert the CommandBuilder to a `std::process::Command` instance.\n pub(crate) fn as_command(&self) -> anyhow::Result {\n use std::os::unix::process::CommandExt;\n\n let home = self.get_home_dir()?;\n let dir: &OsStr = self\n .cwd\n .as_ref()\n .map(|dir| dir.as_os_str())\n .filter(|dir| std::path::Path::new(dir).is_dir())\n .unwrap_or(home.as_ref());\n let shell = self.get_shell();\n\n let mut cmd = if self.is_default_prog() {\n let mut cmd = std::process::Command::new(&shell);\n\n // Run the shell as a login shell by prefixing the shell's\n // basename with `-` and setting that as argv0\n let basename = shell.rsplit('/').next().unwrap_or(&shell);\n cmd.arg0(&format!(\"-{}\", basename));\n cmd\n } else {\n let resolved = self.search_path(&self.args[0], dir)?;\n let mut cmd = std::process::Command::new(&resolved);\n cmd.arg0(&self.args[0]);\n cmd.args(&self.args[1..]);\n cmd\n };\n\n cmd.current_dir(dir);\n\n cmd.env_clear();\n cmd.env(\"SHELL\", shell);\n cmd.envs(self.envs.values().map(\n |EnvEntry {\n is_from_base_env: _,\n preferred_key,\n value,\n }| (preferred_key.as_os_str(), value.as_os_str()),\n ));\n\n Ok(cmd)\n }\n\n /// Determine which shell to run.\n /// We take the contents of the $SHELL env var first, then\n /// fall back to looking it up from the password database.\n pub fn get_shell(&self) -> String {\n use nix::unistd::{access, AccessFlags};\n\n if let Some(shell) = self.get_env(\"SHELL\").and_then(OsStr::to_str) {\n match access(shell, AccessFlags::X_OK) {\n Ok(()) => return shell.into(),\n Err(err) => log::warn!(\n \"$SHELL -> {shell:?} which is \\\n not executable ({err:#}), falling back to password db lookup\"\n ),\n }\n }\n\n get_shell().into()\n }\n\n fn get_home_dir(&self) -> anyhow::Result {\n if let Some(home_dir) = self.get_env(\"HOME\").and_then(OsStr::to_str) {\n return Ok(home_dir.into());\n }\n\n let ent = unsafe { libc::getpwuid(libc::getuid()) };\n if ent.is_null() {\n Ok(\"/\".into())\n } else {\n use std::ffi::CStr;\n use std::str;\n let home = unsafe { CStr::from_ptr((*ent).pw_dir) };\n home.to_str()\n .map(str::to_owned)\n .context(\"failed to resolve home dir\")\n }\n }\n}\n\n#[cfg(windows)]\nimpl CommandBuilder {\n fn search_path(&self, exe: &OsStr) -> OsString {\n if let Some(path) = self.get_env(\"PATH\") {\n let extensions = self.get_env(\"PATHEXT\").unwrap_or(OsStr::new(\".EXE\"));\n for path in std::env::split_paths(&path) {\n // Check for exactly the user's string in this path dir\n let candidate = path.join(&exe);\n if candidate.exists() {\n return candidate.into_os_string();\n }\n\n // otherwise try tacking on some extensions.\n // Note that this really replaces the extension in the\n // user specified path, so this is potentially wrong.\n for ext in std::env::split_paths(&extensions) {\n // PATHEXT includes the leading `.`, but `with_extension`\n // doesn't want that\n let ext = ext.to_str().expect(\"PATHEXT entries must be utf8\");\n let path = path.join(&exe).with_extension(&ext[1..]);\n if path.exists() {\n return path.into_os_string();\n }\n }\n }\n }\n\n exe.to_owned()\n }\n\n pub(crate) fn current_directory(&self) -> Option> {\n let home: Option<&OsStr> = self\n .get_env(\"USERPROFILE\")\n .filter(|path| Path::new(path).is_dir());\n let cwd: Option<&OsStr> = self.cwd.as_deref().filter(|path| Path::new(path).is_dir());\n let dir: Option<&OsStr> = cwd.or(home);\n\n dir.map(|dir| {\n let mut wide = vec![];\n\n if Path::new(dir).is_relative() {\n if let Ok(ccwd) = std::env::current_dir() {\n wide.extend(ccwd.join(dir).as_os_str().encode_wide());\n } else {\n wide.extend(dir.encode_wide());\n }\n } else {\n wide.extend(dir.encode_wide());\n }\n\n wide.push(0);\n wide\n })\n }\n\n /// Constructs an environment block for this spawn attempt.\n /// Uses the current process environment as the base and then\n /// adds/replaces the environment that was specified via the\n /// `env` methods.\n pub(crate) fn environment_block(&self) -> Vec {\n // encode the environment as wide characters\n let mut block = vec![];\n\n for EnvEntry {\n is_from_base_env: _,\n preferred_key,\n value,\n } in self.envs.values()\n {\n block.extend(preferred_key.encode_wide());\n block.push(b'=' as u16);\n block.extend(value.encode_wide());\n block.push(0);\n }\n // and a final terminator for CreateProcessW\n block.push(0);\n\n block\n }\n\n pub fn get_shell(&self) -> String {\n let exe: OsString = self\n .get_env(\"ComSpec\")\n .unwrap_or(OsStr::new(\"cmd.exe\"))\n .into();\n exe.into_string()\n .unwrap_or_else(|_| \"%CompSpec%\".to_string())\n }\n\n pub(crate) fn cmdline(&self) -> anyhow::Result<(Vec, Vec)> {\n let mut cmdline = Vec::::new();\n\n let exe: OsString = if self.is_default_prog() {\n self.get_env(\"ComSpec\")\n .unwrap_or(OsStr::new(\"cmd.exe\"))\n .into()\n } else {\n self.search_path(&self.args[0])\n };\n\n Self::append_quoted(&exe, &mut cmdline);\n\n // Ensure that we nul terminate the module name, otherwise we'll\n // ask CreateProcessW to start something random!\n let mut exe: Vec = exe.encode_wide().collect();\n exe.push(0);\n\n for arg in self.args.iter().skip(1) {\n cmdline.push(' ' as u16);\n anyhow::ensure!(\n !arg.encode_wide().any(|c| c == 0),\n \"invalid encoding for command line argument {:?}\",\n arg\n );\n Self::append_quoted(arg, &mut cmdline);\n }\n // Ensure that the command line is nul terminated too!\n cmdline.push(0);\n Ok((exe, cmdline))\n }\n\n // Borrowed from https://github.com/hniksic/rust-subprocess/blob/873dfed165173e52907beb87118b2c0c05d8b8a1/src/popen.rs#L1117\n // which in turn was translated from ArgvQuote at http://tinyurl.com/zmgtnls\n fn append_quoted(arg: &OsStr, cmdline: &mut Vec) {\n if !arg.is_empty()\n && !arg.encode_wide().any(|c| {\n c == ' ' as u16\n || c == '\\t' as u16\n || c == '\\n' as u16\n || c == '\\x0b' as u16\n || c == '\\\"' as u16\n })\n {\n cmdline.extend(arg.encode_wide());\n return;\n }\n cmdline.push('\"' as u16);\n\n let arg: Vec<_> = arg.encode_wide().collect();\n let mut i = 0;\n while i < arg.len() {\n let mut num_backslashes = 0;\n while i < arg.len() && arg[i] == '\\\\' as u16 {\n i += 1;\n num_backslashes += 1;\n }\n\n if i == arg.len() {\n for _ in 0..num_backslashes * 2 {\n cmdline.push('\\\\' as u16);\n }\n break;\n } else if arg[i] == b'\"' as u16 {\n for _ in 0..num_backslashes * 2 + 1 {\n cmdline.push('\\\\' as u16);\n }\n cmdline.push(arg[i]);\n } else {\n for _ in 0..num_backslashes {\n cmdline.push('\\\\' as u16);\n }\n cmdline.push(arg[i]);\n }\n i += 1;\n }\n cmdline.push('\"' as u16);\n }\n}\n\n#[cfg(unix)]\n/// Returns true if the path begins with `./` or `../`\nfn is_cwd_relative_path>(p: P) -> bool {\n matches!(\n p.as_ref().components().next(),\n Some(Component::CurDir | Component::ParentDir)\n )\n}\n\n#[cfg(test)]\n#[path = \"../../../tests-rs/test_cmdbuilder.rs\"]\nmod tests;\n"
},
{
"path": "crates/portable-pty-psmux/src/lib.rs",
"content": "//! This crate provides a cross platform API for working with the\n//! psuedo terminal (pty) interfaces provided by the system.\n//! Unlike other crates in this space, this crate provides a set\n//! of traits that allow selecting from different implementations\n//! at runtime.\n//! This crate is part of [wezterm](https://github.com/wezterm/wezterm).\n//!\n//! ```no_run\n//! use portable_pty::{CommandBuilder, PtySize, native_pty_system, PtySystem};\n//! use anyhow::Error;\n//!\n//! // Use the native pty implementation for the system\n//! let pty_system = native_pty_system();\n//!\n//! // Create a new pty\n//! let mut pair = pty_system.openpty(PtySize {\n//! rows: 24,\n//! cols: 80,\n//! // Not all systems support pixel_width, pixel_height,\n//! // but it is good practice to set it to something\n//! // that matches the size of the selected font. That\n//! // is more complex than can be shown here in this\n//! // brief example though!\n//! pixel_width: 0,\n//! pixel_height: 0,\n//! })?;\n//!\n//! // Spawn a shell into the pty\n//! let cmd = CommandBuilder::new(\"bash\");\n//! let child = pair.slave.spawn_command(cmd)?;\n//!\n//! // Read and parse output from the pty with reader\n//! let mut reader = pair.master.try_clone_reader()?;\n//!\n//! // Send data to the pty by writing to the master\n//! writeln!(pair.master.take_writer()?, \"ls -l\\r\\n\")?;\n//! # Ok::<(), Error>(())\n//! ```\n//!\nuse anyhow::Error;\nuse downcast_rs::{impl_downcast, Downcast};\n#[cfg(unix)]\nuse libc;\n#[cfg(feature = \"serde_support\")]\nuse serde_derive::*;\nuse std::io::Result as IoResult;\n#[cfg(windows)]\nuse std::os::windows::prelude::{AsRawHandle, RawHandle};\n\npub mod cmdbuilder;\npub use cmdbuilder::CommandBuilder;\n\n#[cfg(unix)]\npub mod unix;\n#[cfg(windows)]\npub mod win;\n\npub mod serial;\n\n/// Represents the size of the visible display area in the pty\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\n#[cfg_attr(feature = \"serde_support\", derive(Serialize, Deserialize))]\npub struct PtySize {\n /// The number of lines of text\n pub rows: u16,\n /// The number of columns of text\n pub cols: u16,\n /// The width of a cell in pixels. Note that some systems never\n /// fill this value and ignore it.\n pub pixel_width: u16,\n /// The height of a cell in pixels. Note that some systems never\n /// fill this value and ignore it.\n pub pixel_height: u16,\n}\n\nimpl Default for PtySize {\n fn default() -> Self {\n PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n }\n }\n}\n\n/// Represents the master/control end of the pty\npub trait MasterPty: Downcast + Send {\n /// Inform the kernel and thus the child process that the window resized.\n /// It will update the winsize information maintained by the kernel,\n /// and generate a signal for the child to notice and update its state.\n fn resize(&self, size: PtySize) -> Result<(), Error>;\n /// Retrieves the size of the pty as known by the kernel\n fn get_size(&self) -> Result;\n /// Obtain a readable handle; output from the slave(s) is readable\n /// via this stream.\n fn try_clone_reader(&self) -> Result, Error>;\n /// Obtain a writable handle; writing to it will send data to the\n /// slave end.\n /// Dropping the writer will send EOF to the slave end.\n /// It is invalid to take the writer more than once.\n fn take_writer(&self) -> Result, Error>;\n\n /// If applicable to the type of the tty, return the local process id\n /// of the process group or session leader\n #[cfg(unix)]\n fn process_group_leader(&self) -> Option;\n\n /// If get_termios() and process_group_leader() are both implemented and\n /// return Some, then as_raw_fd() should return the same underlying fd\n /// associated with the stream. This is to enable applications that\n /// \"know things\" to query similar information for themselves.\n #[cfg(unix)]\n fn as_raw_fd(&self) -> Option;\n\n #[cfg(unix)]\n fn tty_name(&self) -> Option;\n\n /// If applicable to the type of the tty, return the termios\n /// associated with the stream\n #[cfg(unix)]\n fn get_termios(&self) -> Option {\n None\n }\n}\nimpl_downcast!(MasterPty);\n\n/// Represents a child process spawned into the pty.\n/// This handle can be used to wait for or terminate that child process.\npub trait Child: std::fmt::Debug + ChildKiller + Downcast + Send {\n /// Poll the child to see if it has completed.\n /// Does not block.\n /// Returns None if the child has not yet terminated,\n /// else returns its exit status.\n fn try_wait(&mut self) -> IoResult>;\n /// Blocks execution until the child process has completed,\n /// yielding its exit status.\n fn wait(&mut self) -> IoResult;\n /// Returns the process identifier of the child process,\n /// if applicable\n fn process_id(&self) -> Option;\n /// Returns the process handle of the child process, if applicable.\n /// Only available on Windows.\n #[cfg(windows)]\n fn as_raw_handle(&self) -> Option;\n}\nimpl_downcast!(Child);\n\n/// Represents the ability to signal a Child to terminate\npub trait ChildKiller: std::fmt::Debug + Downcast + Send {\n /// Terminate the child process\n fn kill(&mut self) -> IoResult<()>;\n\n /// Clone an object that can be split out from the Child in order\n /// to send it signals independently from a thread that may be\n /// blocked in `.wait`.\n fn clone_killer(&self) -> Box;\n}\nimpl_downcast!(ChildKiller);\n\n/// Represents the slave side of a pty.\n/// Can be used to spawn processes into the pty.\npub trait SlavePty {\n /// Spawns the command specified by the provided CommandBuilder\n fn spawn_command(&self, cmd: CommandBuilder) -> Result, Error>;\n}\n\n/// Represents the exit status of a child process.\n#[derive(Debug, Clone)]\npub struct ExitStatus {\n code: u32,\n signal: Option,\n}\n\nimpl ExitStatus {\n /// Construct an ExitStatus from a process return code\n pub fn with_exit_code(code: u32) -> Self {\n Self { code, signal: None }\n }\n\n /// Construct an ExitStatus from a signal name\n pub fn with_signal(signal: &str) -> Self {\n Self {\n code: 1,\n signal: Some(signal.to_string()),\n }\n }\n\n /// Returns true if the status indicates successful completion\n pub fn success(&self) -> bool {\n match self.signal {\n None => self.code == 0,\n Some(_) => false,\n }\n }\n\n /// Returns the exit code that this ExitStatus was constructed with\n pub fn exit_code(&self) -> u32 {\n self.code\n }\n\n /// Returns the signal if present that this ExitStatus was constructed with\n pub fn signal(&self) -> Option<&str> {\n self.signal.as_deref()\n }\n}\n\nimpl From for ExitStatus {\n fn from(status: std::process::ExitStatus) -> ExitStatus {\n #[cfg(unix)]\n {\n use std::os::unix::process::ExitStatusExt;\n\n if let Some(signal) = status.signal() {\n let signame = unsafe { libc::strsignal(signal) };\n let signal = if signame.is_null() {\n format!(\"Signal {}\", signal)\n } else {\n let signame = unsafe { std::ffi::CStr::from_ptr(signame) };\n signame.to_string_lossy().to_string()\n };\n\n return ExitStatus {\n code: status.code().map(|c| c as u32).unwrap_or(1),\n signal: Some(signal),\n };\n }\n }\n\n let code =\n status\n .code()\n .map(|c| c as u32)\n .unwrap_or_else(|| if status.success() { 0 } else { 1 });\n\n ExitStatus { code, signal: None }\n }\n}\n\nimpl std::fmt::Display for ExitStatus {\n fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {\n if self.success() {\n write!(fmt, \"Success\")\n } else {\n match &self.signal {\n Some(sig) => write!(fmt, \"Terminated by {}\", sig),\n None => write!(fmt, \"Exited with code {}\", self.code),\n }\n }\n }\n}\n\npub struct PtyPair {\n // slave is listed first so that it is dropped first.\n // The drop order is stable and specified by rust rfc 1857\n pub slave: Box,\n pub master: Box,\n}\n\n/// The `PtySystem` trait allows an application to work with multiple\n/// possible Pty implementations at runtime. This is important on\n/// Windows systems which have a variety of implementations.\npub trait PtySystem: Downcast {\n /// Create a new Pty instance with the window size set to the specified\n /// dimensions. Returns a (master, slave) Pty pair. The master side\n /// is used to drive the slave side.\n fn openpty(&self, size: PtySize) -> anyhow::Result;\n}\nimpl_downcast!(PtySystem);\n\nimpl Child for std::process::Child {\n fn try_wait(&mut self) -> IoResult> {\n std::process::Child::try_wait(self).map(|s| match s {\n Some(s) => Some(s.into()),\n None => None,\n })\n }\n\n fn wait(&mut self) -> IoResult {\n std::process::Child::wait(self).map(Into::into)\n }\n\n fn process_id(&self) -> Option {\n Some(self.id())\n }\n\n #[cfg(windows)]\n fn as_raw_handle(&self) -> Option {\n Some(std::os::windows::io::AsRawHandle::as_raw_handle(self))\n }\n}\n\n#[derive(Debug)]\nstruct ProcessSignaller {\n pid: Option,\n\n #[cfg(windows)]\n handle: Option,\n}\n\n#[cfg(windows)]\nimpl ChildKiller for ProcessSignaller {\n fn kill(&mut self) -> IoResult<()> {\n if let Some(handle) = &self.handle {\n unsafe {\n if winapi::um::processthreadsapi::TerminateProcess(handle.as_raw_handle() as _, 127)\n == 0\n {\n return Err(std::io::Error::last_os_error());\n }\n }\n }\n Ok(())\n }\n fn clone_killer(&self) -> Box {\n Box::new(Self {\n pid: self.pid,\n handle: self.handle.as_ref().and_then(|h| h.try_clone().ok()),\n })\n }\n}\n\n#[cfg(unix)]\nimpl ChildKiller for ProcessSignaller {\n fn kill(&mut self) -> IoResult<()> {\n if let Some(pid) = self.pid {\n let result = unsafe { libc::kill(pid as i32, libc::SIGHUP) };\n if result != 0 {\n return Err(std::io::Error::last_os_error());\n }\n }\n Ok(())\n }\n\n fn clone_killer(&self) -> Box {\n Box::new(Self { pid: self.pid })\n }\n}\n\nimpl ChildKiller for std::process::Child {\n fn kill(&mut self) -> IoResult<()> {\n #[cfg(unix)]\n {\n // On unix, we send the SIGHUP signal instead of trying to kill\n // the process. The default behavior of a process receiving this\n // signal is to be killed unless it configured a signal handler.\n let result = unsafe { libc::kill(self.id() as i32, libc::SIGHUP) };\n if result != 0 {\n return Err(std::io::Error::last_os_error());\n }\n\n // We successfully delivered SIGHUP, but the semantics of Child::kill\n // are that on success the process is dead or shortly about to\n // terminate. Since SIGUP doesn't guarantee termination, we\n // give the process a bit of a grace period to shutdown or do whatever\n // it is doing in its signal handler befre we proceed with the\n // full on kill.\n for attempt in 0..5 {\n if attempt > 0 {\n std::thread::sleep(std::time::Duration::from_millis(50));\n }\n\n if let Ok(Some(_)) = self.try_wait() {\n // It completed, so report success!\n return Ok(());\n }\n }\n\n // it's still alive after a grace period, so proceed with a kill\n }\n\n std::process::Child::kill(self)\n }\n\n #[cfg(windows)]\n fn clone_killer(&self) -> Box {\n struct RawDup(RawHandle);\n impl AsRawHandle for RawDup {\n fn as_raw_handle(&self) -> RawHandle {\n self.0\n }\n }\n\n Box::new(ProcessSignaller {\n pid: self.process_id(),\n handle: Child::as_raw_handle(self)\n .as_ref()\n .and_then(|h| filedescriptor::OwnedHandle::dup(&RawDup(*h)).ok()),\n })\n }\n\n #[cfg(unix)]\n fn clone_killer(&self) -> Box {\n Box::new(ProcessSignaller {\n pid: self.process_id(),\n })\n }\n}\n\npub fn native_pty_system() -> Box {\n Box::new(NativePtySystem::default())\n}\n\n#[cfg(unix)]\npub type NativePtySystem = unix::UnixPtySystem;\n#[cfg(windows)]\npub type NativePtySystem = win::conpty::ConPtySystem;\n"
},
{
"path": "crates/portable-pty-psmux/src/serial.rs",
"content": "//! This module implements a serial port based tty.\n//! This is a bit different from the other implementations in that\n//! we cannot explicitly spawn a process into the serial connection,\n//! so we can only use a `CommandBuilder::new_default_prog` with the\n//! `openpty` method.\n//! On most (all?) systems, attempting to open multiple instances of\n//! the same serial port will fail.\nuse crate::{\n Child, ChildKiller, CommandBuilder, ExitStatus, MasterPty, PtyPair, PtySize, PtySystem,\n SlavePty,\n};\nuse anyhow::{ensure, Context};\nuse filedescriptor::FileDescriptor;\nuse serial2::{CharSize, FlowControl, Parity, SerialPort, StopBits};\nuse std::cell::RefCell;\nuse std::ffi::{OsStr, OsString};\nuse std::io::{Read, Result as IoResult, Write};\n#[cfg(unix)]\nuse std::path::PathBuf;\nuse std::sync::Arc;\nuse std::time::Duration;\n\ntype Handle = Arc;\n\npub struct SerialTty {\n port: OsString,\n baud: u32,\n char_size: CharSize,\n parity: Parity,\n stop_bits: StopBits,\n flow_control: FlowControl,\n}\n\nimpl SerialTty {\n pub fn new + ?Sized>(port: &T) -> Self {\n Self {\n port: port.as_ref().to_owned(),\n baud: 9600,\n char_size: CharSize::Bits8,\n parity: Parity::None,\n stop_bits: StopBits::One,\n flow_control: FlowControl::XonXoff,\n }\n }\n\n pub fn set_baud_rate(&mut self, baud: u32) {\n self.baud = baud;\n }\n\n pub fn set_char_size(&mut self, char_size: CharSize) {\n self.char_size = char_size;\n }\n\n pub fn set_parity(&mut self, parity: Parity) {\n self.parity = parity;\n }\n\n pub fn set_stop_bits(&mut self, stop_bits: StopBits) {\n self.stop_bits = stop_bits;\n }\n\n pub fn set_flow_control(&mut self, flow_control: FlowControl) {\n self.flow_control = flow_control;\n }\n}\n\nimpl PtySystem for SerialTty {\n fn openpty(&self, _size: PtySize) -> anyhow::Result {\n let mut port = SerialPort::open(&self.port, self.baud)\n .with_context(|| format!(\"openpty on serial port {:?}\", self.port))?;\n\n let mut settings = port.get_configuration()?;\n settings.set_raw();\n settings.set_baud_rate(self.baud)?;\n settings.set_char_size(self.char_size);\n settings.set_flow_control(self.flow_control);\n settings.set_parity(self.parity);\n settings.set_stop_bits(self.stop_bits);\n log::debug!(\"serial settings: {:#?}\", port.get_configuration());\n port.set_configuration(&settings)?;\n\n // The timeout needs to be rather short because, at least on Windows,\n // a read with a long timeout will block a concurrent write from\n // happening. In wezterm we tend to have a thread looping on read\n // while writes happen occasionally from the gui thread, and if we\n // make this timeout too long we can block the gui thread.\n port.set_read_timeout(Duration::from_millis(50))?;\n port.set_write_timeout(Duration::from_millis(50))?;\n\n let port: Handle = Arc::new(port);\n\n Ok(PtyPair {\n slave: Box::new(Slave {\n port: Arc::clone(&port),\n }),\n master: Box::new(Master {\n port,\n took_writer: RefCell::new(false),\n }),\n })\n }\n}\n\nstruct Slave {\n port: Handle,\n}\n\nimpl SlavePty for Slave {\n fn spawn_command(&self, cmd: CommandBuilder) -> anyhow::Result> {\n ensure!(\n cmd.is_default_prog(),\n \"can only use default prog commands with serial tty implementations\"\n );\n Ok(Box::new(SerialChild {\n port: Arc::clone(&self.port),\n }))\n }\n}\n\n/// There isn't really a child process on the end of the serial connection,\n/// so all of the Child trait impls are NOP\nstruct SerialChild {\n port: Handle,\n}\n\n// An anemic impl of Debug to satisfy some indirect trait bounds\nimpl std::fmt::Debug for SerialChild {\n fn fmt(&self, fmt: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> {\n fmt.debug_struct(\"SerialChild\").finish()\n }\n}\n\nimpl Child for SerialChild {\n fn try_wait(&mut self) -> IoResult> {\n Ok(None)\n }\n\n fn wait(&mut self) -> IoResult {\n // There isn't really a child process to wait for,\n // as the serial connection never really \"dies\",\n // however, for something like a USB serial port,\n // if it is unplugged then it logically is terminated.\n // We read the CD (carrier detect) signal periodically\n // to see if the device has gone away: we actually discard\n // the CD value itself and just look for an error state.\n // We could potentially also decide to call CD==false the\n // same thing as the \"child\" completing.\n loop {\n std::thread::sleep(Duration::from_secs(5));\n\n let port = &self.port;\n if let Err(err) = port.read_cd() {\n log::error!(\"Error reading carrier detect: {:#}\", err);\n return Ok(ExitStatus::with_exit_code(1));\n }\n }\n }\n\n fn process_id(&self) -> Option {\n None\n }\n\n #[cfg(windows)]\n fn as_raw_handle(&self) -> Option {\n None\n }\n}\n\nimpl ChildKiller for SerialChild {\n fn kill(&mut self) -> IoResult<()> {\n Ok(())\n }\n\n fn clone_killer(&self) -> Box {\n Box::new(SerialChildKiller)\n }\n}\n\n#[derive(Debug)]\nstruct SerialChildKiller;\n\nimpl ChildKiller for SerialChildKiller {\n fn kill(&mut self) -> IoResult<()> {\n Ok(())\n }\n\n fn clone_killer(&self) -> Box {\n Box::new(SerialChildKiller)\n }\n}\n\nstruct Master {\n port: Handle,\n took_writer: RefCell,\n}\n\nstruct MasterWriter {\n port: Handle,\n}\n\nimpl Write for MasterWriter {\n fn write(&mut self, buf: &[u8]) -> Result {\n self.port.write(buf)\n }\n\n fn flush(&mut self) -> Result<(), std::io::Error> {\n self.port.flush()\n }\n}\n\nimpl MasterPty for Master {\n fn resize(&self, _size: PtySize) -> anyhow::Result<()> {\n // Serial ports have no concept of size\n Ok(())\n }\n\n fn get_size(&self) -> anyhow::Result {\n // Serial ports have no concept of size\n Ok(PtySize::default())\n }\n\n fn try_clone_reader(&self) -> anyhow::Result> {\n // We rely on the fact that SystemPort implements the traits\n // that expose the underlying file descriptor, and that direct\n // reads from that return the raw data that we want\n let fd = FileDescriptor::dup(&*self.port)?;\n Ok(Box::new(Reader { fd }))\n }\n\n fn take_writer(&self) -> anyhow::Result> {\n if *self.took_writer.borrow() {\n anyhow::bail!(\"cannot take writer more than once\");\n }\n *self.took_writer.borrow_mut() = true;\n let port = Arc::clone(&self.port);\n Ok(Box::new(MasterWriter { port }))\n }\n\n #[cfg(unix)]\n fn process_group_leader(&self) -> Option {\n // N/A: there is no local process\n None\n }\n\n #[cfg(unix)]\n fn as_raw_fd(&self) -> Option {\n None\n }\n\n #[cfg(unix)]\n fn tty_name(&self) -> Option {\n None\n }\n}\n\nstruct Reader {\n fd: FileDescriptor,\n}\n\nimpl Read for Reader {\n fn read(&mut self, buf: &mut [u8]) -> Result {\n // On windows, this self.fd.read will block for up to the time we set\n // as the timeout when we set up the port, but on unix it will\n // never block.\n loop {\n #[cfg(unix)]\n {\n use filedescriptor::{poll, pollfd, AsRawSocketDescriptor, POLLIN};\n // The serial crate puts the serial port in non-blocking mode,\n // so we must explicitly poll for ourselves here to avoid a\n // busy loop.\n let mut poll_array = [pollfd {\n fd: self.fd.as_socket_descriptor(),\n events: POLLIN,\n revents: 0,\n }];\n let _ = poll(&mut poll_array, None);\n }\n\n match self.fd.read(buf) {\n Ok(0) => {\n if cfg!(windows) {\n // Read timeout with no data available yet;\n // loop and try again.\n continue;\n }\n return Err(std::io::Error::new(\n std::io::ErrorKind::UnexpectedEof,\n \"EOF on serial port\",\n ));\n }\n Ok(size) => {\n return Ok(size);\n }\n Err(e) => {\n if e.kind() == std::io::ErrorKind::WouldBlock {\n continue;\n }\n log::error!(\"serial read error: {}\", e);\n return Err(e);\n }\n }\n }\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/unix.rs",
"content": "//! Working with pseudo-terminals\n\nuse crate::{Child, CommandBuilder, MasterPty, PtyPair, PtySize, PtySystem, SlavePty};\nuse anyhow::{bail, Error};\nuse filedescriptor::FileDescriptor;\nuse libc::{self, winsize};\nuse std::cell::RefCell;\nuse std::ffi::OsStr;\nuse std::io::{Read, Write};\nuse std::os::fd::AsFd;\nuse std::os::unix::ffi::OsStrExt;\nuse std::os::unix::io::{AsRawFd, FromRawFd};\nuse std::os::unix::process::CommandExt;\nuse std::path::PathBuf;\nuse std::{io, mem, ptr};\n\npub use std::os::unix::io::RawFd;\n\n#[derive(Default)]\npub struct UnixPtySystem {}\n\nfn openpty(size: PtySize) -> anyhow::Result<(UnixMasterPty, UnixSlavePty)> {\n let mut master: RawFd = -1;\n let mut slave: RawFd = -1;\n\n let mut size = winsize {\n ws_row: size.rows,\n ws_col: size.cols,\n ws_xpixel: size.pixel_width,\n ws_ypixel: size.pixel_height,\n };\n\n let result = unsafe {\n // BSDish systems may require mut pointers to some args\n #[allow(clippy::unnecessary_mut_passed)]\n libc::openpty(\n &mut master,\n &mut slave,\n ptr::null_mut(),\n ptr::null_mut(),\n &mut size,\n )\n };\n\n if result != 0 {\n bail!(\"failed to openpty: {:?}\", io::Error::last_os_error());\n }\n\n let tty_name = tty_name(slave);\n\n let master = UnixMasterPty {\n fd: PtyFd(unsafe { FileDescriptor::from_raw_fd(master) }),\n took_writer: RefCell::new(false),\n tty_name,\n };\n let slave = UnixSlavePty {\n fd: PtyFd(unsafe { FileDescriptor::from_raw_fd(slave) }),\n };\n\n // Ensure that these descriptors will get closed when we execute\n // the child process. This is done after constructing the Pty\n // instances so that we ensure that the Ptys get drop()'d if\n // the cloexec() functions fail (unlikely!).\n cloexec(master.fd.as_raw_fd())?;\n cloexec(slave.fd.as_raw_fd())?;\n\n Ok((master, slave))\n}\n\nimpl PtySystem for UnixPtySystem {\n fn openpty(&self, size: PtySize) -> anyhow::Result {\n let (master, slave) = openpty(size)?;\n Ok(PtyPair {\n master: Box::new(master),\n slave: Box::new(slave),\n })\n }\n}\n\nstruct PtyFd(pub FileDescriptor);\nimpl std::ops::Deref for PtyFd {\n type Target = FileDescriptor;\n fn deref(&self) -> &FileDescriptor {\n &self.0\n }\n}\nimpl std::ops::DerefMut for PtyFd {\n fn deref_mut(&mut self) -> &mut FileDescriptor {\n &mut self.0\n }\n}\n\nimpl Read for PtyFd {\n fn read(&mut self, buf: &mut [u8]) -> Result {\n match self.0.read(buf) {\n Err(ref e) if e.raw_os_error() == Some(libc::EIO) => {\n // EIO indicates that the slave pty has been closed.\n // Treat this as EOF so that std::io::Read::read_to_string\n // and similar functions gracefully terminate when they\n // encounter this condition\n Ok(0)\n }\n x => x,\n }\n }\n}\n\nfn tty_name(fd: RawFd) -> Option {\n let mut buf = vec![0 as std::ffi::c_char; 128];\n\n loop {\n let res = unsafe { libc::ttyname_r(fd, buf.as_mut_ptr(), buf.len()) };\n\n if res == libc::ERANGE {\n if buf.len() > 64 * 1024 {\n // on macOS, if the buf is \"too big\", ttyname_r can\n // return ERANGE, even though that is supposed to\n // indicate buf is \"too small\".\n return None;\n }\n buf.resize(buf.len() * 2, 0 as std::ffi::c_char);\n continue;\n }\n\n return if res == 0 {\n let cstr = unsafe { std::ffi::CStr::from_ptr(buf.as_ptr()) };\n let osstr = OsStr::from_bytes(cstr.to_bytes());\n Some(PathBuf::from(osstr))\n } else {\n None\n };\n }\n}\n\n/// On Big Sur, Cocoa leaks various file descriptors to child processes,\n/// so we need to make a pass through the open descriptors beyond just the\n/// stdio descriptors and close them all out.\n/// This is approximately equivalent to the darwin `posix_spawnattr_setflags`\n/// option POSIX_SPAWN_CLOEXEC_DEFAULT which is used as a bit of a cheat\n/// on macOS.\n/// On Linux, gnome/mutter leak shell extension fds to wezterm too, so we\n/// also need to make an effort to clean up the mess.\n///\n/// This function enumerates the open filedescriptors in the current process\n/// and then will forcibly call close(2) on each open fd that is numbered\n/// 3 or higher, effectively closing all descriptors except for the stdio\n/// streams.\n///\n/// The implementation of this function relies on `/dev/fd` being available\n/// to provide the list of open fds. Any errors in enumerating or closing\n/// the fds are silently ignored.\npub fn close_random_fds() {\n // FreeBSD, macOS and presumably other BSDish systems have /dev/fd as\n // a directory listing the current fd numbers for the process.\n //\n // On Linux, /dev/fd is a symlink to /proc/self/fd\n if let Ok(dir) = std::fs::read_dir(\"/dev/fd\") {\n let mut fds = vec![];\n for entry in dir {\n if let Some(num) = entry\n .ok()\n .map(|e| e.file_name())\n .and_then(|s| s.into_string().ok())\n .and_then(|n| n.parse::().ok())\n {\n if num > 2 {\n fds.push(num);\n }\n }\n }\n for fd in fds {\n unsafe {\n libc::close(fd);\n }\n }\n }\n}\n\nimpl PtyFd {\n fn resize(&self, size: PtySize) -> Result<(), Error> {\n let ws_size = winsize {\n ws_row: size.rows,\n ws_col: size.cols,\n ws_xpixel: size.pixel_width,\n ws_ypixel: size.pixel_height,\n };\n\n if unsafe {\n libc::ioctl(\n self.0.as_raw_fd(),\n libc::TIOCSWINSZ as _,\n &ws_size as *const _,\n )\n } != 0\n {\n bail!(\n \"failed to ioctl(TIOCSWINSZ): {:?}\",\n io::Error::last_os_error()\n );\n }\n\n Ok(())\n }\n\n fn get_size(&self) -> Result {\n let mut size: winsize = unsafe { mem::zeroed() };\n if unsafe {\n libc::ioctl(\n self.0.as_raw_fd(),\n libc::TIOCGWINSZ as _,\n &mut size as *mut _,\n )\n } != 0\n {\n bail!(\n \"failed to ioctl(TIOCGWINSZ): {:?}\",\n io::Error::last_os_error()\n );\n }\n Ok(PtySize {\n rows: size.ws_row,\n cols: size.ws_col,\n pixel_width: size.ws_xpixel,\n pixel_height: size.ws_ypixel,\n })\n }\n\n fn spawn_command(&self, builder: CommandBuilder) -> anyhow::Result {\n let configured_umask = builder.umask;\n\n let mut cmd = builder.as_command()?;\n let controlling_tty = builder.get_controlling_tty();\n\n unsafe {\n cmd.stdin(self.as_stdio()?)\n .stdout(self.as_stdio()?)\n .stderr(self.as_stdio()?)\n .pre_exec(move || {\n // Clean up a few things before we exec the program\n // Clear out any potentially problematic signal\n // dispositions that we might have inherited\n for signo in &[\n libc::SIGCHLD,\n libc::SIGHUP,\n libc::SIGINT,\n libc::SIGQUIT,\n libc::SIGTERM,\n libc::SIGALRM,\n ] {\n libc::signal(*signo, libc::SIG_DFL);\n }\n\n let empty_set: libc::sigset_t = std::mem::zeroed();\n libc::sigprocmask(libc::SIG_SETMASK, &empty_set, std::ptr::null_mut());\n\n // Establish ourselves as a session leader.\n if libc::setsid() == -1 {\n return Err(io::Error::last_os_error());\n }\n\n // Clippy wants us to explicitly cast TIOCSCTTY using\n // type::from(), but the size and potentially signedness\n // are system dependent, which is why we're using `as _`.\n // Suppress this lint for this section of code.\n #[allow(clippy::cast_lossless)]\n if controlling_tty {\n // Set the pty as the controlling terminal.\n // Failure to do this means that delivery of\n // SIGWINCH won't happen when we resize the\n // terminal, among other undesirable effects.\n if libc::ioctl(0, libc::TIOCSCTTY as _, 0) == -1 {\n return Err(io::Error::last_os_error());\n }\n }\n\n close_random_fds();\n\n if let Some(mask) = configured_umask {\n libc::umask(mask);\n }\n\n Ok(())\n })\n };\n\n let mut child = cmd.spawn()?;\n\n // Ensure that we close out the slave fds that Child retains;\n // they are not what we need (we need the master side to reference\n // them) and won't work in the usual way anyway.\n // In practice these are None, but it seems best to be move them\n // out in case the behavior of Command changes in the future.\n child.stdin.take();\n child.stdout.take();\n child.stderr.take();\n\n Ok(child)\n }\n}\n\n/// Represents the master end of a pty.\n/// The file descriptor will be closed when the Pty is dropped.\nstruct UnixMasterPty {\n fd: PtyFd,\n took_writer: RefCell,\n tty_name: Option,\n}\n\n/// Represents the slave end of a pty.\n/// The file descriptor will be closed when the Pty is dropped.\nstruct UnixSlavePty {\n fd: PtyFd,\n}\n\n/// Helper function to set the close-on-exec flag for a raw descriptor\nfn cloexec(fd: RawFd) -> Result<(), Error> {\n let flags = unsafe { libc::fcntl(fd, libc::F_GETFD) };\n if flags == -1 {\n bail!(\n \"fcntl to read flags failed: {:?}\",\n io::Error::last_os_error()\n );\n }\n let result = unsafe { libc::fcntl(fd, libc::F_SETFD, flags | libc::FD_CLOEXEC) };\n if result == -1 {\n bail!(\n \"fcntl to set CLOEXEC failed: {:?}\",\n io::Error::last_os_error()\n );\n }\n Ok(())\n}\n\nimpl SlavePty for UnixSlavePty {\n fn spawn_command(\n &self,\n builder: CommandBuilder,\n ) -> Result, Error> {\n Ok(Box::new(self.fd.spawn_command(builder)?))\n }\n}\n\nimpl MasterPty for UnixMasterPty {\n fn resize(&self, size: PtySize) -> Result<(), Error> {\n self.fd.resize(size)\n }\n\n fn get_size(&self) -> Result {\n self.fd.get_size()\n }\n\n fn try_clone_reader(&self) -> Result, Error> {\n let fd = PtyFd(self.fd.try_clone()?);\n Ok(Box::new(fd))\n }\n\n fn take_writer(&self) -> Result, Error> {\n if *self.took_writer.borrow() {\n anyhow::bail!(\"cannot take writer more than once\");\n }\n *self.took_writer.borrow_mut() = true;\n let fd = PtyFd(self.fd.try_clone()?);\n Ok(Box::new(UnixMasterWriter { fd }))\n }\n\n fn as_raw_fd(&self) -> Option {\n Some(self.fd.0.as_raw_fd())\n }\n\n fn tty_name(&self) -> Option {\n self.tty_name.clone()\n }\n\n fn process_group_leader(&self) -> Option {\n match unsafe { libc::tcgetpgrp(self.fd.0.as_raw_fd()) } {\n pid if pid > 0 => Some(pid),\n _ => None,\n }\n }\n\n fn get_termios(&self) -> Option {\n nix::sys::termios::tcgetattr(self.fd.0.as_fd()).ok()\n }\n}\n\n/// Represents the master end of a pty.\n/// EOT will be sent, and then the file descriptor will be closed when\n/// the Pty is dropped.\nstruct UnixMasterWriter {\n fd: PtyFd,\n}\n\nimpl Drop for UnixMasterWriter {\n fn drop(&mut self) {\n let mut t: libc::termios = unsafe { std::mem::MaybeUninit::zeroed().assume_init() };\n if unsafe { libc::tcgetattr(self.fd.0.as_raw_fd(), &mut t) } == 0 {\n // EOF is only interpreted after a newline, so if it is set,\n // we send a newline followed by EOF.\n let eot = t.c_cc[libc::VEOF];\n if eot != 0 {\n let _ = self.fd.0.write_all(&[b'\\n', eot]);\n }\n }\n }\n}\n\nimpl Write for UnixMasterWriter {\n fn write(&mut self, buf: &[u8]) -> Result {\n self.fd.write(buf)\n }\n fn flush(&mut self) -> Result<(), io::Error> {\n self.fd.flush()\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/win/conpty.rs",
"content": "use crate::cmdbuilder::CommandBuilder;\nuse crate::win::psuedocon::PsuedoCon;\nuse crate::{Child, MasterPty, PtyPair, PtySize, PtySystem, SlavePty};\nuse anyhow::Error;\nuse filedescriptor::FileDescriptor;\nuse std::sync::{Arc, Mutex};\nuse winapi::um::wincon::COORD;\n\n/// Create a pipe pair with an explicit buffer size.\n///\n/// Windows Terminal uses 128 KB pipe buffers for ConPTY I/O. The default\n/// `CreatePipe(..., 0)` typically gets 4 KB, which forces more frequent\n/// kernel transitions during high-throughput output (e.g. `cat large_file`).\n/// Using 64 KB matches Windows Terminal's approach and reduces syscall\n/// overhead for both input (mouse/keyboard) and output.\nfn create_pipe_with_buffer(size: u32) -> anyhow::Result<(FileDescriptor, FileDescriptor)> {\n use std::os::windows::io::FromRawHandle;\n use std::ptr;\n use winapi::shared::minwindef::TRUE;\n use winapi::um::handleapi::INVALID_HANDLE_VALUE;\n use winapi::um::minwinbase::SECURITY_ATTRIBUTES;\n use winapi::um::namedpipeapi::CreatePipe;\n use winapi::um::winnt::HANDLE;\n\n let mut sa = SECURITY_ATTRIBUTES {\n nLength: std::mem::size_of::() as u32,\n lpSecurityDescriptor: ptr::null_mut(),\n bInheritHandle: TRUE as _,\n };\n let mut read: HANDLE = INVALID_HANDLE_VALUE;\n let mut write: HANDLE = INVALID_HANDLE_VALUE;\n if unsafe { CreatePipe(&mut read, &mut write, &mut sa, size) } == 0 {\n return Err(std::io::Error::last_os_error().into());\n }\n Ok(unsafe {(\n FileDescriptor::from_raw_handle(read as _),\n FileDescriptor::from_raw_handle(write as _),\n )})\n}\n\n#[derive(Default)]\npub struct ConPtySystem {}\n\nimpl PtySystem for ConPtySystem {\n fn openpty(&self, size: PtySize) -> anyhow::Result {\n // Use 64KB pipe buffers (Windows Terminal uses 128KB).\n // Default CreatePipe(..., 0) = ~4KB, causing frequent kernel round-trips.\n const PIPE_BUF: u32 = 64 * 1024;\n let (stdin_read, stdin_write) = create_pipe_with_buffer(PIPE_BUF)?;\n let (stdout_read, stdout_write) = create_pipe_with_buffer(PIPE_BUF)?;\n\n let con = PsuedoCon::new(\n COORD {\n X: size.cols as i16,\n Y: size.rows as i16,\n },\n stdin_read,\n stdout_write,\n )?;\n\n let master = ConPtyMasterPty {\n inner: Arc::new(Mutex::new(Inner {\n con,\n readable: stdout_read,\n writable: Some(stdin_write),\n size,\n })),\n };\n\n let slave = ConPtySlavePty {\n inner: master.inner.clone(),\n };\n\n Ok(PtyPair {\n master: Box::new(master),\n slave: Box::new(slave),\n })\n }\n}\n\nstruct Inner {\n con: PsuedoCon,\n readable: FileDescriptor,\n writable: Option,\n size: PtySize,\n}\n\nimpl Inner {\n pub fn resize(\n &mut self,\n num_rows: u16,\n num_cols: u16,\n pixel_width: u16,\n pixel_height: u16,\n ) -> Result<(), Error> {\n self.con.resize(COORD {\n X: num_cols as i16,\n Y: num_rows as i16,\n })?;\n self.size = PtySize {\n rows: num_rows,\n cols: num_cols,\n pixel_width,\n pixel_height,\n };\n Ok(())\n }\n}\n\n#[derive(Clone)]\npub struct ConPtyMasterPty {\n inner: Arc>,\n}\n\npub struct ConPtySlavePty {\n inner: Arc>,\n}\n\nimpl MasterPty for ConPtyMasterPty {\n fn resize(&self, size: PtySize) -> anyhow::Result<()> {\n let mut inner = self.inner.lock().unwrap();\n inner.resize(size.rows, size.cols, size.pixel_width, size.pixel_height)\n }\n\n fn get_size(&self) -> Result {\n let inner = self.inner.lock().unwrap();\n Ok(inner.size.clone())\n }\n\n fn try_clone_reader(&self) -> anyhow::Result> {\n Ok(Box::new(self.inner.lock().unwrap().readable.try_clone()?))\n }\n\n fn take_writer(&self) -> anyhow::Result> {\n Ok(Box::new(\n self.inner\n .lock()\n .unwrap()\n .writable\n .take()\n .ok_or_else(|| anyhow::anyhow!(\"writer already taken\"))?,\n ))\n }\n}\n\nimpl SlavePty for ConPtySlavePty {\n fn spawn_command(&self, cmd: CommandBuilder) -> anyhow::Result> {\n let mut inner = self.inner.lock().unwrap();\n match inner.con.spawn_command(cmd.clone()) {\n Ok(child) => Ok(Box::new(child)),\n Err(e) if inner.con.used_passthrough && is_invalid_parameter(&e) => {\n // CreateProcessW rejected the ConPTY handle that was created\n // with PSEUDOCONSOLE_PASSTHROUGH_MODE. Some Windows 11 builds\n // (notably Insider/Canary builds like 26200) accept the flag\n // during CreatePseudoConsole but later fail in CreateProcessW\n // with ERROR_INVALID_PARAMETER (87).\n //\n // Recovery: recreate the ConPTY without passthrough mode and\n // create fresh pipe pairs for the new pseudo-console.\n log::warn!(\n \"CreateProcessW failed with ERROR_INVALID_PARAMETER while using \\\n ConPTY passthrough mode; retrying without passthrough\"\n );\n const PIPE_BUF: u32 = 64 * 1024;\n let (stdin_read, stdin_write) = create_pipe_with_buffer(PIPE_BUF)?;\n let (stdout_read, stdout_write) = create_pipe_with_buffer(PIPE_BUF)?;\n\n let new_con = PsuedoCon::new_without_passthrough(\n COORD {\n X: inner.size.cols as i16,\n Y: inner.size.rows as i16,\n },\n stdin_read,\n stdout_write,\n )?;\n\n // Replace the ConPTY and pipe endpoints inside Inner.\n // At this point nobody has cloned the reader or taken the\n // writer yet (pane.rs acquires them after spawn_command),\n // so the old FileDescriptors are dropped cleanly.\n inner.con = new_con;\n inner.readable = stdout_read;\n inner.writable = Some(stdin_write);\n\n let child = inner.con.spawn_command(cmd)?;\n Ok(Box::new(child))\n }\n Err(e) => Err(e),\n }\n }\n}\n\n/// Check if an error chain contains Windows ERROR_INVALID_PARAMETER (87).\n/// The OS error number is locale-independent; the textual message varies\n/// (e.g. \"Falscher Parameter\" in German).\nfn is_invalid_parameter(e: &anyhow::Error) -> bool {\n let msg = format!(\"{}\", e);\n msg.contains(\"os error 87\")\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/win/mod.rs",
"content": "use crate::{Child, ChildKiller, ExitStatus};\nuse anyhow::Context as _;\nuse std::io::{Error as IoError, Result as IoResult};\nuse std::os::windows::io::{AsRawHandle, RawHandle};\nuse std::pin::Pin;\nuse std::sync::Mutex;\nuse std::task::{Context, Poll};\nuse winapi::shared::minwindef::DWORD;\nuse winapi::um::minwinbase::STILL_ACTIVE;\nuse winapi::um::processthreadsapi::*;\nuse winapi::um::synchapi::WaitForSingleObject;\nuse winapi::um::winbase::INFINITE;\n\npub mod conpty;\nmod procthreadattr;\nmod psuedocon;\n\nuse filedescriptor::OwnedHandle;\n\n#[derive(Debug)]\npub struct WinChild {\n proc: Mutex,\n}\n\nimpl WinChild {\n fn is_complete(&mut self) -> IoResult> {\n let mut status: DWORD = 0;\n let proc = self.proc.lock().unwrap().try_clone().unwrap();\n let res = unsafe { GetExitCodeProcess(proc.as_raw_handle() as _, &mut status) };\n if res != 0 {\n if status == STILL_ACTIVE {\n Ok(None)\n } else {\n Ok(Some(ExitStatus::with_exit_code(status)))\n }\n } else {\n Ok(None)\n }\n }\n\n fn do_kill(&mut self) -> IoResult<()> {\n let proc = self.proc.lock().unwrap().try_clone().unwrap();\n let res = unsafe { TerminateProcess(proc.as_raw_handle() as _, 1) };\n let err = IoError::last_os_error();\n if res != 0 {\n Err(err)\n } else {\n Ok(())\n }\n }\n}\n\nimpl ChildKiller for WinChild {\n fn kill(&mut self) -> IoResult<()> {\n self.do_kill().ok();\n Ok(())\n }\n\n fn clone_killer(&self) -> Box {\n let proc = self.proc.lock().unwrap().try_clone().unwrap();\n Box::new(WinChildKiller { proc })\n }\n}\n\n#[derive(Debug)]\npub struct WinChildKiller {\n proc: OwnedHandle,\n}\n\nimpl ChildKiller for WinChildKiller {\n fn kill(&mut self) -> IoResult<()> {\n let res = unsafe { TerminateProcess(self.proc.as_raw_handle() as _, 1) };\n let err = IoError::last_os_error();\n if res != 0 {\n Err(err)\n } else {\n Ok(())\n }\n }\n\n fn clone_killer(&self) -> Box {\n let proc = self.proc.try_clone().unwrap();\n Box::new(WinChildKiller { proc })\n }\n}\n\nimpl Child for WinChild {\n fn try_wait(&mut self) -> IoResult> {\n self.is_complete()\n }\n\n fn wait(&mut self) -> IoResult {\n if let Ok(Some(status)) = self.try_wait() {\n return Ok(status);\n }\n let proc = self.proc.lock().unwrap().try_clone().unwrap();\n unsafe {\n WaitForSingleObject(proc.as_raw_handle() as _, INFINITE);\n }\n let mut status: DWORD = 0;\n let res = unsafe { GetExitCodeProcess(proc.as_raw_handle() as _, &mut status) };\n if res != 0 {\n Ok(ExitStatus::with_exit_code(status))\n } else {\n Err(IoError::last_os_error())\n }\n }\n\n fn process_id(&self) -> Option {\n let res = unsafe { GetProcessId(self.proc.lock().unwrap().as_raw_handle() as _) };\n if res == 0 {\n None\n } else {\n Some(res)\n }\n }\n\n fn as_raw_handle(&self) -> Option {\n let proc = self.proc.lock().unwrap();\n Some(proc.as_raw_handle())\n }\n}\n\nimpl std::future::Future for WinChild {\n type Output = anyhow::Result;\n\n fn poll(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll> {\n match self.is_complete() {\n Ok(Some(status)) => Poll::Ready(Ok(status)),\n Err(err) => Poll::Ready(Err(err).context(\"Failed to retrieve process exit status\")),\n Ok(None) => {\n struct PassRawHandleToWaiterThread(pub RawHandle);\n unsafe impl Send for PassRawHandleToWaiterThread {}\n\n let proc = self.proc.lock().unwrap().try_clone()?;\n let handle = PassRawHandleToWaiterThread(proc.as_raw_handle());\n\n let waker = cx.waker().clone();\n std::thread::spawn(move || {\n unsafe {\n WaitForSingleObject(handle.0 as _, INFINITE);\n }\n waker.wake();\n });\n Poll::Pending\n }\n }\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/win/procthreadattr.rs",
"content": "use crate::win::psuedocon::HPCON;\nuse anyhow::{ensure, Error};\nuse std::io::Error as IoError;\nuse std::{mem, ptr};\nuse winapi::shared::minwindef::DWORD;\nuse winapi::um::processthreadsapi::*;\n\nconst PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE: usize = 0x00020016;\n\npub struct ProcThreadAttributeList {\n data: Vec,\n}\n\nimpl ProcThreadAttributeList {\n pub fn with_capacity(num_attributes: DWORD) -> Result {\n let mut bytes_required: usize = 0;\n unsafe {\n InitializeProcThreadAttributeList(\n ptr::null_mut(),\n num_attributes,\n 0,\n &mut bytes_required,\n )\n };\n let mut data = Vec::with_capacity(bytes_required);\n // We have the right capacity, so force the vec to consider itself\n // that length. The contents of those bytes will be maintained\n // by the win32 apis used in this impl.\n unsafe { data.set_len(bytes_required) };\n\n let attr_ptr = data.as_mut_slice().as_mut_ptr() as *mut _;\n let res = unsafe {\n InitializeProcThreadAttributeList(attr_ptr, num_attributes, 0, &mut bytes_required)\n };\n ensure!(\n res != 0,\n \"InitializeProcThreadAttributeList failed: {}\",\n IoError::last_os_error()\n );\n Ok(Self { data })\n }\n\n pub fn as_mut_ptr(&mut self) -> LPPROC_THREAD_ATTRIBUTE_LIST {\n self.data.as_mut_slice().as_mut_ptr() as *mut _\n }\n\n pub fn set_pty(&mut self, con: HPCON) -> Result<(), Error> {\n let res = unsafe {\n UpdateProcThreadAttribute(\n self.as_mut_ptr(),\n 0,\n PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,\n con,\n mem::size_of::(),\n ptr::null_mut(),\n ptr::null_mut(),\n )\n };\n ensure!(\n res != 0,\n \"UpdateProcThreadAttribute failed: {}\",\n IoError::last_os_error()\n );\n Ok(())\n }\n}\n\nimpl Drop for ProcThreadAttributeList {\n fn drop(&mut self) {\n unsafe { DeleteProcThreadAttributeList(self.as_mut_ptr()) };\n }\n}\n"
},
{
"path": "crates/portable-pty-psmux/src/win/psuedocon.rs",
"content": "use super::WinChild;\nuse crate::cmdbuilder::CommandBuilder;\nuse crate::win::procthreadattr::ProcThreadAttributeList;\nuse anyhow::{bail, ensure, Error};\nuse filedescriptor::{FileDescriptor, OwnedHandle};\nuse lazy_static::lazy_static;\nuse shared_library::shared_library;\nuse std::ffi::OsString;\nuse std::io::Error as IoError;\nuse std::os::windows::ffi::OsStringExt;\nuse std::os::windows::io::{AsRawHandle, FromRawHandle};\nuse std::path::Path;\nuse std::sync::Mutex;\nuse std::{mem, ptr};\nuse winapi::shared::minwindef::DWORD;\nuse winapi::shared::winerror::{HRESULT, S_OK};\nuse winapi::um::handleapi::*;\nuse winapi::um::processthreadsapi::*;\nuse winapi::um::winbase::{\n CREATE_UNICODE_ENVIRONMENT, EXTENDED_STARTUPINFO_PRESENT, STARTUPINFOEXW,\n};\nuse winapi::um::wincon::COORD;\nuse winapi::um::winnt::HANDLE;\n\npub type HPCON = HANDLE;\n\npub const PSUEDOCONSOLE_INHERIT_CURSOR: DWORD = 0x1;\npub const PSEUDOCONSOLE_RESIZE_QUIRK: DWORD = 0x2;\npub const PSEUDOCONSOLE_WIN32_INPUT_MODE: DWORD = 0x4;\npub const PSEUDOCONSOLE_PASSTHROUGH_MODE: DWORD = 0x8;\n\nshared_library!(ConPtyFuncs,\n pub fn CreatePseudoConsole(\n size: COORD,\n hInput: HANDLE,\n hOutput: HANDLE,\n flags: DWORD,\n hpc: *mut HPCON\n ) -> HRESULT,\n pub fn ResizePseudoConsole(hpc: HPCON, size: COORD) -> HRESULT,\n pub fn ClosePseudoConsole(hpc: HPCON),\n);\n\nfn load_conpty() -> ConPtyFuncs {\n // Always use the system kernel32.dll ConPTY implementation.\n // Do NOT try to sideload conpty.dll — terminal emulators like WezTerm\n // bundle their own conpty.dll + OpenConsole.exe, and the DLL search order\n // can pick those up when psmux runs inside such a terminal. Using a\n // foreign conpty.dll causes blank panes and broken I/O because the\n // bundled OpenConsole.exe may not be compatible with our ConPTY flags\n // (PASSTHROUGH_MODE, WIN32_INPUT_MODE, etc.).\n ConPtyFuncs::open(Path::new(\"kernel32.dll\")).expect(\n \"this system does not support conpty. Windows 10 October 2018 or newer is required\",\n )\n}\n\nlazy_static! {\n static ref CONPTY: ConPtyFuncs = load_conpty();\n}\n\npub struct PsuedoCon {\n con: HPCON,\n /// Whether this ConPTY was created with PSEUDOCONSOLE_PASSTHROUGH_MODE.\n /// Used by the retry logic in ConPtySlavePty::spawn_command to decide\n /// whether a fallback without passthrough is worth attempting.\n pub used_passthrough: bool,\n}\n\nunsafe impl Send for PsuedoCon {}\nunsafe impl Sync for PsuedoCon {}\n\nimpl Drop for PsuedoCon {\n fn drop(&mut self) {\n unsafe { (CONPTY.ClosePseudoConsole)(self.con) };\n }\n}\n\n/// Returns true if the current Windows build supports ConPTY passthrough mode.\n/// PSEUDOCONSOLE_PASSTHROUGH_MODE requires Windows 11 22H2 (build 22621+).\n/// On older Windows versions, the flag may be silently accepted but produce\n/// broken ConPTY output (no Win32 Console API translation).\n///\n/// Respects `PSMUX_NO_PASSTHROUGH=1` environment variable to let users\n/// force-disable passthrough mode on builds where it causes CreateProcessW\n/// to fail with ERROR_INVALID_PARAMETER (87).\nfn supports_passthrough_mode() -> bool {\n if std::env::var(\"PSMUX_NO_PASSTHROUGH\")\n .map(|v| v == \"1\" || v.eq_ignore_ascii_case(\"true\"))\n .unwrap_or(false)\n {\n log::info!(\"ConPTY passthrough mode disabled via PSMUX_NO_PASSTHROUGH\");\n return false;\n }\n let ver = unsafe {\n let mut info: winapi::um::winnt::OSVERSIONINFOW = mem::zeroed();\n info.dwOSVersionInfoSize = mem::size_of::() as u32;\n // RtlGetVersion is used because GetVersionEx lies on Windows 10+\n // unless the application has a compatibility manifest.\n type RtlGetVersionFn = unsafe extern \"system\" fn(*mut winapi::um::winnt::OSVERSIONINFOW) -> i32;\n let ntdll = winapi::um::libloaderapi::GetModuleHandleW(\n ['n' as u16, 't' as u16, 'd' as u16, 'l' as u16, 'l' as u16, '.' as u16,\n 'd' as u16, 'l' as u16, 'l' as u16, 0].as_ptr()\n );\n if ntdll.is_null() {\n return false;\n }\n let func = winapi::um::libloaderapi::GetProcAddress(\n ntdll,\n b\"RtlGetVersion\\0\".as_ptr() as *const i8,\n );\n if func.is_null() {\n return false;\n }\n let rtl_get_version: RtlGetVersionFn = mem::transmute(func);\n rtl_get_version(&mut info);\n info\n };\n // Windows 11 22H2 = build 22621\n ver.dwBuildNumber >= 22621\n}\n\nimpl PsuedoCon {\n pub fn new(size: COORD, input: FileDescriptor, output: FileDescriptor) -> Result {\n let mut con: HPCON = INVALID_HANDLE_VALUE;\n let base_flags = PSUEDOCONSOLE_INHERIT_CURSOR\n | PSEUDOCONSOLE_RESIZE_QUIRK\n | PSEUDOCONSOLE_WIN32_INPUT_MODE;\n\n // Use PSEUDOCONSOLE_PASSTHROUGH_MODE on Windows 11 22H2+ to relay\n // VT sequences (including DECSCUSR cursor shapes) from child processes\n // directly through the output pipe. On older Windows, this flag is\n // silently accepted but breaks Win32 Console API translation, so we\n // only attempt it on known-good builds.\n if supports_passthrough_mode() {\n let result = unsafe {\n (CONPTY.CreatePseudoConsole)(\n size,\n input.as_raw_handle() as _,\n output.as_raw_handle() as _,\n base_flags | PSEUDOCONSOLE_PASSTHROUGH_MODE,\n &mut con,\n )\n };\n\n if result == S_OK {\n return Ok(Self { con, used_passthrough: true });\n }\n // If the API call failed despite being on a supported build,\n // fall through to the standard path.\n con = INVALID_HANDLE_VALUE;\n }\n\n let result = unsafe {\n (CONPTY.CreatePseudoConsole)(\n size,\n input.as_raw_handle() as _,\n output.as_raw_handle() as _,\n base_flags,\n &mut con,\n )\n };\n ensure!(\n result == S_OK,\n \"failed to create psuedo console: HRESULT {}\",\n result\n );\n Ok(Self { con, used_passthrough: false })\n }\n\n /// Create a ConPTY explicitly without passthrough mode, regardless of\n /// Windows build version. Used by the retry logic when CreateProcessW\n /// rejects the passthrough ConPTY handle.\n pub fn new_without_passthrough(size: COORD, input: FileDescriptor, output: FileDescriptor) -> Result {\n let mut con: HPCON = INVALID_HANDLE_VALUE;\n let base_flags = PSUEDOCONSOLE_INHERIT_CURSOR\n | PSEUDOCONSOLE_RESIZE_QUIRK\n | PSEUDOCONSOLE_WIN32_INPUT_MODE;\n\n let result = unsafe {\n (CONPTY.CreatePseudoConsole)(\n size,\n input.as_raw_handle() as _,\n output.as_raw_handle() as _,\n base_flags,\n &mut con,\n )\n };\n ensure!(\n result == S_OK,\n \"failed to create psuedo console (no passthrough): HRESULT {}\",\n result\n );\n Ok(Self { con, used_passthrough: false })\n }\n\n pub fn resize(&self, size: COORD) -> Result<(), Error> {\n let result = unsafe { (CONPTY.ResizePseudoConsole)(self.con, size) };\n ensure!(\n result == S_OK,\n \"failed to resize console to {}x{}: HRESULT: {}\",\n size.X,\n size.Y,\n result\n );\n Ok(())\n }\n\n pub fn spawn_command(&self, cmd: CommandBuilder) -> anyhow::Result {\n let mut si: STARTUPINFOEXW = unsafe { mem::zeroed() };\n si.StartupInfo.cb = mem::size_of::() as u32;\n // Note: we deliberately do NOT set STARTF_USESTDHANDLES with\n // INVALID_HANDLE_VALUE for stdio. MSDN explicitly requires\n // STARTF_USESTDHANDLES to be paired with bInheritHandles=TRUE,\n // and we use bInheritHandles=FALSE below. Most Windows builds\n // tolerate the combination silently (because INVALID_HANDLE_VALUE\n // is a sentinel rather than a real handle), but newer/restricted\n // configurations — Win 11 26200, Microsoft-account profiles with\n // tighter token policies, certain WDAC/AppLocker rule sets — now\n // enforce the contract strictly and reject the call with\n // ERROR_INVALID_PARAMETER (87). See psmux issue #167.\n //\n // ConPTY routes stdio through the PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE\n // attribute on the attribute list, so the child gets correct stdio\n // regardless of dwFlags. bInheritHandles=FALSE prevents leaking\n // any other inheritable handles.\n\n let mut attrs = ProcThreadAttributeList::with_capacity(1)?;\n attrs.set_pty(self.con)?;\n si.lpAttributeList = attrs.as_mut_ptr();\n\n let mut pi: PROCESS_INFORMATION = unsafe { mem::zeroed() };\n\n let (mut exe, mut cmdline) = cmd.cmdline()?;\n let cmd_os = OsString::from_wide(&cmdline);\n\n let cwd = cmd.current_directory();\n\n let res = unsafe {\n CreateProcessW(\n exe.as_mut_slice().as_mut_ptr(),\n cmdline.as_mut_slice().as_mut_ptr(),\n ptr::null_mut(),\n ptr::null_mut(),\n 0,\n EXTENDED_STARTUPINFO_PRESENT | CREATE_UNICODE_ENVIRONMENT,\n cmd.environment_block().as_mut_slice().as_mut_ptr() as *mut _,\n cwd.as_ref()\n .map(|c| c.as_slice().as_ptr())\n .unwrap_or(ptr::null()),\n &mut si.StartupInfo,\n &mut pi,\n )\n };\n if res == 0 {\n let err = IoError::last_os_error();\n let msg = format!(\n \"CreateProcessW `{:?}` in cwd `{:?}` failed: {}\",\n cmd_os,\n cwd.as_ref().map(|c| OsString::from_wide(c)),\n err\n );\n log::error!(\"{}\", msg);\n bail!(\"{}\", msg);\n }\n\n // Make sure we close out the thread handle so we don't leak it;\n // we do this simply by making it owned\n let _main_thread = unsafe { OwnedHandle::from_raw_handle(pi.hThread as _) };\n let proc = unsafe { OwnedHandle::from_raw_handle(pi.hProcess as _) };\n\n Ok(WinChild {\n proc: Mutex::new(proc),\n })\n }\n}\n"
},
{
"path": "crates/vt100-psmux/.cargo-ok",
"content": "{\"v\":1}"
},
{
"path": "crates/vt100-psmux/.cargo_vcs_info.json",
"content": "{\n \"git\": {\n \"sha1\": \"e79e0d68ab3875f045bc3cc3120907a0e5b3bb0f\"\n },\n \"path_in_vcs\": \"\"\n}"
},
{
"path": "crates/vt100-psmux/CHANGELOG.md",
"content": "# Changelog\n\n## [0.16.2] - 2025-07-11\n\n### Fixed\n\n* Fixed potential cursor out of bounds when using decrc after resizing. (#13)\n\n## [0.16.1] - 2025-07-10\n\n### Changed\n\n* Reverted to the 2021 edition for now.\n\n## [0.16.0] - 2025-07-08\n\n### Added\n\n* `Parser::process_cb`, which works the same as `Parser::process` except that\n it calls callbacks during parsing when it finds a terminal escape which is\n potentially useful but not something that affects the screen itself.\n* Support for xterm window resize request escape codes, via the new callback\n mechanism.\n* Support for dim formatting. (Daniel Faust, #9)\n* Support for CNL/CPL escape codes. (Danny Weinberg, #10)\n* Support for OSC 52 (clipboard manipulation).\n\n### Removed\n\n* These methods on `Screen` have been removed in favor of the new callback\n API described above:\n * `title_formatted`\n * `title_diff`\n * `title`\n * `icon_name`\n * `bells_diff`\n * `audible_bell_count`\n * `visual_bell_count`\n * `errors`\n* Additionally, unhandled escape sequences no longer log to STDERR; they\n instead call various callback methods which can be defined to log if\n desired.\n* `Cell` no longer implements `Default`.\n* `Screen` no longer implements `vte::Perform`.\n\n### Changed\n\n* `Parser::set_size` and `Parser::set_scrollback` have been moved to methods\n on `Screen`, and `Parser::screen_mut` was added to get a mutable reference\n to the screen.\n* `Cell::contents` now returns `&str` instead of `String`, eliminating an\n allocation in many cases. (Chris Olszewski, #14)\n\n### Fixed\n\n* Fixed some issues with calculating scrollback offsets correctly in\n `Grid::visible_rows`. (rezigned, #11)\n\n## [0.15.2] - 2023-02-05\n\n### Changed\n\n* Bumped dependencies\n\n## [0.15.1] - 2021-12-21\n\n### Changed\n\n* Removed a lot of unnecessary test data from the packaged crate, making\n downloads faster\n\n## [0.15.0] - 2021-12-15\n\n### Added\n\n* `Screen::errors` to track the number of parsing errors seen so far\n\n### Fixed\n\n* No longer generate spurious diffs in some cases where the cursor is past the\n end of a row\n* Fix restoring the cursor position when scrolled back\n\n### Changed\n\n* Various internal refactorings\n\n## [0.14.0] - 2021-12-06\n\n### Changed\n\n* Unknown UTF-8 characters default to a width of 1, rather than 0 (except for\n control characters, as mentioned below)\n\n### Fixed\n\n* Ignore C1 control characters rather than adding them to the cell data, since\n they are non-printable\n\n## [0.13.2] - 2021-12-05\n\n### Changed\n\n* Delay allocation of the alternate screen until it is used (saves a bit of\n memory in basic cases)\n\n## [0.13.1] - 2021-12-04\n\n### Fixed\n\n* Fixed various line wrapping state issues\n* Fixed cursor positioning after writing zero width characters at the end of\n the line\n* Fixed `Screen::cursor_state_formatted` to draw the last character in a line\n with the appropriate drawing attributes if it needs to redraw it\n\n## [0.13.0] - 2021-11-17\n\n### Added\n\n* `Screen::alternate_screen` to determine if the alternate screen is in use\n* `Screen::row_wrapped` to determine whether the row at the given index should\n wrap its text\n* `Screen::cursor_state_formatted` to set the cursor position and hidden state\n (including internal state like the one-past-the-end state which isn't visible\n in the return value of `cursor_position`)\n\n### Fixed\n\n* `Screen::rows_formatted` now outputs correct escape codes in some edge cases\n at the beginning of a row when the previous row was wrapped\n* VPA escape sequence can no longer position the cursor off the screen\n\n## [0.12.0] - 2021-03-09\n\n### Added\n\n* `Screen::state_formatted` and `Screen::state_diff` convenience wrappers\n\n### Fixed\n\n* `Screen::attributes_formatted` now correctly resets previously set attributes\n where necessary\n\n### Removed\n\n* Removed `Screen::attributes_diff`, since I can't actually think of any\n situation where it does a thing that makes sense.\n\n## [0.11.1] - 2021-03-07\n\n### Changed\n\n* Drop dependency on `enumset`\n\n## [0.11.0] - 2021-03-07\n\n### Added\n\n* `Screen::attributes_formatted` and `Screen::attributes_diff` to retrieve the\n current state of the drawing attributes as escape sequences\n* `Screen::fgcolor`, `Screen::bgcolor`, `Screen::bold`, `Screen::italic`,\n `Screen::underline`, and `Screen::inverse` to retrieve the current state of\n the drawing attributes directly\n\n## [0.10.0] - 2021-03-06\n\n### Added\n\n* Implementation of `std::io::Write` for `Parser`\n\n## [0.9.0] - 2021-03-05\n\n### Added\n\n* `Screen::contents_between`, for returning the contents logically between two\n given cells (for things like clipboard selection)\n* Support SGR subparameters (so `\\e[38:2:255:0:0m` behaves the same way as\n `\\e[38;2;255;0;0m`)\n\n### Fixed\n\n* Bump `enumset` to fix a dependency which fails to build\n\n## [0.8.1] - 2020-02-09\n\n### Changed\n\n* Bumped `vte` dep to 0.6.\n\n## [0.8.0] - 2019-12-07\n\n### Removed\n\n* Removed the unicode-normalization feature altogether - it turns out that it\n still has a couple edge cases where it causes incorrect behavior, and fixing\n those would be a lot more effort.\n\n### Fixed\n\n* Fix a couple more end-of-line/wrapping bugs, especially around cursor\n positioning.\n* Fix applying combining characters to wide characters.\n* Ensure cells can't have contents with width zero (to avoid ambiguity). If an\n empty cell gets a combining character applied to it, default that cell to a\n (normal-width) space first.\n\n## [0.7.0] - 2019-11-23\n\n### Added\n\n* New (default-on) cargo feature `unicode-normalization` which can be disabled\n to disable normalizing cell contents to NFC - it's a pretty small edge case,\n and the data tables required to support it are quite large, which affects\n size-sensitive targets like wasm\n\n## [0.6.3] - 2019-11-20\n\n### Fixed\n\n* Fix output of `contents_formatted` and `contents_diff` when the cursor\n position ends at one past the end of a row.\n* If the cursor position is one past the end of a row, any char, even a\n combining char, needs to cause the cursor position to wrap.\n\n## [0.6.2] - 2019-11-13\n\n### Fixed\n\n* Fix zero-width characters when the cursor is at the end of a row.\n\n## [0.6.1] - 2019-11-13\n\n### Added\n\n* Add more debug logging for unhandled escape sequences.\n\n### Changed\n\n* Unhandled escape sequence warnings are now at the `debug` log level.\n\n## [0.6.0] - 2019-11-13\n\n### Added\n\n* `Screen::input_mode_formatted` and `Screen::input_mode_diff` give escape\n codes to set the current terminal input modes.\n* `Screen::title_formatted` and `Screen::title_diff` give escape codes to set\n the terminal window title.\n* `Screen::bells_diff` gives escape codes to trigger any audible or visual\n bells which have been seen since the previous state.\n\n### Changed\n\n* `Screen::contents_diff` no longer includes audible or visual bells (see\n `Screen::bells_diff` instead).\n\n## [0.5.1] - 2019-11-12\n\n### Fixed\n\n* `Screen::set_size` now actually resizes when requested (previously the\n underlying storage was not being resized, leading to panics when writing\n outside of the original screen).\n\n## [0.5.0] - 2019-11-12\n\n### Added\n\n* Scrollback support.\n* `Default` impl for `Parser` which creates an 80x24 terminal with no\n scrollback.\n\n### Removed\n\n* `Parser::screen_mut` (and the `pub` `&mut self` methods on `Screen`). The few\n things you can do to change the screen state directly are now exposed as\n methods on `Parser` itself.\n\n### Changed\n\n* `Cell::contents` now returns a `String` instead of a `&str`.\n* `Screen::check_audible_bell` and `Screen::check_visual_bell` have been\n replaced with `Screen::audible_bell_count` and `Screen::visual_bell_count`.\n You should keep track of the \"since the last method call\" state yourself\n instead of having the screen track it for you.\n\n### Fixed\n\n* Lots of performance and output optimizations.\n* Clearing a cell now sets all of that cell's attributes to the current\n attribute set, since different terminals render different things for an empty\n cell based on the attributes.\n* `Screen::contents_diff` now includes audible and visual bells when\n appropriate.\n\n## [0.4.0] - 2019-11-08\n\n### Removed\n\n* `Screen::fgcolor`, `Screen::bgcolor`, `Screen::bold`, `Screen::italic`,\n `Screen::underline`, `Screen::inverse`, and `Screen::alternate_screen`:\n these are just implementation details that people shouldn't need to care\n about.\n\n### Fixed\n\n* Fixed cursor movement when the cursor position is already outside of an\n active scroll region.\n\n## [0.3.2] - 2019-11-08\n\n### Fixed\n\n* Clearing cells now correctly sets the cell background color.\n* Fixed a couple bugs in wide character handling in `contents_formatted` and\n `contents_diff`.\n* Fixed RI when the cursor is at the top of the screen (fixes scrolling up in\n `less`, for instance).\n* Fixed VPA incorrectly being clamped to the scroll region.\n* Stop treating soft hyphen specially (as far as i can tell, no other terminals\n do this, and i'm not sure why i thought it was necessary to begin with).\n* `contents_formatted` now also resets attributes at the start, like\n `contents_diff` does.\n\n## [0.3.1] - 2019-11-06\n\n### Fixed\n\n* Make `contents_formatted` explicitly show the cursor when necessary, in case\n the cursor was previously hidden.\n\n## [0.3.0] - 2019-11-06\n\n### Added\n\n* `Screen::rows` which is like `Screen::contents` except that it returns the\n data by row instead of all at once, and also allows you to restrict the\n region returned to a subset of columns.\n* `Screen::rows_formatted` which is like `Screen::rows`, but returns escape\n sequences sufficient to draw the requested subset of each row.\n* `Screen::contents_diff` and `Screen::rows_diff` which return escape sequences\n sufficient to turn the visible state of one screen (or a subset of the screen\n in the case of `rows_diff`) into another.\n\n### Changed\n\n* The screen is now exposed separately from the parser, and is cloneable.\n* `contents_formatted` now returns `Vec` instead of `String`.\n* `contents` and `contents_formatted` now only allow getting the contents of\n the entire screen rather than a subset (but see the entry for `rows` and\n `rows_formatted` above).\n\n### Removed\n\n* `Cell::new`, since there's not really any reason that this is useful for\n someone to do from outside of the crate.\n\n### Fixed\n\n* `contents_formatted` now preserves the state of empty cells instead of\n filling them with spaces.\n* We now clear the row wrapping state when the number of columns in the\n terminal is changed.\n* `contents_formatted` now ensures that the cursor has the correct hidden state\n and location.\n* `contents_formatted` now clears the screen before starting to draw.\n\n## [0.2.0] - 2019-11-04\n\n### Changed\n\n* Reimplemented in pure safe rust, with a much more accurate parser\n* A bunch of minor API tweaks, some backwards-incompatible\n\n## [0.1.2] - 2016-06-04\n\n### Fixed\n\n* Fix returning uninit memory in get_string_formatted/get_string_plaintext\n* Handle emoji and zero width unicode characters properly\n* Fix cursor positioning with regards to scroll regions and wrapping\n* Fix parsing of (ignored) character set escapes\n* Explicitly suppress status report escapes\n\n## [0.1.1] - 2016-04-28\n\n### Fixed\n\n* Fix builds\n\n## [0.1.0] - 2016-04-28\n\n### Added\n\n* Initial release\n"
},
{
"path": "crates/vt100-psmux/Cargo.toml",
"content": "# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO\n#\n# When uploading crates to the registry Cargo will automatically\n# \"normalize\" Cargo.toml files for maximal compatibility\n# with all versions of Cargo and also rewrite `path` dependencies\n# to registry (e.g., crates.io) dependencies.\n#\n# If you are reading this file be aware that the original Cargo.toml\n# will likely look very different (and much more reasonable).\n# See Cargo.toml.orig for the original contents.\n\n[package]\nedition = \"2021\"\nrust-version = \"1.70\"\nname = \"vt100-psmux\"\nversion = \"0.16.6\"\nauthors = [\"Jesse Luehrs \"]\nbuild = false\ninclude = [\n \"src/**/*\",\n \"LICENSE\",\n \"README.md\",\n \"CHANGELOG.md\",\n]\nautolib = false\nautobins = false\nautoexamples = false\nautotests = false\nautobenches = false\ndescription = \"Library for parsing terminal data (psmux fork with blink/hidden/strikethrough SGR + CSI cursor patches)\"\nhomepage = \"https://github.com/psmux/vt100-rust-patched\"\nreadme = \"README.md\"\nkeywords = [\n \"terminal\",\n \"vt100\",\n]\ncategories = [\n \"command-line-interface\",\n \"encoding\",\n]\nlicense = \"MIT\"\nrepository = \"https://github.com/psmux/vt100-rust-patched\"\n\n[lib]\nname = \"vt100_psmux\"\npath = \"src/lib.rs\"\n\n[dependencies.itoa]\nversion = \"1.0.15\"\n\n[dependencies.unicode-width]\nversion = \"0.2.1\"\n\n[dependencies.vte]\nversion = \"0.15.0\"\n\n[dev-dependencies.nix]\nversion = \"0.30.1\"\nfeatures = [\"term\"]\n\n[dev-dependencies.quickcheck]\nversion = \"1.0\"\n\n[dev-dependencies.rand]\nversion = \"0.10\"\n\n[dev-dependencies.serde]\nversion = \"1.0.219\"\nfeatures = [\"derive\"]\n\n[dev-dependencies.serde_json]\nversion = \"1.0.140\"\n\n[dev-dependencies.terminal_size]\nversion = \"0.4.2\"\n"
},
{
"path": "crates/vt100-psmux/Cargo.toml.orig",
"content": "[package]\nname = \"vt100-psmux\"\nversion = \"0.16.2\"\nauthors = [\"Jesse Luehrs \"]\nedition = \"2021\"\nrust-version = \"1.70\"\n\ndescription = \"Library for parsing terminal data (psmux fork with blink/hidden/strikethrough SGR + CSI cursor patches)\"\nhomepage = \"https://github.com/marlocarlo/vt100-rust-patched\"\nrepository = \"https://github.com/marlocarlo/vt100-rust-patched\"\nreadme = \"README.md\"\nkeywords = [\"terminal\", \"vt100\"]\ncategories = [\"command-line-interface\", \"encoding\"]\nlicense = \"MIT\"\ninclude = [\"src/**/*\", \"LICENSE\", \"README.md\", \"CHANGELOG.md\"]\n\n[dependencies]\nitoa = \"1.0.15\"\nunicode-width = \"0.2.1\"\nvte = \"0.15.0\"\n\n[dev-dependencies]\nnix = { version = \"0.30.1\", features = [\"term\"] }\nquickcheck = \"1.0\"\nrand = \"0.9\"\nserde = { version = \"1.0.219\", features = [\"derive\"] }\nserde_json = \"1.0.140\"\nterminal_size = \"0.4.2\"\n"
},
{
"path": "crates/vt100-psmux/LICENSE",
"content": "The MIT License (MIT)\n\nCopyright (c) 2016 Jesse Luehrs\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "crates/vt100-psmux/README.md",
"content": "# vt100\n\nThis crate parses a terminal byte stream and provides an in-memory\nrepresentation of the rendered contents.\n\n## Overview\n\nThis is essentially the terminal parser component of a graphical terminal\nemulator pulled out into a separate crate. Although you can use this crate\nto build a graphical terminal emulator, it also contains functionality\nnecessary for implementing terminal applications that want to run other\nterminal applications - programs like `screen` or `tmux` for example.\n\n## Synopsis\n\n```rust\nlet mut parser = vt100::Parser::new(24, 80, 0);\n\nlet screen = parser.screen().clone();\nparser.process(b\"this text is \\x1b[31mRED\\x1b[m\");\nassert_eq!(\n parser.screen().cell(0, 13).unwrap().fgcolor(),\n vt100::Color::Idx(1),\n);\n\nlet screen = parser.screen().clone();\nparser.process(b\"\\x1b[3D\\x1b[32mGREEN\");\nassert_eq!(\n parser.screen().contents_formatted(),\n &b\"\\x1b[?25h\\x1b[m\\x1b[H\\x1b[Jthis text is \\x1b[32mGREEN\"[..],\n);\nassert_eq!(\n parser.screen().contents_diff(&screen),\n &b\"\\x1b[1;14H\\x1b[32mGREEN\"[..],\n);\n```\n"
},
{
"path": "crates/vt100-psmux/src/attrs.rs",
"content": "use crate::term::BufWrite as _;\n\n/// Represents a foreground or background color for cells.\n#[derive(Eq, PartialEq, Debug, Copy, Clone, Default)]\npub enum Color {\n /// The default terminal color.\n #[default]\n Default,\n\n /// An indexed terminal color.\n Idx(u8),\n\n /// An RGB terminal color. The parameters are (red, green, blue).\n Rgb(u8, u8, u8),\n}\n\nconst TEXT_MODE_INTENSITY: u8 = 0b0000_0011;\nconst TEXT_MODE_BOLD: u8 = 0b0000_0001;\nconst TEXT_MODE_DIM: u8 = 0b0000_0010;\nconst TEXT_MODE_ITALIC: u8 = 0b0000_0100;\nconst TEXT_MODE_UNDERLINE: u8 = 0b0000_1000;\nconst TEXT_MODE_INVERSE: u8 = 0b0001_0000;\nconst TEXT_MODE_BLINK: u8 = 0b0010_0000;\nconst TEXT_MODE_HIDDEN: u8 = 0b0100_0000;\nconst TEXT_MODE_STRIKETHROUGH: u8 = 0b1000_0000;\n\n#[derive(Default, Clone, Copy, PartialEq, Eq, Debug)]\npub struct Attrs {\n pub fgcolor: Color,\n pub bgcolor: Color,\n pub mode: u8,\n}\n\nimpl Attrs {\n pub fn bold(&self) -> bool {\n self.mode & TEXT_MODE_BOLD != 0\n }\n\n pub fn dim(&self) -> bool {\n self.mode & TEXT_MODE_DIM != 0\n }\n\n fn intensity(&self) -> u8 {\n self.mode & TEXT_MODE_INTENSITY\n }\n\n pub fn set_bold(&mut self) {\n self.mode &= !TEXT_MODE_INTENSITY;\n self.mode |= TEXT_MODE_BOLD;\n }\n\n pub fn set_dim(&mut self) {\n self.mode &= !TEXT_MODE_INTENSITY;\n self.mode |= TEXT_MODE_DIM;\n }\n\n pub fn set_normal_intensity(&mut self) {\n self.mode &= !TEXT_MODE_INTENSITY;\n }\n\n pub fn italic(&self) -> bool {\n self.mode & TEXT_MODE_ITALIC != 0\n }\n\n pub fn set_italic(&mut self, italic: bool) {\n if italic {\n self.mode |= TEXT_MODE_ITALIC;\n } else {\n self.mode &= !TEXT_MODE_ITALIC;\n }\n }\n\n pub fn underline(&self) -> bool {\n self.mode & TEXT_MODE_UNDERLINE != 0\n }\n\n pub fn set_underline(&mut self, underline: bool) {\n if underline {\n self.mode |= TEXT_MODE_UNDERLINE;\n } else {\n self.mode &= !TEXT_MODE_UNDERLINE;\n }\n }\n\n pub fn inverse(&self) -> bool {\n self.mode & TEXT_MODE_INVERSE != 0\n }\n\n pub fn set_inverse(&mut self, inverse: bool) {\n if inverse {\n self.mode |= TEXT_MODE_INVERSE;\n } else {\n self.mode &= !TEXT_MODE_INVERSE;\n }\n }\n\n pub fn blink(&self) -> bool {\n self.mode & TEXT_MODE_BLINK != 0\n }\n\n pub fn set_blink(&mut self, blink: bool) {\n if blink {\n self.mode |= TEXT_MODE_BLINK;\n } else {\n self.mode &= !TEXT_MODE_BLINK;\n }\n }\n\n pub fn hidden(&self) -> bool {\n self.mode & TEXT_MODE_HIDDEN != 0\n }\n\n pub fn set_hidden(&mut self, hidden: bool) {\n if hidden {\n self.mode |= TEXT_MODE_HIDDEN;\n } else {\n self.mode &= !TEXT_MODE_HIDDEN;\n }\n }\n\n pub fn strikethrough(&self) -> bool {\n self.mode & TEXT_MODE_STRIKETHROUGH != 0\n }\n\n pub fn set_strikethrough(&mut self, strikethrough: bool) {\n if strikethrough {\n self.mode |= TEXT_MODE_STRIKETHROUGH;\n } else {\n self.mode &= !TEXT_MODE_STRIKETHROUGH;\n }\n }\n\n pub fn write_escape_code_diff(\n &self,\n contents: &mut Vec,\n other: &Self,\n ) {\n if self != other && self == &Self::default() {\n crate::term::ClearAttrs.write_buf(contents);\n return;\n }\n\n let attrs = crate::term::Attrs::default();\n\n let attrs = if self.fgcolor == other.fgcolor {\n attrs\n } else {\n attrs.fgcolor(self.fgcolor)\n };\n let attrs = if self.bgcolor == other.bgcolor {\n attrs\n } else {\n attrs.bgcolor(self.bgcolor)\n };\n let attrs = if self.intensity() == other.intensity() {\n attrs\n } else {\n attrs.intensity(match self.intensity() {\n 0 => crate::term::Intensity::Normal,\n TEXT_MODE_BOLD => crate::term::Intensity::Bold,\n TEXT_MODE_DIM => crate::term::Intensity::Dim,\n _ => unreachable!(),\n })\n };\n let attrs = if self.italic() == other.italic() {\n attrs\n } else {\n attrs.italic(self.italic())\n };\n let attrs = if self.underline() == other.underline() {\n attrs\n } else {\n attrs.underline(self.underline())\n };\n let attrs = if self.inverse() == other.inverse() {\n attrs\n } else {\n attrs.inverse(self.inverse())\n };\n let attrs = if self.blink() == other.blink() {\n attrs\n } else {\n attrs.blink(self.blink())\n };\n let attrs = if self.hidden() == other.hidden() {\n attrs\n } else {\n attrs.hidden(self.hidden())\n };\n let attrs = if self.strikethrough() == other.strikethrough() {\n attrs\n } else {\n attrs.strikethrough(self.strikethrough())\n };\n\n attrs.write_buf(contents);\n }\n}\n"
},
{
"path": "crates/vt100-psmux/src/callbacks.rs",
"content": "/// This trait is used by the parser to handle extra escape sequences that\n/// don't have an impact on the terminal screen directly.\npub trait Callbacks {\n /// This callback is called when the terminal requests an audible bell\n /// (typically with `^G`).\n fn audible_bell(&mut self, _: &mut crate::Screen) {}\n /// This callback is called when the terminal requests a visual bell\n /// (typically with `\\eg`).\n fn visual_bell(&mut self, _: &mut crate::Screen) {}\n /// This callback is called when the terminal requests a resize\n /// (typically with `\\e[8;;t`).\n fn resize(&mut self, _: &mut crate::Screen, _request: (u16, u16)) {}\n /// This callback is called when the terminal requests the window title\n /// to be set (typically with `\\e]1;\\a`)\n fn set_window_icon_name(\n &mut self,\n _: &mut crate::Screen,\n _icon_name: &[u8],\n ) {\n }\n /// This callback is called when the terminal requests the window title\n /// to be set (typically with `\\e]2;\\a`)\n fn set_window_title(&mut self, _: &mut crate::Screen, _title: &[u8]) {}\n /// This callback is called when the terminal requests data to be copied\n /// to the system clipboard (typically with `\\e]52;<ty>;<data>\\a`). Note\n /// that `data` will be encoded as base64.\n fn copy_to_clipboard(\n &mut self,\n _: &mut crate::Screen,\n _ty: &[u8],\n _data: &[u8],\n ) {\n }\n /// This callback is called when the terminal requests data to be pasted\n /// from the system clipboard (typically with `\\e]52;<ty>;?\\a`).\n fn paste_from_clipboard(&mut self, _: &mut crate::Screen, _ty: &[u8]) {}\n /// This callback is called when the terminal receives an escape sequence\n /// which is otherwise not implemented.\n fn unhandled_char(&mut self, _: &mut crate::Screen, _c: char) {}\n /// This callback is called when the terminal receives a control\n /// character which is otherwise not implemented.\n fn unhandled_control(&mut self, _: &mut crate::Screen, _b: u8) {}\n /// This callback is called when the terminal receives an escape sequence\n /// which is otherwise not implemented.\n fn unhandled_escape(\n &mut self,\n _: &mut crate::Screen,\n _i1: Option<u8>,\n _i2: Option<u8>,\n _b: u8,\n ) {\n }\n /// This callback is called when the terminal receives a CSI sequence\n /// (`\\e[`) which is otherwise not implemented.\n fn unhandled_csi(\n &mut self,\n _: &mut crate::Screen,\n _i1: Option<u8>,\n _i2: Option<u8>,\n _params: &[&[u16]],\n _c: char,\n ) {\n }\n /// This callback is called when the terminal receives a OSC sequence\n /// (`\\e]`) which is otherwise not implemented.\n fn unhandled_osc(&mut self, _: &mut crate::Screen, _params: &[&[u8]]) {}\n\n /// This callback is called when the terminal receives an OSC 9;4\n /// (Windows Terminal progress indicator) sequence. State values:\n /// 0 = hide, 1 = default, 2 = error, 3 = indeterminate, 4 = warning.\n /// Progress is in 0..=100.\n fn set_progress(\n &mut self,\n _: &mut crate::Screen,\n _state: u8,\n _progress: u8,\n ) {\n }\n}\n\nimpl Callbacks for () {}\n"
},
{
"path": "crates/vt100-psmux/src/cell.rs",
"content": "use unicode_width::UnicodeWidthChar as _;\n\n// chosen to make the size of the cell struct 32 bytes\nconst CONTENT_BYTES: usize = 22;\n\nconst IS_WIDE: u8 = 0b1000_0000;\nconst IS_WIDE_CONTINUATION: u8 = 0b0100_0000;\nconst LEN_BITS: u8 = 0b0001_1111;\n\n/// Represents a single terminal cell.\n#[derive(Clone, Debug, Eq)]\npub struct Cell {\n contents: [u8; CONTENT_BYTES],\n len: u8,\n attrs: crate::attrs::Attrs,\n}\nconst _: () = assert!(std::mem::size_of::<Cell>() == 32);\n\nimpl PartialEq<Self> for Cell {\n fn eq(&self, other: &Self) -> bool {\n if self.len != other.len {\n return false;\n }\n if self.attrs != other.attrs {\n return false;\n }\n let len = self.len();\n self.contents[..len] == other.contents[..len]\n }\n}\n\nimpl Cell {\n pub(crate) fn new() -> Self {\n Self {\n contents: Default::default(),\n len: 0,\n attrs: crate::attrs::Attrs::default(),\n }\n }\n\n fn len(&self) -> usize {\n usize::from(self.len & LEN_BITS)\n }\n\n pub(crate) fn set(&mut self, c: char, a: crate::attrs::Attrs) {\n self.len = 0;\n self.append_char(0, c);\n // strings in this context should always be an arbitrary character\n // followed by zero or more zero-width characters, so we should only\n // have to look at the first character\n self.set_wide(c.width().unwrap_or(1) > 1);\n self.attrs = a;\n }\n\n pub(crate) fn append(&mut self, c: char) {\n let len = self.len();\n if len >= CONTENT_BYTES - 4 {\n return;\n }\n if len == 0 {\n self.contents[0] = b' ';\n self.len += 1;\n }\n\n // we already checked that we have space for another codepoint\n self.append_char(self.len(), c);\n }\n\n // Writes bytes representing c at start\n // Requires caller to verify start <= CODEPOINTS_IN_CELL * 4\n fn append_char(&mut self, start: usize, c: char) {\n c.encode_utf8(&mut self.contents[start..]);\n self.len += u8::try_from(c.len_utf8()).unwrap();\n }\n\n pub(crate) fn clear(&mut self, attrs: crate::attrs::Attrs) {\n self.len = 0;\n self.attrs = attrs;\n }\n\n /// Returns the text contents of the cell.\n ///\n /// Can include multiple unicode characters if combining characters are\n /// used, but will contain at most one character with a non-zero character\n /// width.\n // Since contents has been constructed by appending chars encoded as UTF-8 it will be valid UTF-8\n #[allow(clippy::missing_panics_doc)]\n #[must_use]\n pub fn contents(&self) -> &str {\n std::str::from_utf8(&self.contents[..self.len()]).unwrap()\n }\n\n /// Returns whether the cell contains any text data.\n #[must_use]\n pub fn has_contents(&self) -> bool {\n self.len() > 0\n }\n\n /// Returns whether the text data in the cell represents a wide character.\n #[must_use]\n pub fn is_wide(&self) -> bool {\n self.len & IS_WIDE != 0\n }\n\n /// Returns whether the cell contains the second half of a wide character\n /// (in other words, whether the previous cell in the row contains a wide\n /// character)\n #[must_use]\n pub fn is_wide_continuation(&self) -> bool {\n self.len & IS_WIDE_CONTINUATION != 0\n }\n\n fn set_wide(&mut self, wide: bool) {\n if wide {\n self.len |= IS_WIDE;\n } else {\n self.len &= !IS_WIDE;\n }\n }\n\n pub(crate) fn set_wide_continuation(&mut self, wide: bool) {\n if wide {\n self.len |= IS_WIDE_CONTINUATION;\n } else {\n self.len &= !IS_WIDE_CONTINUATION;\n }\n }\n\n pub(crate) fn attrs(&self) -> &crate::attrs::Attrs {\n &self.attrs\n }\n\n /// Returns the foreground color of the cell.\n #[must_use]\n pub fn fgcolor(&self) -> crate::Color {\n self.attrs.fgcolor\n }\n\n /// Returns the background color of the cell.\n #[must_use]\n pub fn bgcolor(&self) -> crate::Color {\n self.attrs.bgcolor\n }\n\n /// Returns whether the cell should be rendered with the bold text\n /// attribute.\n #[must_use]\n pub fn bold(&self) -> bool {\n self.attrs.bold()\n }\n\n /// Returns whether the cell should be rendered with the dim text\n /// attribute.\n #[must_use]\n pub fn dim(&self) -> bool {\n self.attrs.dim()\n }\n\n /// Returns whether the cell should be rendered with the italic text\n /// attribute.\n #[must_use]\n pub fn italic(&self) -> bool {\n self.attrs.italic()\n }\n\n /// Returns whether the cell should be rendered with the underlined text\n /// attribute.\n #[must_use]\n pub fn underline(&self) -> bool {\n self.attrs.underline()\n }\n\n /// Returns whether the cell should be rendered with the inverse text\n /// attribute.\n #[must_use]\n pub fn inverse(&self) -> bool {\n self.attrs.inverse()\n }\n\n /// Returns whether the cell should be rendered with the blink text\n /// attribute.\n #[must_use]\n pub fn blink(&self) -> bool {\n self.attrs.blink()\n }\n\n /// Returns whether the cell should be rendered with the hidden/invisible\n /// text attribute.\n #[must_use]\n pub fn hidden(&self) -> bool {\n self.attrs.hidden()\n }\n\n /// Returns whether the cell should be rendered with the strikethrough\n /// text attribute.\n #[must_use]\n pub fn strikethrough(&self) -> bool {\n self.attrs.strikethrough()\n }\n}\n"
},
{
"path": "crates/vt100-psmux/src/grid.rs",
"content": "use crate::term::BufWrite as _;\n\n#[derive(Clone, Debug)]\npub struct Grid {\n size: Size,\n pos: Pos,\n saved_pos: Pos,\n rows: Vec<crate::row::Row>,\n scroll_top: u16,\n scroll_bottom: u16,\n origin_mode: bool,\n saved_origin_mode: bool,\n scrollback: std::collections::VecDeque<crate::row::Row>,\n scrollback_len: usize,\n scrollback_offset: usize,\n}\n\nimpl Grid {\n pub fn new(size: Size, scrollback_len: usize) -> Self {\n Self {\n size,\n pos: Pos::default(),\n saved_pos: Pos::default(),\n rows: vec![],\n scroll_top: 0,\n scroll_bottom: size.rows - 1,\n origin_mode: false,\n saved_origin_mode: false,\n scrollback: std::collections::VecDeque::new(),\n scrollback_len,\n scrollback_offset: 0,\n }\n }\n\n pub fn allocate_rows(&mut self) {\n if self.rows.is_empty() {\n self.rows.extend(\n std::iter::repeat_with(|| {\n crate::row::Row::new(self.size.cols)\n })\n .take(usize::from(self.size.rows)),\n );\n }\n }\n\n fn new_row(&self) -> crate::row::Row {\n crate::row::Row::new(self.size.cols)\n }\n\n pub fn clear(&mut self) {\n self.pos = Pos::default();\n self.saved_pos = Pos::default();\n for row in self.drawing_rows_mut() {\n row.clear(crate::attrs::Attrs::default());\n }\n self.scroll_top = 0;\n self.scroll_bottom = self.size.rows - 1;\n self.origin_mode = false;\n self.saved_origin_mode = false;\n }\n\n pub fn size(&self) -> Size {\n self.size\n }\n\n pub fn set_size(&mut self, size: Size) {\n if size.cols != self.size.cols {\n for row in &mut self.rows {\n row.wrap(false);\n }\n }\n\n if self.scroll_bottom == self.size.rows - 1 {\n self.scroll_bottom = size.rows - 1;\n }\n\n self.size = size;\n for row in &mut self.rows {\n row.resize(size.cols, crate::Cell::new());\n }\n self.rows.resize(usize::from(size.rows), self.new_row());\n\n if self.scroll_bottom >= size.rows {\n self.scroll_bottom = size.rows - 1;\n }\n if self.scroll_bottom < self.scroll_top {\n self.scroll_top = 0;\n }\n\n self.row_clamp_top(false);\n self.row_clamp_bottom(false);\n self.col_clamp();\n\n if self.saved_pos.row > self.size.rows - 1 {\n self.saved_pos.row = self.size.rows - 1;\n }\n if self.saved_pos.col > self.size.cols - 1 {\n self.saved_pos.col = self.size.cols - 1;\n }\n }\n\n pub fn pos(&self) -> Pos {\n self.pos\n }\n\n pub fn set_pos(&mut self, mut pos: Pos) {\n if self.origin_mode {\n pos.row = pos.row.saturating_add(self.scroll_top);\n }\n self.pos = pos;\n self.row_clamp_top(self.origin_mode);\n self.row_clamp_bottom(self.origin_mode);\n self.col_clamp();\n }\n\n pub fn save_cursor(&mut self) {\n self.saved_pos = self.pos;\n self.saved_origin_mode = self.origin_mode;\n }\n\n pub fn restore_cursor(&mut self) {\n self.pos = self.saved_pos;\n self.origin_mode = self.saved_origin_mode;\n }\n\n pub fn visible_rows(&self) -> impl Iterator<Item = &crate::row::Row> {\n let scrollback_len = self.scrollback.len();\n let rows_len = self.rows.len();\n self.scrollback\n .iter()\n .skip(scrollback_len - self.scrollback_offset)\n // when scrollback_offset > rows_len (e.g. rows = 3,\n // scrollback_len = 10, offset = 9) the skip(10 - 9)\n // will take 9 rows instead of 3. we need to set\n // the upper bound to rows_len (e.g. 3)\n .take(rows_len)\n // same for rows_len - scrollback_offset (e.g. 3 - 9).\n // it'll panic with overflow. we have to saturate the subtraction.\n .chain(\n self.rows\n .iter()\n .take(rows_len.saturating_sub(self.scrollback_offset)),\n )\n }\n\n pub fn drawing_rows(&self) -> impl Iterator<Item = &crate::row::Row> {\n self.rows.iter()\n }\n\n pub fn drawing_rows_mut(\n &mut self,\n ) -> impl Iterator<Item = &mut crate::row::Row> {\n self.rows.iter_mut()\n }\n\n pub fn visible_row(&self, row: u16) -> Option<&crate::row::Row> {\n self.visible_rows().nth(usize::from(row))\n }\n\n pub fn drawing_row(&self, row: u16) -> Option<&crate::row::Row> {\n self.drawing_rows().nth(usize::from(row))\n }\n\n pub fn drawing_row_mut(\n &mut self,\n row: u16,\n ) -> Option<&mut crate::row::Row> {\n self.drawing_rows_mut().nth(usize::from(row))\n }\n\n pub fn current_row_mut(&mut self) -> &mut crate::row::Row {\n self.drawing_row_mut(self.pos.row)\n // we assume self.pos.row is always valid\n .unwrap()\n }\n\n pub fn visible_cell(&self, pos: Pos) -> Option<&crate::Cell> {\n self.visible_row(pos.row).and_then(|r| r.get(pos.col))\n }\n\n pub fn drawing_cell(&self, pos: Pos) -> Option<&crate::Cell> {\n self.drawing_row(pos.row).and_then(|r| r.get(pos.col))\n }\n\n pub fn drawing_cell_mut(&mut self, pos: Pos) -> Option<&mut crate::Cell> {\n self.drawing_row_mut(pos.row)\n .and_then(|r| r.get_mut(pos.col))\n }\n\n pub fn scrollback_len(&self) -> usize {\n self.scrollback_len\n }\n\n pub fn scrollback(&self) -> usize {\n self.scrollback_offset\n }\n\n pub fn set_scrollback(&mut self, rows: usize) {\n self.scrollback_offset = rows.min(self.scrollback.len());\n }\n\n /// Returns the number of rows currently held in the scrollback buffer\n /// (distinct from `scrollback_len`, which is the configured maximum).\n pub fn scrollback_filled(&self) -> usize {\n self.scrollback.len()\n }\n\n /// Updates the scrollback buffer's maximum size. When `new_len` is\n /// smaller than the current fill, the oldest rows are trimmed away.\n pub fn set_scrollback_len(&mut self, new_len: usize) {\n self.scrollback_len = new_len;\n while self.scrollback.len() > self.scrollback_len {\n self.scrollback.pop_front();\n }\n if self.scrollback_offset > self.scrollback.len() {\n self.scrollback_offset = self.scrollback.len();\n }\n }\n\n /// Append a row to the back of scrollback, evicting the oldest if\n /// the cap is reached. Used by the alt-screen-to-scrollback copy\n /// path (psmux issue #88). Honours `scrollback_len = 0` (no-op),\n /// matching how the normal in-flow scrolling treats that case.\n pub fn push_row_to_scrollback(&mut self, row: crate::row::Row) {\n if self.scrollback_len == 0 {\n return;\n }\n self.scrollback.push_back(row);\n while self.scrollback.len() > self.scrollback_len {\n self.scrollback.pop_front();\n }\n if self.scrollback_offset > 0 {\n self.scrollback_offset =\n self.scrollback.len().min(self.scrollback_offset + 1);\n }\n }\n\n pub fn write_contents(&self, contents: &mut String) {\n let mut wrapping = false;\n for row in self.visible_rows() {\n row.write_contents(contents, 0, self.size.cols, wrapping);\n if !row.wrapped() {\n contents.push('\\n');\n }\n wrapping = row.wrapped();\n }\n\n while contents.ends_with('\\n') {\n contents.truncate(contents.len() - 1);\n }\n }\n\n pub fn write_contents_formatted(\n &self,\n contents: &mut Vec<u8>,\n ) -> crate::attrs::Attrs {\n crate::term::ClearAttrs.write_buf(contents);\n crate::term::ClearScreen.write_buf(contents);\n\n let mut prev_attrs = crate::attrs::Attrs::default();\n let mut prev_pos = Pos::default();\n let mut wrapping = false;\n for (i, row) in self.visible_rows().enumerate() {\n // we limit the number of cols to a u16 (see Size), so\n // visible_rows() can never return more rows than will fit\n let i = i.try_into().unwrap();\n let (new_pos, new_attrs) = row.write_contents_formatted(\n contents,\n 0,\n self.size.cols,\n i,\n wrapping,\n Some(prev_pos),\n Some(prev_attrs),\n );\n prev_pos = new_pos;\n prev_attrs = new_attrs;\n wrapping = row.wrapped();\n }\n\n self.write_cursor_position_formatted(\n contents,\n Some(prev_pos),\n Some(prev_attrs),\n );\n\n prev_attrs\n }\n\n pub fn write_contents_diff(\n &self,\n contents: &mut Vec<u8>,\n prev: &Self,\n mut prev_attrs: crate::attrs::Attrs,\n ) -> crate::attrs::Attrs {\n let mut prev_pos = prev.pos;\n let mut wrapping = false;\n let mut prev_wrapping = false;\n for (i, (row, prev_row)) in\n self.visible_rows().zip(prev.visible_rows()).enumerate()\n {\n // we limit the number of cols to a u16 (see Size), so\n // visible_rows() can never return more rows than will fit\n let i = i.try_into().unwrap();\n let (new_pos, new_attrs) = row.write_contents_diff(\n contents,\n prev_row,\n 0,\n self.size.cols,\n i,\n wrapping,\n prev_wrapping,\n prev_pos,\n prev_attrs,\n );\n prev_pos = new_pos;\n prev_attrs = new_attrs;\n wrapping = row.wrapped();\n prev_wrapping = prev_row.wrapped();\n }\n\n self.write_cursor_position_formatted(\n contents,\n Some(prev_pos),\n Some(prev_attrs),\n );\n\n prev_attrs\n }\n\n pub fn write_cursor_position_formatted(\n &self,\n contents: &mut Vec<u8>,\n prev_pos: Option<Pos>,\n prev_attrs: Option<crate::attrs::Attrs>,\n ) {\n let prev_attrs = prev_attrs.unwrap_or_default();\n // writing a character to the last column of a row doesn't wrap the\n // cursor immediately - it waits until the next character is actually\n // drawn. it is only possible for the cursor to have this kind of\n // position after drawing a character though, so if we end in this\n // position, we need to redraw the character at the end of the row.\n if prev_pos != Some(self.pos) && self.pos.col >= self.size.cols {\n let mut pos = Pos {\n row: self.pos.row,\n col: self.size.cols - 1,\n };\n if self\n .drawing_cell(pos)\n // we assume self.pos.row is always valid, and self.size.cols\n // - 1 is always a valid column\n .unwrap()\n .is_wide_continuation()\n {\n pos.col = self.size.cols - 2;\n }\n let cell =\n // we assume self.pos.row is always valid, and self.size.cols\n // - 2 must be a valid column because self.size.cols - 1 is\n // always valid and we just checked that the cell at\n // self.size.cols - 1 is a wide continuation character, which\n // means that the first half of the wide character must be\n // before it\n self.drawing_cell(pos).unwrap();\n if cell.has_contents() {\n if let Some(prev_pos) = prev_pos {\n crate::term::MoveFromTo::new(prev_pos, pos)\n .write_buf(contents);\n } else {\n crate::term::MoveTo::new(pos).write_buf(contents);\n }\n cell.attrs().write_escape_code_diff(contents, &prev_attrs);\n contents.extend(cell.contents().as_bytes());\n prev_attrs.write_escape_code_diff(contents, cell.attrs());\n } else {\n // if the cell doesn't have contents, we can't have gotten\n // here by drawing a character in the last column. this means\n // that as far as i'm aware, we have to have reached here from\n // a newline when we were already after the end of an earlier\n // row. in the case where we are already after the end of an\n // earlier row, we can just write a few newlines, otherwise we\n // also need to do the same as above to get ourselves to after\n // the end of a row.\n let mut found = false;\n for i in (0..self.pos.row).rev() {\n pos.row = i;\n pos.col = self.size.cols - 1;\n if self\n .drawing_cell(pos)\n // i is always less than self.pos.row, which we assume\n // to be always valid, so it must also be valid.\n // self.size.cols - 1 is always a valid col.\n .unwrap()\n .is_wide_continuation()\n {\n pos.col = self.size.cols - 2;\n }\n let cell = self\n .drawing_cell(pos)\n // i is always less than self.pos.row, which we assume\n // to be always valid, so it must also be valid.\n // self.size.cols - 2 is valid because self.size.cols\n // - 1 is always valid, and col gets set to\n // self.size.cols - 2 when the cell at self.size.cols\n // - 1 is a wide continuation character, meaning that\n // the first half of the wide character must be before\n // it\n .unwrap();\n if cell.has_contents() {\n if let Some(prev_pos) = prev_pos {\n if prev_pos.row != i\n || prev_pos.col < self.size.cols\n {\n crate::term::MoveFromTo::new(prev_pos, pos)\n .write_buf(contents);\n cell.attrs().write_escape_code_diff(\n contents,\n &prev_attrs,\n );\n contents.extend(cell.contents().as_bytes());\n prev_attrs.write_escape_code_diff(\n contents,\n cell.attrs(),\n );\n }\n } else {\n crate::term::MoveTo::new(pos).write_buf(contents);\n cell.attrs().write_escape_code_diff(\n contents,\n &prev_attrs,\n );\n contents.extend(cell.contents().as_bytes());\n prev_attrs.write_escape_code_diff(\n contents,\n cell.attrs(),\n );\n }\n contents.extend(\n \"\\n\".repeat(usize::from(self.pos.row - i))\n .as_bytes(),\n );\n found = true;\n break;\n }\n }\n\n // this can happen if you get the cursor off the end of a row,\n // and then do something to clear the end of the current row\n // without moving the cursor (IL, DL, ED, EL, etc). we know\n // there can't be something in the last column because we\n // would have caught that above, so it should be safe to\n // overwrite it.\n if !found {\n pos = Pos {\n row: self.pos.row,\n col: self.size.cols - 1,\n };\n if let Some(prev_pos) = prev_pos {\n crate::term::MoveFromTo::new(prev_pos, pos)\n .write_buf(contents);\n } else {\n crate::term::MoveTo::new(pos).write_buf(contents);\n }\n contents.push(b' ');\n // we know that the cell has no contents, but it still may\n // have drawing attributes (background color, etc)\n let end_cell = self\n .drawing_cell(pos)\n // we assume self.pos.row is always valid, and\n // self.size.cols - 1 is always a valid column\n .unwrap();\n end_cell\n .attrs()\n .write_escape_code_diff(contents, &prev_attrs);\n crate::term::SaveCursor.write_buf(contents);\n crate::term::Backspace.write_buf(contents);\n crate::term::EraseChar::new(1).write_buf(contents);\n crate::term::RestoreCursor.write_buf(contents);\n prev_attrs\n .write_escape_code_diff(contents, end_cell.attrs());\n }\n }\n } else if let Some(prev_pos) = prev_pos {\n crate::term::MoveFromTo::new(prev_pos, self.pos)\n .write_buf(contents);\n } else {\n crate::term::MoveTo::new(self.pos).write_buf(contents);\n }\n }\n\n pub fn clear_scrollback(&mut self) {\n self.scrollback.clear();\n self.scrollback_offset = 0;\n }\n\n pub fn erase_all(&mut self, attrs: crate::attrs::Attrs) {\n for row in self.drawing_rows_mut() {\n row.clear(attrs);\n }\n }\n\n pub fn erase_all_forward(&mut self, attrs: crate::attrs::Attrs) {\n let pos = self.pos;\n for row in self.drawing_rows_mut().skip(usize::from(pos.row) + 1) {\n row.clear(attrs);\n }\n\n self.erase_row_forward(attrs);\n }\n\n pub fn erase_all_backward(&mut self, attrs: crate::attrs::Attrs) {\n let pos = self.pos;\n for row in self.drawing_rows_mut().take(usize::from(pos.row)) {\n row.clear(attrs);\n }\n\n self.erase_row_backward(attrs);\n }\n\n pub fn erase_row(&mut self, attrs: crate::attrs::Attrs) {\n self.current_row_mut().clear(attrs);\n }\n\n pub fn erase_row_forward(&mut self, attrs: crate::attrs::Attrs) {\n let size = self.size;\n let pos = self.pos;\n let row = self.current_row_mut();\n for col in pos.col..size.cols {\n row.erase(col, attrs);\n }\n }\n\n pub fn erase_row_backward(&mut self, attrs: crate::attrs::Attrs) {\n let size = self.size;\n let pos = self.pos;\n let row = self.current_row_mut();\n for col in 0..=pos.col.min(size.cols - 1) {\n row.erase(col, attrs);\n }\n }\n\n pub fn insert_cells(&mut self, count: u16) {\n let size = self.size;\n let pos = self.pos;\n let wide = pos.col < size.cols\n && self\n .drawing_cell(pos)\n // we assume self.pos.row is always valid, and we know we are\n // not off the end of a row because we just checked pos.col <\n // size.cols\n .unwrap()\n .is_wide_continuation();\n let row = self.current_row_mut();\n for _ in 0..count {\n if wide {\n row.get_mut(pos.col).unwrap().set_wide_continuation(false);\n }\n row.insert(pos.col, crate::Cell::new());\n if wide {\n row.get_mut(pos.col).unwrap().set_wide_continuation(true);\n }\n }\n row.truncate(size.cols);\n }\n\n pub fn delete_cells(&mut self, count: u16) {\n let size = self.size;\n let pos = self.pos;\n let row = self.current_row_mut();\n for _ in 0..(count.min(size.cols - pos.col)) {\n row.remove(pos.col);\n }\n row.resize(size.cols, crate::Cell::new());\n }\n\n pub fn erase_cells(&mut self, count: u16, attrs: crate::attrs::Attrs) {\n let size = self.size;\n let pos = self.pos;\n let row = self.current_row_mut();\n for col in pos.col..((pos.col.saturating_add(count)).min(size.cols)) {\n row.erase(col, attrs);\n }\n }\n\n pub fn insert_lines(&mut self, count: u16) {\n for _ in 0..count {\n self.rows.remove(usize::from(self.scroll_bottom));\n self.rows.insert(usize::from(self.pos.row), self.new_row());\n // self.scroll_bottom is maintained to always be a valid row\n self.rows[usize::from(self.scroll_bottom)].wrap(false);\n }\n }\n\n pub fn delete_lines(&mut self, count: u16) {\n for _ in 0..(count.min(self.size.rows - self.pos.row)) {\n self.rows\n .insert(usize::from(self.scroll_bottom) + 1, self.new_row());\n self.rows.remove(usize::from(self.pos.row));\n }\n }\n\n pub fn scroll_up(&mut self, count: u16) {\n for _ in 0..(count.min(self.size.rows - self.scroll_top)) {\n self.rows\n .insert(usize::from(self.scroll_bottom) + 1, self.new_row());\n let removed = self.rows.remove(usize::from(self.scroll_top));\n if self.scrollback_len > 0 && !self.scroll_region_active() {\n self.scrollback.push_back(removed);\n while self.scrollback.len() > self.scrollback_len {\n self.scrollback.pop_front();\n }\n if self.scrollback_offset > 0 {\n self.scrollback_offset =\n self.scrollback.len().min(self.scrollback_offset + 1);\n }\n }\n }\n }\n\n pub fn scroll_down(&mut self, count: u16) {\n for _ in 0..count {\n self.rows.remove(usize::from(self.scroll_bottom));\n self.rows\n .insert(usize::from(self.scroll_top), self.new_row());\n // self.scroll_bottom is maintained to always be a valid row\n self.rows[usize::from(self.scroll_bottom)].wrap(false);\n }\n }\n\n pub fn set_scroll_region(&mut self, top: u16, bottom: u16) {\n let bottom = bottom.min(self.size().rows - 1);\n if top < bottom {\n self.scroll_top = top;\n self.scroll_bottom = bottom;\n } else {\n self.scroll_top = 0;\n self.scroll_bottom = self.size().rows - 1;\n }\n self.pos.row = self.scroll_top;\n self.pos.col = 0;\n }\n\n fn in_scroll_region(&self) -> bool {\n self.pos.row >= self.scroll_top && self.pos.row <= self.scroll_bottom\n }\n\n fn scroll_region_active(&self) -> bool {\n self.scroll_top != 0 || self.scroll_bottom != self.size.rows - 1\n }\n\n pub fn set_origin_mode(&mut self, mode: bool) {\n self.origin_mode = mode;\n self.set_pos(Pos { row: 0, col: 0 });\n }\n\n pub fn row_inc_clamp(&mut self, count: u16) {\n let in_scroll_region = self.in_scroll_region();\n self.pos.row = self.pos.row.saturating_add(count);\n self.row_clamp_bottom(in_scroll_region);\n }\n\n pub fn row_inc_scroll(&mut self, count: u16) -> u16 {\n let in_scroll_region = self.in_scroll_region();\n self.pos.row = self.pos.row.saturating_add(count);\n let lines = self.row_clamp_bottom(in_scroll_region);\n if in_scroll_region {\n self.scroll_up(lines);\n lines\n } else {\n 0\n }\n }\n\n pub fn row_dec_clamp(&mut self, count: u16) {\n let in_scroll_region = self.in_scroll_region();\n self.pos.row = self.pos.row.saturating_sub(count);\n self.row_clamp_top(in_scroll_region);\n }\n\n pub fn row_dec_scroll(&mut self, count: u16) {\n let in_scroll_region = self.in_scroll_region();\n // need to account for clamping by both row_clamp_top and by\n // saturating_sub\n let extra_lines = count.saturating_sub(self.pos.row);\n self.pos.row = self.pos.row.saturating_sub(count);\n let lines = self.row_clamp_top(in_scroll_region);\n self.scroll_down(lines + extra_lines);\n }\n\n pub fn row_set(&mut self, i: u16) {\n self.pos.row = i;\n self.row_clamp();\n }\n\n pub fn col_inc(&mut self, count: u16) {\n self.pos.col = self.pos.col.saturating_add(count);\n }\n\n pub fn col_inc_clamp(&mut self, count: u16) {\n self.pos.col = self.pos.col.saturating_add(count);\n self.col_clamp();\n }\n\n pub fn col_dec(&mut self, count: u16) {\n self.pos.col = self.pos.col.saturating_sub(count);\n }\n\n pub fn col_tab(&mut self) {\n self.pos.col -= self.pos.col % 8;\n self.pos.col += 8;\n self.col_clamp();\n }\n\n pub fn col_set(&mut self, i: u16) {\n self.pos.col = i;\n self.col_clamp();\n }\n\n pub fn col_wrap(&mut self, width: u16, wrap: bool) {\n if self.pos.col > self.size.cols - width {\n let mut prev_pos = self.pos;\n self.pos.col = 0;\n let scrolled = self.row_inc_scroll(1);\n prev_pos.row -= scrolled;\n let new_pos = self.pos;\n self.drawing_row_mut(prev_pos.row)\n // we assume self.pos.row is always valid, and so prev_pos.row\n // must be valid because it is always less than or equal to\n // self.pos.row\n .unwrap()\n .wrap(wrap && prev_pos.row + 1 == new_pos.row);\n }\n }\n\n fn row_clamp_top(&mut self, limit_to_scroll_region: bool) -> u16 {\n if limit_to_scroll_region && self.pos.row < self.scroll_top {\n let rows = self.scroll_top - self.pos.row;\n self.pos.row = self.scroll_top;\n rows\n } else {\n 0\n }\n }\n\n fn row_clamp_bottom(&mut self, limit_to_scroll_region: bool) -> u16 {\n let bottom = if limit_to_scroll_region {\n self.scroll_bottom\n } else {\n self.size.rows - 1\n };\n if self.pos.row > bottom {\n let rows = self.pos.row - bottom;\n self.pos.row = bottom;\n rows\n } else {\n 0\n }\n }\n\n fn row_clamp(&mut self) {\n if self.pos.row > self.size.rows - 1 {\n self.pos.row = self.size.rows - 1;\n }\n }\n\n fn col_clamp(&mut self) {\n if self.pos.col > self.size.cols - 1 {\n self.pos.col = self.size.cols - 1;\n }\n }\n}\n\n#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]\npub struct Size {\n pub rows: u16,\n pub cols: u16,\n}\n\n#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]\npub struct Pos {\n pub row: u16,\n pub col: u16,\n}\n"
},
{
"path": "crates/vt100-psmux/src/lib.rs",
"content": "#![allow(dead_code)]\n//! This crate parses a terminal byte stream and provides an in-memory\n//! representation of the rendered contents.\n//!\n//! # Overview\n//!\n//! This is essentially the terminal parser component of a graphical terminal\n//! emulator pulled out into a separate crate. Although you can use this crate\n//! to build a graphical terminal emulator, it also contains functionality\n//! necessary for implementing terminal applications that want to run other\n//! terminal applications - programs like `screen` or `tmux` for example.\n//!\n//! # Synopsis\n//!\n//! ```\n//! # use vt100_psmux as vt100;\n//! let mut parser = vt100::Parser::new(24, 80, 0);\n//!\n//! let screen = parser.screen().clone();\n//! parser.process(b\"this text is \\x1b[31mRED\\x1b[m\");\n//! assert_eq!(\n//! parser.screen().cell(0, 13).unwrap().fgcolor(),\n//! vt100::Color::Idx(1),\n//! );\n//!\n//! let screen = parser.screen().clone();\n//! parser.process(b\"\\x1b[3D\\x1b[32mGREEN\");\n//! assert_eq!(\n//! parser.screen().contents_formatted(),\n//! &b\"\\x1b[?25h\\x1b[m\\x1b[H\\x1b[Jthis text is \\x1b[32mGREEN\"[..],\n//! );\n//! assert_eq!(\n//! parser.screen().contents_diff(&screen),\n//! &b\"\\x1b[1;14H\\x1b[32mGREEN\"[..],\n//! );\n//! ```\n\n#![warn(missing_docs)]\n#![warn(clippy::cargo)]\n#![warn(clippy::pedantic)]\n#![warn(clippy::nursery)]\n#![warn(clippy::as_conversions)]\n#![warn(clippy::get_unwrap)]\n#![allow(clippy::cognitive_complexity)]\n#![allow(clippy::missing_const_for_fn)]\n#![allow(clippy::similar_names)]\n#![allow(clippy::struct_excessive_bools)]\n#![allow(clippy::too_many_arguments)]\n#![allow(clippy::too_many_lines)]\n#![allow(clippy::type_complexity)]\n\n#[cfg(test)]\nextern crate self as vt100;\n\nmod attrs;\nmod callbacks;\nmod cell;\nmod grid;\nmod parser;\nmod perform;\nmod row;\nmod screen;\nmod term;\n\npub use attrs::Color;\npub use callbacks::Callbacks;\npub use cell::Cell;\npub use parser::Parser;\npub use screen::{MouseProtocolEncoding, MouseProtocolMode, Screen};\n"
},
{
"path": "crates/vt100-psmux/src/parser.rs",
"content": "/// A parser for terminal output which produces an in-memory representation of\n/// the terminal contents.\npub struct Parser<CB: crate::callbacks::Callbacks = ()> {\n parser: vte::Parser,\n screen: crate::perform::WrappedScreen<CB>,\n}\n\nimpl Parser {\n /// Creates a new terminal parser of the given size and with the given\n /// amount of scrollback.\n #[must_use]\n pub fn new(rows: u16, cols: u16, scrollback_len: usize) -> Self {\n Self {\n parser: vte::Parser::new(),\n screen: crate::perform::WrappedScreen::new(\n rows,\n cols,\n scrollback_len,\n ),\n }\n }\n}\n\nimpl<CB: crate::callbacks::Callbacks> Parser<CB> {\n /// Creates a new terminal parser of the given size and with the given\n /// amount of scrollback. Terminal events will be reported via method\n /// calls on the provided [`Callbacks`](crate::callbacks::Callbacks)\n /// implementation.\n pub fn new_with_callbacks(\n rows: u16,\n cols: u16,\n scrollback_len: usize,\n callbacks: CB,\n ) -> Self {\n Self {\n parser: vte::Parser::new(),\n screen: crate::perform::WrappedScreen::new_with_callbacks(\n rows,\n cols,\n scrollback_len,\n callbacks,\n ),\n }\n }\n\n /// Processes the contents of the given byte string, and updates the\n /// in-memory terminal state.\n pub fn process(&mut self, bytes: &[u8]) {\n self.parser.advance(&mut self.screen, bytes);\n }\n\n /// Returns a reference to a [`Screen`](crate::Screen) object containing\n /// the terminal state.\n #[must_use]\n pub fn screen(&self) -> &crate::Screen {\n &self.screen.screen\n }\n\n /// Returns a mutable reference to a [`Screen`](crate::Screen) object\n /// containing the terminal state.\n #[must_use]\n pub fn screen_mut(&mut self) -> &mut crate::Screen {\n &mut self.screen.screen\n }\n\n /// Returns a reference to the [`Callbacks`](crate::callbacks::Callbacks)\n /// state object passed into the constructor.\n pub fn callbacks(&self) -> &CB {\n &self.screen.callbacks\n }\n\n /// Returns a mutable reference to the\n /// [`Callbacks`](crate::callbacks::Callbacks) state object passed into\n /// the constructor.\n pub fn callbacks_mut(&mut self) -> &mut CB {\n &mut self.screen.callbacks\n }\n}\n\nimpl Default for Parser {\n /// Returns a parser with dimensions 80x24 and no scrollback.\n fn default() -> Self {\n Self::new(24, 80, 0)\n }\n}\n\nimpl std::io::Write for Parser {\n fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {\n self.process(buf);\n Ok(buf.len())\n }\n\n fn flush(&mut self) -> std::io::Result<()> {\n Ok(())\n }\n}\n"
},
{
"path": "crates/vt100-psmux/src/perform.rs",
"content": "const BASE64: &[u8] =\n b\"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=\";\nconst CLIPBOARD_SELECTOR: &[u8] = b\"cpqs01234567\";\n\npub struct WrappedScreen<CB: crate::callbacks::Callbacks = ()> {\n pub screen: crate::screen::Screen,\n pub callbacks: CB,\n}\n\nimpl WrappedScreen<()> {\n pub fn new(rows: u16, cols: u16, scrollback_len: usize) -> Self {\n Self::new_with_callbacks(rows, cols, scrollback_len, ())\n }\n}\n\nimpl<CB: crate::callbacks::Callbacks> WrappedScreen<CB> {\n pub fn new_with_callbacks(\n rows: u16,\n cols: u16,\n scrollback_len: usize,\n callbacks: CB,\n ) -> Self {\n Self {\n screen: crate::screen::Screen::new(\n crate::grid::Size { rows, cols },\n scrollback_len,\n ),\n callbacks,\n }\n }\n}\n\nimpl<CB: crate::callbacks::Callbacks> vte::Perform for WrappedScreen<CB> {\n fn print(&mut self, c: char) {\n if c == '\\u{fffd}' || ('\\u{80}'..'\\u{a0}').contains(&c) {\n self.callbacks.unhandled_char(&mut self.screen, c);\n } else {\n self.screen.text(c);\n }\n }\n\n fn execute(&mut self, b: u8) {\n match b {\n 7 => {\n self.screen.audible_bell_count = self.screen.audible_bell_count.wrapping_add(1);\n self.callbacks.audible_bell(&mut self.screen);\n }\n 8 => self.screen.bs(),\n 9 => self.screen.tab(),\n 10 => self.screen.lf(),\n 11 => self.screen.vt(),\n 12 => self.screen.ff(),\n 13 => self.screen.cr(),\n // we don't implement shift in/out alternate character sets, but\n // it shouldn't count as an \"error\"\n 14 | 15 => {}\n _ => self.callbacks.unhandled_control(&mut self.screen, b),\n }\n }\n\n fn esc_dispatch(&mut self, intermediates: &[u8], _ignore: bool, b: u8) {\n if let Some(i) = intermediates.first() {\n self.callbacks.unhandled_escape(\n &mut self.screen,\n Some(*i),\n intermediates.get(1).copied(),\n b,\n );\n } else {\n match b {\n b'7' => self.screen.decsc(),\n b'8' => self.screen.decrc(),\n b'=' => self.screen.deckpam(),\n b'>' => self.screen.deckpnm(),\n b'M' => self.screen.ri(),\n b'c' => self.screen.ris(),\n b'g' => self.callbacks.visual_bell(&mut self.screen),\n _ => {\n self.callbacks.unhandled_escape(\n &mut self.screen,\n None,\n None,\n b,\n );\n }\n }\n }\n }\n\n fn csi_dispatch(\n &mut self,\n params: &vte::Params,\n intermediates: &[u8],\n _ignore: bool,\n c: char,\n ) {\n let unhandled = |screen: &mut crate::screen::Screen| {\n self.callbacks.unhandled_csi(\n screen,\n intermediates.first().copied(),\n intermediates.get(1).copied(),\n ¶ms.iter().collect::<Vec<_>>(),\n c,\n );\n };\n match intermediates.first() {\n None => match c {\n '@' => self.screen.ich(canonicalize_params_1(params, 1)),\n 'A' => self.screen.cuu(canonicalize_params_1(params, 1)),\n 'B' => self.screen.cud(canonicalize_params_1(params, 1)),\n 'C' => self.screen.cuf(canonicalize_params_1(params, 1)),\n 'D' => self.screen.cub(canonicalize_params_1(params, 1)),\n 'E' => self.screen.cnl(canonicalize_params_1(params, 1)),\n 'F' => self.screen.cpl(canonicalize_params_1(params, 1)),\n 'G' => self.screen.cha(canonicalize_params_1(params, 1)),\n 'H' | 'f' => self.screen.cup(canonicalize_params_2(params, 1, 1)),\n 'J' => self\n .screen\n .ed(canonicalize_params_1(params, 0), unhandled),\n 'K' => self\n .screen\n .el(canonicalize_params_1(params, 0), unhandled),\n 'L' => self.screen.il(canonicalize_params_1(params, 1)),\n 'M' => self.screen.dl(canonicalize_params_1(params, 1)),\n 'P' => self.screen.dch(canonicalize_params_1(params, 1)),\n 'S' => self.screen.su(canonicalize_params_1(params, 1)),\n 'T' => self.screen.sd(canonicalize_params_1(params, 1)),\n 'X' => self.screen.ech(canonicalize_params_1(params, 1)),\n 'd' => self.screen.vpa(canonicalize_params_1(params, 1)),\n 'm' => self.screen.sgr(params, unhandled),\n 'n' => {\n // DSR (Device Status Report) — in passthrough mode the\n // child sends this and expects a response. We ignore it\n // at the parser level (the host must respond via the PTY\n // writer if needed), but we must not call unhandled.\n }\n 'r' => self.screen.decstbm(canonicalize_params_decstbm(\n params,\n self.screen.grid().size(),\n )),\n 's' => self.screen.decsc(),\n 'u' => self.screen.decrc(),\n 't' => {\n let mut params_iter = params.iter();\n let op =\n params_iter.next().and_then(|x| x.first().copied());\n if op == Some(8) {\n let (screen_rows, screen_cols) = self.screen.size();\n let rows =\n params_iter.next().map_or(screen_rows, |x| {\n *x.first().unwrap_or(&screen_rows)\n });\n let cols =\n params_iter.next().map_or(screen_cols, |x| {\n *x.first().unwrap_or(&screen_cols)\n });\n self.callbacks.resize(&mut self.screen, (rows, cols));\n } else {\n self.callbacks.unhandled_csi(\n &mut self.screen,\n None,\n None,\n ¶ms.iter().collect::<Vec<_>>(),\n c,\n );\n }\n }\n _ => {\n self.callbacks.unhandled_csi(\n &mut self.screen,\n None,\n None,\n ¶ms.iter().collect::<Vec<_>>(),\n c,\n );\n }\n },\n Some(b'?') => match c {\n 'J' => self\n .screen\n .decsed(canonicalize_params_1(params, 0), unhandled),\n 'K' => self\n .screen\n .decsel(canonicalize_params_1(params, 0), unhandled),\n 'h' => self.screen.decset(params, unhandled),\n 'l' => self.screen.decrst(params, unhandled),\n _ => {\n self.callbacks.unhandled_csi(\n &mut self.screen,\n Some(b'?'),\n intermediates.get(1).copied(),\n ¶ms.iter().collect::<Vec<_>>(),\n c,\n );\n }\n },\n Some(i) => {\n self.callbacks.unhandled_csi(\n &mut self.screen,\n Some(*i),\n intermediates.get(1).copied(),\n ¶ms.iter().collect::<Vec<_>>(),\n c,\n );\n }\n }\n }\n\n fn osc_dispatch(&mut self, params: &[&[u8]], _bel_terminated: bool) {\n match params {\n [b\"0\", s] => {\n self.callbacks.set_window_icon_name(&mut self.screen, s);\n self.callbacks.set_window_title(&mut self.screen, s);\n self.screen.set_title(s);\n }\n [b\"1\", s] => {\n self.callbacks.set_window_icon_name(&mut self.screen, s);\n }\n [b\"2\", s] => {\n self.callbacks.set_window_title(&mut self.screen, s);\n self.screen.set_title(s);\n }\n [b\"7\", uri] => {\n self.screen.set_path(uri);\n }\n [b\"9\", b\"4\", state, progress] => {\n // OSC 9;4 — Windows Terminal progress indicator.\n // state: 0=hide, 1=default, 2=error, 3=indeterminate, 4=warning\n // progress: 0..=100\n let s = std::str::from_utf8(state)\n .ok()\n .and_then(|s| s.parse::<u8>().ok())\n .unwrap_or(0);\n let v = std::str::from_utf8(progress)\n .ok()\n .and_then(|s| s.parse::<u8>().ok())\n .unwrap_or(0);\n self.screen.set_progress(s, v);\n self.callbacks.set_progress(&mut self.screen, s, v);\n }\n [b\"9999\", ..] => {\n self.screen.squelch_cleared = true;\n }\n [b\"52\", ty, data] => {\n match (\n ty.iter().all(|c| CLIPBOARD_SELECTOR.contains(c)),\n *data,\n ) {\n (true, b\"?\") => {\n self.callbacks\n .paste_from_clipboard(&mut self.screen, ty);\n }\n (true, data)\n if data.iter().all(|c| BASE64.contains(c)) =>\n {\n // Stage the payload on Screen so the psmux server\n // can drain it and forward an OSC 52 to the host\n // terminal. Unblocks tools like Claude Code's\n // `/copy` running inside a pane (OSC 52 was being\n // swallowed by the default no-op callbacks).\n self.screen.set_clipboard(ty, data);\n self.callbacks.copy_to_clipboard(\n &mut self.screen,\n ty,\n data,\n );\n }\n _ => {\n self.callbacks\n .unhandled_osc(&mut self.screen, params);\n }\n }\n }\n _ => {\n self.callbacks.unhandled_osc(&mut self.screen, params);\n }\n }\n }\n}\n\nfn canonicalize_params_1(params: &vte::Params, default: u16) -> u16 {\n let first = params.iter().next().map_or(0, |x| *x.first().unwrap_or(&0));\n if first == 0 {\n default\n } else {\n first\n }\n}\n\nfn canonicalize_params_2(\n params: &vte::Params,\n default1: u16,\n default2: u16,\n) -> (u16, u16) {\n let mut iter = params.iter();\n let first = iter.next().map_or(0, |x| *x.first().unwrap_or(&0));\n let first = if first == 0 { default1 } else { first };\n\n let second = iter.next().map_or(0, |x| *x.first().unwrap_or(&0));\n let second = if second == 0 { default2 } else { second };\n\n (first, second)\n}\n\nfn canonicalize_params_decstbm(\n params: &vte::Params,\n size: crate::grid::Size,\n) -> (u16, u16) {\n let mut iter = params.iter();\n let top = iter.next().map_or(0, |x| *x.first().unwrap_or(&0));\n let top = if top == 0 { 1 } else { top };\n\n let bottom = iter.next().map_or(0, |x| *x.first().unwrap_or(&0));\n let bottom = if bottom == 0 { size.rows } else { bottom };\n\n (top, bottom)\n}\n"
},
{
"path": "crates/vt100-psmux/src/row.rs",
"content": "use crate::term::BufWrite as _;\n\n#[derive(Clone, Debug)]\npub struct Row {\n cells: Vec<crate::Cell>,\n wrapped: bool,\n}\n\nimpl Row {\n pub fn new(cols: u16) -> Self {\n Self {\n cells: vec![crate::Cell::new(); usize::from(cols)],\n wrapped: false,\n }\n }\n\n fn cols(&self) -> u16 {\n self.cells\n .len()\n .try_into()\n // we limit the number of cols to a u16 (see Size)\n .unwrap()\n }\n\n pub fn clear(&mut self, attrs: crate::attrs::Attrs) {\n for cell in &mut self.cells {\n cell.clear(attrs);\n }\n self.wrapped = false;\n }\n\n /// True when every cell on this row holds no glyph. Used by the\n /// alt-screen-to-scrollback copy path (issue #88) to skip the\n /// trailing blank rows a TUI did not draw into.\n pub fn is_blank(&self) -> bool {\n !self.cells.iter().any(|c| c.has_contents())\n }\n\n fn cells(&self) -> impl Iterator<Item = &crate::Cell> {\n self.cells.iter()\n }\n\n pub fn get(&self, col: u16) -> Option<&crate::Cell> {\n self.cells.get(usize::from(col))\n }\n\n pub fn get_mut(&mut self, col: u16) -> Option<&mut crate::Cell> {\n self.cells.get_mut(usize::from(col))\n }\n\n pub fn insert(&mut self, i: u16, cell: crate::Cell) {\n self.cells.insert(usize::from(i), cell);\n self.wrapped = false;\n }\n\n pub fn remove(&mut self, i: u16) {\n self.clear_wide(i);\n self.cells.remove(usize::from(i));\n self.wrapped = false;\n }\n\n pub fn erase(&mut self, i: u16, attrs: crate::attrs::Attrs) {\n let wide = self.cells[usize::from(i)].is_wide();\n self.clear_wide(i);\n self.cells[usize::from(i)].clear(attrs);\n if i == self.cols() - if wide { 2 } else { 1 } {\n self.wrapped = false;\n }\n }\n\n pub fn truncate(&mut self, len: u16) {\n self.cells.truncate(usize::from(len));\n self.wrapped = false;\n let last_cell = &mut self.cells[usize::from(len) - 1];\n if last_cell.is_wide() {\n last_cell.clear(*last_cell.attrs());\n }\n }\n\n pub fn resize(&mut self, len: u16, cell: crate::Cell) {\n self.cells.resize(usize::from(len), cell);\n self.wrapped = false;\n }\n\n pub fn wrap(&mut self, wrap: bool) {\n self.wrapped = wrap;\n }\n\n pub fn wrapped(&self) -> bool {\n self.wrapped\n }\n\n pub fn clear_wide(&mut self, col: u16) {\n let col_idx = usize::from(col);\n if col_idx >= self.cells.len() {\n return;\n }\n let cell = &self.cells[col_idx];\n if cell.is_wide() {\n let next = usize::from(col + 1);\n if next < self.cells.len() {\n let attrs = *self.cells[next].attrs();\n self.cells[next].clear(attrs);\n }\n } else if cell.is_wide_continuation() {\n if col > 0 {\n let prev = usize::from(col - 1);\n let attrs = *self.cells[prev].attrs();\n self.cells[prev].clear(attrs);\n }\n }\n }\n\n pub fn write_contents(\n &self,\n contents: &mut String,\n start: u16,\n width: u16,\n wrapping: bool,\n ) {\n let mut prev_was_wide = false;\n\n let mut prev_col = start;\n for (col, cell) in self\n .cells()\n .enumerate()\n .skip(usize::from(start))\n .take(usize::from(width))\n {\n if prev_was_wide {\n prev_was_wide = false;\n continue;\n }\n prev_was_wide = cell.is_wide();\n\n // we limit the number of cols to a u16 (see Size)\n let col: u16 = col.try_into().unwrap();\n if cell.has_contents() {\n for _ in 0..(col - prev_col) {\n contents.push(' ');\n }\n prev_col += col - prev_col;\n\n contents.push_str(cell.contents());\n prev_col += if cell.is_wide() { 2 } else { 1 };\n }\n }\n if prev_col == start && wrapping {\n contents.push('\\n');\n }\n }\n\n pub fn write_contents_formatted(\n &self,\n contents: &mut Vec<u8>,\n start: u16,\n width: u16,\n row: u16,\n wrapping: bool,\n prev_pos: Option<crate::grid::Pos>,\n prev_attrs: Option<crate::attrs::Attrs>,\n ) -> (crate::grid::Pos, crate::attrs::Attrs) {\n let mut prev_was_wide = false;\n let default_cell = crate::Cell::new();\n\n let mut prev_pos = prev_pos.unwrap_or_else(|| {\n if wrapping {\n crate::grid::Pos {\n row: row - 1,\n col: self.cols(),\n }\n } else {\n crate::grid::Pos { row, col: start }\n }\n });\n let mut prev_attrs = prev_attrs.unwrap_or_default();\n\n let first_cell = &self.cells[usize::from(start)];\n if wrapping && first_cell == &default_cell {\n let default_attrs = default_cell.attrs();\n if &prev_attrs != default_attrs {\n default_attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *default_attrs;\n }\n contents.push(b' ');\n crate::term::Backspace.write_buf(contents);\n crate::term::EraseChar::new(1).write_buf(contents);\n prev_pos = crate::grid::Pos { row, col: 0 };\n }\n\n let mut erase: Option<(u16, &crate::attrs::Attrs)> = None;\n for (col, cell) in self\n .cells()\n .enumerate()\n .skip(usize::from(start))\n .take(usize::from(width))\n {\n if prev_was_wide {\n prev_was_wide = false;\n continue;\n }\n prev_was_wide = cell.is_wide();\n\n // we limit the number of cols to a u16 (see Size)\n let col: u16 = col.try_into().unwrap();\n let pos = crate::grid::Pos { row, col };\n\n if let Some((prev_col, attrs)) = erase {\n if cell.has_contents() || cell.attrs() != attrs {\n let new_pos = crate::grid::Pos { row, col: prev_col };\n if wrapping\n && prev_pos.row + 1 == new_pos.row\n && prev_pos.col >= self.cols()\n {\n if new_pos.col > 0 {\n contents.extend(\n \" \".repeat(usize::from(new_pos.col))\n .as_bytes(),\n );\n } else {\n contents.extend(b\" \");\n crate::term::Backspace.write_buf(contents);\n }\n } else {\n crate::term::MoveFromTo::new(prev_pos, new_pos)\n .write_buf(contents);\n }\n prev_pos = new_pos;\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n crate::term::EraseChar::new(pos.col - prev_col)\n .write_buf(contents);\n erase = None;\n }\n }\n\n if cell != &default_cell {\n let attrs = cell.attrs();\n if cell.has_contents() {\n if pos != prev_pos {\n if !wrapping\n || prev_pos.row + 1 != pos.row\n || prev_pos.col\n < self.cols() - u16::from(cell.is_wide())\n || pos.col != 0\n {\n crate::term::MoveFromTo::new(prev_pos, pos)\n .write_buf(contents);\n }\n prev_pos = pos;\n }\n\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n\n prev_pos.col += if cell.is_wide() { 2 } else { 1 };\n let cell_contents = cell.contents();\n contents.extend(cell_contents.as_bytes());\n } else if erase.is_none() {\n erase = Some((pos.col, attrs));\n }\n }\n }\n if let Some((prev_col, attrs)) = erase {\n let new_pos = crate::grid::Pos { row, col: prev_col };\n if wrapping\n && prev_pos.row + 1 == new_pos.row\n && prev_pos.col >= self.cols()\n {\n if new_pos.col > 0 {\n contents.extend(\n \" \".repeat(usize::from(new_pos.col)).as_bytes(),\n );\n } else {\n contents.extend(b\" \");\n crate::term::Backspace.write_buf(contents);\n }\n } else {\n crate::term::MoveFromTo::new(prev_pos, new_pos)\n .write_buf(contents);\n }\n prev_pos = new_pos;\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n crate::term::ClearRowForward.write_buf(contents);\n }\n\n (prev_pos, prev_attrs)\n }\n\n // while it's true that most of the logic in this is identical to\n // write_contents_formatted, i can't figure out how to break out the\n // common parts without making things noticeably slower.\n pub fn write_contents_diff(\n &self,\n contents: &mut Vec<u8>,\n prev: &Self,\n start: u16,\n width: u16,\n row: u16,\n wrapping: bool,\n prev_wrapping: bool,\n mut prev_pos: crate::grid::Pos,\n mut prev_attrs: crate::attrs::Attrs,\n ) -> (crate::grid::Pos, crate::attrs::Attrs) {\n let mut prev_was_wide = false;\n\n let first_cell = &self.cells[usize::from(start)];\n let prev_first_cell = &prev.cells[usize::from(start)];\n if wrapping\n && !prev_wrapping\n && first_cell == prev_first_cell\n && prev_pos.row + 1 == row\n && prev_pos.col\n >= self.cols() - u16::from(prev_first_cell.is_wide())\n {\n let first_cell_attrs = first_cell.attrs();\n if &prev_attrs != first_cell_attrs {\n first_cell_attrs\n .write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *first_cell_attrs;\n }\n let mut cell_contents = prev_first_cell.contents();\n let need_erase = if cell_contents.is_empty() {\n cell_contents = \" \";\n true\n } else {\n false\n };\n contents.extend(cell_contents.as_bytes());\n crate::term::Backspace.write_buf(contents);\n if prev_first_cell.is_wide() {\n crate::term::Backspace.write_buf(contents);\n }\n if need_erase {\n crate::term::EraseChar::new(1).write_buf(contents);\n }\n prev_pos = crate::grid::Pos { row, col: 0 };\n }\n\n let mut erase: Option<(u16, &crate::attrs::Attrs)> = None;\n for (col, (cell, prev_cell)) in self\n .cells()\n .zip(prev.cells())\n .enumerate()\n .skip(usize::from(start))\n .take(usize::from(width))\n {\n if prev_was_wide {\n prev_was_wide = false;\n continue;\n }\n prev_was_wide = cell.is_wide();\n\n // we limit the number of cols to a u16 (see Size)\n let col: u16 = col.try_into().unwrap();\n let pos = crate::grid::Pos { row, col };\n\n if let Some((prev_col, attrs)) = erase {\n if cell.has_contents() || cell.attrs() != attrs {\n let new_pos = crate::grid::Pos { row, col: prev_col };\n if wrapping\n && prev_pos.row + 1 == new_pos.row\n && prev_pos.col >= self.cols()\n {\n if new_pos.col > 0 {\n contents.extend(\n \" \".repeat(usize::from(new_pos.col))\n .as_bytes(),\n );\n } else {\n contents.extend(b\" \");\n crate::term::Backspace.write_buf(contents);\n }\n } else {\n crate::term::MoveFromTo::new(prev_pos, new_pos)\n .write_buf(contents);\n }\n prev_pos = new_pos;\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n crate::term::EraseChar::new(pos.col - prev_col)\n .write_buf(contents);\n erase = None;\n }\n }\n\n if cell != prev_cell {\n let attrs = cell.attrs();\n if cell.has_contents() {\n if pos != prev_pos {\n if !wrapping\n || prev_pos.row + 1 != pos.row\n || prev_pos.col\n < self.cols() - u16::from(cell.is_wide())\n || pos.col != 0\n {\n crate::term::MoveFromTo::new(prev_pos, pos)\n .write_buf(contents);\n }\n prev_pos = pos;\n }\n\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n\n prev_pos.col += if cell.is_wide() { 2 } else { 1 };\n contents.extend(cell.contents().as_bytes());\n } else if erase.is_none() {\n erase = Some((pos.col, attrs));\n }\n }\n }\n if let Some((prev_col, attrs)) = erase {\n let new_pos = crate::grid::Pos { row, col: prev_col };\n if wrapping\n && prev_pos.row + 1 == new_pos.row\n && prev_pos.col >= self.cols()\n {\n if new_pos.col > 0 {\n contents.extend(\n \" \".repeat(usize::from(new_pos.col)).as_bytes(),\n );\n } else {\n contents.extend(b\" \");\n crate::term::Backspace.write_buf(contents);\n }\n } else {\n crate::term::MoveFromTo::new(prev_pos, new_pos)\n .write_buf(contents);\n }\n prev_pos = new_pos;\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n crate::term::ClearRowForward.write_buf(contents);\n }\n\n // if this row is going from wrapped to not wrapped, we need to erase\n // and redraw the last character to break wrapping. if this row is\n // wrapped, we need to redraw the last character without erasing it to\n // position the cursor after the end of the line correctly so that\n // drawing the next line can just start writing and be wrapped.\n if (!self.wrapped && prev.wrapped) || (!prev.wrapped && self.wrapped)\n {\n let end_pos = if self.cells[usize::from(self.cols() - 1)]\n .is_wide_continuation()\n {\n crate::grid::Pos {\n row,\n col: self.cols() - 2,\n }\n } else {\n crate::grid::Pos {\n row,\n col: self.cols() - 1,\n }\n };\n crate::term::MoveFromTo::new(prev_pos, end_pos)\n .write_buf(contents);\n prev_pos = end_pos;\n if !self.wrapped {\n crate::term::EraseChar::new(1).write_buf(contents);\n }\n let end_cell = &self.cells[usize::from(end_pos.col)];\n if end_cell.has_contents() {\n let attrs = end_cell.attrs();\n if &prev_attrs != attrs {\n attrs.write_escape_code_diff(contents, &prev_attrs);\n prev_attrs = *attrs;\n }\n contents.extend(end_cell.contents().as_bytes());\n prev_pos.col += if end_cell.is_wide() { 2 } else { 1 };\n }\n }\n\n (prev_pos, prev_attrs)\n }\n}\n"
},
{
"path": "crates/vt100-psmux/src/screen.rs",
"content": "use crate::term::BufWrite as _;\nuse unicode_width::UnicodeWidthChar as _;\n\n/// Parse an OSC 7 URI into a filesystem path.\n/// Accepts `file://hostname/path`, `file:///path`, or a bare `/path`.\n/// Percent-decodes the path component.\nfn parse_osc7_uri(raw: &str) -> String {\n let stripped = if let Some(rest) = raw.strip_prefix(\"file://\") {\n // Skip hostname: everything up to the next '/'\n if let Some(slash) = rest.find('/') {\n &rest[slash..]\n } else {\n rest\n }\n } else {\n raw\n };\n percent_decode(stripped)\n}\n\n/// Minimal percent-decoding for OSC 7 paths (e.g. `%20` → ` `).\nfn percent_decode(input: &str) -> String {\n let mut out = String::with_capacity(input.len());\n let bytes = input.as_bytes();\n let mut i = 0;\n while i < bytes.len() {\n if bytes[i] == b'%' && i + 2 < bytes.len() {\n if let (Some(hi), Some(lo)) = (\n hex_val(bytes[i + 1]),\n hex_val(bytes[i + 2]),\n ) {\n out.push(char::from(hi << 4 | lo));\n i += 3;\n continue;\n }\n }\n out.push(char::from(bytes[i]));\n i += 1;\n }\n out\n}\n\nfn hex_val(b: u8) -> Option<u8> {\n match b {\n b'0'..=b'9' => Some(b - b'0'),\n b'a'..=b'f' => Some(b - b'a' + 10),\n b'A'..=b'F' => Some(b - b'A' + 10),\n _ => None,\n }\n}\n\nconst MODE_APPLICATION_KEYPAD: u8 = 0b0000_0001;\nconst MODE_APPLICATION_CURSOR: u8 = 0b0000_0010;\nconst MODE_HIDE_CURSOR: u8 = 0b0000_0100;\nconst MODE_ALTERNATE_SCREEN: u8 = 0b0000_1000;\nconst MODE_BRACKETED_PASTE: u8 = 0b0001_0000;\n\n/// The xterm mouse handling mode currently in use.\n#[derive(Copy, Clone, Debug, Eq, PartialEq, Default)]\npub enum MouseProtocolMode {\n /// Mouse handling is disabled.\n #[default]\n None,\n\n /// Mouse button events should be reported on button press. Also known as\n /// X10 mouse mode.\n Press,\n\n /// Mouse button events should be reported on button press and release.\n /// Also known as VT200 mouse mode.\n PressRelease,\n\n // Highlight,\n /// Mouse button events should be reported on button press and release, as\n /// well as when the mouse moves between cells while a button is held\n /// down.\n ButtonMotion,\n\n /// Mouse button events should be reported on button press and release,\n /// and mouse motion events should be reported when the mouse moves\n /// between cells regardless of whether a button is held down or not.\n AnyMotion,\n // DecLocator,\n}\n\n/// The encoding to use for the enabled [`MouseProtocolMode`].\n#[derive(Copy, Clone, Debug, Eq, PartialEq, Default)]\npub enum MouseProtocolEncoding {\n /// Default single-printable-byte encoding.\n #[default]\n Default,\n\n /// UTF-8-based encoding.\n Utf8,\n\n /// SGR-like encoding.\n Sgr,\n // Urxvt,\n}\n\n/// Represents the overall terminal state.\n#[derive(Clone, Debug)]\npub struct Screen {\n grid: crate::grid::Grid,\n alternate_grid: crate::grid::Grid,\n\n attrs: crate::attrs::Attrs,\n saved_attrs: crate::attrs::Attrs,\n\n modes: u8,\n mouse_protocol_mode: MouseProtocolMode,\n mouse_protocol_encoding: MouseProtocolEncoding,\n\n /// Window title set by the application via OSC 0 or OSC 2.\n osc_title: String,\n\n /// Path announced by the shell via OSC 7 (`\\e]7;file://host/path\\a`).\n /// Used as a fallback for CWD when PEB walking fails (SSH, WSL).\n osc7_path: Option<String>,\n\n /// Progress indicator state set via OSC 9;4 (Windows Terminal progress).\n /// Format: `Some((state, value))` where state ∈ {0=hide,1=default,2=error,\n /// 3=indeterminate,4=warning} and value ∈ 0..=100. `None` until first set;\n /// stays `Some` after that so a clear (state=0) is also forwarded.\n osc94_progress: Option<(u8, u8)>,\n\n /// Pending OSC 52 clipboard payload emitted by the child process inside\n /// this pane. Format: `Some((selector_bytes, base64_payload))`. The\n /// selector is the raw selector field from the OSC (e.g. `b\"c\"`,\n /// `b\"p\"`, etc., or empty) and `base64_payload` is the still-encoded\n /// data string. Consumed once via [`Screen::take_clipboard`]; the\n /// psmux server drains this and stages it onto `App.clipboard_osc52`\n /// so the client re-emits OSC 52 on its own stdout to reach the host\n /// terminal (Windows Terminal, etc.).\n osc52_clipboard: Option<(Vec<u8>, Vec<u8>)>,\n\n /// Set to `true` when the screen is cleared (CSI 2J) while\n /// `squelch_clear_pending` is active. The layout serialiser\n /// checks this flag to know that `cls` has finished.\n pub(crate) squelch_cleared: bool,\n\n /// Set by the server before injecting `cd; cls`. When true,\n /// the next CSI 2J (erase display mode 2) sets `squelch_cleared`.\n pub(crate) squelch_clear_pending: bool,\n\n /// Incremented each time the parser encounters a standalone BEL (0x07)\n /// that is NOT an OSC/DCS/APC string terminator. Use `take_audible_bell()`\n /// to consume the counter.\n pub(crate) audible_bell_count: u32,\n\n /// Controls how alternate-screen exits interact with main-grid\n /// scrollback. Default `true` = legacy behaviour: alt-screen\n /// content is ephemeral, vanishes on exit (matches xterm/tmux\n /// default). When set `false`, the visible rows of the alt grid\n /// are copied into main-grid scrollback at the moment of exit,\n /// so a user running `capture-pane -S` or copy-mode page-up\n /// after a TUI session sees what was on screen when the app left.\n ///\n /// We keep the option name `alternate-screen` to match tmux, but\n /// the Windows implementation differs: ConPTY emits its own\n /// \"clear + restore\" sequences around 1049 toggles regardless of\n /// whether we honour the toggle, so simply dropping 1049 (the\n /// tmux approach) does not preserve content on this platform.\n /// Copy-on-exit is the equivalent end-user behaviour.\n pub(crate) allow_alternate_screen: bool,\n}\n\nimpl Screen {\n pub(crate) fn new(\n size: crate::grid::Size,\n scrollback_len: usize,\n ) -> Self {\n let mut grid = crate::grid::Grid::new(size, scrollback_len);\n grid.allocate_rows();\n Self {\n grid,\n alternate_grid: crate::grid::Grid::new(size, 0),\n\n attrs: crate::attrs::Attrs::default(),\n saved_attrs: crate::attrs::Attrs::default(),\n\n modes: 0,\n mouse_protocol_mode: MouseProtocolMode::default(),\n mouse_protocol_encoding: MouseProtocolEncoding::default(),\n osc_title: String::new(),\n osc7_path: None,\n osc94_progress: None,\n osc52_clipboard: None,\n squelch_cleared: false,\n squelch_clear_pending: false,\n audible_bell_count: 0,\n allow_alternate_screen: true,\n }\n }\n\n /// Resizes the terminal.\n pub fn set_size(&mut self, rows: u16, cols: u16) {\n self.grid.set_size(crate::grid::Size { rows, cols });\n self.alternate_grid\n .set_size(crate::grid::Size { rows, cols });\n }\n\n /// Returns the current size of the terminal.\n ///\n /// The return value will be (rows, cols).\n #[must_use]\n pub fn size(&self) -> (u16, u16) {\n let size = self.grid().size();\n (size.rows, size.cols)\n }\n\n /// Scrolls to the given position in the scrollback.\n ///\n /// This position indicates the offset from the top of the screen, and\n /// should be `0` to put the normal screen in view.\n ///\n /// This affects the return values of methods called on the screen: for\n /// instance, `screen.cell(0, 0)` will return the top left corner of the\n /// screen after taking the scrollback offset into account.\n ///\n /// The value given will be clamped to the actual size of the scrollback.\n pub fn set_scrollback(&mut self, rows: usize) {\n self.grid_mut().set_scrollback(rows);\n }\n\n /// Returns the number of rows currently held in main-grid\n /// scrollback (the actual retained count, not the configured\n /// maximum). Always reads the main grid, even while alt-screen\n /// is active — `#{history_size}` and capture-pane-S are about\n /// \"what can the user scroll back to\", and that lives on the\n /// main grid regardless of which grid is currently rendering.\n #[must_use]\n pub fn scrollback_filled(&self) -> usize {\n self.grid.scrollback_filled()\n }\n\n /// Updates the maximum scrollback buffer size for the main grid. Rows\n /// in excess of the new limit are trimmed from the oldest end. The\n /// alternate grid is intentionally left at zero scrollback (apps like\n /// vim use the alternate screen and do not retain history).\n pub fn set_scrollback_len(&mut self, new_len: usize) {\n self.grid_mut().set_scrollback_len(new_len);\n }\n\n /// Returns the configured maximum size of the scrollback buffer.\n #[must_use]\n pub fn scrollback_len(&self) -> usize {\n self.grid().scrollback_len()\n }\n\n /// Whether DEC private modes 47/1049 (alternate screen) are honoured.\n #[must_use]\n pub fn allow_alternate_screen(&self) -> bool {\n self.allow_alternate_screen\n }\n\n /// Toggle whether alt-screen content is preserved into main-grid\n /// scrollback when the alt screen exits. See the field comment.\n /// If we are currently inside alt mode at the moment of toggling\n /// off, also flush what's visible into scrollback right now —\n /// otherwise a user who flipped the option on while a TUI is\n /// already running would lose the current frame.\n pub fn set_allow_alternate_screen(&mut self, allowed: bool) {\n let was = self.allow_alternate_screen;\n self.allow_alternate_screen = allowed;\n if !allowed && was && self.mode(MODE_ALTERNATE_SCREEN) {\n self.copy_alt_visible_to_main_scrollback();\n }\n }\n\n /// Returns the current position in the scrollback.\n ///\n /// This position indicates the offset from the top of the screen, and is\n /// `0` when the normal screen is in view.\n #[must_use]\n pub fn scrollback(&self) -> usize {\n self.grid().scrollback()\n }\n\n /// Returns the text contents of the terminal.\n ///\n /// This will not include any formatting information, and will be in plain\n /// text format.\n #[must_use]\n pub fn contents(&self) -> String {\n let mut contents = String::new();\n self.write_contents(&mut contents);\n contents\n }\n\n fn write_contents(&self, contents: &mut String) {\n self.grid().write_contents(contents);\n }\n\n /// Returns the text contents of the terminal by row, restricted to the\n /// given subset of columns.\n ///\n /// This will not include any formatting information, and will be in plain\n /// text format.\n ///\n /// Newlines will not be included.\n pub fn rows(\n &self,\n start: u16,\n width: u16,\n ) -> impl Iterator<Item = String> + '_ {\n self.grid().visible_rows().map(move |row| {\n let mut contents = String::new();\n row.write_contents(&mut contents, start, width, false);\n contents\n })\n }\n\n /// Returns the text contents of the terminal logically between two cells.\n /// This will include the remainder of the starting row after `start_col`,\n /// followed by the entire contents of the rows between `start_row` and\n /// `end_row`, followed by the beginning of the `end_row` up until\n /// `end_col`. This is useful for things like determining the contents of\n /// a clipboard selection.\n #[must_use]\n pub fn contents_between(\n &self,\n start_row: u16,\n start_col: u16,\n end_row: u16,\n end_col: u16,\n ) -> String {\n match start_row.cmp(&end_row) {\n std::cmp::Ordering::Less => {\n let (_, cols) = self.size();\n let mut contents = String::new();\n for (i, row) in self\n .grid()\n .visible_rows()\n .enumerate()\n .skip(usize::from(start_row))\n .take(usize::from(end_row) - usize::from(start_row) + 1)\n {\n if i == usize::from(start_row) {\n row.write_contents(\n &mut contents,\n start_col,\n cols - start_col,\n false,\n );\n if !row.wrapped() {\n contents.push('\\n');\n }\n } else if i == usize::from(end_row) {\n row.write_contents(&mut contents, 0, end_col, false);\n } else {\n row.write_contents(&mut contents, 0, cols, false);\n if !row.wrapped() {\n contents.push('\\n');\n }\n }\n }\n contents\n }\n std::cmp::Ordering::Equal => {\n if start_col < end_col {\n self.rows(start_col, end_col - start_col)\n .nth(usize::from(start_row))\n .unwrap_or_default()\n } else {\n String::new()\n }\n }\n std::cmp::Ordering::Greater => String::new(),\n }\n }\n\n /// Return escape codes sufficient to reproduce the entire contents of the\n /// current terminal state. This is a convenience wrapper around\n /// [`contents_formatted`](Self::contents_formatted) and\n /// [`input_mode_formatted`](Self::input_mode_formatted).\n #[must_use]\n pub fn state_formatted(&self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_contents_formatted(&mut contents);\n self.write_input_mode_formatted(&mut contents);\n contents\n }\n\n /// Return escape codes sufficient to turn the terminal state of the\n /// screen `prev` into the current terminal state. This is a convenience\n /// wrapper around [`contents_diff`](Self::contents_diff) and\n /// [`input_mode_diff`](Self::input_mode_diff).\n #[must_use]\n pub fn state_diff(&self, prev: &Self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_contents_diff(&mut contents, prev);\n self.write_input_mode_diff(&mut contents, prev);\n contents\n }\n\n /// Returns the formatted visible contents of the terminal.\n ///\n /// Formatting information will be included inline as terminal escape\n /// codes. The result will be suitable for feeding directly to a raw\n /// terminal parser, and will result in the same visual output.\n #[must_use]\n pub fn contents_formatted(&self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_contents_formatted(&mut contents);\n contents\n }\n\n fn write_contents_formatted(&self, contents: &mut Vec<u8>) {\n crate::term::HideCursor::new(self.hide_cursor()).write_buf(contents);\n let prev_attrs = self.grid().write_contents_formatted(contents);\n self.attrs.write_escape_code_diff(contents, &prev_attrs);\n }\n\n /// Returns the formatted visible contents of the terminal by row,\n /// restricted to the given subset of columns.\n ///\n /// Formatting information will be included inline as terminal escape\n /// codes. The result will be suitable for feeding directly to a raw\n /// terminal parser, and will result in the same visual output.\n ///\n /// You are responsible for positioning the cursor before printing each\n /// row, and the final cursor position after displaying each row is\n /// unspecified.\n // the unwraps in this method shouldn't be reachable\n #[allow(clippy::missing_panics_doc)]\n pub fn rows_formatted(\n &self,\n start: u16,\n width: u16,\n ) -> impl Iterator<Item = Vec<u8>> + '_ {\n let mut wrapping = false;\n self.grid().visible_rows().enumerate().map(move |(i, row)| {\n // number of rows in a grid is stored in a u16 (see Size), so\n // visible_rows can never return enough rows to overflow here\n let i = i.try_into().unwrap();\n let mut contents = vec![];\n row.write_contents_formatted(\n &mut contents,\n start,\n width,\n i,\n wrapping,\n None,\n None,\n );\n if start == 0 && width == self.grid.size().cols {\n wrapping = row.wrapped();\n }\n contents\n })\n }\n\n /// Returns a terminal byte stream sufficient to turn the visible contents\n /// of the screen described by `prev` into the visible contents of the\n /// screen described by `self`.\n ///\n /// The result of rendering `prev.contents_formatted()` followed by\n /// `self.contents_diff(prev)` should be equivalent to the result of\n /// rendering `self.contents_formatted()`. This is primarily useful when\n /// you already have a terminal parser whose state is described by `prev`,\n /// since the diff will likely require less memory and cause less\n /// flickering than redrawing the entire screen contents.\n #[must_use]\n pub fn contents_diff(&self, prev: &Self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_contents_diff(&mut contents, prev);\n contents\n }\n\n fn write_contents_diff(&self, contents: &mut Vec<u8>, prev: &Self) {\n if self.hide_cursor() != prev.hide_cursor() {\n crate::term::HideCursor::new(self.hide_cursor())\n .write_buf(contents);\n }\n let prev_attrs = self.grid().write_contents_diff(\n contents,\n prev.grid(),\n prev.attrs,\n );\n self.attrs.write_escape_code_diff(contents, &prev_attrs);\n }\n\n /// Returns a sequence of terminal byte streams sufficient to turn the\n /// visible contents of the subset of each row from `prev` (as described\n /// by `start` and `width`) into the visible contents of the corresponding\n /// row subset in `self`.\n ///\n /// You are responsible for positioning the cursor before printing each\n /// row, and the final cursor position after displaying each row is\n /// unspecified.\n // the unwraps in this method shouldn't be reachable\n #[allow(clippy::missing_panics_doc)]\n pub fn rows_diff<'a>(\n &'a self,\n prev: &'a Self,\n start: u16,\n width: u16,\n ) -> impl Iterator<Item = Vec<u8>> + 'a {\n self.grid()\n .visible_rows()\n .zip(prev.grid().visible_rows())\n .enumerate()\n .map(move |(i, (row, prev_row))| {\n // number of rows in a grid is stored in a u16 (see Size), so\n // visible_rows can never return enough rows to overflow here\n let i = i.try_into().unwrap();\n let mut contents = vec![];\n row.write_contents_diff(\n &mut contents,\n prev_row,\n start,\n width,\n i,\n false,\n false,\n crate::grid::Pos { row: i, col: start },\n crate::attrs::Attrs::default(),\n );\n contents\n })\n }\n\n /// Returns terminal escape sequences sufficient to set the current\n /// terminal's input modes.\n ///\n /// Supported modes are:\n /// * application keypad\n /// * application cursor\n /// * bracketed paste\n /// * xterm mouse support\n #[must_use]\n pub fn input_mode_formatted(&self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_input_mode_formatted(&mut contents);\n contents\n }\n\n fn write_input_mode_formatted(&self, contents: &mut Vec<u8>) {\n crate::term::ApplicationKeypad::new(\n self.mode(MODE_APPLICATION_KEYPAD),\n )\n .write_buf(contents);\n crate::term::ApplicationCursor::new(\n self.mode(MODE_APPLICATION_CURSOR),\n )\n .write_buf(contents);\n crate::term::BracketedPaste::new(self.mode(MODE_BRACKETED_PASTE))\n .write_buf(contents);\n crate::term::MouseProtocolMode::new(\n self.mouse_protocol_mode,\n MouseProtocolMode::None,\n )\n .write_buf(contents);\n crate::term::MouseProtocolEncoding::new(\n self.mouse_protocol_encoding,\n MouseProtocolEncoding::Default,\n )\n .write_buf(contents);\n }\n\n /// Returns terminal escape sequences sufficient to change the previous\n /// terminal's input modes to the input modes enabled in the current\n /// terminal.\n #[must_use]\n pub fn input_mode_diff(&self, prev: &Self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_input_mode_diff(&mut contents, prev);\n contents\n }\n\n fn write_input_mode_diff(&self, contents: &mut Vec<u8>, prev: &Self) {\n if self.mode(MODE_APPLICATION_KEYPAD)\n != prev.mode(MODE_APPLICATION_KEYPAD)\n {\n crate::term::ApplicationKeypad::new(\n self.mode(MODE_APPLICATION_KEYPAD),\n )\n .write_buf(contents);\n }\n if self.mode(MODE_APPLICATION_CURSOR)\n != prev.mode(MODE_APPLICATION_CURSOR)\n {\n crate::term::ApplicationCursor::new(\n self.mode(MODE_APPLICATION_CURSOR),\n )\n .write_buf(contents);\n }\n if self.mode(MODE_BRACKETED_PASTE) != prev.mode(MODE_BRACKETED_PASTE)\n {\n crate::term::BracketedPaste::new(self.mode(MODE_BRACKETED_PASTE))\n .write_buf(contents);\n }\n crate::term::MouseProtocolMode::new(\n self.mouse_protocol_mode,\n prev.mouse_protocol_mode,\n )\n .write_buf(contents);\n crate::term::MouseProtocolEncoding::new(\n self.mouse_protocol_encoding,\n prev.mouse_protocol_encoding,\n )\n .write_buf(contents);\n }\n\n /// Returns terminal escape sequences sufficient to set the current\n /// terminal's drawing attributes.\n ///\n /// Supported drawing attributes are:\n /// * fgcolor\n /// * bgcolor\n /// * bold\n /// * dim\n /// * italic\n /// * underline\n /// * inverse\n ///\n /// This is not typically necessary, since\n /// [`contents_formatted`](Self::contents_formatted) will leave\n /// the current active drawing attributes in the correct state, but this\n /// can be useful in the case of drawing additional things on top of a\n /// terminal output, since you will need to restore the terminal state\n /// without the terminal contents necessarily being the same.\n #[must_use]\n pub fn attributes_formatted(&self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_attributes_formatted(&mut contents);\n contents\n }\n\n fn write_attributes_formatted(&self, contents: &mut Vec<u8>) {\n crate::term::ClearAttrs.write_buf(contents);\n self.attrs.write_escape_code_diff(\n contents,\n &crate::attrs::Attrs::default(),\n );\n }\n\n /// Returns the current cursor position of the terminal.\n ///\n /// The return value will be (row, col).\n #[must_use]\n pub fn cursor_position(&self) -> (u16, u16) {\n let pos = self.grid().pos();\n (pos.row, pos.col)\n }\n\n /// Returns terminal escape sequences sufficient to set the current\n /// cursor state of the terminal.\n ///\n /// This is not typically necessary, since\n /// [`contents_formatted`](Self::contents_formatted) will leave\n /// the cursor in the correct state, but this can be useful in the case of\n /// drawing additional things on top of a terminal output, since you will\n /// need to restore the terminal state without the terminal contents\n /// necessarily being the same.\n ///\n /// Note that the bytes returned by this function may alter the active\n /// drawing attributes, because it may require redrawing existing cells in\n /// order to position the cursor correctly (for instance, in the case\n /// where the cursor is past the end of a row). Therefore, you should\n /// ensure to reset the active drawing attributes if necessary after\n /// processing this data, for instance by using\n /// [`attributes_formatted`](Self::attributes_formatted).\n #[must_use]\n pub fn cursor_state_formatted(&self) -> Vec<u8> {\n let mut contents = vec![];\n self.write_cursor_state_formatted(&mut contents);\n contents\n }\n\n fn write_cursor_state_formatted(&self, contents: &mut Vec<u8>) {\n crate::term::HideCursor::new(self.hide_cursor()).write_buf(contents);\n self.grid()\n .write_cursor_position_formatted(contents, None, None);\n\n // we don't just call write_attributes_formatted here, because that\n // would still be confusing - consider the case where the user sets\n // their own unrelated drawing attributes (on a different parser\n // instance) and then calls cursor_state_formatted. just documenting\n // it and letting the user handle it on their own is more\n // straightforward.\n }\n\n /// Returns the [`Cell`](crate::Cell) object at the given location in the\n /// terminal, if it exists.\n #[must_use]\n pub fn cell(&self, row: u16, col: u16) -> Option<&crate::Cell> {\n self.grid().visible_cell(crate::grid::Pos { row, col })\n }\n\n /// Returns whether the text in row `row` should wrap to the next line.\n #[must_use]\n pub fn row_wrapped(&self, row: u16) -> bool {\n self.grid()\n .visible_row(row)\n .is_some_and(crate::row::Row::wrapped)\n }\n\n /// Returns whether the alternate screen is currently in use.\n #[must_use]\n pub fn alternate_screen(&self) -> bool {\n self.mode(MODE_ALTERNATE_SCREEN)\n }\n\n /// Returns whether the terminal should be in application keypad mode.\n #[must_use]\n pub fn application_keypad(&self) -> bool {\n self.mode(MODE_APPLICATION_KEYPAD)\n }\n\n /// Returns whether the terminal should be in application cursor mode.\n #[must_use]\n pub fn application_cursor(&self) -> bool {\n self.mode(MODE_APPLICATION_CURSOR)\n }\n\n /// Returns whether the terminal should be in hide cursor mode.\n #[must_use]\n pub fn hide_cursor(&self) -> bool {\n self.mode(MODE_HIDE_CURSOR)\n }\n\n /// Returns whether the terminal should be in bracketed paste mode.\n #[must_use]\n pub fn bracketed_paste(&self) -> bool {\n self.mode(MODE_BRACKETED_PASTE)\n }\n\n /// Returns the currently active [`MouseProtocolMode`].\n #[must_use]\n pub fn mouse_protocol_mode(&self) -> MouseProtocolMode {\n self.mouse_protocol_mode\n }\n\n /// Returns the currently active [`MouseProtocolEncoding`].\n #[must_use]\n pub fn mouse_protocol_encoding(&self) -> MouseProtocolEncoding {\n self.mouse_protocol_encoding\n }\n\n /// Returns the window title set via OSC 0 or OSC 2.\n #[must_use]\n pub fn title(&self) -> &str {\n &self.osc_title\n }\n\n /// Store a window title set via OSC 0 or OSC 2.\n pub fn set_title(&mut self, raw: &[u8]) {\n if let Ok(s) = std::str::from_utf8(raw) {\n self.osc_title = s.to_string();\n }\n }\n\n /// Returns the path announced by the shell via OSC 7, if any.\n #[must_use]\n pub fn path(&self) -> Option<&str> {\n self.osc7_path.as_deref()\n }\n\n /// Store a path announced via OSC 7.\n /// The raw URI is parsed: `file://host/path` → `/path`.\n pub fn set_path(&mut self, raw: &[u8]) {\n if let Ok(s) = std::str::from_utf8(raw) {\n let path = parse_osc7_uri(s);\n if !path.is_empty() {\n self.osc7_path = Some(path);\n }\n }\n }\n\n /// Returns the most recent OSC 9;4 progress indicator state, if any.\n /// `Some((state, value))` once an OSC 9;4 has been received, even when\n /// state==0 (hide); `None` when none has ever been received. Consumers\n /// (psmux server) forward this to the host terminal so tools like\n /// GitHub Copilot CLI keep working inside a pane.\n #[must_use]\n pub fn progress(&self) -> Option<(u8, u8)> {\n self.osc94_progress\n }\n\n /// Store an OSC 9;4 progress indicator. State is clamped to 0..=4 and\n /// value to 0..=100 to match the Windows Terminal contract.\n pub fn set_progress(&mut self, state: u8, value: u8) {\n let s = state.min(4);\n let v = value.min(100);\n self.osc94_progress = Some((s, v));\n }\n\n /// Store an OSC 52 clipboard copy request emitted by the child.\n /// `selector` is the raw selector field (e.g. `b\"c\"`), `data` is the\n /// base64-encoded payload exactly as received. Later writes overwrite\n /// earlier ones until [`Screen::take_clipboard`] consumes the slot.\n pub fn set_clipboard(&mut self, selector: &[u8], data: &[u8]) {\n self.osc52_clipboard = Some((selector.to_vec(), data.to_vec()));\n }\n\n /// Returns and clears any pending OSC 52 clipboard payload. Consume-once:\n /// after a successful drain this returns `None` until the next OSC 52\n /// arrives. Used by the psmux server to forward child-emitted clipboard\n /// requests onto `App.clipboard_osc52`, which the client re-emits as an\n /// OSC 52 sequence on its own stdout so the host terminal (Windows\n /// Terminal, etc.) can perform the actual copy.\n pub fn take_clipboard(&mut self) -> Option<(Vec<u8>, Vec<u8>)> {\n self.osc52_clipboard.take()\n }\n\n /// Peek at the pending OSC 52 clipboard payload without consuming it.\n /// Returns `None` if no copy request is currently staged.\n #[must_use]\n pub fn clipboard(&self) -> Option<(&[u8], &[u8])> {\n self.osc52_clipboard\n .as_ref()\n .map(|(s, d)| (s.as_slice(), d.as_slice()))\n }\n\n /// Returns `true` if a screen clear (CSI 2J) was detected while\n /// squelch was pending, signalling that `cls`/`clear` finished.\n /// Calling this does NOT clear the flag; use [`take_squelch_cleared`]\n /// for a consume-style check.\n #[must_use]\n pub fn squelch_cleared(&self) -> bool {\n self.squelch_cleared\n }\n\n /// Returns `true` and resets the flag if screen clear was detected.\n pub fn take_squelch_cleared(&mut self) -> bool {\n let v = self.squelch_cleared;\n self.squelch_cleared = false;\n v\n }\n\n /// Returns `true` if one or more audible bells (standalone BEL, not OSC\n /// terminators) were received since the last call. Resets the counter.\n pub fn take_audible_bell(&mut self) -> bool {\n let v = self.audible_bell_count;\n self.audible_bell_count = 0;\n v > 0\n }\n\n /// Arm the squelch detector: the next CSI 2J or CSI 3J will\n /// set `squelch_cleared` to `true`.\n pub fn set_squelch_clear_pending(&mut self, v: bool) {\n self.squelch_clear_pending = v;\n }\n\n /// Internal: fire the squelch signal if armed.\n fn check_squelch_signal(&mut self) {\n if self.squelch_clear_pending {\n self.squelch_cleared = true;\n self.squelch_clear_pending = false;\n }\n }\n\n /// Returns the currently active foreground color.\n #[must_use]\n pub fn fgcolor(&self) -> crate::Color {\n self.attrs.fgcolor\n }\n\n /// Returns the currently active background color.\n #[must_use]\n pub fn bgcolor(&self) -> crate::Color {\n self.attrs.bgcolor\n }\n\n /// Returns whether newly drawn text should be rendered with the bold text\n /// attribute.\n #[must_use]\n pub fn bold(&self) -> bool {\n self.attrs.bold()\n }\n\n /// Returns whether newly drawn text should be rendered with the dim text\n /// attribute.\n #[must_use]\n pub fn dim(&self) -> bool {\n self.attrs.dim()\n }\n\n /// Returns whether newly drawn text should be rendered with the italic\n /// text attribute.\n #[must_use]\n pub fn italic(&self) -> bool {\n self.attrs.italic()\n }\n\n /// Returns whether newly drawn text should be rendered with the\n /// underlined text attribute.\n #[must_use]\n pub fn underline(&self) -> bool {\n self.attrs.underline()\n }\n\n /// Returns whether newly drawn text should be rendered with the inverse\n /// text attribute.\n #[must_use]\n pub fn inverse(&self) -> bool {\n self.attrs.inverse()\n }\n\n pub(crate) fn grid(&self) -> &crate::grid::Grid {\n if self.mode(MODE_ALTERNATE_SCREEN) {\n &self.alternate_grid\n } else {\n &self.grid\n }\n }\n\n fn grid_mut(&mut self) -> &mut crate::grid::Grid {\n if self.mode(MODE_ALTERNATE_SCREEN) {\n &mut self.alternate_grid\n } else {\n &mut self.grid\n }\n }\n\n fn enter_alternate_grid(&mut self) {\n self.grid_mut().set_scrollback(0);\n self.set_mode(MODE_ALTERNATE_SCREEN);\n self.alternate_grid.allocate_rows();\n }\n\n fn exit_alternate_grid(&mut self) {\n // Issue #88: when the user has opted in via `alternate-screen\n // off`, append the alt grid's currently-visible rows to the\n // main grid's scrollback BEFORE flipping the mode. Done in\n // this order so the rows are read off the alt grid (which is\n // still selected by `grid()` while MODE_ALTERNATE_SCREEN is\n // set) and pushed into the main grid's buffer. A no-op when\n // the option is left at the default `on`.\n if !self.allow_alternate_screen {\n self.copy_alt_visible_to_main_scrollback();\n }\n self.clear_mode(MODE_ALTERNATE_SCREEN);\n }\n\n /// Append every non-blank visible row of the alt grid to the\n /// main grid's scrollback. Trailing blank rows are skipped so a\n /// TUI that didn't fill the screen does not leave a tail of empty\n /// lines in scrollback. Cheap: O(rows × cols) per exit, with the\n /// usual scrollback eviction rules applied by main grid's append.\n fn copy_alt_visible_to_main_scrollback(&mut self) {\n // Snapshot the alt grid's visible rows; we will hand them to\n // the main grid afterwards.\n let alt_rows: Vec<crate::row::Row> = self\n .alternate_grid\n .drawing_rows()\n .cloned()\n .collect();\n\n // Trim trailing blank rows — they're just empty lines beneath\n // the TUI's last drawn row and would clutter scrollback.\n let last_nonblank = alt_rows\n .iter()\n .rposition(|r| !r.is_blank())\n .map(|i| i + 1)\n .unwrap_or(0);\n\n for row in alt_rows.into_iter().take(last_nonblank) {\n self.grid.push_row_to_scrollback(row);\n }\n }\n\n fn save_cursor(&mut self) {\n self.grid_mut().save_cursor();\n self.saved_attrs = self.attrs;\n }\n\n fn restore_cursor(&mut self) {\n self.grid_mut().restore_cursor();\n self.attrs = self.saved_attrs;\n }\n\n fn set_mode(&mut self, mode: u8) {\n self.modes |= mode;\n }\n\n fn clear_mode(&mut self, mode: u8) {\n self.modes &= !mode;\n }\n\n fn mode(&self, mode: u8) -> bool {\n self.modes & mode != 0\n }\n\n fn set_mouse_mode(&mut self, mode: MouseProtocolMode) {\n self.mouse_protocol_mode = mode;\n }\n\n fn clear_mouse_mode(&mut self, mode: MouseProtocolMode) {\n if self.mouse_protocol_mode == mode {\n self.mouse_protocol_mode = MouseProtocolMode::default();\n }\n }\n\n fn set_mouse_encoding(&mut self, encoding: MouseProtocolEncoding) {\n self.mouse_protocol_encoding = encoding;\n }\n\n fn clear_mouse_encoding(&mut self, encoding: MouseProtocolEncoding) {\n if self.mouse_protocol_encoding == encoding {\n self.mouse_protocol_encoding = MouseProtocolEncoding::default();\n }\n }\n}\n\nimpl Screen {\n pub(crate) fn text(&mut self, c: char) {\n let pos = self.grid().pos();\n let size = self.grid().size();\n let attrs = self.attrs;\n\n let width = c.width();\n if width.is_none() && (u32::from(c)) < 256 {\n // don't even try to draw control characters\n return;\n }\n let width = width\n .unwrap_or(1)\n .try_into()\n // width() can only return 0, 1, or 2\n .unwrap();\n\n // it doesn't make any sense to wrap if the last column in a row\n // didn't already have contents. don't try to handle the case where a\n // character wraps because there was only one column left in the\n // previous row - literally everything handles this case differently,\n // and this is tmux behavior (and also the simplest). i'm open to\n // reconsidering this behavior, but only with a really good reason\n // (xterm handles this by introducing the concept of triple width\n // cells, which i really don't want to do).\n let mut wrap = false;\n if pos.col > size.cols - width {\n let last_cell = self\n .grid()\n .drawing_cell(crate::grid::Pos {\n row: pos.row,\n col: size.cols - 1,\n })\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always have a valid\n // row value. size.cols - 1 is also always a valid column.\n .unwrap();\n if last_cell.has_contents() || last_cell.is_wide_continuation() {\n wrap = true;\n }\n }\n self.grid_mut().col_wrap(width, wrap);\n let pos = self.grid().pos();\n\n if width == 0 {\n if pos.col > 0 {\n let mut prev_cell = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row,\n col: pos.col - 1,\n })\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always have a\n // valid row value. pos.col - 1 is valid because we just\n // checked for pos.col > 0.\n .unwrap();\n if prev_cell.is_wide_continuation() {\n prev_cell = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row,\n col: pos.col - 2,\n })\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always have a\n // valid row value. we know pos.col - 2 is valid\n // because the cell at pos.col - 1 is a wide\n // continuation character, which means there must be\n // the first half of the wide character before it.\n .unwrap();\n }\n prev_cell.append(c);\n } else if pos.row > 0 {\n let prev_row = self\n .grid()\n .drawing_row(pos.row - 1)\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always have a\n // valid row value. pos.row - 1 is valid because we just\n // checked for pos.row > 0.\n .unwrap();\n if prev_row.wrapped() {\n let mut prev_cell = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row - 1,\n col: size.cols - 1,\n })\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always have a\n // valid row value. pos.row - 1 is valid because we\n // just checked for pos.row > 0. col of size.cols - 1\n // is always valid.\n .unwrap();\n if prev_cell.is_wide_continuation() {\n prev_cell = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row - 1,\n col: size.cols - 2,\n })\n // pos.row is valid, since it comes directly from\n // self.grid().pos() which we assume to always\n // have a valid row value. pos.row - 1 is valid\n // because we just checked for pos.row > 0. col of\n // size.cols - 2 is valid because the cell at\n // size.cols - 1 is a wide continuation character,\n // so it must have the first half of the wide\n // character before it.\n .unwrap();\n }\n prev_cell.append(c);\n }\n }\n } else {\n // After a resize, cells may be in inconsistent states (e.g.\n // a wide char at the last column without its continuation).\n // Use safe accessors to avoid panics on out-of-bounds.\n if let Some(cell_ref) = self.grid().drawing_cell(pos) {\n if cell_ref.is_wide_continuation() {\n if let Some(prev_cell) = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row,\n col: pos.col - 1,\n })\n {\n prev_cell.clear(attrs);\n }\n }\n }\n\n let is_wide_at_pos = self\n .grid()\n .drawing_cell(pos)\n .map_or(false, |c| c.is_wide());\n if is_wide_at_pos {\n if let Some(next_cell) = self\n .grid_mut()\n .drawing_cell_mut(crate::grid::Pos {\n row: pos.row,\n col: pos.col + 1,\n })\n {\n next_cell.set(' ', attrs);\n }\n }\n\n if let Some(cell) = self\n .grid_mut()\n .drawing_cell_mut(pos)\n {\n cell.set(c, attrs);\n } else {\n return;\n }\n self.grid_mut().col_inc(1);\n if width > 1 {\n let pos = self.grid().pos();\n let is_wide_here = self\n .grid()\n .drawing_cell(pos)\n .map_or(false, |c| c.is_wide());\n if is_wide_here {\n let next_next_pos = crate::grid::Pos {\n row: pos.row,\n col: pos.col + 1,\n };\n if let Some(next_next_cell) = self\n .grid_mut()\n .drawing_cell_mut(next_next_pos)\n {\n next_next_cell.clear(attrs);\n if next_next_pos.col == size.cols - 1 {\n if let Some(row) = self.grid_mut()\n .drawing_row_mut(pos.row)\n {\n row.wrap(false);\n }\n }\n }\n }\n if let Some(next_cell) = self\n .grid_mut()\n .drawing_cell_mut(pos)\n {\n next_cell.clear(crate::attrs::Attrs::default());\n next_cell.set_wide_continuation(true);\n }\n self.grid_mut().col_inc(1);\n }\n }\n }\n\n // control codes\n\n pub(crate) fn bs(&mut self) {\n self.grid_mut().col_dec(1);\n }\n\n pub(crate) fn tab(&mut self) {\n self.grid_mut().col_tab();\n }\n\n pub(crate) fn lf(&mut self) {\n self.grid_mut().row_inc_scroll(1);\n }\n\n pub(crate) fn vt(&mut self) {\n self.lf();\n }\n\n pub(crate) fn ff(&mut self) {\n self.lf();\n }\n\n pub(crate) fn cr(&mut self) {\n self.grid_mut().col_set(0);\n }\n\n // escape codes\n\n // ESC 7\n pub(crate) fn decsc(&mut self) {\n self.save_cursor();\n }\n\n // ESC 8\n pub(crate) fn decrc(&mut self) {\n self.restore_cursor();\n }\n\n // ESC =\n pub(crate) fn deckpam(&mut self) {\n self.set_mode(MODE_APPLICATION_KEYPAD);\n }\n\n // ESC >\n pub(crate) fn deckpnm(&mut self) {\n self.clear_mode(MODE_APPLICATION_KEYPAD);\n }\n\n // ESC M\n pub(crate) fn ri(&mut self) {\n self.grid_mut().row_dec_scroll(1);\n }\n\n // ESC c\n pub(crate) fn ris(&mut self) {\n *self = Self::new(self.grid.size(), self.grid.scrollback_len());\n }\n\n // csi codes\n\n // CSI @\n pub(crate) fn ich(&mut self, count: u16) {\n self.grid_mut().insert_cells(count);\n }\n\n // CSI A\n pub(crate) fn cuu(&mut self, offset: u16) {\n self.grid_mut().row_dec_clamp(offset);\n }\n\n // CSI B\n pub(crate) fn cud(&mut self, offset: u16) {\n self.grid_mut().row_inc_clamp(offset);\n }\n\n // CSI C\n pub(crate) fn cuf(&mut self, offset: u16) {\n self.grid_mut().col_inc_clamp(offset);\n }\n\n // CSI D\n pub(crate) fn cub(&mut self, offset: u16) {\n self.grid_mut().col_dec(offset);\n }\n\n // CSI E\n pub(crate) fn cnl(&mut self, offset: u16) {\n self.grid_mut().col_set(0);\n self.grid_mut().row_inc_clamp(offset);\n }\n\n // CSI F\n pub(crate) fn cpl(&mut self, offset: u16) {\n self.grid_mut().col_set(0);\n self.grid_mut().row_dec_clamp(offset);\n }\n\n // CSI G\n pub(crate) fn cha(&mut self, col: u16) {\n self.grid_mut().col_set(col - 1);\n }\n\n // CSI H\n pub(crate) fn cup(&mut self, (row, col): (u16, u16)) {\n self.grid_mut().set_pos(crate::grid::Pos {\n row: row - 1,\n col: col - 1,\n });\n }\n\n // CSI J\n pub(crate) fn ed(\n &mut self,\n mode: u16,\n mut unhandled: impl FnMut(&mut Self),\n ) {\n let attrs = self.attrs;\n match mode {\n 0 => self.grid_mut().erase_all_forward(attrs),\n 1 => self.grid_mut().erase_all_backward(attrs),\n 2 => {\n self.grid_mut().erase_all(attrs);\n self.check_squelch_signal();\n }\n 3 => {\n self.grid_mut().clear_scrollback();\n self.check_squelch_signal();\n }\n _ => unhandled(self),\n }\n }\n\n // CSI ? J\n pub(crate) fn decsed(\n &mut self,\n mode: u16,\n unhandled: impl FnMut(&mut Self),\n ) {\n self.ed(mode, unhandled);\n }\n\n // CSI K\n pub(crate) fn el(\n &mut self,\n mode: u16,\n mut unhandled: impl FnMut(&mut Self),\n ) {\n let attrs = self.attrs;\n match mode {\n 0 => self.grid_mut().erase_row_forward(attrs),\n 1 => self.grid_mut().erase_row_backward(attrs),\n 2 => self.grid_mut().erase_row(attrs),\n _ => unhandled(self),\n }\n }\n\n // CSI ? K\n pub(crate) fn decsel(\n &mut self,\n mode: u16,\n unhandled: impl FnMut(&mut Self),\n ) {\n self.el(mode, unhandled);\n }\n\n // CSI L\n pub(crate) fn il(&mut self, count: u16) {\n self.grid_mut().insert_lines(count);\n }\n\n // CSI M\n pub(crate) fn dl(&mut self, count: u16) {\n self.grid_mut().delete_lines(count);\n }\n\n // CSI P\n pub(crate) fn dch(&mut self, count: u16) {\n self.grid_mut().delete_cells(count);\n }\n\n // CSI S\n pub(crate) fn su(&mut self, count: u16) {\n self.grid_mut().scroll_up(count);\n }\n\n // CSI T\n pub(crate) fn sd(&mut self, count: u16) {\n self.grid_mut().scroll_down(count);\n }\n\n // CSI X\n pub(crate) fn ech(&mut self, count: u16) {\n let attrs = self.attrs;\n self.grid_mut().erase_cells(count, attrs);\n }\n\n // CSI d\n pub(crate) fn vpa(&mut self, row: u16) {\n self.grid_mut().row_set(row - 1);\n }\n\n // CSI ? h\n pub(crate) fn decset(\n &mut self,\n params: &vte::Params,\n mut unhandled: impl FnMut(&mut Self),\n ) {\n for param in params {\n match param {\n [1] => self.set_mode(MODE_APPLICATION_CURSOR),\n [6] => self.grid_mut().set_origin_mode(true),\n [9] => self.set_mouse_mode(MouseProtocolMode::Press),\n [25] => self.clear_mode(MODE_HIDE_CURSOR),\n [47] => self.enter_alternate_grid(),\n [1000] => {\n self.set_mouse_mode(MouseProtocolMode::PressRelease);\n }\n [1002] => {\n self.set_mouse_mode(MouseProtocolMode::ButtonMotion);\n }\n [1003] => self.set_mouse_mode(MouseProtocolMode::AnyMotion),\n [1005] => {\n self.set_mouse_encoding(MouseProtocolEncoding::Utf8);\n }\n [1006] => {\n self.set_mouse_encoding(MouseProtocolEncoding::Sgr);\n }\n [1049] => {\n self.decsc();\n self.alternate_grid.clear();\n self.enter_alternate_grid();\n }\n [2004] => self.set_mode(MODE_BRACKETED_PASTE),\n _ => unhandled(self),\n }\n }\n }\n\n // CSI ? l\n pub(crate) fn decrst(\n &mut self,\n params: &vte::Params,\n mut unhandled: impl FnMut(&mut Self),\n ) {\n for param in params {\n match param {\n [1] => self.clear_mode(MODE_APPLICATION_CURSOR),\n [6] => self.grid_mut().set_origin_mode(false),\n [9] => self.clear_mouse_mode(MouseProtocolMode::Press),\n [25] => self.set_mode(MODE_HIDE_CURSOR),\n [47] => {\n self.exit_alternate_grid();\n }\n [1000] => {\n self.clear_mouse_mode(MouseProtocolMode::PressRelease);\n }\n [1002] => {\n self.clear_mouse_mode(MouseProtocolMode::ButtonMotion);\n }\n [1003] => {\n self.clear_mouse_mode(MouseProtocolMode::AnyMotion);\n }\n [1005] => {\n self.clear_mouse_encoding(MouseProtocolEncoding::Utf8);\n }\n [1006] => {\n self.clear_mouse_encoding(MouseProtocolEncoding::Sgr);\n }\n [1049] => {\n self.exit_alternate_grid();\n self.decrc();\n }\n [2004] => self.clear_mode(MODE_BRACKETED_PASTE),\n _ => unhandled(self),\n }\n }\n }\n\n // CSI m\n pub(crate) fn sgr(\n &mut self,\n params: &vte::Params,\n mut unhandled: impl FnMut(&mut Self),\n ) {\n // XXX really i want to just be able to pass in a default Params\n // instance with a 0 in it, but vte doesn't allow creating new Params\n // instances\n if params.is_empty() {\n self.attrs = crate::attrs::Attrs::default();\n return;\n }\n\n let mut iter = params.iter();\n\n macro_rules! next_param {\n () => {\n match iter.next() {\n Some(n) => n,\n _ => return,\n }\n };\n }\n\n macro_rules! to_u8 {\n ($n:expr) => {\n if let Some(n) = u16_to_u8($n) {\n n\n } else {\n return;\n }\n };\n }\n\n macro_rules! next_param_u8 {\n () => {\n if let &[n] = next_param!() {\n to_u8!(n)\n } else {\n return;\n }\n };\n }\n\n loop {\n match next_param!() {\n [0] => self.attrs = crate::attrs::Attrs::default(),\n [1] => self.attrs.set_bold(),\n [2] => self.attrs.set_dim(),\n [3] => self.attrs.set_italic(true),\n [4] => self.attrs.set_underline(true),\n [5] | [6] => self.attrs.set_blink(true),\n [7] => self.attrs.set_inverse(true),\n [8] => self.attrs.set_hidden(true),\n [9] => self.attrs.set_strikethrough(true),\n [22] => self.attrs.set_normal_intensity(),\n [23] => self.attrs.set_italic(false),\n [24] => self.attrs.set_underline(false),\n [25] => self.attrs.set_blink(false),\n [27] => self.attrs.set_inverse(false),\n [28] => self.attrs.set_hidden(false),\n [29] => self.attrs.set_strikethrough(false),\n [n] if (30..=37).contains(n) => {\n self.attrs.fgcolor = crate::Color::Idx(to_u8!(*n) - 30);\n }\n [38, 2, r, g, b] => {\n self.attrs.fgcolor =\n crate::Color::Rgb(to_u8!(*r), to_u8!(*g), to_u8!(*b));\n }\n [38, 5, i] => {\n self.attrs.fgcolor = crate::Color::Idx(to_u8!(*i));\n }\n [38] => match next_param!() {\n [2] => {\n let r = next_param_u8!();\n let g = next_param_u8!();\n let b = next_param_u8!();\n self.attrs.fgcolor = crate::Color::Rgb(r, g, b);\n }\n [5] => {\n self.attrs.fgcolor =\n crate::Color::Idx(next_param_u8!());\n }\n _ => {\n unhandled(self);\n return;\n }\n },\n [39] => {\n self.attrs.fgcolor = crate::Color::Default;\n }\n [n] if (40..=47).contains(n) => {\n self.attrs.bgcolor = crate::Color::Idx(to_u8!(*n) - 40);\n }\n [48, 2, r, g, b] => {\n self.attrs.bgcolor =\n crate::Color::Rgb(to_u8!(*r), to_u8!(*g), to_u8!(*b));\n }\n [48, 5, i] => {\n self.attrs.bgcolor = crate::Color::Idx(to_u8!(*i));\n }\n [48] => match next_param!() {\n [2] => {\n let r = next_param_u8!();\n let g = next_param_u8!();\n let b = next_param_u8!();\n self.attrs.bgcolor = crate::Color::Rgb(r, g, b);\n }\n [5] => {\n self.attrs.bgcolor =\n crate::Color::Idx(next_param_u8!());\n }\n _ => {\n unhandled(self);\n return;\n }\n },\n [49] => {\n self.attrs.bgcolor = crate::Color::Default;\n }\n [n] if (90..=97).contains(n) => {\n self.attrs.fgcolor = crate::Color::Idx(to_u8!(*n) - 82);\n }\n [n] if (100..=107).contains(n) => {\n self.attrs.bgcolor = crate::Color::Idx(to_u8!(*n) - 92);\n }\n _ => unhandled(self),\n }\n }\n }\n\n // CSI r\n pub(crate) fn decstbm(&mut self, (top, bottom): (u16, u16)) {\n self.grid_mut().set_scroll_region(top - 1, bottom - 1);\n }\n}\n\nfn u16_to_u8(i: u16) -> Option<u8> {\n if i > u16::from(u8::MAX) {\n None\n } else {\n // safe because we just ensured that the value fits in a u8\n Some(i.try_into().unwrap())\n }\n}\n\n#[cfg(test)]\n#[path = \"../../../tests-rs/test_vt100_screen.rs\"]\nmod tests;\n\n#[cfg(test)]\n#[path = \"../../../tests-rs/test_issue155_sgr_attrs.rs\"]\nmod test_issue155_sgr_attrs;\n\n"
},
{
"path": "crates/vt100-psmux/src/term.rs",
"content": "// TODO: read all of this from terminfo\n\npub trait BufWrite {\n fn write_buf(&self, buf: &mut Vec<u8>);\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct ClearScreen;\n\nimpl BufWrite for ClearScreen {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x1b[H\\x1b[J\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct ClearRowForward;\n\nimpl BufWrite for ClearRowForward {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x1b[K\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct Crlf;\n\nimpl BufWrite for Crlf {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\r\\n\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct Backspace;\n\nimpl BufWrite for Backspace {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x08\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct SaveCursor;\n\nimpl BufWrite for SaveCursor {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x1b7\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct RestoreCursor;\n\nimpl BufWrite for RestoreCursor {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x1b8\");\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct MoveTo {\n row: u16,\n col: u16,\n}\n\nimpl MoveTo {\n pub fn new(pos: crate::grid::Pos) -> Self {\n Self {\n row: pos.row,\n col: pos.col,\n }\n }\n}\n\nimpl BufWrite for MoveTo {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.row == 0 && self.col == 0 {\n buf.extend_from_slice(b\"\\x1b[H\");\n } else {\n buf.extend_from_slice(b\"\\x1b[\");\n extend_itoa(buf, self.row + 1);\n buf.push(b';');\n extend_itoa(buf, self.col + 1);\n buf.push(b'H');\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct ClearAttrs;\n\nimpl BufWrite for ClearAttrs {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n buf.extend_from_slice(b\"\\x1b[m\");\n }\n}\n\n#[derive(Debug, Clone, Copy)]\npub enum Intensity {\n Normal,\n Bold,\n Dim,\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct Attrs {\n fgcolor: Option<crate::Color>,\n bgcolor: Option<crate::Color>,\n intensity: Option<Intensity>,\n italic: Option<bool>,\n underline: Option<bool>,\n inverse: Option<bool>,\n blink: Option<bool>,\n hidden: Option<bool>,\n strikethrough: Option<bool>,\n}\n\nimpl Attrs {\n pub fn fgcolor(mut self, fgcolor: crate::Color) -> Self {\n self.fgcolor = Some(fgcolor);\n self\n }\n\n pub fn bgcolor(mut self, bgcolor: crate::Color) -> Self {\n self.bgcolor = Some(bgcolor);\n self\n }\n\n pub fn intensity(mut self, intensity: Intensity) -> Self {\n self.intensity = Some(intensity);\n self\n }\n\n pub fn italic(mut self, italic: bool) -> Self {\n self.italic = Some(italic);\n self\n }\n\n pub fn underline(mut self, underline: bool) -> Self {\n self.underline = Some(underline);\n self\n }\n\n pub fn inverse(mut self, inverse: bool) -> Self {\n self.inverse = Some(inverse);\n self\n }\n\n pub fn blink(mut self, blink: bool) -> Self {\n self.blink = Some(blink);\n self\n }\n\n pub fn hidden(mut self, hidden: bool) -> Self {\n self.hidden = Some(hidden);\n self\n }\n\n pub fn strikethrough(mut self, strikethrough: bool) -> Self {\n self.strikethrough = Some(strikethrough);\n self\n }\n}\n\nimpl BufWrite for Attrs {\n #[allow(unused_assignments)]\n #[allow(clippy::branches_sharing_code)]\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.fgcolor.is_none()\n && self.bgcolor.is_none()\n && self.intensity.is_none()\n && self.italic.is_none()\n && self.underline.is_none()\n && self.inverse.is_none()\n && self.blink.is_none()\n && self.hidden.is_none()\n && self.strikethrough.is_none()\n {\n return;\n }\n\n buf.extend_from_slice(b\"\\x1b[\");\n let mut first = true;\n\n macro_rules! write_param {\n ($i:expr) => {{\n if first {\n first = false;\n } else {\n buf.push(b';');\n }\n extend_itoa(buf, $i);\n }};\n }\n\n if let Some(fgcolor) = self.fgcolor {\n match fgcolor {\n crate::Color::Default => {\n write_param!(39);\n }\n crate::Color::Idx(i) => {\n if i < 8 {\n write_param!(i + 30);\n } else if i < 16 {\n write_param!(i + 82);\n } else {\n write_param!(38);\n write_param!(5);\n write_param!(i);\n }\n }\n crate::Color::Rgb(r, g, b) => {\n write_param!(38);\n write_param!(2);\n write_param!(r);\n write_param!(g);\n write_param!(b);\n }\n }\n }\n\n if let Some(bgcolor) = self.bgcolor {\n match bgcolor {\n crate::Color::Default => {\n write_param!(49);\n }\n crate::Color::Idx(i) => {\n if i < 8 {\n write_param!(i + 40);\n } else if i < 16 {\n write_param!(i + 92);\n } else {\n write_param!(48);\n write_param!(5);\n write_param!(i);\n }\n }\n crate::Color::Rgb(r, g, b) => {\n write_param!(48);\n write_param!(2);\n write_param!(r);\n write_param!(g);\n write_param!(b);\n }\n }\n }\n\n if let Some(intensity) = self.intensity {\n match intensity {\n Intensity::Normal => write_param!(22),\n Intensity::Bold => write_param!(1),\n Intensity::Dim => write_param!(2),\n }\n }\n\n if let Some(italic) = self.italic {\n if italic {\n write_param!(3);\n } else {\n write_param!(23);\n }\n }\n\n if let Some(underline) = self.underline {\n if underline {\n write_param!(4);\n } else {\n write_param!(24);\n }\n }\n\n if let Some(inverse) = self.inverse {\n if inverse {\n write_param!(7);\n } else {\n write_param!(27);\n }\n }\n\n if let Some(blink) = self.blink {\n if blink {\n write_param!(5);\n } else {\n write_param!(25);\n }\n }\n\n if let Some(hidden) = self.hidden {\n if hidden {\n write_param!(8);\n } else {\n write_param!(28);\n }\n }\n\n if let Some(strikethrough) = self.strikethrough {\n if strikethrough {\n write_param!(9);\n } else {\n write_param!(29);\n }\n }\n\n buf.push(b'm');\n }\n}\n\n#[derive(Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct MoveRight {\n count: u16,\n}\n\nimpl MoveRight {\n pub fn new(count: u16) -> Self {\n Self { count }\n }\n}\n\nimpl Default for MoveRight {\n fn default() -> Self {\n Self { count: 1 }\n }\n}\n\nimpl BufWrite for MoveRight {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n match self.count {\n 0 => {}\n 1 => buf.extend_from_slice(b\"\\x1b[C\"),\n n => {\n buf.extend_from_slice(b\"\\x1b[\");\n extend_itoa(buf, n);\n buf.push(b'C');\n }\n }\n }\n}\n\n#[derive(Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct EraseChar {\n count: u16,\n}\n\nimpl EraseChar {\n pub fn new(count: u16) -> Self {\n Self { count }\n }\n}\n\nimpl Default for EraseChar {\n fn default() -> Self {\n Self { count: 1 }\n }\n}\n\nimpl BufWrite for EraseChar {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n match self.count {\n 0 => {}\n 1 => buf.extend_from_slice(b\"\\x1b[X\"),\n n => {\n buf.extend_from_slice(b\"\\x1b[\");\n extend_itoa(buf, n);\n buf.push(b'X');\n }\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct HideCursor {\n state: bool,\n}\n\nimpl HideCursor {\n pub fn new(state: bool) -> Self {\n Self { state }\n }\n}\n\nimpl BufWrite for HideCursor {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.state {\n buf.extend_from_slice(b\"\\x1b[?25l\");\n } else {\n buf.extend_from_slice(b\"\\x1b[?25h\");\n }\n }\n}\n\n#[derive(Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct MoveFromTo {\n from: crate::grid::Pos,\n to: crate::grid::Pos,\n}\n\nimpl MoveFromTo {\n pub fn new(from: crate::grid::Pos, to: crate::grid::Pos) -> Self {\n Self { from, to }\n }\n}\n\nimpl BufWrite for MoveFromTo {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.to.row == self.from.row + 1 && self.to.col == 0 {\n crate::term::Crlf.write_buf(buf);\n } else if self.from.row == self.to.row && self.from.col < self.to.col\n {\n crate::term::MoveRight::new(self.to.col - self.from.col)\n .write_buf(buf);\n } else if self.to != self.from {\n crate::term::MoveTo::new(self.to).write_buf(buf);\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct ApplicationKeypad {\n state: bool,\n}\n\nimpl ApplicationKeypad {\n pub fn new(state: bool) -> Self {\n Self { state }\n }\n}\n\nimpl BufWrite for ApplicationKeypad {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.state {\n buf.extend_from_slice(b\"\\x1b=\");\n } else {\n buf.extend_from_slice(b\"\\x1b>\");\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct ApplicationCursor {\n state: bool,\n}\n\nimpl ApplicationCursor {\n pub fn new(state: bool) -> Self {\n Self { state }\n }\n}\n\nimpl BufWrite for ApplicationCursor {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.state {\n buf.extend_from_slice(b\"\\x1b[?1h\");\n } else {\n buf.extend_from_slice(b\"\\x1b[?1l\");\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct BracketedPaste {\n state: bool,\n}\n\nimpl BracketedPaste {\n pub fn new(state: bool) -> Self {\n Self { state }\n }\n}\n\nimpl BufWrite for BracketedPaste {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.state {\n buf.extend_from_slice(b\"\\x1b[?2004h\");\n } else {\n buf.extend_from_slice(b\"\\x1b[?2004l\");\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct MouseProtocolMode {\n mode: crate::MouseProtocolMode,\n prev: crate::MouseProtocolMode,\n}\n\nimpl MouseProtocolMode {\n pub fn new(\n mode: crate::MouseProtocolMode,\n prev: crate::MouseProtocolMode,\n ) -> Self {\n Self { mode, prev }\n }\n}\n\nimpl BufWrite for MouseProtocolMode {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.mode == self.prev {\n return;\n }\n\n match self.mode {\n crate::MouseProtocolMode::None => match self.prev {\n crate::MouseProtocolMode::None => {}\n crate::MouseProtocolMode::Press => {\n buf.extend_from_slice(b\"\\x1b[?9l\");\n }\n crate::MouseProtocolMode::PressRelease => {\n buf.extend_from_slice(b\"\\x1b[?1000l\");\n }\n crate::MouseProtocolMode::ButtonMotion => {\n buf.extend_from_slice(b\"\\x1b[?1002l\");\n }\n crate::MouseProtocolMode::AnyMotion => {\n buf.extend_from_slice(b\"\\x1b[?1003l\");\n }\n },\n crate::MouseProtocolMode::Press => {\n buf.extend_from_slice(b\"\\x1b[?9h\");\n }\n crate::MouseProtocolMode::PressRelease => {\n buf.extend_from_slice(b\"\\x1b[?1000h\");\n }\n crate::MouseProtocolMode::ButtonMotion => {\n buf.extend_from_slice(b\"\\x1b[?1002h\");\n }\n crate::MouseProtocolMode::AnyMotion => {\n buf.extend_from_slice(b\"\\x1b[?1003h\");\n }\n }\n }\n}\n\n#[derive(Default, Debug)]\n#[must_use = \"this struct does nothing unless you call write_buf\"]\npub struct MouseProtocolEncoding {\n encoding: crate::MouseProtocolEncoding,\n prev: crate::MouseProtocolEncoding,\n}\n\nimpl MouseProtocolEncoding {\n pub fn new(\n encoding: crate::MouseProtocolEncoding,\n prev: crate::MouseProtocolEncoding,\n ) -> Self {\n Self { encoding, prev }\n }\n}\n\nimpl BufWrite for MouseProtocolEncoding {\n fn write_buf(&self, buf: &mut Vec<u8>) {\n if self.encoding == self.prev {\n return;\n }\n\n match self.encoding {\n crate::MouseProtocolEncoding::Default => match self.prev {\n crate::MouseProtocolEncoding::Default => {}\n crate::MouseProtocolEncoding::Utf8 => {\n buf.extend_from_slice(b\"\\x1b[?1005l\");\n }\n crate::MouseProtocolEncoding::Sgr => {\n buf.extend_from_slice(b\"\\x1b[?1006l\");\n }\n },\n crate::MouseProtocolEncoding::Utf8 => {\n buf.extend_from_slice(b\"\\x1b[?1005h\");\n }\n crate::MouseProtocolEncoding::Sgr => {\n buf.extend_from_slice(b\"\\x1b[?1006h\");\n }\n }\n }\n}\n\nfn extend_itoa<I: itoa::Integer>(buf: &mut Vec<u8>, i: I) {\n let mut itoa_buf = itoa::Buffer::new();\n buf.extend_from_slice(itoa_buf.format(i).as_bytes());\n}\n"
},
{
"path": "docker/Dockerfile",
"content": "# escape=`\n# psmux build environment: Windows + Rust (MSVC) + OpenSSH (key-only auth)\n#\n# Build: docker build -t psmux-dev .\n# Run: pwsh -File docker\\Run-PsmuxDev.ps1\n# SSH: (printed by Run-PsmuxDev.ps1 after container starts)\n#\nFROM mcr.microsoft.com/powershell:windowsservercore-ltsc2022\n\n# NOTE: We keep the default cmd shell for RUN steps and invoke pwsh explicitly.\n# Using SHELL [\"pwsh\",...] breaks Hyper-V isolated builds on Win11 25H2 hosts.\n\nENV VS_INSTALL_PATH=\"C:\\BuildTools\"\nENV RUSTUP_HOME=\"C:\\rustup\"\nENV CARGO_HOME=\"C:\\cargo\"\nENV PATH=\"C:\\cargo\\bin;C:\\OpenSSH;C:\\git\\cmd;C:\\Windows\\System32;C:\\Windows;C:\\Program Files\\PowerShell\\latest;${PATH}\"\n\n# Create directories and copy all scripts first\nRUN mkdir C:\\Tools && mkdir C:\\Profile && mkdir \"C:\\Users\\ContainerAdministrator\\Documents\\PowerShell\"\nCOPY Tools\\ C:\\Tools\\\nCOPY Profile\\ C:\\Users\\ContainerAdministrator\\Documents\\PowerShell\\\n\n# Single combined install step: Rust + VS Build Tools + OpenSSH + Git + cleanup\n# (Combined to avoid Docker layer commit failures from VS Build Tools long paths)\nRUN pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File C:\\Tools\\InstallAll.ps1\n\nEXPOSE 2222\n\nCMD [\"pwsh\", \"-NoLogo\", \"-NoProfile\", \"-ExecutionPolicy\", \"Bypass\", \"-File\", \"C:\\\\Tools\\\\StartContainer.ps1\"]\n"
},
{
"path": "docker/Profile/Microsoft.PowerShell_profile.ps1",
"content": "$ErrorActionPreference = \"Continue\"\n\n# Ensure Cargo bin is on PATH\nif ($env:CARGO_HOME -and (Test-Path \"$env:CARGO_HOME\\bin\")) {\n if ($env:PATH -notlike \"*$env:CARGO_HOME\\bin*\") {\n $env:PATH = \"$env:CARGO_HOME\\bin;$env:PATH\"\n }\n}\n\n# Ensure git is on PATH\nif (Test-Path \"C:\\git\\cmd\") {\n if ($env:PATH -notlike \"*C:\\git\\cmd*\") {\n $env:PATH = \"C:\\git\\cmd;$env:PATH\"\n }\n}\n\n# Auto-load VS dev environment (cl.exe, link.exe) if not already loaded\nif (-not $env:VSCMD_VER) {\n $helper = \"C:\\Tools\\ImportVsDevEnv.ps1\"\n if (Test-Path $helper) {\n . $helper\n }\n}\n"
},
{
"path": "docker/README.md",
"content": "# psmux Docker Dev Environment\n\nA Windows container with Rust (MSVC), Visual Studio Build Tools, and OpenSSH — ready to build and run psmux.\n\n## What's inside\n\n| Component | Details |\n|-----------|---------|\n| Base image | `mcr.microsoft.com/powershell:windowsservercore-ltsc2022` |\n| Rust | stable-x86_64-pc-windows-msvc via rustup |\n| MSVC | Visual Studio Build Tools 2022 (`cl.exe`, `link.exe`) |\n| SSH | OpenSSH Server on port 2222 (key-only auth, no passwords) |\n| Shell | PowerShell 7 with auto-loaded VS dev environment |\n| Git | MinGit for cloning repos |\n\n## Quick start\n\n### One command\n\n```powershell\npwsh -File docker\\Run-PsmuxDev.ps1\n```\n\nThis will:\n1. Generate an SSH key at `~/.ssh/psmux_docker_key` (if not present)\n2. Build the Docker image (first time only)\n3. Start the container with your public key injected\n4. Print the SSH command to connect\n\n### Manual steps\n\n#### 1. Build the image\n\n```powershell\ncd docker\ndocker build -t psmux-dev .\n```\n\n> **Note:** The build takes a while (~15-30 min) because it downloads and installs Visual Studio Build Tools. The resulting image is large (~15 GB). This is expected for Windows MSVC containers.\n\n#### 2. Run the container\n\n```powershell\n# Generate SSH key (once)\nssh-keygen -t ed25519 -f ~/.ssh/psmux_docker_key -N \"\" -C \"psmux-docker\"\n\n# Run with your public key\n$pubkey = Get-Content ~/.ssh/psmux_docker_key.pub\ndocker run -d --name psmux-dev --isolation=hyperv `\n -e \"SSH_PUBLIC_KEY=$pubkey\" `\n psmux-dev\n```\n\n#### 3. SSH in\n\n```powershell\n$ip = docker inspect psmux-dev --format \"{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}\"\nssh -i ~/.ssh/psmux_docker_key -p 2222 ContainerAdministrator@$ip\n```\n\n### 4. Build psmux\n\n```powershell\ngit clone https://github.com/psmux/psmux.git\ncd psmux\ncargo install --path .\npsmux --version\n```\n\n## SSH authentication\n\nThis container uses **key-only SSH** — no passwords. Your public key is passed in via the `SSH_PUBLIC_KEY` environment variable at container start. The `Run-PsmuxDev.ps1` script handles this automatically.\n\nYou can also mount a public key file:\n\n```powershell\ndocker run -d --name psmux-dev --isolation=hyperv `\n -v \"$HOME\\.ssh\\id_ed25519.pub:C:\\ssh_public_key\" `\n psmux-dev\n```\n\n## Verifying the toolchain\n\nAfter SSH-ing in, these should all work:\n\n```powershell\nrustc --version\ncargo --version\nwhere cl\nwhere link\n```\n\n## Safety notes\n\n- No passwords are used — SSH key auth only\n- Container runs with Hyper-V isolation (full VM separation from host)\n- SSH listens on port 2222 to avoid conflicts with host sshd\n- Key is stored at `~/.ssh/psmux_docker_key` (never inside the repo)\n\n## File layout\n\n```\ndocker/\n Dockerfile\n README.md\n Run-PsmuxDev.ps1 # Host-side: generates key, builds, runs, prints SSH command\n Tools/\n StartContainer.ps1 # Entrypoint: configures sshd with key auth, starts sshd\n InstallAll.ps1 # Build-time: installs Rust, VS Build Tools, OpenSSH, Git\n ImportVsDevEnv.ps1 # Loads VS dev environment (cl.exe, link.exe) into PowerShell\n Profile/\n Microsoft.PowerShell_profile.ps1 # Auto-loads Rust + MSVC env on every shell\n```\n"
},
{
"path": "docker/Run-PsmuxDev.ps1",
"content": "<#\n.SYNOPSIS\n Build (if needed) and run the psmux-dev Docker container with SSH key auth.\n\n.DESCRIPTION\n - Generates an SSH keypair in ~/.ssh/psmux_docker_key (if not present)\n - Builds the psmux-dev image (if not present)\n - Starts the container with your public key injected\n - Prints the SSH command to connect\n\n.EXAMPLE\n pwsh -File docker\\Run-PsmuxDev.ps1\n pwsh -File docker\\Run-PsmuxDev.ps1 -Rebuild\n#>\nparam(\n [switch]$Rebuild\n)\n\n$ErrorActionPreference = \"Stop\"\n\n$imageName = \"psmux-dev\"\n$containerName = \"psmux-dev\"\n$keyPath = Join-Path $env:USERPROFILE \".ssh\\psmux_docker_key\"\n$pubKeyPath = \"$keyPath.pub\"\n$dockerDir = $PSScriptRoot # docker/ folder\n\n# ── 1. Generate SSH key if missing ──\nif (-not (Test-Path $keyPath)) {\n Write-Host \"Generating SSH key at $keyPath ...\"\n $sshDir = Split-Path $keyPath\n if (-not (Test-Path $sshDir)) { New-Item -ItemType Directory -Path $sshDir -Force | Out-Null }\n ssh-keygen -t ed25519 -f $keyPath -N \"\" -C \"psmux-docker\" -q\n Write-Host \" Key generated.\"\n} else {\n Write-Host \"Using existing SSH key: $keyPath\"\n}\n\n$pubKey = (Get-Content $pubKeyPath -Raw).Trim()\nWrite-Host \" Public key: $($pubKey.Substring(0, [Math]::Min(60, $pubKey.Length)))...\"\n\n# ── 2. Build image if needed ──\n$imageExists = docker images $imageName -q 2>$null\nif (-not $imageExists -or $Rebuild) {\n Write-Host \"\"\n Write-Host \"Building $imageName image (this takes a while on first run)...\"\n docker build -t $imageName $dockerDir\n if ($LASTEXITCODE -ne 0) { throw \"Docker build failed\" }\n}\n\n# ── 3. Remove old container if exists ──\n$existing = docker ps -aq -f \"name=$containerName\" 2>$null\nif ($existing) {\n Write-Host \"Removing existing container...\"\n docker rm -f $containerName 2>$null | Out-Null\n}\n\n# ── 4. Run container with public key ──\nWrite-Host \"Starting container...\"\ndocker run -d `\n --name $containerName `\n --isolation=hyperv `\n -e \"SSH_PUBLIC_KEY=$pubKey\" `\n $imageName | Out-Null\n\nif ($LASTEXITCODE -ne 0) { throw \"Docker run failed\" }\n\n# Wait for container to initialize\nWrite-Host \"Waiting for sshd to start...\"\nStart-Sleep 5\n\n# ── 5. Get container IP ──\n$containerIP = docker inspect $containerName --format \"{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}\"\nif (-not $containerIP) { throw \"Could not get container IP\" }\n\n# ── 6. Print connection info ──\nWrite-Host \"\"\nWrite-Host \"============================================\" -ForegroundColor Green\nWrite-Host \" psmux dev container is running\" -ForegroundColor Green\nWrite-Host \"============================================\" -ForegroundColor Green\nWrite-Host \"\"\nWrite-Host \" Connect:\" -ForegroundColor Cyan\nWrite-Host \" ssh -i ~/.ssh/psmux_docker_key -p 2222 ContainerAdministrator@$containerIP\"\nWrite-Host \"\"\nWrite-Host \" Quick build:\" -ForegroundColor Cyan\nWrite-Host \" git clone https://github.com/psmux/psmux.git\"\nWrite-Host \" cd psmux && cargo install --path .\"\nWrite-Host \"\"\nWrite-Host \" Stop:\" -ForegroundColor Cyan\nWrite-Host \" docker stop $containerName\"\nWrite-Host \"\"\nWrite-Host \" Restart:\" -ForegroundColor Cyan\nWrite-Host \" docker start $containerName\"\nWrite-Host \"\"\nWrite-Host \"============================================\" -ForegroundColor Green\n\n# ── 7. Verify SSH connectivity ──\nWrite-Host \"\"\nWrite-Host \"Testing SSH connection...\"\n$result = ssh -i $keyPath -o StrictHostKeyChecking=no -o UserKnownHostsFile=NUL -o ConnectTimeout=10 -p 2222 ContainerAdministrator@$containerIP \"hostname\" 2>$null\nif ($result) {\n Write-Host \" Connected to: $result\" -ForegroundColor Green\n} else {\n Write-Host \" SSH not ready yet — container may still be initializing.\" -ForegroundColor Yellow\n Write-Host \" Try manually: ssh -i ~/.ssh/psmux_docker_key -p 2222 ContainerAdministrator@$containerIP\"\n}\n"
},
{
"path": "docker/Tools/ImportVsDevEnv.ps1",
"content": "param(\n [string]$VsInstallPath = $env:VS_INSTALL_PATH\n)\n\n$ErrorActionPreference = \"Stop\"\n\n$vsDevCmd = Join-Path $VsInstallPath \"Common7\\Tools\\VsDevCmd.bat\"\nif (-not (Test-Path $vsDevCmd)) {\n throw \"VsDevCmd.bat not found: $vsDevCmd\"\n}\n\ncmd /c \"`\"$vsDevCmd`\" -arch=x64 -host_arch=x64 && set\" | ForEach-Object {\n if ($_ -match \"^(.*?)=(.*)$\") {\n Set-Item -Path \"Env:\\$($matches[1])\" -Value $matches[2]\n }\n}\n"
},
{
"path": "docker/Tools/InstallAll.ps1",
"content": "$ErrorActionPreference = \"Continue\"\n\n# ============================================\n# 0. Download everything first (before heavy installs use up disk/memory)\n# ============================================\nWrite-Host \"=== Downloading all installers ===\"\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\nWrite-Host \" Downloading Rust...\"\nInvoke-WebRequest https://win.rustup.rs -OutFile C:\\rustup-init.exe -UseBasicParsing\n\nWrite-Host \" Downloading VS Build Tools...\"\nInvoke-WebRequest https://aka.ms/vs/17/release/vs_BuildTools.exe -OutFile C:\\vs_BuildTools.exe -UseBasicParsing\n\nWrite-Host \" Downloading OpenSSH...\"\ntry {\n Invoke-WebRequest \"https://github.com/PowerShell/Win32-OpenSSH/releases/download/v9.8.3.0p2-Preview/OpenSSH-Win64.zip\" -OutFile C:\\openssh.zip -UseBasicParsing\n Write-Host \" OpenSSH downloaded: $((Get-Item C:\\openssh.zip).Length) bytes\"\n} catch {\n Write-Host \" OpenSSH download error: $($_.Exception.Message)\"\n exit 1\n}\n\nWrite-Host \" Downloading Git...\"\ntry {\n Invoke-WebRequest \"https://github.com/git-for-windows/git/releases/download/v2.47.1.windows.2/MinGit-2.47.1.2-64-bit.zip\" -OutFile C:\\git.zip -UseBasicParsing\n Write-Host \" Git downloaded: $((Get-Item C:\\git.zip).Length) bytes\"\n} catch {\n Write-Host \" Git download error: $($_.Exception.Message)\"\n exit 1\n}\n\nWrite-Host \"All downloads complete.\"\n\n# ============================================\n# 1. Install Rust\n# ============================================\nWrite-Host \"=== Installing Rust ===\" \nStart-Process -FilePath C:\\rustup-init.exe -ArgumentList \"-y\" -Wait\nRemove-Item C:\\rustup-init.exe -Force\n& C:\\cargo\\bin\\rustup.exe default stable-x86_64-pc-windows-msvc\n& C:\\cargo\\bin\\rustc.exe --version\n& C:\\cargo\\bin\\cargo.exe --version\n\n# ============================================\n# 2. Install Visual Studio Build Tools\n# ============================================\nWrite-Host \"=== Installing Visual Studio Build Tools ===\"\n$proc = Start-Process -FilePath C:\\vs_BuildTools.exe -ArgumentList @(\n \"--quiet\",\"--wait\",\"--norestart\",\"--nocache\",\n \"--installPath\",\"C:\\BuildTools\",\n \"--add\",\"Microsoft.VisualStudio.Workload.VCTools\",\n \"--add\",\"Microsoft.VisualStudio.Component.VC.Tools.x86.x64\",\n \"--add\",\"Microsoft.VisualStudio.Component.Windows10SDK.19041\"\n) -Wait -PassThru\nWrite-Host \"VS Build Tools exit code: $($proc.ExitCode)\"\nRemove-Item C:\\vs_BuildTools.exe -Force -ErrorAction SilentlyContinue\n\nif (-not (Test-Path \"C:\\BuildTools\\VC\\Tools\\MSVC\")) {\n throw \"MSVC toolset missing after install\"\n}\nWrite-Host \"VS Build Tools installed.\"\n\n# Clean up VS installer temp immediately to free disk space\nRemove-Item \"C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\*\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"C:\\ProgramData\\Package Cache\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"C:\\BuildTools\\Installer\" -Recurse -Force -ErrorAction SilentlyContinue\n\n# ============================================\n# 3. Install OpenSSH Server\n# ============================================\nWrite-Host \"=== Installing OpenSSH Server ===\"\nAdd-Type -AssemblyName System.IO.Compression.FileSystem\n[System.IO.Compression.ZipFile]::ExtractToDirectory(\"C:\\openssh.zip\", \"C:\\sshtmp\")\nRemove-Item C:\\openssh.zip -Force\n\n# Move extracted dir (OpenSSH-Win64) to C:\\OpenSSH\n$extracted = Get-ChildItem \"C:\\sshtmp\" -Directory | Select-Object -First 1\nif ($extracted) {\n Move-Item $extracted.FullName \"C:\\OpenSSH\" -Force\n} else {\n Move-Item \"C:\\sshtmp\" \"C:\\OpenSSH\" -Force\n}\nRemove-Item \"C:\\sshtmp\" -Recurse -Force -ErrorAction SilentlyContinue\n\nif (Test-Path \"C:\\OpenSSH\\sshd.exe\") {\n Write-Host \"OpenSSH Server installed to C:\\OpenSSH\"\n} else {\n throw \"sshd.exe not found after OpenSSH install\"\n}\n\n# ============================================\n# 4. Install Git\n# ============================================\nWrite-Host \"=== Installing Git ===\"\nExpand-Archive C:\\git.zip -DestinationPath C:\\git -Force\nRemove-Item C:\\git.zip -Force\n[Environment]::SetEnvironmentVariable(\"PATH\", \"C:\\git\\cmd;\" + [Environment]::GetEnvironmentVariable(\"PATH\",\"Machine\"), \"Machine\")\nWrite-Host \"Git installed.\"\n\n# ============================================\n# 5. Aggressive cleanup to avoid Docker layer commit failures\n# ============================================\nWrite-Host \"=== Cleanup ===\"\n# VS Build Tools installer caches and temp files with very long paths\nRemove-Item \"C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\*\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"$env:TEMP\\*\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"C:\\ProgramData\\Package Cache\" -Recurse -Force -ErrorAction SilentlyContinue\n# Remove VS installer metadata (keeps long path dirs)\nRemove-Item \"C:\\BuildTools\\Installer\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"C:\\ProgramData\\Microsoft\\VisualStudio\" -Recurse -Force -ErrorAction SilentlyContinue\n# Remove NuGet cache\nRemove-Item \"C:\\Users\\ContainerAdministrator\\.nuget\" -Recurse -Force -ErrorAction SilentlyContinue\n\nWrite-Host \"=== All installations complete ===\"\n"
},
{
"path": "docker/Tools/InstallGit.ps1",
"content": "$ErrorActionPreference = \"Stop\"\n\n$url = \"https://github.com/git-for-windows/git/releases/download/v2.47.1.windows.2/MinGit-2.47.1.2-64-bit.zip\"\n\nWrite-Host \"Downloading MinGit...\"\nInvoke-WebRequest $url -OutFile C:\\git.zip\n\nWrite-Host \"Extracting...\"\nExpand-Archive C:\\git.zip -DestinationPath C:\\git -Force\nRemove-Item C:\\git.zip -Force\n\n[Environment]::SetEnvironmentVariable(\"PATH\", \"C:\\git\\cmd;\" + [Environment]::GetEnvironmentVariable(\"PATH\", \"Machine\"), \"Machine\")\nWrite-Host \"Git installed.\"\n"
},
{
"path": "docker/Tools/InstallOpenSSH.ps1",
"content": "$ErrorActionPreference = \"Stop\"\n\n$url = \"https://github.com/PowerShell/Win32-OpenSSH/releases/download/v9.8.3.0p2-Preview/OpenSSH-Win64.zip\"\n\nWrite-Host \"Downloading Win32-OpenSSH...\"\nInvoke-WebRequest $url -OutFile C:\\openssh.zip -UseBasicParsing\n\nWrite-Host \"Extracting...\"\nAdd-Type -AssemblyName System.IO.Compression.FileSystem\n[System.IO.Compression.ZipFile]::ExtractToDirectory(\"C:\\openssh.zip\", \"C:\\sshtmp\")\nRemove-Item C:\\openssh.zip -Force\n\n$extracted = Get-ChildItem \"C:\\sshtmp\" -Directory | Select-Object -First 1\nif ($extracted) {\n Move-Item $extracted.FullName \"C:\\OpenSSH\" -Force\n} else {\n Move-Item \"C:\\sshtmp\" \"C:\\OpenSSH\" -Force\n}\nRemove-Item \"C:\\sshtmp\" -Recurse -Force -ErrorAction SilentlyContinue\n\nif (Test-Path \"C:\\OpenSSH\\sshd.exe\") {\n Write-Host \"OpenSSH Server installed to C:\\OpenSSH\"\n} else {\n throw \"sshd.exe not found after OpenSSH install\"\n}\n"
},
{
"path": "docker/Tools/InstallRust.ps1",
"content": "$ErrorActionPreference = \"Stop\"\n\nWrite-Host \"Downloading rustup...\"\nInvoke-WebRequest https://win.rustup.rs -OutFile C:\\rustup-init.exe\n\nWrite-Host \"Installing Rust...\"\nStart-Process -FilePath C:\\rustup-init.exe -ArgumentList \"-y\" -Wait\nRemove-Item C:\\rustup-init.exe -Force\n\n& C:\\cargo\\bin\\rustup.exe default stable-x86_64-pc-windows-msvc\n& C:\\cargo\\bin\\rustc.exe --version\n& C:\\cargo\\bin\\cargo.exe --version\nWrite-Host \"Rust installed.\"\n"
},
{
"path": "docker/Tools/InstallVsBuildTools.ps1",
"content": "$ErrorActionPreference = \"Stop\"\n\n$installPath = \"C:\\BuildTools\"\n$logFile = \"C:\\vsbuildtools-install.log\"\n\nWrite-Host \"Downloading Visual Studio Build Tools...\"\nInvoke-WebRequest https://aka.ms/vs/17/release/vs_BuildTools.exe -OutFile C:\\vs_BuildTools.exe\n\nWrite-Host \"Installing Visual Studio Build Tools (this takes a while)...\"\n$proc = Start-Process -FilePath C:\\vs_BuildTools.exe -ArgumentList @(\n \"--quiet\",\"--wait\",\"--norestart\",\"--nocache\",\n \"--installPath\", $installPath,\n \"--add\",\"Microsoft.VisualStudio.Workload.VCTools\",\n \"--add\",\"Microsoft.VisualStudio.Component.VC.Tools.x86.x64\",\n \"--add\",\"Microsoft.VisualStudio.Component.Windows10SDK.19041\"\n) -Wait -PassThru\n\nWrite-Host \"Installer exit code: $($proc.ExitCode)\"\n\nRemove-Item C:\\vs_BuildTools.exe -Force -ErrorAction SilentlyContinue\n\nif (-not (Test-Path \"$installPath\\VC\\Tools\\MSVC\")) {\n Write-Host \"Build Tools install FAILED.\"\n # Try to find log files\n Get-ChildItem \"C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\" -Filter \"dd_*.log\" -ErrorAction SilentlyContinue | ForEach-Object {\n Write-Host \"=== $($_.Name) (tail) ===\"\n Get-Content $_.FullName -Tail 50\n }\n throw \"MSVC toolset missing after install (exit code: $($proc.ExitCode))\"\n}\n\nWrite-Host \"Visual Studio Build Tools installed successfully.\"\n\n# Clean up installer temp files (extremely long paths break Docker layer commit)\nWrite-Host \"Cleaning up temp files...\"\nRemove-Item \"C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\*\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"$env:TEMP\\*\" -Recurse -Force -ErrorAction SilentlyContinue\n# Remove installer cache & logs\nRemove-Item \"C:\\ProgramData\\Package Cache\\*\" -Recurse -Force -ErrorAction SilentlyContinue\nRemove-Item \"C:\\BuildTools\\Installer\" -Recurse -Force -ErrorAction SilentlyContinue\nWrite-Host \"Cleanup done.\"\n"
},
{
"path": "docker/Tools/StartContainer.ps1",
"content": "$ErrorActionPreference = \"Stop\"\n\n$opensshDir = \"C:\\OpenSSH\"\n$sshdConfig = \"C:\\ProgramData\\ssh\\sshd_config\"\n$adminKeysFile = \"C:\\ProgramData\\ssh\\administrators_authorized_keys\"\n\n# ── Ensure critical system paths and OpenSSH are on PATH ──\n# (docker commit can lose System32 from PATH depending on how ENV was set)\n# Use exact-match check to avoid substring false positives (e.g. System32\\OpenSSH)\n$pathEntries = $env:PATH -split ';' | ForEach-Object { $_.TrimEnd('\\') }\nforeach ($p in @(\"C:\\Windows\\System32\", \"C:\\Windows\", $opensshDir, \"C:\\git\\cmd\")) {\n if ($p.TrimEnd('\\') -notin $pathEntries) { $env:PATH = \"$p;$env:PATH\" }\n}\n# Also persist to machine-level so SSH sessions inherit the full PATH\n[Environment]::SetEnvironmentVariable(\"PATH\", $env:PATH, \"Machine\")\n\n# ── Set default shell to PowerShell ──\nNew-Item -Path \"HKLM:\\SOFTWARE\\OpenSSH\" -Force | Out-Null\n$pwshPath = (Get-Command pwsh -ErrorAction SilentlyContinue).Source\nif (-not $pwshPath) { $pwshPath = \"C:\\Program Files\\PowerShell\\7\\pwsh.exe\" }\nNew-ItemProperty -Path \"HKLM:\\SOFTWARE\\OpenSSH\" -Name \"DefaultShell\" -Value $pwshPath -PropertyType String -Force | Out-Null\nNew-ItemProperty -Path \"HKLM:\\SOFTWARE\\OpenSSH\" -Name \"DefaultShellCommandOption\" -Value \"-c\" -PropertyType String -Force | Out-Null\n\n# ── Generate host keys if missing ──\nNew-Item -ItemType Directory -Path \"C:\\ProgramData\\ssh\" -Force | Out-Null\nif (-not (Test-Path \"C:\\ProgramData\\ssh\\ssh_host_ed25519_key\")) {\n & \"$opensshDir\\ssh-keygen.exe\" -A 2>$null\n}\n\n# ── Write sshd_config: key-only auth, port 2222 ──\n@\"\nPort 2222\nListenAddress 0.0.0.0\nHostKey C:/ProgramData/ssh/ssh_host_rsa_key\nHostKey C:/ProgramData/ssh/ssh_host_ecdsa_key\nHostKey C:/ProgramData/ssh/ssh_host_ed25519_key\nPasswordAuthentication no\nPubkeyAuthentication yes\nStrictModes no\nSubsystem sftp C:/OpenSSH/sftp-server.exe\n\nMatch Group administrators\n AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys\n\"@ | Set-Content -Path $sshdConfig -Encoding ascii\n\n# ── Install authorized public key ──\n# Accepts key via: SSH_PUBLIC_KEY env var, or mounted file at C:\\ssh_public_key\n$pubkey = $env:SSH_PUBLIC_KEY\nif (-not $pubkey -and (Test-Path \"C:\\ssh_public_key\")) {\n $pubkey = (Get-Content \"C:\\ssh_public_key\" -Raw).Trim()\n}\nif (-not $pubkey) {\n Write-Host \"\"\n Write-Host \"ERROR: No SSH public key provided.\" -ForegroundColor Red\n Write-Host \"Pass your public key via one of:\"\n Write-Host ' -e SSH_PUBLIC_KEY=\"ssh-ed25519 AAAA...\"'\n Write-Host ' -v C:\\Users\\you\\.ssh\\id_ed25519.pub:C:\\ssh_public_key'\n Write-Host \"\"\n exit 1\n}\n\nSet-Content -Path $adminKeysFile -Value $pubkey -Encoding ascii\n# Note: StrictModes is disabled in sshd_config, so we don't need to set\n# restrictive ACLs on administrators_authorized_keys. Setting ACLs via\n# icacls or Set-Acl crashes Hyper-V isolated containers.\n\n# ── Start sshd directly (not as a service) ──\n$sshdProc = Start-Process -FilePath \"$opensshDir\\sshd.exe\" `\n -ArgumentList \"-f\", $sshdConfig `\n -PassThru -WindowStyle Hidden\n\nStart-Sleep 2\nif ($sshdProc.HasExited) {\n Write-Host \"ERROR: sshd failed to start (exit code $($sshdProc.ExitCode))\" -ForegroundColor Red\n & \"$opensshDir\\sshd.exe\" -f $sshdConfig -d -d 2>&1 | Select-Object -First 20\n exit 1\n}\n\n# ── Print connection info ──\n# Get-NetIPAddress isn't available in windowsservercore containers; use .NET instead\n$ip = ([System.Net.Dns]::GetHostAddresses($env:COMPUTERNAME) |\n Where-Object { $_.AddressFamily -eq 'InterNetwork' -and $_.ToString() -ne '127.0.0.1' } |\n Select-Object -First 1).ToString()\nWrite-Host \"\"\nWrite-Host \"============================================\"\nWrite-Host \" psmux dev container ready\" -ForegroundColor Green\nWrite-Host \"============================================\"\nWrite-Host \" SSH : ssh -i ~/.ssh/psmux_docker_key -p 2222 ContainerAdministrator@$ip\"\nWrite-Host \" Rust : $(& rustc --version 2>$null)\"\nWrite-Host \" Cargo: $(& cargo --version 2>$null)\"\nWrite-Host \"============================================\"\nWrite-Host \"\"\nWrite-Host \"Quick start:\"\nWrite-Host \" git clone https://github.com/psmux/psmux.git\"\nWrite-Host \" cd psmux\"\nWrite-Host \" cargo install --path .\"\nWrite-Host \"\"\n\n# Keep container alive + restart sshd if it crashes\nwhile ($true) {\n Start-Sleep -Seconds 30\n if ($sshdProc.HasExited) {\n Write-Host \"sshd exited, restarting...\"\n $sshdProc = Start-Process -FilePath \"$opensshDir\\sshd.exe\" `\n -ArgumentList \"-f\", $sshdConfig `\n -PassThru -WindowStyle Hidden\n }\n}\n"
},
{
"path": "docs/claude-code.md",
"content": "# Claude Code Agent Teams\n\npsmux has first-class support for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agent teams. When Claude Code runs inside a psmux session, it automatically spawns teammate agents in separate tmux panes instead of running them in-process — giving you full visibility into what each agent is doing.\n\n## Prerequisites\n\n### PowerShell 7+\n\n[Install PowerShell 7 on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.6)\n\nTo work with Claude Code, psmux **requires PowerShell 7 or later**. The env shim and teammate mode injection rely on PowerShell 7+ features that are not available in the legacy Windows PowerShell 5.1.\n\nCheck your current version:\n\n```powershell\n$PSVersionTable.PSVersion\n```\n\nIf you are on an older version, install PowerShell 7+ via winget:\n\n```powershell\nwinget install --id Microsoft.PowerShell --source winget\n```\n\nAfter installation, restart your terminal and verify the version again.\n\n- `pwsh` will run the new version\n- `powershell` will still run the older legacy version as a fallback\n\nYou may need to restart VS Code for changes to the default terminal to take effect.\n\n> **Credit:** This prerequisite documentation was contributed by [@LiamKarlMitchell](https://github.com/LiamKarlMitchell) in [#184](https://github.com/psmux/psmux/pull/184) after discovering the PowerShell version requirement while troubleshooting [#173](https://github.com/psmux/psmux/issues/173).\n\n## Quick Start\n\n1. **Install psmux** (see [README](../README.md#installation))\n\n2. **Start a psmux session:**\n\n ```powershell\n psmux new-session -s work\n ```\n\n3. **Run Claude Code inside the psmux pane:**\n\n ```powershell\n claude\n ```\n\n4. **Ask Claude to create a team.** Claude Code will automatically split panes for each teammate agent.\n\nThat's it. No extra configuration needed — psmux handles everything automatically.\n\n## How It Works\n\nWhen a pane spawns inside psmux, several environment variables are set automatically:\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `TMUX` | `/tmp/psmux-{pid}/...` | Tells Claude Code it's inside tmux |\n| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `1` | Enables the agent teams feature gate |\n| `PSMUX_CLAUDE_TEAMMATE_MODE` | `tmux` | Triggers the `--teammate-mode tmux` CLI injection |\n\nClaude Code detects the `TMUX` environment variable, recognizes it's inside a tmux-compatible multiplexer, and uses the **TmuxBackend** to spawn teammate agents via `split-window` and `send-keys` — the same mechanism it uses on Linux/macOS tmux.\n\n### The Two Things psmux Fixes\n\nClaude Code's standalone binary (the Bun SFE `claude.exe`) has two issues on Windows that psmux works around:\n\n1. **Agent teams feature gate**: The entire teammate tool-set (spawnTeam, spawnTeammate) is gated behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Without this env var, Claude only has the in-process \"Agent\" tool and never creates separate panes. psmux sets this automatically.\n\n2. **`teammateMode` config ignored**: The standalone binary ignores `teammateMode: \"tmux\"` from `~/.claude/settings.json`. psmux injects `--teammate-mode tmux` via a PowerShell wrapper function that's loaded in every pane.\n\n## Configuration Options\n\nThese options can be set in `~/.psmux.conf` or at runtime:\n\n```tmux\n# Auto-inject --teammate-mode tmux for Claude Code (default: on)\nset -g claude-code-fix-tty on\n\n# Disable the Claude Code teammate-mode workaround\nset -g claude-code-fix-tty off\n```\n\n### What each option controls\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `claude-code-fix-tty` | `on` | Sets `PSMUX_CLAUDE_TEAMMATE_MODE=tmux` and defines a `claude` wrapper function that injects `--teammate-mode tmux` into every `claude` invocation |\n\nThe `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var is always set (not gated by any option) since it's required for the feature to work at all.\n\n## Two Agent Systems in Claude Code\n\nClaude Code has **two completely separate agent systems**. Understanding both is critical because psmux can only control one of them.\n\n### 1. Teammate Agents (tmux panes) ✅\n\nThe **teammate system** spawns agents in visible tmux panes. This is the system psmux fully supports.\n\n- Triggered when the model passes `team_name` + `name` to the subagent tool\n- Gated by `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (psmux sets this)\n- Controlled by `--teammate-mode tmux` (psmux injects this)\n- Each agent gets its own pane with full terminal visibility\n- Lower-tier models (Haiku, Sonnet) tend to prefer this path\n\n### 2. Worktree Agents (in-process, invisible) ⚠️\n\nThe **worktree system** creates isolated git worktrees and runs agents in-process — **invisible to the user**.\n\n- Triggered when the model passes `isolation: \"worktree\"` to the subagent tool\n- Creates git worktrees at `.claude/worktrees/agent-<id>/` via `git worktree add`\n- Each agent works on a separate branch in an isolated repo copy\n- Runs entirely in-process (no pane, no terminal output visible)\n- Higher-tier models (Opus) tend to prefer this path for git-level isolation\n- **On Windows, worktree tmux integration is hardcoded disabled** (`\"--tmux may not have effect on Windows when model chooses worktrees. Opus tends to always choose that.\"`)\n- There is **no env var or setting** to force worktree agents into tmux panes\n\n### Why Opus says \"Let me launch agents in worktrees\"\n\nBoth systems are exposed through the **same subagent tool**. The model chooses which to use:\n\n| Parameter | System | Visibility | Model preference |\n|-----------|--------|------------|-----------------|\n| `team_name` + `name` | Teammate | Visible tmux pane | Haiku, Sonnet |\n| `isolation: \"worktree\"` | Worktree | Invisible in-process | Opus |\n\nOpus prefers worktree agents because they provide **git-level isolation** — each agent works on its own branch and can't cause merge conflicts with other agents. The tradeoff is zero visibility.\n\n### Workaround: Project Instructions\n\nSince the model decides which system to use, you can influence its choice via `CLAUDE.md` project instructions:\n\n```markdown\n# Agent Configuration\nWhen spawning subagents, always use the teammate system (team_name + name parameters)\ninstead of worktree isolation. This ensures agents are visible in tmux panes.\nDo NOT use isolation: \"worktree\" — use teammates instead.\n```\n\nPlace this in your project's `CLAUDE.md` or `~/.claude/CLAUDE.md` for global effect. This is a **best-effort** approach — the model may still choose worktree isolation for complex parallel tasks.\n\n## Important: Interactive Mode Required\n\nAgent teams spawn in separate tmux panes only when Claude Code is running **interactively** (the default when you type `claude` in a pane). When using `-p` (pipe/print mode), Claude intentionally runs agents in-process since there's no interactive terminal to split.\n\n```powershell\n# ✅ Interactive — agents spawn in tmux panes\nclaude\n\n# ❌ Pipe mode — agents run in-process (by design)\nclaude -p \"do something\"\n```\n\n## Verifying the Setup\n\nTo confirm everything is configured correctly inside a psmux pane:\n\n```powershell\n# Check environment variables\nWrite-Host \"TMUX: $env:TMUX\"\nWrite-Host \"AGENT_TEAMS: $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\"\nWrite-Host \"TEAMMATE_MODE: $env:PSMUX_CLAUDE_TEAMMATE_MODE\"\n```\n\nExpected output:\n```\nTMUX: /tmp/psmux-{pid}/default,{port},0\nAGENT_TEAMS: 1\nTEAMMATE_MODE: tmux\n```\n\nYou can also verify the `claude` wrapper is active:\n\n```powershell\nGet-Command claude | Format-List\n```\n\nIf the wrapper is active, this shows a `Function` (not an `Application`). The wrapper auto-injects `--teammate-mode tmux` when calling `claude.exe`.\n\n## Troubleshooting\n\n### Agents still running in-process\n\n1. **Check you're in interactive mode** — not using `-p` or `--print`\n2. **Verify env vars** — run the verification commands above\n3. **Check debug log** — start Claude with `--debug-file $env:TEMP\\claude_debug.log` and look for:\n - `[TeammateModeSnapshot] Captured from CLI override: tmux` — teammate mode is set\n - `[BackendRegistry] isInProcessEnabled: false` — tmux panes will be used\n - `[BackendRegistry] isInProcessEnabled: true (non-interactive session)` — you're in pipe mode\n\n### Opus using \"worktree agents\" instead of tmux panes\n\nThis is expected behavior. Opus prefers `isolation: \"worktree\"` over the teammate system. These are two completely different agent systems — see [Two Agent Systems](#two-agent-systems-in-claude-code) above.\n\n**What you'll see:** Claude says \"Let me launch 3 implementation agents in worktrees\" — agents run invisibly, no panes appear.\n\n**Workaround:** Add a `CLAUDE.md` instruction telling the model to prefer teammates over worktree isolation. This is best-effort — the model ultimately decides.\n\n### Claude command not found\n\nMake sure `claude.exe` is on your PATH. Install via:\n```powershell\nnpm install -g @anthropic-ai/claude-code\n```\n\n### Wrapper not injecting `--teammate-mode`\n\nThe wrapper is only defined when `claude-code-fix-tty` is `on` (default). Check:\n```powershell\ntmux show-options -g claude-code-fix-tty\n```\n\n## Technical Details\n\nFor the curious — here's what happens under the hood when Claude Code spawns a teammate:\n\n1. Claude calls `spawnTeammate` tool (available because `T8()` gate passes due to `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)\n2. `BackendRegistry.detectAndGetBackend()` checks `isInProcessEnabled`:\n - If non-interactive → true → in-process (by design)\n - If interactive → checks `teammateMode` → `\"tmux\"` → false → uses TmuxBackend\n3. `TmuxBackend` runs `tmux split-window` via psmux's tmux compatibility\n4. Sends `cd <workdir> && claude.exe --agent-id <id> --agent-name <name> ...` via `tmux send-keys`\n5. The teammate agent starts in its own pane with full terminal access\n"
},
{
"path": "docs/compatibility.md",
"content": "# tmux Compatibility\n\npsmux is the most tmux-compatible terminal multiplexer on Windows.\n\n## Overview\n\n| Feature | Support |\n|---------|---------|\n| Commands | **83** tmux commands implemented |\n| Format variables | **140+** variables with full modifier support |\n| Config file | Reads `~/.tmux.conf` directly |\n| Key bindings | `bind-key`/`unbind-key` with key tables, case-sensitive |\n| Hooks | 15+ event hooks (`after-new-window`, etc.) with `set-hook`/`show-hooks` |\n| Status bar | Full format engine with conditionals, loops, and multi-line support |\n| Themes | 14 style options, 24-bit color, text attributes |\n| Layouts | 5 layouts (even-h, even-v, main-h, main-v, tiled) |\n| Copy mode | 53 vim keybindings, search, registers, rectangle select |\n| Targets | `session:window.pane`, `session:window_name`, `%id`, `@id` syntax |\n| `if-shell` / `run-shell` | ✅ Conditional config logic |\n| Paste buffers | ✅ Full buffer management |\n| Control mode | ✅ `-C` / `-CC` programmatic protocol |\n| Popups and menus | ✅ `display-popup`, `display-menu` |\n| Interactive choosers | ✅ `choose-tree`, `choose-buffer`, `choose-client` |\n| Server namespaces | ✅ `-L` for isolated instances |\n| Command chaining | ✅ Sequential `;` operator |\n| Nesting prevention | ✅ Blocks psmux inside psmux |\n| Session environment | ✅ `set-environment` / `show-environment` |\n\n**Your existing `.tmux.conf` works.** psmux reads it automatically. Just install and go.\n\n## Comparison\n\n| | psmux | Windows Terminal tabs | WSL + tmux |\n|---|:---:|:---:|:---:|\n| Session persist (detach/reattach) | ✅ | ❌ | ⚠️ WSL only |\n| Synchronized panes | ✅ | ❌ | ✅ |\n| tmux keybindings | ✅ | ❌ | ✅ |\n| Reads `.tmux.conf` | ✅ | ❌ | ✅ |\n| tmux theme support | ✅ | ❌ | ✅ |\n| Native Windows shells | ✅ | ✅ | ❌ |\n| Full mouse support | ✅ | ✅ | ⚠️ Partial |\n| Zero dependencies | ✅ | ✅ | ❌ (needs WSL) |\n| Scriptable (83 commands) | ✅ | ❌ | ✅ |\n| Claude Code agent teams | ✅ | ❌ | ✅ |\n| CJK/IME text input | ✅ | ✅ | ✅ |\n| Warm session pre-spawn | ✅ | N/A | ❌ |\n\n## Supported Commands\n\nFor the full list of supported tmux commands and arguments, see [tmux_args_reference.md](tmux_args_reference.md).\n\n## Recent Parity Improvements\n\nThis section covers tmux features that were recently brought to full parity.\n\n### Case-sensitive Key Bindings\n\nKey bindings now distinguish between lowercase and uppercase letters exactly like tmux. `bind-key T` binds to `Shift+T`, while `bind-key t` binds to lowercase `t`. This is critical for plugins like PPM (`Prefix+I` to install) and psmux-sensible (`Prefix+R` to reload).\n\n### Ctrl+Space as Prefix\n\n`set -g prefix C-Space` now works correctly. Previously, multi-character key names like `Space` were parsed as single character fallbacks.\n\n### Wrapped Directional Pane Navigation\n\nDirectional pane navigation (`select-pane -U/-D/-L/-R`) now wraps at layout edges, matching tmux behavior. Navigating past the rightmost pane wraps to the leftmost, and so on. Wrap is also correctly suppressed while zoomed.\n\n### Prefix Repeat Chaining\n\nAfter pressing the prefix key, successive keypresses within the `repeat-time` window (default 500ms) each trigger the bound action without needing to re-enter the prefix. This matches tmux's repeat behavior for pane navigation and resize bindings.\n\n### Switch Client\n\n`switch-client` is fully functional with all standard flags (`-t`, `-n`, `-p`, `-l`). Use it to programmatically switch between sessions.\n\n### Window Name Resolution in Targets\n\nTarget syntax now resolves window names, not just indices. `send-keys -t mysession:mywindow` correctly finds the window named \"mywindow\" in session \"mysession\".\n\n### Manual Rename Flag\n\n`new-window -n NAME` now sets the `manual_rename` flag, preventing `automatic-rename` from overwriting the explicitly specified window name with the foreground process name.\n\n### List Commands from Within Session\n\nCommands like `list-panes`, `list-windows`, `list-clients`, `list-commands`, and `show-hooks` now work when run from within a psmux session (via `Prefix + :`). Output is displayed in a temporary overlay.\n\n### Source File from Within Session\n\n`source-file` works from within a live session via `Prefix + :`. Previously, config changes only took effect after detaching and reattaching or killing the server.\n\n### Display Panes Overlay\n\n`display-panes` (and `Prefix + q`) now shows pane numbers briefly and auto-dismisses after `display-panes-time` (default 1s). Type a number during the overlay to switch to that pane.\n\n### Hook Deduplication\n\n`set-hook -g` now replaces existing hooks on reload instead of stacking duplicates. `set-hook -gu` correctly removes hooks.\n\n### Command Chaining with Semicolons\n\nMultiple commands can be chained with `;` on a single line, matching tmux behavior:\n\n```tmux\nbind-key M-s split-window -h \\; select-pane -L\n```\n\n### Run Shell Output\n\n`run-shell` now displays output in the status bar, matching tmux behavior. Background mode with `-b` runs fire and forget.\n\n### Session Server Persistence\n\nThe psmux session server now survives SSH disconnects. On reconnect, sessions are intact and `psmux attach` reattaches normally.\n\n### Bell and Alert Support\n\nBEL characters (`\\x07`) from programs are forwarded to your host terminal for audible beep. The `bell-action` option controls when bells are forwarded and when the status bar tab gets a bell flag.\n\n### Pane Border Labels with Truncation\n\n`pane-border-format` labels that exceed the pane width are now truncated with ellipsis instead of overflowing or clipping mid-character.\n\n### Pane Title Management\n\n`select-pane -T \"\"` correctly clears a pane title. The default pane title is the hostname, matching tmux convention. Programs can update the pane title via OSC 0/2 escape sequences (controlled by the `allow-set-title` option). See [pane-titles.md](pane-titles.md) for details on how this interacts with PowerShell and other shells.\n\n### Multi-line Status Bar\n\n`set -g status 2` enables a multi-line status bar with `status-format[0]` and `status-format[1]` fully rendering style directives like `#[fg=red]`, `#[align=left]`, and `#[fill=blue]`.\n\n### Status Bar Style Directives\n\nThe following inline style directives are now rendered correctly in status-format lines:\n\n- `#[list]` for the window list region\n- `#[fill=colour]` for background fill\n- `#[align=left|centre|right]` for text alignment\n- `#[range=...]` for click regions\n\n### Format Variable Expansion in Bindings\n\nThe `-F` flag on `bind-key` now properly expands format variables, enabling plugins like smart-splits.nvim to query pane dimensions.\n\n### Set Environment\n\n`set-environment` and `show-environment` are fully functional. Environment variables set with `set-environment -g` are inherited by all new panes at the process level (no shell commands echoed). The `new-session -e VAR=val` flag also sets session environment correctly.\n\n### Unbind All Keys\n\n`unbind-key -a` correctly removes all key bindings across all key tables. You can also target specific tables: `unbind-key -a -T prefix`, `unbind-key -a -T root`, `unbind-key -a -T copy-mode`.\n\n### Client Prefix Format Variable\n\nThe `#{client_prefix}` format variable is correctly set when the prefix key is pressed. This enables status bar indicators like:\n\n```tmux\nset -g status-right \"#{?client_prefix,#[bg=red] PREFIX ,}\"\n```\n\n### Window Zoomed Flag\n\nThe `#{window_zoomed_flag}` format variable is correctly maintained during zoom/unzoom operations.\n\n### Capture Pane\n\n`capture-pane -p` correctly outputs pane content to stdout, enabling scripts and integrations (including Claude Code agent team coordination) to read pane state.\n\n### Split Window Percentage\n\n`split-window -p <percent>` correctly creates splits at the specified percentage instead of defaulting to 50/50.\n\n### Split Window Working Directory\n\n`split-window -c \"#{pane_current_path}\"` correctly resolves the format variable and opens the new pane in the current pane's working directory.\n\n### UTF-8 and CJK Support\n\nMulti-byte UTF-8 characters (box-drawing, emoji, CJK text) render correctly in panes. Pasting CJK text no longer crashes the session. Japanese and Korean IME input is handled with minimal latency (the paste-detection heuristic was tuned to avoid misidentifying rapid IME bursts).\n\n## Format Variables\n\npsmux supports 140+ format variables with full modifier support, including:\n\n- Session/window/pane variables (`#S`, `#W`, `#P`, `#{pane_current_path}`, etc.)\n- Style and color modifiers\n- Conditional expressions (`#{?condition,true,false}`)\n- Comparison operators (`#{==:a,b}`, `#{!=:a,b}`, `#{<:a,b}`)\n- Logical operators (`#{||:a,b}`, `#{&&:a,b}`)\n- Regex substitution (`#{s/pat/rep/:var}`)\n- String operations: basename (`#{b:}`), dirname (`#{d:}`), lowercase (`#{l:}`), shell quote (`#{q:}`)\n- Truncation and padding (`#{=N:var}`, `#{pN:var}`)\n- Loop iteration over windows (`#{W:fmt}`), panes (`#{P:fmt}`), and sessions (`#{S:fmt}`)\n\n## Named Paste Buffers\n\npsmux supports named paste buffers, matching tmux behavior:\n\n```powershell\n# Set a named buffer\npsmux set-buffer -b mybuf \"hello world\"\n\n# Show a named buffer\npsmux show-buffer -b mybuf\n\n# Delete a named buffer\npsmux delete-buffer -b mybuf\n\n# Paste from a named buffer\npsmux paste-buffer -b mybuf\n```\n\nNamed buffers are separate from the default (anonymous) buffer stack. They persist for the lifetime of the session and can be used for inter-pane data exchange in scripts and automation workflows.\n\n## Developer Integration: Using psmux as a tmux Drop-in on Windows\n\npsmux implements the same CLI protocol as tmux. Any tool, library, or script that drives tmux via subprocess commands will work on psmux with minimal or zero changes. This section covers what developers need to know when integrating.\n\n### Same Protocol, Same Commands\n\npsmux accepts the same command syntax as tmux:\n\n```python\n# This code works identically with both tmux (Linux/macOS) and psmux (Windows)\nimport subprocess\n\ndef run_mux(cmd):\n binary = \"tmux\" # psmux installs a tmux.exe alias\n result = subprocess.run([binary] + cmd, capture_output=True, text=True)\n return result.stdout.strip()\n\n# All of these work on both platforms\nrun_mux([\"new-session\", \"-d\", \"-s\", \"work\"])\nrun_mux([\"list-sessions\"])\nrun_mux([\"send-keys\", \"-t\", \"work\", \"echo hello\", \"Enter\"])\nrun_mux([\"capture-pane\", \"-t\", \"work\", \"-p\"])\nrun_mux([\"list-windows\", \"-F\", \"#{window_id}:#{window_name}\"])\nrun_mux([\"kill-session\", \"-t\", \"work\"])\n```\n\nBecause psmux installs a `tmux.exe` alias, existing scripts that call `tmux` by name will find psmux on the PATH without any binary name changes.\n\n### Stable IDs: `$N`, `@N`, `%N`\n\npsmux uses the same stable ID scheme as tmux:\n\n| Prefix | Entity | Example |\n|--------|--------|---------|\n| `$` | Session | `$0`, `$1` |\n| `@` | Window | `@0`, `@1`, `@2` |\n| `%` | Pane | `%0`, `%1`, `%2` |\n\nThese IDs are monotonically increasing and never reused during a server's lifetime. Use them for reliable targeting:\n\n```powershell\n# Target by session ID\npsmux has-session -t \"$0\"\n\n# Target by window ID\npsmux select-window -t @2\n\n# Target by pane ID\npsmux send-keys -t %3 \"echo hello\" Enter\n\n# Compound targets work too\npsmux send-keys -t \"$0:@2.%3\" \"echo hello\" Enter\n```\n\n### Format Separator Encoding (Windows UTF-8)\n\nLibraries that parse format output from `list-sessions -F`, `list-windows -F`, or `list-panes -F` should be aware of encoding on Windows.\n\npsmux outputs UTF-8 encoded text. On Linux, tmux also outputs UTF-8, and most tools decode correctly because the system locale is UTF-8. On Windows, the default console code page is often cp1252 or cp437, not UTF-8.\n\nIf your library uses `subprocess.Popen(text=True)` in Python without specifying an encoding, Python will use the system default encoding (cp1252 on most Windows systems). This will garble any non-ASCII bytes in the output, including Unicode separator characters like U+241E that some libraries use internally.\n\n**Fix**: Always specify `encoding=\"utf-8\"` when reading psmux output:\n\n```python\nimport subprocess\n\nproc = subprocess.Popen(\n [\"psmux\", \"list-sessions\", \"-F\", \"#{session_name}\"],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n encoding=\"utf-8\", # Required on Windows\n errors=\"backslashreplace\"\n)\nstdout, stderr = proc.communicate()\n```\n\nAlternatively, set the `PYTHONUTF8=1` environment variable to make Python use UTF-8 everywhere:\n\n```powershell\n$env:PYTHONUTF8 = \"1\"\npython your_script.py\n```\n\n### libtmux Compatibility\n\n[libtmux](https://github.com/tmux-python/libtmux) is the most popular Python library for programmatically controlling tmux. psmux is compatible with libtmux's API because it implements the same CLI commands and output formats.\n\n#### Setup\n\n```powershell\npip install libtmux\n```\n\n#### Usage\n\n```python\nimport libtmux\n\n# Connect to the running psmux server\nserver = libtmux.Server(socket_name=\"default\")\n\n# List sessions\nfor session in server.sessions:\n print(f\"Session: {session.name} (ID: {session.id})\")\n\n# Get windows and panes\nsession = server.sessions[0]\nfor window in session.windows:\n print(f\" Window: {window.name} (ID: {window.id})\")\n for pane in window.panes:\n print(f\" Pane: {pane.id}\")\n\n# Create a new window\nnew_win = session.new_window(window_name=\"build\")\n\n# Send keys to a pane\npane = new_win.panes[0]\npane.send_keys(\"echo hello from libtmux\")\n\n# Capture pane content\noutput = pane.capture_pane()\nprint(output)\n\n# Kill the window\nnew_win.kill()\n```\n\n#### Windows Encoding Note for libtmux\n\nlibtmux internally uses a Unicode separator character (U+241E, `SYMBOL FOR RECORD SEPARATOR`) to split format query results. On Linux, this works transparently because tmux outputs UTF-8 and Python decodes with UTF-8.\n\nOn Windows, libtmux's `tmux_cmd` class uses `subprocess.Popen(text=True)` which defaults to cp1252 encoding. The 3-byte UTF-8 sequence for U+241E (0xE2 0x90 0x9E) gets decoded as three separate cp1252 characters, breaking the field parser.\n\n**Workaround**: Patch libtmux's `common.py` to add `encoding=\"utf-8\"` to the Popen call:\n\n```python\n# In libtmux/common.py, tmux_cmd.__init__\n# Change:\n# subprocess.Popen(cmd, stdout=PIPE, stderr=PIPE, text=True)\n# To:\nsubprocess.Popen(cmd, stdout=PIPE, stderr=PIPE, text=True, encoding=\"utf-8\", errors=\"backslashreplace\")\n```\n\nOr set `PYTHONUTF8=1` globally before importing libtmux. This is an upstream libtmux issue (it should specify encoding explicitly for cross-platform support) and not specific to psmux.\n\n### Cross-Platform Project Pattern\n\nFor projects that need terminal multiplexing on both Linux/macOS (tmux) and Windows (psmux):\n\n```python\nimport platform\nimport subprocess\n\ndef get_mux_binary():\n \"\"\"Get the terminal multiplexer binary for the current platform.\"\"\"\n # psmux installs a tmux.exe alias, so \"tmux\" works everywhere\n return \"tmux\"\n\ndef mux_run(args, **kwargs):\n \"\"\"Run a tmux/psmux command portably.\"\"\"\n binary = get_mux_binary()\n kwargs.setdefault(\"capture_output\", True)\n kwargs.setdefault(\"text\", True)\n if platform.system() == \"Windows\":\n kwargs.setdefault(\"encoding\", \"utf-8\")\n return subprocess.run([binary] + args, **kwargs)\n\ndef create_session(name, width=120, height=30):\n \"\"\"Create a detached session.\"\"\"\n return mux_run([\"new-session\", \"-d\", \"-s\", name, \"-x\", str(width), \"-y\", str(height)])\n\ndef send_keys(target, keys):\n \"\"\"Send keys to a target pane.\"\"\"\n return mux_run([\"send-keys\", \"-t\", target] + keys)\n\ndef capture_pane(target):\n \"\"\"Capture pane content.\"\"\"\n result = mux_run([\"capture-pane\", \"-t\", target, \"-p\"])\n return result.stdout\n\ndef list_sessions():\n \"\"\"List all sessions.\"\"\"\n result = mux_run([\"list-sessions\", \"-F\", \"#{session_name}\"])\n return result.stdout.strip().split(\"\\n\") if result.stdout.strip() else []\n\ndef kill_session(name):\n \"\"\"Kill a session.\"\"\"\n return mux_run([\"kill-session\", \"-t\", name])\n```\n\nThis pattern works identically on Linux (with tmux) and Windows (with psmux) because:\n\n1. psmux installs a `tmux.exe` alias, so the binary name is the same\n2. The CLI protocol (commands, flags, format strings) is identical\n3. Stable IDs (`$N`, `@N`, `%N`) follow the same scheme\n4. Control mode (`-C`/`-CC`) uses the same wire protocol\n\n### What About GUI/IDE Integrations?\n\nIf you are building an IDE plugin, VS Code extension, or GUI application that manages terminal sessions:\n\n1. **Use control mode** (`psmux -CC`) for persistent, event-driven integration. See [control-mode.md](control-mode.md).\n2. **Use `dump-state`** (psmux extension) to get the full session state as JSON, including screen content.\n3. **Query format variables** with `display-message -p \"#{var}\"` for lightweight state reads.\n4. **Set environment variables** with `set-environment -g KEY val` to pass configuration to child processes.\n5. **Use hooks** (`set-hook -g after-new-window ...`) to react to session events.\n6. **Use `wait-for`** for cross-pane synchronization in multi-step automation.\n\nFor a complete developer integration guide with examples in Python, PowerShell, Node.js, and more, see [integration.md](integration.md).\n"
},
{
"path": "docs/configuration.md",
"content": "# Configuration\n\npsmux reads its config on startup from the **first file found** (in order):\n\n1. `~/.psmux.conf`\n2. `~/.psmuxrc`\n3. `~/.tmux.conf`\n4. `~/.config/psmux/psmux.conf`\n\nConfig syntax is **tmux-compatible**. Most `.tmux.conf` lines work as-is.\n\nYou can also specify a custom config file path with the `-f` flag:\n\n```powershell\n# Use a specific config file instead of default search\npsmux -f ~/.config/psmux/custom.conf\n\n# Use an empty config (no settings loaded)\npsmux -f NUL\n```\n\nThis sets the `PSMUX_CONFIG_FILE` environment variable internally, which the server checks before searching the default locations.\n\n## Basic Config Example\n\nCreate `~/.psmux.conf`:\n\n```tmux\n# Change prefix key to Ctrl+a\nset -g prefix C-a\n\n# Enable mouse\nset -g mouse on\n\n# Window numbering base (default is 1)\nset -g base-index 1\n\n# Customize status bar\nset -g status-left \"[#S] \"\nset -g status-right \"%H:%M %d-%b-%y\"\nset -g status-style \"bg=green,fg=black\"\n\n# Cursor style: block, underline, or bar\nset -g cursor-style bar\nset -g cursor-blink on\n\n# Scrollback history\nset -g history-limit 5000\n\n# Prediction dimming (disable for apps like Neovim)\nset -g prediction-dimming off\n\n# Key bindings\nbind-key -T prefix h split-window -h\nbind-key -T prefix v split-window -v\n```\n\n## Choosing a Shell\n\npsmux launches **PowerShell 7 (pwsh)** by default. You can change this:\n\n```tmux\n# Use cmd.exe\nset -g default-shell cmd\n\n# Use PowerShell 5 (Windows built-in)\nset -g default-shell powershell\n\n# Use PowerShell 7 (explicit path)\nset -g default-shell \"C:/Program Files/PowerShell/7/pwsh.exe\"\n\n# Use Git Bash\nset -g default-shell \"C:/Program Files/Git/bin/bash.exe\"\n\n# Use Nushell\nset -g default-shell nu\n\n# Use Windows Subsystem for Linux (via wsl.exe)\nset -g default-shell wsl\n```\n\nYou can also launch a window with a specific command without changing the default:\n\n```powershell\npsmux new-window -- cmd /K echo hello\npsmux new-session -s py -- python\npsmux split-window -- \"C:/Program Files/Git/bin/bash.exe\"\n```\n\n## All Set Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `prefix` | Key | `C-b` | Prefix key |\n| `prefix2` | Key | `none` | Secondary prefix key (optional) |\n| `base-index` | Int | `0` | First window number |\n| `pane-base-index` | Int | `0` | First pane number |\n| `escape-time` | Int | `500` | Escape delay (ms) |\n| `repeat-time` | Int | `500` | Repeat key timeout (ms) |\n| `history-limit` | Int | `2000` | Scrollback lines per pane |\n| `display-time` | Int | `750` | Message display time (ms) |\n| `display-panes-time` | Int | `1000` | Pane overlay time (ms) |\n| `status-interval` | Int | `15` | Status refresh (seconds) |\n| `mouse` | Bool | `on` | Mouse support |\n| `mouse-selection` | Bool | `on` | psmux's client-side drag selection. Set `off` to let in-pane TUI apps (opencode, nvim, etc.) handle their own mouse selection without psmux drawing on top |\n| `scroll-enter-copy-mode` | Bool | `on` | Enter copy mode on mouse scroll (set `off` to disable) |\n| `pwsh-mouse-selection` | Bool | `off` | Windows 11 PowerShell-style word/line selection (double/triple-click) |\n| `paste-detection` | Bool | `on` | Detect Ctrl+V paste from console host and send as bracketed paste (set `off` to let Ctrl+V reach child apps like neovim) |\n| `choose-tree-preview` | Bool | `off` | Open `choose-session` / `choose-tree` pickers with the live preview pane already visible (saves pressing `p`). See [preview.md](preview.md) |\n| `status` | Bool/Int | `on` | Show status bar (number = line count) |\n| `status-position` | Str | `bottom` | `top` or `bottom` |\n| `status-justify` | Str | `left` | `left`, `centre`, `right`, `absolute-centre` |\n| `status-left-length` | Int | `10` | Max width of status-left |\n| `status-right-length` | Int | `40` | Max width of status-right |\n| `focus-events` | Bool | `off` | Pass focus events to apps |\n| `mode-keys` | Str | `emacs` | `vi` or `emacs` |\n| `renumber-windows` | Bool | `off` | Auto-renumber windows on close |\n| `automatic-rename` | Bool | `on` | Rename windows from foreground process |\n| `monitor-activity` | Bool | `off` | Flag windows with new output |\n| `monitor-silence` | Int | `0` | Seconds before silence flag (0=off) |\n| `visual-activity` | Bool | `off` | Visual indicator for activity |\n| `synchronize-panes` | Bool | `off` | Send input to all panes |\n| `remain-on-exit` | Bool | `off` | Keep panes after process exits |\n| `aggressive-resize` | Bool | `off` | Resize to smallest client |\n| `window-size` | Str | `latest` | `largest`, `smallest`, `manual`, `latest` |\n| `destroy-unattached` | Bool | `off` | Exit server when no clients attached |\n| `exit-empty` | Bool | `on` | Exit server when all windows closed |\n| `set-titles` | Bool | `off` | Update terminal title |\n| `set-titles-string` | Str | | Terminal title format |\n| `default-shell` | Str | `pwsh` | Shell to launch |\n| `default-command` | Str | | Alias for default-shell |\n| `word-separators` | Str | `\" -_@\"` | Copy-mode word delimiters |\n| `activity-action` | Str | `other` | Action on window activity: `any`, `none`, `current`, `other` |\n| `silence-action` | Str | `other` | Action on window silence: `any`, `none`, `current`, `other` |\n| `bell-action` | Str | `any` | Bell action: controls audible bell forwarding and status bar flag (`any`, `none`, `current`, `other`) |\n| `visual-bell` | Bool | `off` | Visual bell indicator |\n| `allow-passthrough` | Str | `off` | Allow terminal passthrough sequences (`on`/`off`/`all`) |\n| `allow-rename` | Bool | `on` | Allow programs to set window title via escape sequences |\n| `allow-set-title` | Bool | `off` | Allow programs to set pane title via OSC 0/2 escape sequences (see [pane-titles.md](pane-titles.md)) |\n| `allow-predictions` | Bool | `off` | Preserve PSReadLine prediction settings (see below) |\n| `default-terminal` | Str | | Terminal type string (sets `TERM` env var in panes) |\n| `update-environment` | Str | *(tmux defaults)* | Space-separated list of env vars to refresh on client attach |\n| `warm` | Bool | `on` | Pre-spawn shells for instant window/pane creation (see [warm-sessions.md](warm-sessions.md)) |\n| `copy-command` | Str | | Shell command for clipboard pipe |\n| `set-clipboard` | Str | `on` | Clipboard interaction (`on`/`off`/`external`) |\n| `main-pane-width` | Int | `0` | Main pane width in main-vertical layout |\n| `main-pane-height` | Int | `0` | Main pane height in main-horizontal layout |\n\n### Style Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `status-left` | Str | `[#S] ` | Left status bar content |\n| `status-right` | Str | | Right status bar content |\n| `status-style` | Str | `bg=green,fg=black` | Status bar style |\n| `status-left-style` | Str | | Left status style |\n| `status-right-style` | Str | | Right status style |\n| `message-style` | Str | `bg=yellow,fg=black` | Message style |\n| `message-command-style` | Str | `bg=black,fg=yellow` | Command prompt style |\n| `mode-style` | Str | `bg=yellow,fg=black` | Copy-mode highlight |\n| `pane-border-style` | Str | | Inactive border style |\n| `pane-active-border-style` | Str | `fg=green` | Active border style |\n| `pane-border-format` | Str | | Pane border format string (e.g. `#{pane_index}: #{pane_title}`) |\n| `pane-border-status` | Str | | Pane border status position (`top`/`bottom`/`off`) |\n| `window-status-format` | Str | `#I:#W#F` | Inactive tab format |\n| `window-status-current-format` | Str | `#I:#W#F` | Active tab format |\n| `window-status-separator` | Str | `\" \"` | Tab separator |\n| `window-status-style` | Str | | Inactive tab style |\n| `window-status-current-style` | Str | | Active tab style |\n| `window-status-activity-style` | Str | `reverse` | Activity tab style |\n| `window-status-bell-style` | Str | `reverse` | Bell tab style |\n| `window-status-last-style` | Str | | Last-active tab style |\n\n### Multi-line Status Bar (`status-format[]`)\n\npsmux supports a multi-line status bar using the `status-format[]` array. Set the `status` option to a number to control how many lines the status bar displays:\n\n```tmux\n# Enable a 2-line status bar\nset -g status 2\n\n# Configure each line (0-indexed)\nset -g status-format[0] \"#[align=left]#S #[align=right]%H:%M\"\nset -g status-format[1] \"#[align=left]#{W:#I:#W }\"\n```\n\nThe first line (`status-format[0]`) replaces the default status bar content. Additional lines stack below (or above, depending on `status-position`).\n\n### Pane Border Labels\n\nShow pane information on the border between panes:\n\n```tmux\n# Enable pane border labels at the top of each pane\nset -g pane-border-status top\n\n# Customize what the label shows\nset -g pane-border-format \" #{pane_index}: #{pane_title} [#{pane_current_command}] \"\n\n# Disable pane border labels\nset -g pane-border-status off\n```\n\nUse `select-pane -T \"title\"` to set a pane title that appears in the border label. Clear a title with `select-pane -T \"\"`. The default pane title is the hostname, matching tmux convention.\n\n> **Note:** PowerShell 7 automatically sets the pane title to the current working directory on every prompt via OSC escape sequences. If you see a file path in your pane border labels instead of the hostname, see [pane-titles.md](pane-titles.md) for details and options to control this.\n\n### Bell\n\nWhen a program inside a pane emits BEL (`\\x07`), psmux forwards the bell character to your host terminal so you hear the audible beep. The `bell-action` option controls when this happens and when the status bar tab gets a bell flag (`!`):\n\n```tmux\n# Forward bell from any window (default)\nset -g bell-action any\n\n# Forward bell only from the active window\nset -g bell-action current\n\n# Forward bell only from non-active windows\nset -g bell-action other\n\n# Mute bell completely (no sound, no status bar flag)\nset -g bell-action none\n```\n\nThe `window-status-bell-style` option controls how the tab looks when flagged:\n\n```tmux\nset -g window-status-bell-style \"fg=red,bold\"\n```\n\nPowerShell example to test:\n\n```powershell\n# These should all produce an audible beep inside psmux:\nWrite-Host \"`a\"\n[Console]::Beep()\n[char]7\n```\n\n### Mouse Configuration\n\nMouse support is enabled by default. You can customize how the mouse interacts with psmux:\n\n```tmux\n# Disable mouse entirely (no click, scroll, or drag)\nset -g mouse off\n\n# Disable entering copy mode on mouse scroll\nset -g scroll-enter-copy-mode off\n\n# Enable Windows 11 PowerShell-style word/line selection\n# Double-click selects a word, triple-click selects a line\nset -g pwsh-mouse-selection on\n```\n\nWhen `scroll-enter-copy-mode` is `off`, scrolling in a pane does not enter copy mode and instead passes scroll events directly to the running application.\n\n#### Disabling psmux's drag selection (`mouse-selection`)\n\nSome TUI applications render their own internal layouts (multiple columns, sidebars, panels) inside a single psmux pane. Examples include `opencode`, `lazygit`, `nvim` with split windows, and similar dashboards.\n\npsmux's own client-side drag selection does not know about those internal layouts, so a left-click drag inside such an app draws a selection rectangle that crosses the app's internal columns instead of respecting them.\n\nIf you would rather have the application handle mouse selection itself, disable psmux's drag selection:\n\n```tmux\n# Let the app inside the pane handle its own mouse selection.\n# psmux will no longer render its drag-selection rectangle.\nset -g mouse-selection off\n```\n\nWhat still works when `mouse-selection` is `off`:\n\n- Click on a pane to focus it\n- Click on a window tab in the status bar to switch to it\n- Mouse wheel scrolling and scroll-into-copy-mode\n- Pane border drag-to-resize\n- Mouse events being forwarded to applications that request mouse tracking (DECSET 1000/1002/1003), so `opencode`, `htop`, `nvim`, `claude`, etc. continue to receive their clicks and drags\n\nWhat changes when `mouse-selection` is `off`:\n\n- psmux no longer draws its own selection rectangle on left-click drag\n- Right-click clipboard copy via psmux's selection is no longer triggered (selection never starts)\n- The Windows 11 style word/line multi-click (`pwsh-mouse-selection`) is suppressed too while `mouse-selection off` is in effect\n\nTo restore the default behaviour:\n\n```tmux\nset -g mouse-selection on\n```\n\nYou can also toggle this at runtime without restarting:\n\n```\npsmux set-option -g mouse-selection off\npsmux set-option -g mouse-selection on\n```\n\nThis option is independent of `mouse` (which controls whether mouse events are received at all) and `pwsh-mouse-selection` (which only affects the style of the drag selection when it is active).\n\n### Paste Detection (Ctrl+V Passthrough)\n\nOn Windows, the console host intercepts Ctrl+V, reads the clipboard, and injects the content as character events. psmux detects this pattern and reassembles it into a single bracketed paste for child applications. This is the `paste-detection` option and it is enabled by default.\n\nIf you use TUI applications like **neovim** or **vim** where Ctrl+V has a different meaning (visual block mode), the paste detection will intercept the keypress before it reaches the application. To let Ctrl+V pass through to the child app:\n\n```tmux\n# Disable paste detection so Ctrl+V reaches child apps\nset -g paste-detection off\n```\n\nWith paste detection off, you can still paste using:\n\n* **Ctrl+Shift+V** (Windows Terminal default paste shortcut)\n* **Right click** (paste in most terminals)\n* **Prefix + ]** (psmux paste from buffer)\n* **`psmux send-keys C-v`** from another terminal\n\n> **Note:** `unbind-key -n C-v` alone is not sufficient to stop Ctrl+V interception because the paste detection operates outside the key binding system. You must use `set -g paste-detection off`.\n\n### Live Preview in Choosers\n\n`choose-session` (prefix + s) and `choose-tree` (prefix + w) include a live preview pane that mirrors the selected session or window in real time. By default it is hidden and you press `p` to toggle it. To make it visible by default:\n\n```tmux\n# Open all choosers with the preview pane already visible\nset -g choose-tree-preview on\n```\n\nYou can still press `p` inside the chooser to hide it for the current session. The setting is read once when the chooser opens, so changes to the option take effect immediately on the next open. See [preview.md](preview.md) for the full feature documentation.\n\n### Command Chaining\n\npsmux supports tmux-style command chaining with the `;` operator. Multiple commands on a single line are executed sequentially:\n\n```tmux\n# Split and move focus in one binding\nbind-key M-s split-window -h \\; select-pane -L\n\n# Create a development layout\nbind-key D split-window -v -p 30 \\; split-window -h \\; select-pane -t 0\n```\n\nIn config files, escape the semicolon with `\\;` so it is not treated as a comment delimiter.\n\n### Case-Sensitive Key Bindings\n\npsmux distinguishes between lowercase and uppercase letters in key bindings, matching tmux behavior:\n\n```tmux\n# These are two different bindings:\nbind-key t clock-mode # Prefix + t (lowercase)\nbind-key T choose-tree # Prefix + Shift+T (uppercase)\n\n# Uppercase bindings for plugin managers\nbind-key I run-shell '~/.psmux/plugins/ppm/scripts/install_plugins.ps1'\nbind-key U run-shell '~/.psmux/plugins/ppm/scripts/update_plugins.ps1'\n```\n\n### Ctrl+Space as Prefix\n\nMulti-character key names like `Space`, `Enter`, `Tab`, and `Escape` are fully supported in prefix configuration:\n\n```tmux\nset -g prefix C-Space\nunbind-key C-b\nbind-key C-Space send-prefix\n```\n\n### psmux Extensions (Windows-specific)\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `prediction-dimming` | Bool | `off` | Dim predictive/speculative text |\n| `paste-detection` | Bool | `on` | Detect Ctrl+V paste from console host (set `off` for neovim/vim Ctrl+V) |\n| `cursor-style` | Str | | Cursor shape: `block`, `underline`, or `bar` |\n| `cursor-blink` | Bool | `off` | Cursor blinking |\n| `env-shim` | Bool | `on` | Inject Unix-compatible `env` function in PowerShell panes |\n| `claude-code-fix-tty` | Bool | `on` | Patch Node.js process.stdout.isTTY for Claude Code |\n| `claude-code-force-interactive` | Bool | `on` | Set CLAUDE_CODE_FORCE_INTERACTIVE=1 in panes |\n\nStyle format: `\"fg=colour,bg=colour,bold,dim,underscore,italics,reverse,strikethrough\"`\n\nColours: `default`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `colour0`–`colour255`, `#RRGGBB`\n\n## Environment Variables\n\n```powershell\n# Default session name used when not explicitly provided\n$env:PSMUX_DEFAULT_SESSION = \"work\"\n\n# Enable prediction dimming (off by default; dims predictive/speculative text)\n$env:PSMUX_DIM_PREDICTIONS = \"1\"\n\n# Disable warm pane pre-spawning (same as set -g warm off)\n$env:PSMUX_NO_WARM = \"1\"\n\n# Override the config file path (same effect as -f flag)\n$env:PSMUX_CONFIG_FILE = \"C:\\Users\\me\\.psmux-alt.conf\"\n\n# These are set INSIDE psmux panes (tmux-compatible):\n# TMUX - socket path and server info\n# TMUX_PANE - current pane ID (%0, %1, etc.)\n```\n\n## Managing Environment Variables\n\nUse `set-environment` to set env vars that are inherited by newly created panes:\n\n```powershell\n# Set a global env var (inherited by all new panes)\npsmux set-environment -g EDITOR vim\n\n# Set a session-scoped env var\npsmux set-environment MY_VAR value\n\n# Unset an env var\npsmux set-environment -gu MY_VAR\n\n# Show all environment variables\npsmux show-environment\npsmux show-environment -g\n```\n\nEnvironment variables set this way are injected at the process level when new panes spawn, so they are completely invisible (no commands echoed in the shell).\n\n## PSReadLine Predictions (Intellisense / Autocompletion)\n\nBy default, psmux disables PSReadLine inline predictions (the grayed-out autocompletion/intellisense suggestions that appear as you type) to avoid additional unexpected bugs caused by the interaction between predictions and ConPTY. This means `PredictionSource` defaults to `None` inside psmux, even if your profile sets it to `HistoryAndPlugin` ([#150](https://github.com/psmux/psmux/issues/150)).\n\nIf enough people test predictions and the community supports enabling them by default, this will be changed in a future release.\n\nTo preserve your prediction/autocompletion settings, enable `allow-predictions`:\n\n```tmux\nset -g allow-predictions on\n```\n\nWith this enabled:\n- If your profile sets `PredictionSource`, psmux respects your choice\n- If your profile does not set it, psmux restores the system default (typically `HistoryAndPlugin`)\n\n## Prediction Dimming\n\nPrediction dimming is off by default. If you want psmux to dim predictive/speculative text (e.g. shell autosuggestions), you can enable it in `~/.psmux.conf`:\n\n```tmux\nset -g prediction-dimming on\n```\n\nYou can also enable it for the current shell only:\n\n```powershell\n$env:PSMUX_DIM_PREDICTIONS = \"1\"\npsmux\n```\n\nTo make it persistent for new shells:\n\n```powershell\nsetx PSMUX_DIM_PREDICTIONS 1\n```\n\n## Reloading Configuration at Runtime\n\nYou can reload your config file without restarting psmux. From the command prompt (`Prefix + :`), run:\n\n```tmux\nsource-file ~/.psmux.conf\n```\n\nOr from outside psmux:\n\n```powershell\npsmux source-file ~/.psmux.conf\n```\n\nThis re-executes every line in the config file, applying any changes to options, key bindings, hooks, and styles immediately.\n\n## Window and Pane Numbering\n\nBy default, windows and panes are numbered starting from 0. You can change the starting index for both:\n\n```tmux\n# Start window numbering at 1\nset -g base-index 1\n\n# Start pane numbering at 1\nset -g pane-base-index 1\n```\n\nThe `pane-base-index` setting affects:\n\n- **Display Panes overlay** (`Prefix + q`): The numbers shown on each pane start from your configured base index\n- **Pane targets**: When referencing panes by number (e.g. `select-pane -t 1`), numbering follows your base index\n- **Format variables**: `#{pane_index}` reflects the base index setting\n- **Status bar and border labels**: Pane numbers in format strings use the configured base\n\nA common setup for both windows and panes to start at 1:\n\n```tmux\nset -g base-index 1\nset -g pane-base-index 1\n```\n\n## Display Panes Overlay\n\nPress `Prefix + q` to show numbered overlays on each pane. While the overlay is visible, press any displayed number key to jump to that pane. The overlay auto-dismisses after `display-panes-time` milliseconds (default: 1000ms).\n\n```tmux\n# Show pane numbers for 3 seconds\nset -g display-panes-time 3000\n```\n\nThe numbers shown respect your `pane-base-index` setting. For example, with `pane-base-index 1`, three panes show as 1, 2, 3 instead of 0, 1, 2.\n\nYou can also trigger this overlay from the command line:\n\n```powershell\npsmux display-panes\n```\n\n## Split Window Options\n\nWhen splitting panes, you can control the size and starting directory of the new pane:\n\n```tmux\n# Split vertically, new pane takes 30% of the space\nsplit-window -v -p 30\n\n# Split horizontally, new pane takes 70% of the space\nsplit-window -h -p 70\n\n# Split and start in a specific directory\nsplit-window -v -c \"C:\\Projects\\myapp\"\n\n# Split and start in the current pane's directory\nsplit-window -h -c \"#{pane_current_path}\"\n\n# Split and run a specific command\nsplit-window -v -- python\n```\n\nThese flags also work when creating new windows:\n\n```tmux\n# New window with a specific name\nnew-window -n \"logs\"\n\n# New window in a specific directory\nnew-window -c \"C:\\Projects\"\n\n# New window running a specific command with a name\nnew-window -n \"build\" -- cargo build --watch\n```\n\nWhen you set a window name with `-n`, the `automatic-rename` flag is turned off for that window so psmux does not overwrite your chosen name with the foreground process name. To re-enable automatic renaming for that window:\n\n```tmux\nset-option -w automatic-rename on\n```\n\n## Detach and Exit Policies\n\nControl what happens when clients disconnect or all windows close:\n\n```tmux\n# Exit the server when no clients are attached (default: off)\nset -g destroy-unattached on\n\n# Exit the server when the last window/session closes (default: on)\nset -g exit-empty on\n```\n\nWith `destroy-unattached on`, the server process terminates as soon as the last client detaches. This is useful for single-use sessions.\n\nWith `exit-empty off`, the server stays alive even after all sessions are closed, allowing new sessions to be created without restarting.\n\n## Dead Panes and Respawn\n\nWhen a process inside a pane exits, the pane normally closes. To keep the pane visible after its process exits:\n\n```tmux\nset -g remain-on-exit on\n```\n\nA pane with a dead process shows its last output and can be respawned:\n\n```powershell\n# Restart the default shell in the pane\npsmux respawn-pane\n\n# Kill any remaining process and restart\npsmux respawn-pane -k\n\n# Respawn in a different directory\npsmux respawn-pane -c \"C:\\Projects\"\n\n# Respawn with a specific command\npsmux respawn-pane -- python app.py\n```\n\nThis is useful for monitoring: if a long-running process crashes, you can see its final output and restart it without losing the pane layout.\n\n## Session Environment Variables\n\nYou can set environment variables at the session or global level that get inherited by all new panes:\n\n```powershell\n# Set a global env var (all new panes in all sessions inherit this)\npsmux set-environment -g EDITOR vim\n\n# Set a session-scoped env var\npsmux set-environment MY_VAR value\n\n# Unset a global env var\npsmux set-environment -gu MY_VAR\n\n# View all environment variables\npsmux show-environment\npsmux show-environment -g\n```\n\nYou can also pass environment variables when creating a new session:\n\n```powershell\n# Create a session with custom environment\npsmux new-session -s work -e \"PROJECT=myapp\" -e \"ENV=production\"\n```\n\n## Status Bar Time Updates\n\nThe status bar supports time format variables that update in real time:\n\n```tmux\n# Show current time in the status bar (updates every second)\nset -g status-right \"%H:%M:%S %d-%b-%y\"\n\n# Common time format variables:\n# %H Hour (24-hour, 00-23)\n# %I Hour (12-hour, 01-12)\n# %M Minute (00-59)\n# %S Second (00-59)\n# %p AM/PM\n# %r Full time in 12-hour format (e.g. 02:30:45 PM)\n# %R Hour:Minute in 24-hour format (e.g. 14:30)\n# %d Day of month (01-31)\n# %b Abbreviated month name (Jan, Feb, ...)\n# %Y Full year (2025)\n# %a Abbreviated weekday (Mon, Tue, ...)\n```\n\nTime variables refresh based on the `status-interval` option (default: 15 seconds). For second-level precision, reduce the interval:\n\n```tmux\n# Update status bar every second (for live clock)\nset -g status-interval 1\n```\n\n## PSReadLine ListView\n\npsmux supports PSReadLine's ListView prediction style, which shows a dropdown list of suggestions:\n\n```powershell\n# In your PowerShell profile ($PROFILE)\nSet-PSReadLineOption -PredictionSource HistoryAndPlugin\nSet-PSReadLineOption -PredictionViewStyle ListView\n```\n\nFor this to work inside psmux, enable `allow-predictions` in your psmux config:\n\n```tmux\nset -g allow-predictions on\n```\n\nWithout `allow-predictions on`, psmux resets PSReadLine's prediction settings during initialization, which disables ListView mode.\n"
},
{
"path": "docs/control-mode.md",
"content": "# Control Mode\n\nControl mode lets external programs drive psmux programmatically over a structured text protocol. Instead of rendering a TUI, psmux sends machine-readable notifications and accepts commands over stdin/stdout, making it the foundation for building plugins, IDE integrations, custom dashboards, session monitors, and any tooling that needs to interact with terminal sessions.\n\nThis is the same protocol that tmux uses for its control mode (`tmux -C` / `tmux -CC`), so existing knowledge and many client libraries transfer directly to psmux.\n\n## Quick Start\n\n```powershell\n# 1. Create a detached session\npsmux new-session -d -s work -x 120 -y 30\n\n# 2. Attach in control mode (no-echo)\npsmux -CC\n```\n\npsmux connects to the running session and enters a command/response loop. You type commands on stdin, and psmux responds on stdout with structured output.\n\n```\nlist-windows\n%begin 1700000000 1 1\n0: pwsh* (1 panes) [120x30]\n%end 1700000000 1 1\n```\n\nTo exit, close stdin (Ctrl+D / EOF) or send `kill-server`.\n\n## Flags\n\n| Flag | Mode | Behavior |\n|------|------|----------|\n| `-C` | Echo | Commands you send are echoed back to stdout before the response. Useful for debugging and interactive testing. |\n| `-CC` | No-echo | Commands are not echoed. This is the mode you want for programmatic use. In this mode, `%exit` is followed by an ST sequence (`ESC \\`). |\n\n## Session Targeting\n\nBy default, control mode connects to the session stored in `PSMUX_SESSION_NAME`. You can set it before launching:\n\n```powershell\n$env:PSMUX_SESSION_NAME = \"my-session\"\npsmux -CC\n```\n\n## Wire Protocol\n\n### Command/Response Framing\n\nEvery command you send gets a response wrapped in `%begin` / `%end` (or `%error`) markers:\n\n```\n<your command>\n%begin <timestamp> <command_number> <flags>\n<response lines>\n%end <timestamp> <command_number> <flags>\n```\n\n| Field | Description |\n|-------|-------------|\n| `timestamp` | Unix epoch seconds when the command was processed |\n| `command_number` | Sequential counter (1, 2, 3, ...) for each command in the session |\n| `flags` | Reserved, always `1` |\n\nThe `%begin` and `%end` lines always share the same timestamp, command number, and flags. If a command fails, the closing frame is `%error` instead of `%end`:\n\n```\nnonexistent-command\n%begin 1700000000 1 1\nunknown command: nonexistent-command\n%error 1700000000 1 1\n```\n\nCommand response blocks never interleave with each other. Notifications (described below) arrive between command blocks, never inside them.\n\n### Notifications\n\nNotifications are asynchronous lines that psmux sends whenever something happens in the session. They always start with `%` and arrive between command response blocks.\n\n#### Window Notifications\n\n| Notification | Meaning |\n|---|---|\n| `%window-add @<WID>` | A new window was created |\n| `%window-close @<WID>` | A window was destroyed |\n| `%window-renamed @<WID> <name>` | A window was renamed |\n| `%window-pane-changed @<WID> %<PID>` | The active pane in a window changed |\n| `%layout-change @<WID> <layout> <visible_layout> <flags>` | A window's pane layout changed (split, resize, etc.) |\n\n#### Session Notifications\n\n| Notification | Meaning |\n|---|---|\n| `%session-changed $<SID> <name>` | The attached session changed |\n| `%session-renamed <name>` | The current session was renamed |\n| `%session-window-changed $<SID> @<WID>` | The active window in a session changed |\n| `%sessions-changed` | A session was created or destroyed |\n\n#### Pane Output\n\n| Notification | Meaning |\n|---|---|\n| `%output %<PID> <escaped_data>` | A pane produced output |\n| `%pane-mode-changed %<PID>` | A pane entered or exited a special mode (e.g. copy mode) |\n\n#### Flow Control\n\n| Notification | Meaning |\n|---|---|\n| `%pause %<PID>` | Output for this pane has been paused (client is too far behind) |\n| `%continue %<PID>` | Output for this pane has resumed |\n\n#### Client and Buffer\n\n| Notification | Meaning |\n|---|---|\n| `%client-detached <client>` | A client disconnected from the session |\n| `%client-session-changed <client> $<SID> <name>` | Another client changed its attached session |\n| `%paste-buffer-changed <name>` | A paste buffer was modified |\n| `%paste-buffer-deleted <name>` | A paste buffer was deleted |\n| `%message <text>` | A status message was generated (e.g. from `display-message`) |\n\n#### Exit\n\n| Notification | Meaning |\n|---|---|\n| `%exit` | The control client is disconnecting. In `-CC` mode, followed by `ESC \\` (ST sequence). |\n| `%exit <reason>` | Disconnecting with a reason (e.g. `too far behind`). |\n\n### ID Formats\n\nAll IDs are stable, monotonically increasing integers that never get reused during a server's lifetime:\n\n| Prefix | Entity | Example |\n|--------|--------|---------|\n| `$` | Session | `$0` |\n| `@` | Window | `@0`, `@1`, `@2` |\n| `%` | Pane | `%0`, `%1`, `%2` |\n\n### Output Escaping\n\nData in `%output` notifications uses octal escaping for non-printable bytes:\n\n| Byte | Encoding |\n|------|----------|\n| Printable ASCII (0x20 to 0x7E) | Passed through as-is |\n| Tab (0x09) | Passed through as-is |\n| Backslash (0x5C) | `\\\\` (doubled) |\n| Carriage return (0x0D) | `\\015` |\n| Line feed (0x0A) | `\\012` |\n| Any other byte | `\\NNN` (3-digit octal) |\n\nExample: `hello\\r\\n` becomes `%output %0 hello\\015\\012`.\n\n## Supported Commands\n\nAll standard psmux/tmux commands work in control mode. Here are the most useful ones for plugin development:\n\n### Session and Window Management\n\n```\nnew-window # Create a new window\nnew-window -n editor # Create a named window\nsplit-window -v # Split vertically\nsplit-window -h # Split horizontally\nkill-pane # Kill the active pane\nkill-window # Kill the active window\nselect-window -t 1 # Switch to window 1\nselect-pane -t %3 # Switch to pane %3\nrename-window new-name # Rename the active window\nrename-session new-name # Rename the session\n```\n\n### Querying State\n\n```\nlist-windows # List all windows\nlist-windows -F '#{window_id}' # Custom format\nlist-panes # List panes in active window\nlist-panes -a # List all panes across all windows\nlist-sessions # List sessions\nlist-clients # List connected clients\ndisplay-message -p '#{pane_id}' # Print a format variable\nhas-session -t my-session # Check if session exists (exit code)\n```\n\n### Interacting with Panes\n\n```\nsend-keys -t %0 \"echo hello\" Enter # Send keystrokes to a pane\nsend-keys -t %0 -l \"literal text\" # Send text literally (no key parsing)\ncapture-pane -t %0 -p # Capture the visible content of a pane\n```\n\n### Configuration and Hooks\n\n```\nset-option -g status-style \"bg=blue\" # Set an option\nshow-options -g # Show all global options\nset-hook -g after-new-window \"display-message hi\" # Set a hook\nbind-key M-x display-message \"pressed!\" # Bind a key\n```\n\n### Server\n\n```\nlist-commands # List all available commands\nserver-info # Server information\nkill-server # Shut down the server\n```\n\n### psmux Extension Commands\n\nThese commands are available in psmux but do not exist in tmux:\n\n| Command | Description |\n|---|---|\n| `dump-state` | Returns the entire session state as a JSON blob (windows, panes, options, sizes, screen content). Invaluable for building rich UIs. |\n| `dump-layout` | Returns the pane layout tree structure |\n| `list-tree` | Returns a hierarchical session/window/pane tree view |\n| `send-text <text>` | Send raw text directly to the active pane (no key name parsing) |\n| `send-paste <text>` | Send text as a bracketed paste sequence |\n| `claim-session` | Claim a warm (pre spawned) session for faster startup |\n| `set-pane-title <title>` | Set the title of the current pane |\n| `toggle-sync` | Toggle synchronized input across all panes in a window |\n\n## Building a Plugin\n\n### Minimal Python Example\n\n```python\nimport subprocess\nimport threading\n\nproc = subprocess.Popen(\n [\"psmux\", \"-CC\"],\n stdin=subprocess.PIPE,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n env={**__import__(\"os\").environ, \"PSMUX_SESSION_NAME\": \"work\"},\n)\n\ndef read_notifications():\n for line in proc.stdout:\n line = line.rstrip(\"\\n\")\n if line.startswith(\"%output\"):\n parts = line.split(\" \", 2)\n pane_id = parts[1]\n data = parts[2] if len(parts) > 2 else \"\"\n print(f\"[{pane_id}] {data}\")\n elif line.startswith(\"%window-add\"):\n print(f\"Window created: {line}\")\n elif line.startswith(\"%begin\"):\n pass # Start of command response\n elif line.startswith(\"%end\"):\n pass # End of command response\n elif line.startswith(\"%error\"):\n print(f\"Command error: {line}\")\n\nreader = threading.Thread(target=read_notifications, daemon=True)\nreader.start()\n\n# Send a command\nproc.stdin.write(\"list-windows\\n\")\nproc.stdin.flush()\n\n# Create a new window\nproc.stdin.write(\"new-window -n build\\n\")\nproc.stdin.flush()\n\n# Run a command in it\nproc.stdin.write('send-keys \"cargo build\" Enter\\n')\nproc.stdin.flush()\n\nimport time\ntime.sleep(5)\nproc.stdin.close()\nproc.wait()\n```\n\n### Minimal PowerShell Example\n\n```powershell\n$env:PSMUX_SESSION_NAME = \"work\"\n$psi = [System.Diagnostics.ProcessStartInfo]::new()\n$psi.FileName = (Get-Command psmux).Source\n$psi.Arguments = \"-CC\"\n$psi.RedirectStandardInput = $true\n$psi.RedirectStandardOutput = $true\n$psi.UseShellExecute = $false\n\n$proc = [System.Diagnostics.Process]::Start($psi)\n\n# Send a command\n$proc.StandardInput.WriteLine(\"list-windows\")\n$proc.StandardInput.Flush()\nStart-Sleep -Seconds 1\n\n# Read the response\nwhile ($proc.StandardOutput.Peek() -ge 0) {\n $line = $proc.StandardOutput.ReadLine()\n Write-Host $line\n}\n\n$proc.StandardInput.Close()\n$proc.WaitForExit(5000)\n```\n\n### Minimal Node.js Example\n\n```javascript\nconst { spawn } = require(\"child_process\");\n\nconst proc = spawn(\"psmux\", [\"-CC\"], {\n env: { ...process.env, PSMUX_SESSION_NAME: \"work\" },\n stdio: [\"pipe\", \"pipe\", \"pipe\"],\n});\n\nproc.stdout.on(\"data\", (chunk) => {\n for (const line of chunk.toString().split(\"\\n\")) {\n if (line.startsWith(\"%output\")) {\n const [, paneId, ...rest] = line.split(\" \");\n console.log(`[${paneId}] ${rest.join(\" \")}`);\n } else if (line.startsWith(\"%begin\")) {\n // Command response starting\n } else if (line.startsWith(\"%end\")) {\n // Command response complete\n }\n }\n});\n\nproc.stdin.write(\"list-windows\\n\");\nproc.stdin.write(\"new-window -n monitor\\n\");\nproc.stdin.write('send-keys \"top\" Enter\\n');\n\nsetTimeout(() => {\n proc.stdin.end();\n}, 5000);\n```\n\n## Parsing Tips\n\n1. **Read line by line.** Every notification and framing marker is a single line terminated by `\\n`.\n\n2. **Track command state.** When you send a command, set a flag. Lines between `%begin` and `%end`/`%error` are the command's output. Everything outside those blocks is asynchronous notifications.\n\n3. **Match begin/end pairs by command number.** The second field in `%begin` and `%end` lines is the command counter. Use it to correlate responses with requests.\n\n4. **Buffer line parsing for `%output`.** Split on the first two spaces: `%output`, pane ID, then the rest is escaped output data.\n\n5. **Decode octal escapes.** Replace `\\NNN` sequences in output data with the corresponding byte value. `\\134` is a literal backslash.\n\n6. **Handle connection loss gracefully.** If the session dies or the server shuts down, stdout will close (EOF). Your reader loop should exit cleanly.\n\n## Differences from tmux\n\npsmux control mode is wire-compatible with tmux's protocol. A few features that exist in tmux but are not yet implemented in psmux:\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| `refresh-client -f` flags | Planned | Per-client flags like `no-output`, `pause-after=N` |\n| `refresh-client -A` pane actions | Planned | Per-pane on/off/continue/pause |\n| `refresh-client -B` subscriptions | Planned | Filtered format variable monitoring |\n| `refresh-client -C WxH` | Planned | Client-side size override |\n| `%extended-output` | Planned | Output with age info for flow control |\n| `%subscription-changed` | Planned | Subscription value change events |\n| Unlinked window notifications | N/A | psmux uses one session per server |\n\nThe core protocol (framing, notifications, escaping, IDs, command dispatch) is fully compatible. Plugins targeting the basic tmux control mode protocol will work identically on psmux.\n\n### Windows ConPTY Considerations\n\nIf you are porting a Unix tmux plugin to psmux, be aware of these ConPTY behaviors:\n\n- **SMCUP/RMCUP consumed internally.** ConPTY processes alternate screen buffer switches before the output reaches psmux. The `alternate_on` flag is always false. psmux uses a heuristic (last row content analysis) to detect fullscreen TUI applications.\n- **Output normalization.** ConPTY may normalize line endings and process certain cursor movement sequences internally. `%output` data may look slightly different from what a Unix tmux session would produce for the same shell command.\n- **`capture-pane` always reflects the primary screen buffer.** There is no reliable way to detect whether a pane is showing the alternate screen.\n- **Ctrl+C propagation.** `GenerateConsoleCtrlEvent` sends to ALL processes sharing the console, not just the foreground process. When testing TUI apps via `send-keys`, prefer using the app's quit key (e.g. `q`) rather than `C-c`.\n- **TUI exit timing.** After a TUI application exits and sends RMCUP, ConPTY needs time to generate the restore sequences. If you `capture-pane` immediately after a TUI exits, you may still see TUI content. Allow 4 to 6 seconds for the screen to settle.\n\n### Namespace Isolation\n\nUse `-L` to run multiple independent psmux servers on the same machine:\n\n```powershell\npsmux -L dev new-session -d -s myapp -x 120 -y 30\n$env:PSMUX_SESSION_NAME = \"dev__myapp\"\npsmux -CC\n```\n\nThe `PSMUX_SESSION_NAME` value follows the format `<namespace>__<session>` when using `-L`. The double underscore is the separator.\n\n## Format Variables\n\nUse `display-message -p` to query any format variable:\n\n```\ndisplay-message -p '#{session_name}: #{window_index} #{pane_id}'\n```\n\nCommon variables for control mode plugins:\n\n| Variable | Example | Description |\n|----------|---------|-------------|\n| `#{session_name}` | `work` | Session name |\n| `#{session_id}` | `$0` | Session stable ID |\n| `#{window_id}` | `@0` | Window stable ID |\n| `#{window_index}` | `0` | Window index |\n| `#{window_name}` | `pwsh` | Window name |\n| `#{pane_id}` | `%0` | Pane stable ID |\n| `#{pane_index}` | `0` | Pane index within window |\n| `#{pane_pid}` | `12345` | Pane child process PID |\n| `#{pane_current_command}` | `pwsh` | Pane running command |\n| `#{pane_width}` | `120` | Pane width in columns |\n| `#{pane_height}` | `30` | Pane height in rows |\n| `#{cursor_x}` | `5` | Cursor column |\n| `#{cursor_y}` | `10` | Cursor row |\n"
},
{
"path": "docs/faq.md",
"content": "# FAQ\n\n**Q: Is psmux cross-platform?**\nA: No. psmux is built exclusively for Windows using the Windows ConPTY API. For Linux/macOS, use tmux. psmux is the Windows counterpart.\n\n**Q: Does psmux work with Windows Terminal?**\nA: Yes! psmux works great with Windows Terminal, PowerShell, cmd.exe, ConEmu, and other Windows terminal emulators.\n\n**Q: Why use psmux instead of Windows Terminal tabs?**\nA: psmux offers session persistence (detach/reattach), synchronized input to multiple panes, full tmux command scripting, hooks, format engine, and tmux-compatible keybindings. Windows Terminal tabs can't do any of that.\n\n**Q: Can I use my existing `.tmux.conf`?**\nA: Yes! psmux reads `~/.tmux.conf` automatically. Most tmux config options, key bindings, and style settings work as-is.\n\n**Q: Can I use tmux themes?**\nA: Yes. psmux supports 14 style options with 24-bit true color, 256 indexed colors, and text attributes (bold, italic, dim, etc.). Most tmux theme configs are compatible.\n\n**Q: Can I use tmux commands with psmux?**\nA: Yes! psmux includes a `tmux` alias. Commands like `tmux new-session`, `tmux attach`, `tmux ls`, `tmux split-window` all work. 83 commands in total.\n\n**Q: How fast is psmux?**\nA: Session creation takes < 100ms. New windows/panes add < 80ms overhead. The bottleneck is your shell's startup time, not psmux. Compiled with opt-level 3 and full LTO.\n\n**Q: Does psmux support mouse?**\nA: Full mouse support: click to focus panes, drag to resize borders, scroll wheel, click status-bar tabs, drag-select text, right-click copy. Plus VT mouse forwarding for TUI apps like vim, htop, and midnight commander.\n\n**Q: What shells does psmux support?**\nA: PowerShell 7 (default), PowerShell 5, cmd.exe, Git Bash, WSL, nushell, and any Windows executable. Change with `set -g default-shell <shell>`.\n\n**Q: Is it stable for daily use?**\nA: Yes. psmux is stress-tested with 15+ rapid windows, 18+ concurrent panes, 5 concurrent sessions, kill+recreate cycles, and sustained load, all with zero hangs or resource leaks.\n\n**Q: PSReadLine predictions / intellisense / autocompletion (inline history suggestions) are disabled inside psmux. How do I enable them?**\nA: Add `set -g allow-predictions on` to your `~/.psmux.conf`. This tells psmux to preserve your `PredictionSource` setting after initialization. If your profile sets `PredictionSource` explicitly, psmux respects that. If not, psmux restores the system default (typically `HistoryAndPlugin`). See the [PSReadLine Predictions](configuration.md#psreadline-predictions-intellisense--autocompletion) section in the configuration docs for details.\n\n**Q: How do I use a custom config file?**\nA: Use the `-f` flag: `psmux -f /path/to/config.conf`. This loads the specified file instead of the default search order.\n\n**Q: How do I disable warm (pre-spawned) sessions?**\nA: Add `set -g warm off` to your config, or set `$env:PSMUX_NO_WARM = \"1\"`. See [warm-sessions.md](warm-sessions.md) for details.\n\n**Q: Can I set environment variables for panes?**\nA: Yes. Use `psmux set-environment -g VARNAME value` to set env vars inherited by all new panes. Use `-gu` to unset. See [configuration.md](configuration.md) for details.\n\n**Q: How do I mute the audible bell inside psmux?**\nA: Add `set -g bell-action none` to your `~/.psmux.conf`. This silences both the audible beep and the status bar bell flag. To keep the visual flag but mute the sound, this is not currently split into separate controls. See the [Bell](configuration.md#bell) section in the configuration docs.\n\n**Q: Does psmux work with Claude Code agent teams?**\nA: Yes, first-class support. Start psmux, run `claude` inside a pane, and ask Claude to create a team. psmux automatically sets the required environment variables and injects `--teammate-mode tmux`. Each teammate agent gets its own visible pane. See [claude-code.md](claude-code.md) for details.\n\n**Q: Do CJK characters (Chinese/Japanese/Korean) and IME input work?**\nA: Yes. CJK character input, IME composition, and pasting CJK text all work correctly. The paste detection heuristic is tuned to avoid misidentifying rapid IME bursts as clipboard pastes, keeping IME input latency minimal.\n\n**Q: Can I save and restore sessions across reboots?**\nA: Yes, using the [psmux-resurrect](https://github.com/psmux/psmux-plugins/tree/main/psmux-resurrect) plugin. For automatic periodic save/restore, pair it with [psmux-continuum](https://github.com/psmux/psmux-plugins/tree/main/psmux-continuum). See [plugins.md](plugins.md) for setup.\n\n**Q: Do sessions survive SSH disconnects?**\nA: Yes. The psmux session server persists even when your SSH connection drops. After reconnecting, run `psmux attach` to reattach to your sessions.\n\n**Q: How do I reload my config without restarting psmux?**\nA: Press `Prefix + :` to open the command prompt, then type `source-file ~/.psmux.conf`. You can also run `psmux source-file ~/.psmux.conf` from another terminal. This re-applies all options, key bindings, and styles immediately.\n\n**Q: How do I run commands from inside a psmux session?**\nA: Press `Prefix + :` to open the command prompt. Type any command (e.g. `split-window -h`, `new-window -n logs`, `set -g status-style \"bg=blue\"`). You can also run `list-commands` from the prompt to see all available commands.\n\n**Q: How do I switch between sessions?**\nA: Press `Prefix + s` to open the interactive session chooser. Use arrow keys to navigate and Enter to select. You can also use `Prefix + (` and `Prefix + )` to cycle through sessions, or `switch-client -t sessionname` from the command prompt.\n\n**Q: How do I split a pane with a specific size?**\nA: Use the `-p` flag with a percentage: `split-window -v -p 30` gives the new pane 30% of the space. This works with both `-v` (vertical) and `-h` (horizontal) splits.\n\n**Q: How do I open a new pane in the same directory?**\nA: Use `split-window -c \"#{pane_current_path}\"`. You can bind this in your config for convenience: `bind-key '\"' split-window -v -c \"#{pane_current_path}\"`.\n\n**Q: How do I prevent psmux from nesting inside itself?**\nA: psmux automatically detects when it is already running inside a psmux session and prevents accidental nesting. If you try to start `psmux` inside an existing session, it will warn you instead of creating a nested instance. To explicitly create a new session from within psmux, use the command prompt (`Prefix + :`) and type `new-session`.\n\n**Q: How do I keep a pane open after its process exits?**\nA: Add `set -g remain-on-exit on` to your config. When a process exits, the pane stays visible with its last output. Use `respawn-pane` (or `respawn-pane -k`) to restart the process in that pane.\n\n**Q: How do I make pane numbers start from 1 instead of 0?**\nA: Add `set -g pane-base-index 1` to your config. This affects the `Prefix + q` display panes overlay and pane target numbering. For windows, use `set -g base-index 1`.\n\n**Q: How do I set a window name that does not get overwritten?**\nA: Use the `-n` flag when creating: `new-window -n \"myname\"`. This automatically disables `automatic-rename` for that window. If you renamed a window with `Prefix + ,` and it keeps getting overwritten, add `set -g automatic-rename off` to your config or set it per-window with `set -w automatic-rename off`.\n\n**Q: How do I use PSReadLine ListView (dropdown suggestions) inside psmux?**\nA: First, add `set -g allow-predictions on` to your `~/.psmux.conf`. Then in your PowerShell profile, set `Set-PSReadLineOption -PredictionViewStyle ListView`. Without `allow-predictions on`, psmux resets PSReadLine settings during initialization.\n\n**Q: How do I get a live updating clock in my status bar?**\nA: Use time format variables like `%H:%M:%S` in your status-right: `set -g status-right \"%H:%M:%S %d-%b-%y\"`. Then set `set -g status-interval 1` to refresh every second.\n\n**Q: What is the difference between psmux, pmux, and tmux executables?**\nA: They are all the same binary. psmux installs as `psmux.exe` with `pmux.exe` and `tmux.exe` as aliases. Use whichever name you prefer. The `tmux` alias lets existing tmux scripts and muscle memory work without changes.\n\n**Q: Can I prevent psmux from entering copy mode on mouse scroll?**\nA: Yes. Add `set -g scroll-enter-copy-mode off` to your config. Scroll events will be passed directly to the running application instead of entering copy mode.\n\n**Q: Ctrl+V is intercepted by psmux even after unbinding. How do I let Ctrl+V reach neovim/vim?**\nA: psmux has a Windows paste detection system that intercepts Ctrl+V at the client input layer, outside of the key binding system. `unbind-key -n C-v` alone will not stop it. Add `set -g paste-detection off` to your `~/.psmux.conf`. This forwards Ctrl+V to the child application so neovim can use it for visual block mode. You can still paste using Ctrl+Shift+V, right click, or Prefix + ]. See [configuration.md](configuration.md#paste-detection-ctrlv-passthrough) for details.\n\n**Q: How do I chain multiple commands in a key binding?**\nA: Use `\\;` to separate commands: `bind-key M-s split-window -h \\; select-pane -L`. The semicolon must be escaped in config files.\n\n**Q: Can I run psmux inside psmux (nested sessions)?**\nA: No. psmux prevents nesting to avoid UI confusion. This matches tmux behavior. If you need to connect to a remote psmux, use SSH from within a psmux pane to reach the remote session.\n\n**Q: How do I use Ctrl+Space as my prefix key?**\nA: Add to your config: `set -g prefix C-Space` followed by `unbind-key C-b` and `bind-key C-Space send-prefix`.\n\n**Q: Why does `Prefix + I` not work for plugin install?**\nA: Make sure you are pressing `Shift+I` (uppercase). Key bindings are case-sensitive: `I` and `i` are distinct bindings.\n\n**Q: How do I reload my config without restarting?**\nA: Press `Prefix + :` and type `source-file ~/.psmux.conf`. This works from within a live session. Alternatively, bind it: `bind-key R source-file ~/.psmux.conf \\; display-message \"Config reloaded\"`.\n\n**Q: Does psmux work with Neovim/Vim?**\nA: Yes. Ctrl+[, Shift+Tab, mouse events, and truecolor rendering all work correctly inside psmux panes. Set `set -g default-terminal \"xterm-256color\"` for best compatibility.\n\n**Q: Why does my status bar show a file path instead of the hostname?**\nA: PowerShell 7 automatically sets the terminal title to the current working directory on every prompt. If your config has `set -g allow-set-title on` and your status bar format uses `#{pane_title}` or `#T`, you will see that path. By default, `allow-set-title` is `off` in psmux so this does not happen. If you enabled it and want to revert, remove the `allow-set-title on` line from your config, replace `#{pane_title}` with `#H` in your status bar format, or add `$PSStyle.WindowTitle = ''` to your PowerShell profile. See [pane-titles.md](pane-titles.md) for full details.\n\n**Q: Can I run multiple isolated psmux servers?**\nA: Yes, use the `-L` flag for server namespaces: `psmux -L work new-session -s dev`. Each namespace gets its own server, sessions, and discovery files.\n\n**Q: How many tmux commands does psmux support?**\nA: 83 tmux-compatible commands including session management, window/pane control, copy mode, display popups/menus, interactive choosers, hooks, environment variables, pipe-pane, wait-for synchronization, and more. See [tmux_args_reference.md](tmux_args_reference.md) for the full list.\n\n---\n\n## Developer Integration FAQ\n\n**Q: Can I use psmux as a drop-in replacement for tmux in my project?**\nA: Yes. psmux implements the same CLI protocol, commands, flags, and output formats as tmux. It also installs a `tmux.exe` alias, so scripts calling `tmux` will find psmux on the PATH without any code changes.\n\n**Q: Does libtmux work with psmux?**\nA: Yes. libtmux (the Python tmux API library) works with psmux because psmux implements the same commands and output formats. On Windows, you need to ensure UTF-8 encoding is used (set `PYTHONUTF8=1` or patch libtmux's `common.py` to add `encoding=\"utf-8\"` to the Popen call). See [integration.md](integration.md) for details.\n\n**Q: Why does libtmux return empty sessions on Windows?**\nA: libtmux uses a Unicode separator character (U+241E) internally to parse format output. On Windows, Python defaults to cp1252 encoding which garbles this character. Set `$env:PYTHONUTF8 = \"1\"` before running your script, or patch libtmux to use `encoding=\"utf-8\"`. This is an upstream libtmux issue, not psmux-specific.\n\n**Q: Does psmux support control mode for IDE integrations?**\nA: Yes. `psmux -CC` enters control mode with the same wire protocol as tmux (command/response framing with `%begin`/`%end`, async notifications for window/session/pane events, output escaping). See [control-mode.md](control-mode.md) for the full protocol reference.\n\n**Q: What is `dump-state` and when should I use it?**\nA: `dump-state` is a psmux extension command (not in tmux) that returns the entire session state as a JSON blob, including windows, panes, options, sizes, and screen content. Use it when building rich UIs or debugging integrations.\n\n**Q: Do named paste buffers work?**\nA: Yes. `set-buffer -b <name> \"text\"`, `show-buffer -b <name>`, `paste-buffer -b <name>`, and `delete-buffer -b <name>` all work. Named buffers are useful for structured data exchange between automation steps.\n\n**Q: How do I handle encoding when reading psmux output in Python?**\nA: Always specify `encoding=\"utf-8\"` in `subprocess.Popen()` or `subprocess.run()` calls on Windows. Alternatively, set the `PYTHONUTF8=1` environment variable globally. psmux outputs UTF-8, but Python defaults to cp1252 on Windows.\n\n**Q: Can I target windows by their stable ID (`@N`) instead of index?**\nA: Yes. `psmux select-window -t @2` targets the window with stable ID 2 (not display index 2). Stable IDs are assigned when windows are created and never change during the server's lifetime.\n\n**Q: What environment variables does psmux set?**\nA: `TMUX` (session info), `TMUX_PANE` (pane ID like `%0`), `TERM=xterm-256color`, and `COLORTERM=truecolor`. Tools that check `$TMUX` to detect tmux will correctly detect psmux.\n\n**Q: Where is the full developer integration guide?**\nA: See [integration.md](integration.md) for examples in Python, PowerShell, Node.js, Go, and Rust, plus cross-platform project patterns, libtmux usage, control mode integration, and troubleshooting.\n"
},
{
"path": "docs/features.md",
"content": "# Features\n\n## Highlights\n\n- 🦠 **Made in Rust** : opt-level 3, full LTO, single codegen unit. Maximum performance.\n- 🖱️ **Full mouse support** : click panes, drag-resize borders, scroll, click tabs, select text, right-click copy\n- 🎨 **tmux theme support** : 16 named colors + 256 indexed + 24-bit true color (`#RRGGBB`), 14 style options\n- 📋 **Reads your `.tmux.conf`** : drop-in config compatibility, zero learning curve\n- ⚡ **Blazing fast startup** : sub-100ms session creation, near-zero overhead over shell startup\n- 🔌 **83 tmux-compatible commands** : `bind-key`, `set-option`, `if-shell`, `run-shell`, `display-popup`, `display-menu`, hooks, and more\n- 🪟 **Windows-native** : ConPTY, Win32 API, works with PowerShell, cmd, bash, WSL, nushell\n- 📦 **Single binary, no dependencies** : install via `cargo`, `winget`, `scoop`, or `choco`\n- 🤖 **Claude Code agent teams** : first-class support for teammate pane spawning\n- 🌐 **CJK/IME input** : full support for Chinese, Japanese, and Korean input methods\n\n## Terminal Multiplexing\n\n- Split panes horizontally (`Prefix + %`) and vertically (`Prefix + \"`)\n- Multiple windows with clickable status-bar tabs\n- Session management: detach (`Prefix + d`) and reattach from anywhere\n- 5 layouts: even-horizontal, even-vertical, main-horizontal, main-vertical, tiled\n\n## Full Mouse Support\n\n- **Click** any pane to focus it, input goes to the right shell\n- **Drag** pane borders to resize splits interactively\n- **Click** status-bar tabs to switch windows\n- **Scroll wheel** in any pane, scrolls that pane's output (configurable via `scroll-enter-copy-mode`)\n- **Drag-select** text to copy to clipboard\n- **Right-click** to paste or copy selection\n- **Windows 11 PowerShell selection** : word and line selection with double/triple-click (`pwsh-mouse-selection on`)\n- **Disable client-side selection** : let in-pane TUI apps (opencode, lazygit, etc.) handle their own mouse selection (`mouse-selection off`)\n- **VT mouse forwarding** : apps like vim, htop, and midnight commander get full mouse events\n- **3-layer mouse injection** : VT protocol, VT bridge (for WSL/SSH), and native Win32 MOUSE_EVENT\n- **Mouse over SSH** : works from any OS client when server runs Windows 11 build 22523+\n- **Disable mouse** : `set -g mouse off` fully suppresses mouse event handling\n\n## tmux Theme & Style Support\n\n- **14 customizable style options** : status bar, pane borders, messages, copy-mode highlights, popups, menus\n- **Full color spectrum** : 16 named colors, 256 indexed (`colour0`–`colour255`), 24-bit true color (`#RRGGBB`)\n- **Text attributes** : bold, dim, italic, underline, blink, reverse, strikethrough, and more\n- **Status bar** : fully customizable left/right content with format variables\n- **Window tab styling** : separate styles for active, inactive, activity, bell, and last-used tabs\n- Compatible with existing tmux theme configs\n\n## Copy Mode (Vim Keybindings)\n\n- **53 vi-style key bindings** : motions, selections, search, text objects\n- Visual, line, and **rectangle selection** modes (`v`, `V`, `Ctrl+v`)\n- `/` and `?` search with `n`/`N` navigation\n- `f`/`F`/`t`/`T` character find, `%` bracket matching, `{`/`}` paragraph jump\n- Named registers (`\"a`–`\"z`), count prefixes, word/WORD variants\n- Mouse drag-select copies to Windows clipboard on release\n\nSee [keybindings.md](keybindings.md) for the full copy mode key reference.\n\n## Format Engine\n\n- **140+ tmux-compatible format variables** across sessions, windows, panes, cursor, client, and server\n- Conditionals (`#{?cond,true,false}`), comparisons (`#{==:a,b}`, `#{!=:a,b}`), boolean logic (`#{||:}`, `#{&&:}`)\n- Regex substitution (`#{s/pat/rep/:var}`), string manipulation\n- Loop iteration (`#{W:fmt}`, `#{P:fmt}`, `#{S:fmt}`) over windows, panes, sessions\n- Truncation, padding, basename, dirname, strftime, shell quoting\n- Inline style directives: `#[list]`, `#[fill]`, `#[align=left|centre|right]`, `#[range=...]`\n\n## Scripting & Automation\n\n- **83 tmux-compatible commands** : everything you need for automation\n- `send-keys`, `capture-pane`, `pipe-pane` for CI/CD and DevOps workflows\n- `display-popup` for floating popup windows with custom commands\n- `display-menu` for interactive context menus\n- `choose-tree` for interactive session/window/pane selection\n- `choose-buffer` and `choose-client` for interactive buffer and client picking\n- `if-shell` and `run-shell` for conditional config logic\n- **15+ event hooks** : `after-new-window`, `after-split-window`, `client-attached`, etc.\n- Paste buffers, named registers, `display-message` with format variables\n- Server namespaces via `-L` for running isolated psmux instances\n- Command chaining with `;` for multi-step bindings\n- `switch-client` for programmatic session switching\n- `break-pane` and `join-pane` for pane reorganization\n- `wait-for` with lock/signal/unlock for cross-pane synchronization\n- `confirm-before` for user confirmation dialogs\n\nSee [scripting.md](scripting.md) for full command reference and examples.\n\n## Session Persistence\n\n- psmux session servers survive SSH disconnects and terminal crashes\n- Detach with `Prefix + d`, reconnect with `psmux attach` from any terminal\n- Warm sessions (`set -g warm on`, default) pre-spawn background servers for instant session creation\n- Use [psmux-resurrect](https://github.com/psmux/psmux-plugins/tree/main/psmux-resurrect) to save/restore sessions across reboots\n- Use [psmux-continuum](https://github.com/psmux/psmux-plugins/tree/main/psmux-continuum) for automatic periodic save/restore\n\n## Session Switching\n\n- **Prefix + s** opens an interactive session/window/pane tree chooser\n- **Prefix + (** and **Prefix + )** cycle through sessions\n- `switch-client -t sessionname` switches to a named session\n- `switch-client -l` returns to the last (most recently used) session\n- Create multiple sessions with `new-session -s name` and switch freely between them\n\n## Display Panes Overlay\n\n- **Prefix + q** shows numbered overlays on all panes for quick selection\n- Press a number key to jump to that pane instantly\n- Numbers respect `pane-base-index` (e.g., starts from 1 if configured)\n- Overlay auto-dismisses after `display-panes-time` milliseconds (default: 1000ms)\n- Only single-digit pane numbers (0 through 9) can be selected by keypress\n\n## Nesting Prevention\n\n- psmux automatically detects when running inside an existing session\n- Prevents accidental creation of nested psmux instances\n- To create a new session from inside psmux, use the command prompt (`Prefix + :`)\n\n## Dead Pane Handling\n\n- `set -g remain-on-exit on` keeps panes visible after their process exits\n- Dead panes display their final output for inspection\n- `respawn-pane` restarts the shell or a new command in a dead pane\n- Useful for monitoring long-running processes that may crash\n\n## Command Prompt\n\n- **Prefix + :** opens a command prompt at the bottom of the screen\n- Full cursor movement (arrow keys, Home, End) within the command line\n- Command history (Up/Down arrows recall previous commands)\n- Any psmux/tmux command can be typed and executed interactively\n- Supports `source-file`, `set-option`, `split-window`, `list-commands`, and all 83 commands\n\n## Claude Code Agent Teams\n\n- First-class support for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) teammate pane spawning\n- Automatically sets `TMUX`, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`, and teammate mode\n- Each agent gets its own visible pane with full terminal output\n- No extra configuration needed: start psmux, run `claude`, and ask it to create a team\n\nSee [claude-code.md](claude-code.md) for detailed setup and troubleshooting.\n\n## CJK and IME Input\n\n- Full support for Chinese, Japanese, and Korean character input\n- IME composition handled with minimal latency (paste-detection heuristic tuned for rapid IME bursts)\n- Korean IME input correctly handled without bracketed paste sequence injection\n- CJK text pasting works reliably for any length\n- UTF-8 multi-byte characters (box-drawing, emoji, CJK) render correctly in ConPTY panes\n\n## Interactive Choosers\n\n- `choose-tree` (`Prefix + w`): browse and select sessions, windows, and panes interactively, with optional [live preview pane](preview.md) (`p` to toggle, `set -g choose-tree-preview on` to default on)\n- `choose-session` (`Prefix + s`): browse sessions only, same live preview support\n- `choose-buffer` (`Prefix + =`): pick from paste buffers with preview\n- `choose-client`: view connected clients\n- `customize-mode`: interactive options editor\n- **Digit-jump** (all pickers): type a number and press `Enter` to jump directly to that row (1-based). A `go to N` indicator appears at the bottom; `Backspace` edits the number, `Esc` cancels. Every row is numbered so the mapping is visible at a glance. See [keybindings.md](keybindings.md#picker-navigation-choose-session-choose-tree-choose-buffer-list-keys-customize) for the full key reference.\n\n## Nesting Prevention\n\npsmux prevents launching a psmux session inside an existing psmux session. If you attempt to nest sessions, psmux blocks it to avoid UI confusion. This matches tmux behavior where nesting requires explicitly unsetting `$TMUX`.\n\n## Multi-Shell Support\n\n- **PowerShell 7** (default), PowerShell 5, cmd.exe\n- **Git Bash**, WSL, nushell, and any Windows executable\n- Sets `TERM=xterm-256color`, `COLORTERM=truecolor` automatically\n- Sets `TMUX` and `TMUX_PANE` env vars for tmux-aware tool compatibility\n\nSee [configuration.md](configuration.md) for `default-shell` and other options.\n\n## Named Paste Buffers\n\n- `set-buffer -b <name> \"text\"` to create a named buffer\n- `show-buffer -b <name>` to read it back\n- `paste-buffer -b <name>` to paste into the active pane\n- `delete-buffer -b <name>` to remove it\n- Named buffers are separate from the anonymous buffer stack\n- Useful for structured data exchange between automation steps\n\n## Developer Integration and tmux API Compatibility\n\npsmux is designed as a drop-in replacement for tmux on Windows at the API level:\n\n- **Same CLI protocol**: 83 tmux commands with identical flags, arguments, and output formats\n- **Same stable IDs**: `$N` (session), `@N` (window), `%N` (pane) targeting works identically\n- **Same control mode**: `-C`/`-CC` wire protocol with `%begin`/`%end` framing and async notifications\n- **Same format engine**: 140+ format variables, conditionals, loops, regex, string ops\n- **Same config**: Reads `~/.tmux.conf` directly\n- **libtmux compatible**: The libtmux Python library works with psmux (see note on Windows encoding)\n- **tmux.exe alias**: psmux installs a `tmux.exe` alias so existing scripts find it on the PATH\n\nFor a full developer integration guide with examples in Python, PowerShell, Node.js, Go, and Rust, see [integration.md](integration.md).\n\nFor the tmux command and feature compatibility matrix, see [compatibility.md](compatibility.md).\n"
},
{
"path": "docs/integration.md",
"content": "# Developer Integration Guide\n\nThis guide is for developers who want to build tools, scripts, IDE extensions, or automation pipelines that use psmux on Windows, especially if you already have tmux integrations on Linux/macOS.\n\n## Why psmux for Developers\n\npsmux implements the same CLI protocol and command set as tmux. If your project already integrates with tmux via subprocess calls, control mode, or libraries like libtmux, you can run on Windows with minimal or zero code changes.\n\nKey points:\n\n- **Same binary name**: psmux installs `tmux.exe` as an alias. Existing scripts that call `tmux` will find psmux on the PATH.\n- **Same commands**: 83 tmux commands with the same flags, arguments, and output formats.\n- **Same IDs**: `$N` (session), `@N` (window), `%N` (pane) stable IDs follow the tmux scheme.\n- **Same control mode**: `-C`/`-CC` wire protocol with `%begin`/`%end` framing, notifications, and output escaping.\n- **Same config**: Reads `~/.tmux.conf` directly. Your config, key bindings, and themes transfer as-is.\n- **Same format engine**: 140+ format variables with conditionals, loops, regex, and string operations.\n\n## Installation\n\n```powershell\n# Cargo (recommended for developers)\ncargo install --git https://github.com/psmux/psmux\n\n# Scoop\nscoop bucket add extras\nscoop install psmux\n\n# Winget\nwinget install psmux\n\n# Chocolatey\nchoco install psmux\n```\n\nAfter installation, `psmux`, `pmux`, and `tmux` are all available as commands. Use whichever fits your project.\n\n## Quick Start: Subprocess Integration\n\nThe simplest integration pattern. Works with any language that can spawn processes.\n\n### Python\n\n```python\nimport subprocess\nimport platform\n\ndef mux_cmd(args, encoding=\"utf-8\"):\n \"\"\"Run a tmux/psmux command and return stdout.\"\"\"\n kwargs = {\"capture_output\": True, \"text\": True}\n if platform.system() == \"Windows\":\n kwargs[\"encoding\"] = encoding\n result = subprocess.run([\"tmux\"] + args, **kwargs)\n if result.returncode != 0:\n raise RuntimeError(f\"tmux command failed: {result.stderr}\")\n return result.stdout.strip()\n\n# Create a session\nmux_cmd([\"new-session\", \"-d\", \"-s\", \"dev\", \"-x\", \"120\", \"-y\", \"30\"])\n\n# Send a command\nmux_cmd([\"send-keys\", \"-t\", \"dev\", \"echo hello\", \"Enter\"])\n\n# Read pane output\ncontent = mux_cmd([\"capture-pane\", \"-t\", \"dev\", \"-p\"])\nprint(content)\n\n# Query format variables\npane_path = mux_cmd([\"display-message\", \"-t\", \"dev\", \"-p\", \"#{pane_current_path}\"])\n\n# List all sessions\nsessions = mux_cmd([\"list-sessions\", \"-F\", \"#{session_name}\"])\n\n# Clean up\nmux_cmd([\"kill-session\", \"-t\", \"dev\"])\n```\n\n### PowerShell\n\n```powershell\nfunction Invoke-Mux {\n param([string[]]$Args)\n $result = & tmux @Args 2>&1\n if ($LASTEXITCODE -ne 0) { throw \"tmux command failed: $result\" }\n return $result\n}\n\n# Create and interact with a session\nInvoke-Mux new-session -d -s dev -x 120 -y 30\nInvoke-Mux send-keys -t dev \"Get-Process | Select -First 5\" Enter\nStart-Sleep -Seconds 1\n$content = Invoke-Mux capture-pane -t dev -p\nWrite-Host $content\nInvoke-Mux kill-session -t dev\n```\n\n### Node.js\n\n```javascript\nconst { execFileSync } = require(\"child_process\");\n\nfunction muxCmd(args) {\n return execFileSync(\"tmux\", args, { encoding: \"utf-8\" }).trim();\n}\n\n// Create a session\nmuxCmd([\"new-session\", \"-d\", \"-s\", \"dev\", \"-x\", \"120\", \"-y\", \"30\"]);\n\n// Send keys\nmuxCmd([\"send-keys\", \"-t\", \"dev\", \"echo hello\", \"Enter\"]);\n\n// Capture output\nconst content = muxCmd([\"capture-pane\", \"-t\", \"dev\", \"-p\"]);\nconsole.log(content);\n\n// Clean up\nmuxCmd([\"kill-session\", \"-t\", \"dev\"]);\n```\n\n### Go\n\n```go\npackage main\n\nimport (\n \"fmt\"\n \"os/exec\"\n \"strings\"\n)\n\nfunc muxCmd(args ...string) (string, error) {\n out, err := exec.Command(\"tmux\", args...).Output()\n return strings.TrimSpace(string(out)), err\n}\n\nfunc main() {\n muxCmd(\"new-session\", \"-d\", \"-s\", \"dev\", \"-x\", \"120\", \"-y\", \"30\")\n muxCmd(\"send-keys\", \"-t\", \"dev\", \"echo hello\", \"Enter\")\n content, _ := muxCmd(\"capture-pane\", \"-t\", \"dev\", \"-p\")\n fmt.Println(content)\n muxCmd(\"kill-session\", \"-t\", \"dev\")\n}\n```\n\n### Rust\n\n```rust\nuse std::process::Command;\n\nfn mux_cmd(args: &[&str]) -> String {\n let output = Command::new(\"tmux\")\n .args(args)\n .output()\n .expect(\"failed to run tmux/psmux\");\n String::from_utf8_lossy(&output.stdout).trim().to_string()\n}\n\nfn main() {\n mux_cmd(&[\"new-session\", \"-d\", \"-s\", \"dev\", \"-x\", \"120\", \"-y\", \"30\"]);\n mux_cmd(&[\"send-keys\", \"-t\", \"dev\", \"echo hello\", \"Enter\"]);\n let content = mux_cmd(&[\"capture-pane\", \"-t\", \"dev\", \"-p\"]);\n println!(\"{}\", content);\n mux_cmd(&[\"kill-session\", \"-t\", \"dev\"]);\n}\n```\n\n## libtmux Integration\n\n[libtmux](https://github.com/tmux-python/libtmux) is the most popular Python library for controlling tmux programmatically. psmux is compatible with libtmux because it implements the same commands and output formats.\n\n### Setup\n\n```powershell\npip install libtmux\n```\n\n### Basic Usage\n\n```python\nimport libtmux\n\n# Connect to the psmux server\nserver = libtmux.Server(socket_name=\"default\")\n\n# List sessions\nfor session in server.sessions:\n print(f\"{session.name} ({session.id}): {len(session.windows)} windows\")\n\n# Work with a session\nsession = server.sessions[0]\n\n# Create a window\nwindow = session.new_window(window_name=\"build\")\n\n# Access panes\npane = window.panes[0]\n\n# Send commands\npane.send_keys(\"cargo build\")\n\n# Capture output\nlines = pane.capture_pane()\nfor line in lines:\n print(line)\n\n# Kill the window\nwindow.kill()\n```\n\n### Windows Encoding Fix\n\nlibtmux uses the Unicode character U+241E (SYMBOL FOR RECORD SEPARATOR) internally to split format fields when querying tmux. On Linux, this works transparently because both tmux and Python use UTF-8.\n\nOn Windows, Python's `subprocess.Popen(text=True)` defaults to cp1252 encoding, which garbles the 3-byte UTF-8 sequence for U+241E. This causes `server.sessions` and similar queries to return empty results or parse errors.\n\n**Option 1**: Set `PYTHONUTF8=1` before running your script:\n\n```powershell\n$env:PYTHONUTF8 = \"1\"\npython my_script.py\n```\n\n**Option 2**: Patch libtmux locally. In your installed libtmux package, edit `common.py` and add `encoding=\"utf-8\"` to the `Popen` call in the `tmux_cmd.__init__` method:\n\n```python\nsubprocess.Popen(\n cmd, stdout=PIPE, stderr=PIPE, text=True,\n encoding=\"utf-8\", errors=\"backslashreplace\"\n)\n```\n\nThis is an upstream libtmux issue (not psmux-specific). The library should specify encoding explicitly for cross-platform compatibility.\n\n### libtmux API Coverage\n\nThe following libtmux operations are verified working with psmux:\n\n| Operation | Status | Notes |\n|-----------|--------|-------|\n| `Server(socket_name=\"default\")` | Works | Connects to the running psmux server |\n| `server.sessions` | Works | Returns all sessions (needs encoding fix on Windows) |\n| `session.id` (`$N`) | Works | Returns the stable session ID |\n| `session.windows` | Works | Lists all windows in the session |\n| `session.new_window()` | Works | Creates a new window |\n| `window.id` (`@N`) | Works | Returns the stable window ID |\n| `window.panes` | Works | Lists all panes in the window |\n| `pane.id` (`%N`) | Works | Returns the stable pane ID |\n| `pane.send_keys()` | Works | Sends keystrokes to the pane |\n| `pane.capture_pane()` | Works | Captures visible pane content |\n| `window.kill()` | Works | Destroys the window |\n| `session.kill()` | Works | Destroys the session |\n| `server.has_session()` | Works | Checks if a session exists |\n| Custom format queries (`-F`) | Works | All 140+ format variables supported |\n\n## Control Mode Integration\n\nFor persistent, event-driven integration (IDE plugins, session managers, monitoring tools), use control mode. See [control-mode.md](control-mode.md) for the full protocol reference.\n\n### Quick Example\n\n```python\nimport subprocess\nimport threading\n\nproc = subprocess.Popen(\n [\"psmux\", \"-CC\"],\n stdin=subprocess.PIPE,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n encoding=\"utf-8\",\n)\n\ndef reader():\n for line in proc.stdout:\n line = line.rstrip(\"\\n\")\n if line.startswith(\"%output\"):\n _, pane_id, *data = line.split(\" \", 2)\n print(f\"[{pane_id}] {data[0] if data else ''}\")\n elif line.startswith(\"%window-add\"):\n print(f\"Window created: {line}\")\n elif line.startswith(\"%session-changed\"):\n print(f\"Session changed: {line}\")\n\nt = threading.Thread(target=reader, daemon=True)\nt.start()\n\n# Send commands\nproc.stdin.write(\"list-windows\\n\")\nproc.stdin.flush()\n\nproc.stdin.write(\"new-window -n monitor\\n\")\nproc.stdin.flush()\n\nproc.stdin.write('send-keys \"Get-Process\" Enter\\n')\nproc.stdin.flush()\n```\n\n### psmux Extension Commands\n\nIn addition to the 83 standard tmux commands, psmux provides extra commands useful for rich integrations:\n\n| Command | Description |\n|---------|-------------|\n| `dump-state` | Full session state as JSON (windows, panes, options, screen content) |\n| `dump-layout` | Pane layout tree structure |\n| `list-tree` | Hierarchical session/window/pane tree |\n| `send-text <text>` | Send raw text to active pane (no key name parsing) |\n| `send-paste <text>` | Send text as a bracketed paste sequence |\n| `claim-session` | Claim a warm (pre-spawned) session for instant startup |\n| `set-pane-title <title>` | Set pane title directly |\n| `toggle-sync` | Toggle synchronized input for all panes in a window |\n\n## Named Paste Buffers\n\npsmux supports named paste buffers for structured inter-pane data exchange:\n\n```powershell\n# Set a named buffer\npsmux set-buffer -b config \"key=value\"\n\n# Read it from another pane or script\npsmux show-buffer -b config\n\n# Delete when done\npsmux delete-buffer -b config\n\n# Paste into the active pane\npsmux paste-buffer -b config\n```\n\nNamed buffers are useful for passing structured data between automation steps without relying on environment variables or temporary files.\n\n## Cross-Platform Project Structure\n\nFor projects that need to work on both Linux/macOS (tmux) and Windows (psmux), here is a recommended pattern:\n\n### 1. Use the `tmux` Binary Name\n\npsmux installs `tmux.exe` as an alias. Your code can call `tmux` on all platforms:\n\n```python\nbinary = \"tmux\" # Works on Linux (real tmux) and Windows (psmux alias)\n```\n\n### 2. Set Encoding on Windows\n\nThe only platform-specific code you need:\n\n```python\nimport platform\n\ndef get_mux_kwargs():\n kwargs = {\"capture_output\": True, \"text\": True}\n if platform.system() == \"Windows\":\n kwargs[\"encoding\"] = \"utf-8\"\n return kwargs\n```\n\n### 3. Handle Path Separators\n\ntmux uses Unix paths (`/home/user/project`), psmux uses Windows paths (`C:\\Users\\user\\project`). Format variables like `#{pane_current_path}` return the native path format. If your code compares paths, normalize them:\n\n```python\nfrom pathlib import Path\n\npane_path = Path(mux_cmd([\"display-message\", \"-p\", \"#{pane_current_path}\"]))\n```\n\n### 4. Shell Differences\n\nOn Linux, the default shell in tmux is usually `bash` or `zsh`. On Windows, psmux defaults to PowerShell 7 (`pwsh`). Keep this in mind when sending commands:\n\n```python\nimport platform\n\nif platform.system() == \"Windows\":\n mux_cmd([\"send-keys\", \"-t\", target, \"Get-ChildItem\", \"Enter\"])\nelse:\n mux_cmd([\"send-keys\", \"-t\", target, \"ls -la\", \"Enter\"])\n```\n\n### 5. Test Matrix\n\nA typical CI/CD matrix for a cross-platform tmux integration:\n\n```yaml\n# GitHub Actions example\nstrategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n include:\n - os: ubuntu-latest\n mux: tmux\n - os: windows-latest\n mux: psmux\n\nsteps:\n - name: Install multiplexer\n run: |\n if [ \"${{ matrix.mux }}\" = \"psmux\" ]; then\n cargo install --git https://github.com/psmux/psmux\n else\n sudo apt-get install -y tmux\n fi\n shell: bash\n\n - name: Run integration tests\n run: python -m pytest tests/test_mux_integration.py\n env:\n PYTHONUTF8: \"1\"\n```\n\n## Environment Variables\n\npsmux sets these environment variables in child processes, matching tmux:\n\n| Variable | Example | Description |\n|----------|---------|-------------|\n| `TMUX` | `/tmp/tmux-1000/default,12345,0` | Indicates a tmux/psmux session is active |\n| `TMUX_PANE` | `%0` | The pane ID of the current pane |\n| `TERM` | `xterm-256color` | Terminal type |\n| `COLORTERM` | `truecolor` | Indicates 24-bit color support |\n\nTools that check for `$TMUX` to detect tmux will correctly detect psmux as well.\n\n### Propagating Environment Variables\n\nUse `set-environment` to pass configuration to panes:\n\n```powershell\n# Global: all new panes inherit this\npsmux set-environment -g API_KEY \"sk-...\"\n\n# Session-scoped\npsmux set-environment PROJECT_ROOT \"C:\\Projects\\myapp\"\n\n# On session creation\npsmux new-session -s work -e \"NODE_ENV=development\"\n```\n\n## Server Namespaces\n\nUse `-L` to run isolated psmux instances (each with its own sessions, windows, and options):\n\n```powershell\n# Create isolated servers for different projects\npsmux -L frontend new-session -d -s app\npsmux -L backend new-session -d -s api\n\n# Each namespace is completely independent\npsmux -L frontend list-sessions # Only shows \"app\"\npsmux -L backend list-sessions # Only shows \"api\"\n\n# Attach to a specific namespace\npsmux -L frontend attach -t app\n```\n\nIn control mode, the session name includes the namespace:\n\n```powershell\n$env:PSMUX_SESSION_NAME = \"frontend__app\"\npsmux -CC\n```\n\nThe double underscore separates namespace from session name.\n\n## Targeting Syntax Reference\n\npsmux supports the full tmux target syntax for the `-t` flag:\n\n| Target | Meaning |\n|--------|---------|\n| `mysession` | Session by name |\n| `$0` | Session by stable ID |\n| `mysession:2` | Window 2 in session \"mysession\" |\n| `mysession:editor` | Window named \"editor\" in session \"mysession\" |\n| `:2` | Window 2 in the current session |\n| `@3` | Window by stable ID |\n| `%5` | Pane by stable ID |\n| `mysession:2.1` | Pane 1 of window 2 in session \"mysession\" |\n| `.+1` | Next pane |\n| `.-1` | Previous pane |\n\n## Hooks for Event-Driven Automation\n\nHooks let you react to session events without polling:\n\n```powershell\n# Run a script when a new window is created\npsmux set-hook -g after-new-window \"run-shell 'echo window created >> /tmp/events.log'\"\n\n# Notify on session attach\npsmux set-hook -g client-attached \"display-message 'Welcome back!'\"\n\n# Auto-layout on split\npsmux set-hook -g after-split-window \"select-layout tiled\"\n```\n\nAvailable hooks: `after-new-session`, `after-new-window`, `after-split-window`, `client-attached`, `client-detached`, `after-select-window`, `after-select-pane`, `after-resize-pane`, `pane-died`, `alert-activity`, `alert-silence`, `alert-bell`, `after-kill-pane`.\n\n## Synchronization with `wait-for`\n\nFor multi-step automation that needs coordination between panes:\n\n```powershell\n# Pane 1: Wait for a signal\npsmux send-keys -t %0 \"psmux wait-for ready && echo 'proceeding'\" Enter\n\n# Pane 2: Do some work, then signal\npsmux send-keys -t %1 \"cargo build && psmux wait-for -S ready\" Enter\n```\n\n`wait-for` supports `-L` (lock), `-S` (signal/unlock), and bare wait. Use it for producer/consumer patterns across panes.\n\n## Troubleshooting\n\n### \"no server running\" Error\n\npsmux requires a running session. Create one first:\n\n```powershell\npsmux new-session -d -s work\n```\n\nOr use `has-session` to check:\n\n```powershell\npsmux has-session -t work 2>$null\nif ($LASTEXITCODE -ne 0) {\n psmux new-session -d -s work\n}\n```\n\n### Empty Results from Format Queries on Windows\n\nIf `list-sessions -F`, `list-windows -F`, or `list-panes -F` returns garbled or empty output, your process is decoding psmux's UTF-8 output with the wrong encoding. See the [encoding section](#windows-encoding-fix) above.\n\n### Control Mode Connection Issues\n\nIf `psmux -CC` exits immediately, ensure a session exists and `PSMUX_SESSION_NAME` is set:\n\n```powershell\npsmux new-session -d -s work\n$env:PSMUX_SESSION_NAME = \"work\"\npsmux -CC\n```\n\n### ConPTY Differences from Unix PTY\n\nWhen porting Unix tmux integrations to Windows:\n\n- **Alternate screen buffer**: ConPTY processes SMCUP/RMCUP internally. The `alternate_on` flag is always false in psmux. Use content-based heuristics to detect fullscreen TUI apps.\n- **Output normalization**: ConPTY may normalize line endings. `%output` data may differ slightly from Unix tmux output.\n- **Ctrl+C**: `GenerateConsoleCtrlEvent` sends to all processes sharing the console. Prefer app-specific quit keys over `C-c` in automation.\n- **TUI exit timing**: After a TUI exits, ConPTY needs 4 to 6 seconds to restore the screen. Add a delay before `capture-pane` after TUI exit.\n\n## Related Documentation\n\n- [compatibility.md](compatibility.md) : Full tmux command and feature compatibility matrix\n- [control-mode.md](control-mode.md) : Control mode wire protocol reference\n- [scripting.md](scripting.md) : Command reference and scripting examples\n- [configuration.md](configuration.md) : All options and config file format\n- [claude-code.md](claude-code.md) : Claude Code agent team integration\n- [features.md](features.md) : Complete feature list\n"
},
{
"path": "docs/iterm2-control-mode.md",
"content": "# Using psmux with iTerm2 (`tmux -CC` integration)\n\niTerm2's [tmux integration](https://iterm2.com/documentation-tmux-integration.html)\ntreats `tmux -CC` as a wire protocol. Each tmux window becomes a native\niTerm2 tab, panes become native iTerm2 split panes, scrollback is local,\nand the connection survives network drops.\n\n`psmux` ships full `-CC` support, so the same workflow works against a\nWindows host running `psmux.exe`. This document shows how to set it up.\n\n---\n\n## Quick start\n\nOn the **macOS** machine running iTerm2:\n\n```sh\nstty raw -echo -isig\nssh -T user@windows-host 'C:/path/to/psmux.exe -CC'\n```\n\nThat's it — iTerm2 detects the DCS opener emitted by psmux and switches\ninto tmux gateway mode automatically. You'll see your shell prompt\nappear in a fresh native iTerm2 tab.\n\nTo detach (return iTerm2 to a normal terminal), press `Esc` in the\ngateway-mode tab; psmux continues running and you can re-attach later.\n\n---\n\n## Why each flag is needed\n\n### `stty raw -echo -isig`\n\nPuts your **local** macOS TTY into raw mode *before* launching SSH.\niTerm2 sends a `\\x03` (Ctrl-C) byte the moment it enters tmux gateway\nmode. With the default cooked TTY, the `ISIG` flag would convert that\nbyte to `SIGINT` and kill the SSH process before the gateway handshake\never happens. The `-echo` and `raw` flags also stop the local TTY\nfrom corrupting the byte stream.\n\n### `ssh -T`\n\nDisables remote PTY allocation. Without `-T`, OpenSSH for Windows\nwraps psmux's stdio in a **ConPTY** (`FILE_TYPE_CHAR`), and ConPTY\nsilently consumes the DCS escape sequences (`\\x1bP1000p ... \\x1b\\`)\nthat the tmux-CC protocol depends on, plus injects its own cursor\npositioning sequences between protocol lines. With `-T` the channel\nis plain pipes (`FILE_TYPE_PIPE`) and every byte is preserved.\n\n### `psmux -CC` (no extra arguments)\n\n`-CC` is \"control mode, no echo\" — the same flag real tmux uses.\npsmux automatically:\n\n1. Spawns a background server if none is running.\n2. Creates a numbered session (`0`, `1`, `2`, …) the way tmux does\n when invoked bare.\n3. Connects to the server, authenticates, and switches stdin/stdout\n into the tmux control protocol.\n\nYou can pass `new-session -A -s NAME` if you want a stable named\nsession, but it isn't required.\n\n---\n\n## Drop-in tmux replacement\n\nAnywhere a workflow uses `tmux -CC`, replace it with `psmux -CC`:\n\n| Real tmux command | psmux equivalent |\n| ------------------------- | ------------------------- |\n| `tmux -CC` | `psmux -CC` |\n| `tmux -CC new -A -s work` | `psmux -CC new -A -s work`|\n| `tmux -CC attach -t work` | `psmux -CC attach -t work`|\n\niTerm2's \"**Session → tmux → New tmux Window**\" / \"**Attach to tmux\nSession**\" menu items work the same way once you've launched any of\nthese from a profile command.\n\n---\n\n## Configuring an iTerm2 profile\n\nFor a one-click experience:\n\n1. `iTerm2 → Settings → Profiles → +` (new profile).\n2. **General → Command → Custom Shell**:\n ```sh\n /bin/sh -c \"stty raw -echo -isig; ssh -T user@windows-host 'C:/path/to/psmux.exe -CC'\"\n ```\n3. Save. Open a new tab with this profile and iTerm2 enters tmux\n integration mode immediately.\n\n---\n\n## What works\n\n- ✅ Multiple tmux windows → multiple iTerm2 tabs.\n- ✅ `split-window` / `split-pane` → native iTerm2 splits.\n- ✅ Cmd-T (new tmux window/tab), Cmd-D (split), Cmd-W (kill pane), etc.\n When you press Cmd-T in a tmux-attached pane, iTerm2 prompts\n **\"New tmux Tab / Use Default Profile / Cancel\"** — picking\n *New tmux Tab* opens a new native tab backed by a fresh tmux\n window via `new-window -PF '#{window_id}'`.\n- ✅ Drag-resizing the native iTerm2 window resizes all panes\n inside it. iTerm2 sends `refresh-client -C w,h` (on attach) and\n `resize-window -x w -y h -t @N` (on every drag) and psmux\n propagates the new geometry to every pane and emits\n `%layout-change` so the splits repaint.\n- ✅ Typing `exit` (or otherwise terminating the shell) in a pane\n removes that split natively in iTerm2. psmux diffs window state\n on every reap cycle and emits `%layout-change` /\n `%window-pane-changed` (or `%window-close` for the last pane in\n a window) so iTerm2 stays in sync.\n- ✅ Native iTerm2 scrollback, copy-mode (⌘F find), Touch Bar, tab\n reordering — all work because iTerm2 renders the panes locally.\n- ✅ Keyboard input including Enter, Tab, Backspace, arrow keys,\n Ctrl chords, function keys, and Alt sequences.\n- ✅ ANSI escape sequences (cursor moves, colors, mouse reporting,\n bracketed paste) round-trip correctly to the shell.\n- ✅ Reconnecting after network drop: re-run the SSH command and\n iTerm2 re-attaches to the live psmux session.\n\n---\n\n## Known quirks\n\n### First prompt of a new pane appears at the top\n\nWhen iTerm2 first opens a tmux pane (initial connection or a fresh\nCmd-T tab), the first shell prompt is rendered at the **top** of\nthe pane. After you press Enter once, the next prompt jumps to the\n**bottom** and subsequent output behaves normally.\n\nThis is intrinsic ConPTY behaviour, not a psmux bug. ConPTY starts\nthe Windows console buffer with the cursor at row 0; pwsh prints\nits first prompt there. `capture-pane` faithfully reports a single\nrow of content, so iTerm2 paints it at the top. Once the shell\nemits its first newline, ConPTY's normal scroll-region behaviour\ntakes over and the prompt settles at the bottom of the visible\nregion. Real tmux running against pwsh through ConPTY shows the\nsame thing.\n\n---\n\n## Troubleshooting\n\n### `Detached` immediately after `** tmux mode started **`\n\nAlmost always one of:\n\n1. **Forgot `stty raw -echo -isig`** — iTerm2's `\\x03` was caught by\n the local TTY and converted to SIGINT.\n2. **Used `ssh -t` instead of `ssh -T`** — ConPTY ate the DCS bytes.\n3. **Wrong path to psmux.exe** — use forward slashes inside the SSH\n single-quoted command: `'C:/Users/you/psmux.exe -CC'`.\n\n### Inspecting the protocol log\n\npsmux writes a verbose dump of every CC command and `%output` to\n`%USERPROFILE%\\.psmux\\cc_debug.log` on the Windows side. Tail it:\n\n```sh\nssh user@windows-host 'Get-Content -Wait $env:USERPROFILE\\.psmux\\cc_debug.log'\n```\n\nLook for:\n- `unknown command:` — psmux didn't recognize a CC command iTerm2\n sent. Please open an issue with the line.\n- `FATAL:` — control-mode bootstrap failed (port file missing,\n auth rejected, etc.).\n- `IN (N bytes):` — a hex dump of bytes iTerm2 sent.\n- `OUT (N bytes):` — a quoted dump of bytes psmux sent back.\n\n### Arrow keys / function keys printing literal characters\n\nFixed in psmux ≥ 3.4 (commit referenced from issue #261). If you\nsee `[A` instead of recall-previous-command, you're on an older\nbuild — pull, rebuild, redeploy.\n\n### Garbled output after attaching\n\nMake sure the macOS-side `stty` setup runs **before** SSH and that\nthe iTerm2 profile isn't re-cooking the TTY (e.g. don't add\n`stty sane` to your `.zprofile`).\n\n---\n\n## Implementation notes (for contributors)\n\nThese are the pieces of psmux that make iTerm2's `tmux -CC` happy:\n\n- **`run_control_mode`** in `src/main.rs` — TCP/AUTH client +\n CONTROL_NOECHO handshake + raw-mode setup + stdin `\\r→\\n`\n translation + `cc_debug.log`.\n- **iTerm CC command surface** in `src/server/connection.rs`:\n - `phony-command`, `copy-mode`, `resize-window` no-op handlers\n (iTerm2 sends these during kickoff).\n - `send` alias for `send-keys` (iTerm uses the short form).\n - `0xNN` hex codepoint argument decoding (every iTerm keystroke).\n - Combined short-flag clusters where the **last** char takes a\n value: `new-window -PF '#{window_id}'`,\n `capture-pane -peqJN -t %1 -S -1000`, `send -lt %1 X` etc.\n Parsed by `cli::has_short_flag` and the cluster-tail branch\n of `cli::extract_flag_value`.\n - `refresh-client -C w,h` and `resize-window -x w -y h -t @N`\n update `app.last_window_area`, run `resize_all_panes`, and\n emit `%layout-change` so the gateway always stays in sync\n with the iTerm2 window's actual cell dimensions.\n - Top-level `;` command separation with a queue (one\n `%begin/%end` pair per sub-command).\n - **Send-coalescing**: consecutive `send`/`send-keys` sub-commands\n on a single input line are merged into one PTY write so VT\n sequences like `\\x1b[A` arrive atomically. Without this,\n PSReadLine in pwsh times out between the ESC and the\n `[A` and prints them as literal characters.\n- **`%subscription-changed`** format in `src/control.rs` — uses `:`\n separator (iTerm requires colon, not dash).\n- **Pane-death notifications** in `src/server/mod.rs` reap loop —\n snapshots `(window_id, active_pane_id, leaf_count)` per window\n before `tree::reap_children`, then diffs after to emit\n `%layout-change` / `%window-pane-changed` / `%window-close` /\n `%session-window-changed` to control-mode clients. Without this,\n shells that exit naturally (`exit` in pwsh) leave dead splits\n visible in iTerm2 forever.\n- **ConPTY raw mode** in `src/main.rs` — when stdin is a console\n handle (e.g. `ssh -t`), clear `ENABLE_PROCESSED_INPUT |\n ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT` and set\n `ENABLE_VIRTUAL_TERMINAL_INPUT`; on stdout set\n `ENABLE_VIRTUAL_TERMINAL_PROCESSING |\n DISABLE_NEWLINE_AUTO_RETURN`. This makes the `ssh -t` path also\n work, though `ssh -T` is preferred.\n"
},
{
"path": "docs/keybindings.md",
"content": "# Key Bindings\n\nDefault prefix: `Ctrl+b` (same as tmux). Change with `set -g prefix C-a`.\n\nSupported prefix keys include `C-a` through `C-z`, `C-Space`, and any printable character.\n\n## Case Sensitivity\n\nKey bindings are **case-sensitive**, matching tmux behavior:\n\n- `bind-key t` binds to lowercase `t` (just press `t`)\n- `bind-key T` binds to uppercase `T` (`Shift+t`)\n\nThis is essential for plugins like PPM (`Prefix+I`/`Prefix+U`) and psmux-sensible (`Prefix+R`).\n\n## Prefix Keys\n\n### Window Management\n\n| Key | Action |\n|-----|--------|\n| `Prefix + c` | Create new window |\n| `Prefix + n` | Next window |\n| `Prefix + p` | Previous window |\n| `Prefix + l` | Last (previously active) window |\n| `Prefix + w` | Interactive session/window/pane chooser (`choose-tree`) |\n| `Prefix + &` | Kill current window (with confirmation) |\n| `Prefix + ,` | Rename current window |\n| `Prefix + '` | Prompt for window index (jump to any window) |\n| `Prefix + 0-9` | Select window by number |\n\n### Pane Splitting\n\n| Key | Action |\n|-----|--------|\n| `Prefix + %` | Split pane left/right (horizontal) |\n| `Prefix + \"` | Split pane top/bottom (vertical) |\n\n### Pane Navigation\n\n| Key | Action |\n|-----|--------|\n| `Prefix + Arrow` | Navigate between panes (Up/Down/Left/Right), wraps at edges |\n| `Prefix + o` | Select next pane (rotate) |\n| `Prefix + ;` | Last (previously active) pane |\n| `Prefix + q` | Display pane numbers (type number to switch, auto-dismisses) |\n\n### Pane Management\n\n| Key | Action |\n|-----|--------|\n| `Prefix + x` | Kill current pane (with confirmation) |\n| `Prefix + z` | Toggle pane zoom (fullscreen) |\n| `Prefix + {` | Swap pane up |\n| `Prefix + }` | Swap pane down |\n| `Prefix + !` | Break pane out to new window |\n\n### Pane Resize\n\n| Key | Action |\n|-----|--------|\n| `Prefix + Ctrl+Arrow` | Resize pane by 1 cell |\n| `Prefix + Alt+Arrow` | Resize pane by 5 cells |\n\n### Layout\n\n| Key | Action |\n|-----|--------|\n| `Prefix + Space` | Cycle to next layout |\n| `Prefix + Alt+1` | Even-horizontal layout |\n| `Prefix + Alt+2` | Even-vertical layout |\n| `Prefix + Alt+3` | Main-horizontal layout |\n| `Prefix + Alt+4` | Main-vertical layout |\n| `Prefix + Alt+5` | Tiled layout |\n\n### Session\n\n| Key | Action |\n|-----|--------|\n| `Prefix + d` | Detach from session |\n| `Prefix + $` | Rename session |\n| `Prefix + s` | Session chooser/switcher (`choose-tree -s`) |\n| `Prefix + (` | Switch to previous session |\n| `Prefix + )` | Switch to next session |\n\n### Copy / Paste\n\n| Key | Action |\n|-----|--------|\n| `Prefix + [` | Enter copy/scroll mode |\n| `Prefix + ]` | Paste from buffer |\n| `Prefix + =` | Interactive buffer chooser |\n\n### Miscellaneous\n\n| Key | Action |\n|-----|--------|\n| `Prefix + :` | Command prompt (with cursor, arrow key navigation, and history) |\n| `Prefix + ?` | List keybindings (help overlay) |\n| `Prefix + i` | Display window/pane info |\n| `Prefix + t` | Clock mode |\n| `Prefix + !` | Break pane out to new window |\n\n### Repeat Bindings\n\nNavigation and resize bindings support **repeat mode**: after pressing the prefix key once, successive keypresses within the `repeat-time` window (default 500ms) trigger the action without needing to re-enter the prefix. This applies to arrow-based pane navigation and resize bindings by default.\n\n## Picker Navigation (choose-session, choose-tree, choose-buffer, list-keys, customize)\n\nOnce a picker is open (`Prefix + s`, `Prefix + w`, `Prefix + =`, `Prefix + ?`, or `customize-mode`), the following keys move the selection. This matches tmux's `mode-tree` behavior, so muscle memory carries over.\n\n| Key | Action |\n|-----|--------|\n| `Up` / `k` / `h` | Move selection up |\n| `Down` / `j` / `l` | Move selection down |\n| `g` / `Home` | Jump to first entry |\n| `G` / `End` | Jump to last entry |\n| `PageUp` / `PageDown` | Page up / down |\n| `1`..`9`, `0` | Append digit to jump buffer (Enter consumes it) |\n| `Backspace` | Edit the jump buffer |\n| `Enter` | Switch to the selected entry (or to the jump buffer index if non-empty) |\n| `p` | Toggle live preview (choose-session / choose-tree only) |\n| `x` | Kill selected session (choose-session only) |\n| `d` / `Delete` | Delete selected buffer (choose-buffer only) |\n| `Esc` / `q` | Close the picker |\n\n## Command Prompt\n\nPress `Prefix + :` to open the command prompt at the bottom of the screen. You can type any psmux/tmux command here.\n\n### Command Prompt Editing Keys\n\n| Key | Action |\n|-----|--------|\n| `Left` / `Right` | Move cursor within the command |\n| `Home` / `Ctrl+A` | Jump to start of line |\n| `End` / `Ctrl+E` | Jump to end of line |\n| `Backspace` | Delete character before cursor |\n| `Delete` | Delete character at cursor |\n| `Up` / `Down` | Browse command history (previous/next) |\n| `Tab` | Command name completion |\n| `Enter` | Execute the command |\n| `Escape` | Cancel and close the prompt |\n\nThe command prompt remembers your history across the session. Use Up/Down arrows to recall previous commands.\n\nYou can run any command from the prompt that you would run from the CLI. For example:\n\n- `:split-window -h` to split horizontally\n- `:new-window -n logs` to create a named window\n- `:source-file ~/.psmux.conf` to reload your config\n- `:set -g status-style \"bg=blue\"` to change a setting live\n- `:list-keys` to see all current key bindings\n\n## Copy/Scroll Mode (Vi)\n\nEnter copy mode with `Prefix + [` to scroll through terminal history with vim-style keybindings.\n\nMouse scroll wheel also enters copy mode by default. To disable this, set `scroll-enter-copy-mode off` in your config.\n\n### Cursor Movement\n\n| Key | Action |\n|-----|--------|\n| `h` / `Left` | Move cursor left |\n| `j` / `Down` | Move cursor down |\n| `k` / `Up` | Move cursor up |\n| `l` / `Right` | Move cursor right |\n\n### Word Motions\n\n| Key | Action |\n|-----|--------|\n| `w` / `b` / `e` | Next word / prev word / end of word |\n| `W` / `B` / `E` | WORD variants (whitespace-delimited) |\n\n### Line Motions\n\n| Key | Action |\n|-----|--------|\n| `0` / `Home` | Start of line |\n| `$` / `End` | End of line |\n| `^` | First non-blank character |\n\n### Scrolling\n\n| Key | Action |\n|-----|--------|\n| `Ctrl+u` / `Ctrl+d` | Half page up / down |\n| `Ctrl+b` / `PageUp` | Full page up |\n| `Ctrl+f` / `PageDown` | Full page down |\n| `g` | Top of scrollback |\n| `G` | Bottom (live output) |\n\n### Screen Position\n\n| Key | Action |\n|-----|--------|\n| `H` | Jump to top of visible area |\n| `M` | Jump to middle of visible area |\n| `L` | Jump to bottom of visible area |\n\n### Character Find\n\n| Key | Action |\n|-----|--------|\n| `f{char}` / `F{char}` | Find char forward / backward |\n| `t{char}` / `T{char}` | Till char forward / backward |\n\n### Bracket / Paragraph\n\n| Key | Action |\n|-----|--------|\n| `%` | Jump to matching bracket (`()`, `[]`, `{}`, `<>`) |\n| `{` | Jump to previous paragraph (blank line) |\n| `}` | Jump to next paragraph (blank line) |\n\n### Selection\n\n| Key | Action |\n|-----|--------|\n| `Space` | Begin character selection |\n| `v` | Toggle rectangle selection |\n| `V` | Line selection |\n| `Ctrl+v` | Toggle rectangle selection |\n| `o` | Swap cursor/anchor ends |\n\n### Yank (Copy)\n\n| Key | Action |\n|-----|--------|\n| `y` / `Enter` | Copy selection and exit |\n| `D` | Copy to end of line and exit |\n| `A` | Append selection to buffer |\n\n### Search\n\n| Key | Action |\n|-----|--------|\n| `/` | Search forward |\n| `?` | Search backward |\n| `n` / `N` | Next / previous match |\n\n### Text Objects & Registers\n\n| Key | Action |\n|-----|--------|\n| `\"a`–`\"z` | Named registers (set register for next yank) |\n| `aw` / `iw` | Select a word / inner word |\n| `aW` / `iW` | Select a WORD / inner WORD |\n| `1`–`9` | Numeric prefix for motions (up to 9999) |\n\n### Exit\n\n| Key | Action |\n|-----|--------|\n| `Esc` / `q` | Exit copy mode |\n| `Ctrl+C` / `Ctrl+G` | Exit copy mode |\n\n### Copy Mode Search Input\n\n| Key | Action |\n|-----|--------|\n| `Esc` | Cancel search |\n| `Enter` | Accept search / jump to match |\n| `Backspace` | Delete character |\n| Any char | Append to search pattern |\n\n### Emacs Copy Mode\n\nWhen `set mode-keys emacs`, additional bindings are available:\n\n| Key | Action |\n|-----|--------|\n| `Ctrl+N` / `Ctrl+P` | Scroll down / up 1 line |\n| `Ctrl+A` / `Ctrl+E` | Line start / end |\n| `Ctrl+V` | Page down |\n| `Alt+V` | Page up |\n| `Alt+F` / `Alt+B` | Word forward / backward |\n| `Alt+W` | Yank and exit |\n| `Ctrl+S` / `Ctrl+R` | Search forward / backward |\n\nWhen in copy mode:\n- The pane border turns **yellow**\n- `[copy mode]` appears in the title\n- A scroll position indicator shows in the top-right corner\n- Mouse drag-select copies to Windows clipboard on release\n\n## Command Prompt\n\nOpen with `Prefix + :`:\n\n| Key | Action |\n|-----|--------|\n| `Esc` | Cancel |\n| `Enter` | Execute command (saved to history) |\n| `Backspace` / `Delete` | Delete character |\n| `Left` / `Right` | Move cursor |\n| `Home` / `Ctrl+A` | Start of line |\n| `End` / `Ctrl+E` | End of line |\n| `Up` / `Down` | Cycle command history |\n| `Ctrl+U` | Kill line (clear to start) |\n| `Ctrl+K` | Kill to end of line |\n| `Ctrl+W` | Delete word backward |\n\n## Mouse Bindings\n\nWhen `mouse on` (default):\n\n| Action | Behavior |\n|--------|----------|\n| Left-click status tab | Switch to clicked window |\n| Left-click pane | Focus that pane |\n| Left-click/drag border | Resize split interactively |\n| Scroll up/down | Scroll pane (or enter copy mode at prompt) |\n| Mouse drag in copy mode | Select text → auto-copy on release |\n| Right-click | Paste clipboard |\n\n## Supported Key Names\n\nKey names for `bind-key` and `send-keys`:\n\n| Key | Name |\n|-----|------|\n| Arrow keys | `Up`, `Down`, `Left`, `Right` |\n| Function keys | `F1` through `F12` |\n| Special keys | `Enter`, `Tab`, `Escape`, `Space`, `Backspace` |\n| Navigation | `Home`, `End`, `PageUp`, `PageDown`, `Insert`, `Delete` |\n| Ctrl modifier | `C-a` through `C-z`, `C-Space` |\n| Alt modifier | `M-a` through `M-z`, `M-Left`, `M-Right`, etc. |\n| Shift+key | Use uppercase letter: `T` for `Shift+t` |\n| Shift+Enter | `S-Enter` (sends proper escape sequence) |\n| Shift+Tab | `BTab` (sends `ESC [ Z`) |\n\n## Custom Key Bindings\n\n```tmux\n# Bind in prefix table (default)\nbind-key h split-window -h\nbind-key v split-window -v\n\n# Bind in root table (no prefix needed)\nbind-key -n C-h select-pane -L\n\n# Repeatable binding (stay in prefix mode)\nbind-key -r H resize-pane -L 5\n\n# Unbind a key\nunbind-key C-b\n\n# Unbind all\nunbind-key -a\n```\n\n## Confirmation Prompts (confirm-before)\n\nBy default, destructive keybindings like `Prefix + x` (kill-pane) and `Prefix + &` (kill-window) show a y/n confirmation prompt before executing. This uses the `confirm-before` wrapper, matching tmux behavior.\n\n### Skipping Confirmation\n\nTo bind kill commands **without** confirmation, bind the command directly in your config:\n\n```tmux\n# Kill pane immediately (no y/n prompt)\nbind-key x kill-pane\n\n# Kill window immediately (no y/n prompt)\nbind-key & kill-window\n\n# Kill session on a custom key (no prompt)\nbind-key X kill-session\n```\n\n### Adding Confirmation to Any Command\n\nYou can wrap any command with `confirm-before` to require y/n confirmation:\n\n```tmux\n# Confirm before killing pane (this is the default)\nbind-key x confirm-before -p 'kill-pane #P? (y/n)' kill-pane\n\n# Confirm before killing window (this is the default)\nbind-key & confirm-before -p 'kill-window #W? (y/n)' kill-window\n\n# Confirm before killing session\nbind-key X confirm-before -p 'kill-session? (y/n)' kill-session\n\n# Confirm before detaching\nbind-key d confirm-before -p 'detach? (y/n)' detach-client\n```\n\nThe `-p` flag sets a custom prompt string. Without it, a generic prompt is shown.\n"
},
{
"path": "docs/mouse-ssh.md",
"content": "# Mouse Over SSH\n\npsmux has **first-class mouse support over SSH** when the server runs **Windows 11 build 22523+ (22H2+)**. Click panes, drag-resize borders, scroll, click tabs — everything works, from any SSH client on any OS.\n\n## Compatibility\n\n### Remote access (over SSH)\n\n| Client → Server | Keyboard | Mouse | Notes |\n|---|:---:|:---:|---|\n| Linux → Windows 11 (22523+) | ✅ | ✅ | Full support |\n| macOS → Windows 11 (22523+) | ✅ | ✅ | Full support |\n| Windows 10 → Windows 11 (22523+) | ✅ | ✅ | Full support |\n| Windows 11 → Windows 11 (22523+) | ✅ | ✅ | Full support |\n| WSL → Windows 11 (22523+) | ✅ | ✅ | Full support |\n| Any OS → Windows 10 | ✅ | ❌ | ConPTY limitation (see below) |\n| Any OS → Windows 11 (pre-22523) | ✅ | ❌ | ConPTY limitation (see below) |\n\n### Local use (no SSH)\n\n| Platform | Keyboard | Mouse |\n|---|:---:|:---:|\n| Windows 11 (local) | ✅ | ✅ |\n| Windows 10 (local) | ✅ | ✅ |\n\nMouse works perfectly when running psmux locally on both Windows 10 and 11.\n\n## Why No Mouse Over SSH on Windows 10?\n\nWindows 10's ConPTY consumes mouse-enable escape sequences internally and does not forward them to sshd. The SSH client never receives the signal to start sending mouse data. This is a Windows 10 ConPTY limitation that was fixed in Windows 11 (build 22523+). Keyboard input works fully on both versions — only mouse over SSH is affected.\n\n> **Recommendation:** Use Windows 11 build 22523+ (22H2 or later) as your psmux server for full SSH mouse support.\n"
},
{
"path": "docs/multi-shell.md",
"content": "# Multi-Shell Workflows\n\npsmux lets you run **any combination of shells** side by side in the same session.\nPowerShell, Git Bash, cmd.exe, WSL, Nushell, or any other shell or program,\neach in its own pane, window, or session. Switch between them instantly.\n\n```\n +-----------------------+-----------------------+\n | PowerShell 7 | Git Bash |\n | PS C:\\project> ... | user@pc ~/project $ |\n | | |\n +-----------------------+-----------------------+\n | cmd.exe | WSL (Ubuntu) |\n | C:\\project> | user@pc:~/project$ |\n | | |\n +-----------------------+-----------------------+\n [0] pwsh* [1] bash [2] node [3] python\n```\n\n## Setting Your Default Shell\n\nAdd one line to `~/.psmux.conf`:\n\n```tmux\n# Git Bash\nset -g default-shell \"C:/Program Files/Git/bin/bash.exe\"\n\n# Git Bash (backslashes work too)\nset -g default-shell \"C:\\Program Files\\Git\\bin\\bash.exe\"\n\n# Git Bash with login profile\nset -g default-shell \"C:/Program Files/Git/bin/bash.exe\" --login\n\n# cmd.exe\nset -g default-shell cmd.exe\n\n# PowerShell 7 (the default if nothing is set)\nset -g default-shell pwsh\n\n# Windows PowerShell 5\nset -g default-shell powershell\n\n# Nushell\nset -g default-shell nu\n\n# WSL default distro\nset -g default-shell wsl\n```\n\nBare names like `bash`, `pwsh`, `cmd`, `nu`, `wsl` are resolved via PATH.\nFull paths with spaces must be wrapped in quotes. Both forward slashes and\nbackslashes are supported.\n\n## Changing the Shell at Runtime\n\nYou don't need to restart psmux to switch shells. Press `Prefix + :` (default\n`Ctrl+B` then `:`) to open the command prompt, then type:\n\n```tmux\nset -g default-shell \"C:/Program Files/Git/bin/bash.exe\"\n```\n\nEvery new window and pane created after this will use the new shell.\nExisting panes keep their current shell.\n\n## Mix and Match: Different Shells in Different Panes\n\nThis is where psmux really shines. You can override the default shell for\nany individual window or pane by passing the shell as a command:\n\n### From the command prompt (`Prefix + :`)\n\n```tmux\n# Open a new Git Bash window while your default is pwsh\nnew-window \"C:/Program Files/Git/bin/bash.exe\"\n\n# Split the current pane and run cmd.exe in the new split\nsplit-window cmd.exe\n\n# Split horizontally and run WSL\nsplit-window -h wsl\n\n# Open a new window running Python\nnew-window python\n\n# Open a new window running Node.js REPL\nnew-window node\n```\n\n### From the CLI (PowerShell, cmd, or any terminal)\n\n```powershell\n# Create a bash window in an existing session\npsmux new-window -- \"C:/Program Files/Git/bin/bash.exe\"\n\n# Split with cmd.exe\npsmux split-window -- cmd.exe\n\n# Create a whole new session running WSL\npsmux new-session -s linux -- wsl\n\n# Launch a Python REPL in a split pane\npsmux split-window -- python\n```\n\n### From your config file (`~/.psmux.conf`)\n\n```tmux\n# Default shell is PowerShell\nset -g default-shell pwsh\n\n# Bind keys to quickly open specific shells\nbind-key B new-window \"C:/Program Files/Git/bin/bash.exe\"\nbind-key C new-window cmd.exe\nbind-key W new-window wsl\nbind-key N new-window nu\n\n# Bind keys for splitting with a specific shell\nbind-key b split-window -v \"C:/Program Files/Git/bin/bash.exe\"\nbind-key c split-window -v cmd.exe\n```\n\nNow `Prefix + B` opens a bash window, `Prefix + C` opens cmd, etc.\n\n## Real-World Use Cases\n\n### Web Development\n\nYour default shell is PowerShell for project management, but you need bash\nfor your build tools and Node scripts:\n\n```tmux\n# ~/.psmux.conf\nset -g default-shell pwsh\n\n# Quick access to bash for npm/node\nbind-key B new-window \"C:/Program Files/Git/bin/bash.exe\" --login\nbind-key b split-window -v \"C:/Program Files/Git/bin/bash.exe\" --login\n```\n\nWorkflow:\n1. Window 0 (pwsh): `git status`, `dotnet build`, project management\n2. `Prefix + B` to open Window 1 (bash): `npm run dev`\n3. `Prefix + b` to split (bash): `npm test` running alongside\n4. `Prefix + :` then `split-window node` for a quick Node REPL\n\n### DevOps / Infrastructure\n\nMix WSL Linux tools with native Windows admin shells:\n\n```tmux\nset -g default-shell pwsh\n\nbind-key L new-window wsl\nbind-key l split-window -v wsl\n```\n\nWorkflow:\n1. Window 0 (pwsh): Azure/AWS CLI, Windows admin tasks\n2. `Prefix + L` for Window 1 (WSL): `kubectl`, `docker`, `terraform`\n3. Split both windows as needed for logs, monitoring, editors\n\n### Cross-Platform Testing\n\nTest your scripts in every shell without leaving your session:\n\n```tmux\nbind-key F1 new-window pwsh\nbind-key F2 new-window \"C:/Program Files/Git/bin/bash.exe\"\nbind-key F3 new-window cmd.exe\nbind-key F4 new-window wsl\n```\n\n### Dedicated Tool Windows\n\nRun long-running tools in their own shells:\n\n```tmux\n# Quick launch for common tools\nbind-key P new-window python\nbind-key J new-window node\nbind-key S new-window \"C:/Program Files/Git/bin/bash.exe\" -c \"ssh myserver\"\n```\n\n## Multiple Sessions with Different Defaults\n\nYou can also create entirely separate sessions, each with its own default shell:\n\n```powershell\n# Session for PowerShell work\npsmux new-session -d -s work\n\n# Session for Linux/bash work\npsmux new-session -d -s linux -- wsl\n\n# Session for a specific project using bash\npsmux new-session -d -s webapp -- \"C:/Program Files/Git/bin/bash.exe\" --login\n```\n\nSwitch between sessions with `Prefix + s` (session picker) or `Prefix + (` / `)`.\n\n## Supported Shells\n\npsmux works with any program that reads from stdin and writes to stdout.\nHere are common shells and how to configure them:\n\n| Shell | Config Value | Notes |\n|-------|-------------|-------|\n| PowerShell 7 | `pwsh` | Default. Fastest startup with psmux optimizations |\n| Windows PowerShell 5 | `powershell` | Built into Windows |\n| Git Bash | `\"C:/Program Files/Git/bin/bash.exe\"` | Quotes required (path has spaces) |\n| Git Bash (login) | `\"C:/Program Files/Git/bin/bash.exe\" --login` | Loads `.bash_profile` |\n| cmd.exe | `cmd` or `cmd.exe` | Classic Windows command prompt |\n| WSL | `wsl` | Launches your default WSL distro |\n| WSL (specific distro) | `wsl -d Ubuntu` | Specify a distro by name |\n| Nushell | `nu` | Modern structured-data shell |\n| Fish | `\"C:/path/to/fish.exe\"` | If installed via MSYS2/Cygwin |\n| Python REPL | `python` | Not a shell, but works great in a pane |\n| Node.js REPL | `node` | Same, useful for quick JS testing |\n\n## Tips\n\n- **Paths with spaces** must be wrapped in double quotes: `\"C:/Program Files/...\"`\n- **Forward slashes and backslashes** both work: `C:/Program Files` and `C:\\Program Files` are equivalent\n- **Bare names** like `bash`, `pwsh`, `cmd`, `nu` are resolved via your system PATH\n- **Extra arguments** go after the path: `\"C:/Program Files/Git/bin/bash.exe\" --login`\n- **Changing default-shell at runtime** only affects new panes/windows. Existing ones keep their shell\n- **Each pane is independent**. Closing a bash pane does not affect your pwsh panes\n- **Environment variables** (`TMUX`, `PSMUX_SESSION`, `TERM`) are set correctly in all shell types\n- **Pane titles differ by shell**: PowerShell 7 sets the pane title to the CWD on every prompt, while cmd.exe and nushell do not. See [pane-titles.md](pane-titles.md) for how this affects your status bar and how to control it\n"
},
{
"path": "docs/pane-titles.md",
"content": "# Pane Titles and OSC Escape Sequences\n\n## How Pane Titles Work\n\nEvery pane in psmux has a **title**. By default this is the system hostname, matching tmux convention. You can see it in the status bar, pane border labels, and format variables like `#{pane_title}` and `#T`.\n\nPrograms running inside a pane can change its title by sending **OSC (Operating System Command) escape sequences**:\n\n| Sequence | Name | Effect |\n|----------|------|--------|\n| `ESC ] 0 ; <title> BEL` | OSC 0 | Sets both the window icon name and the pane title |\n| `ESC ] 2 ; <title> BEL` | OSC 2 | Sets the pane title |\n\nWhen psmux receives one of these from a child process, it updates `pane_title` so that format variables, status bar, and border labels all reflect the new value.\n\n## PowerShell and OSC Titles\n\nHere is the important part for Windows users: **PowerShell 7 sends OSC 0 automatically on every single prompt**. It sets the terminal title to the current working directory (e.g. `C:\\Users\\you\\Projects\\myapp`).\n\nThis means that if your status bar format references `#{pane_title}` or `#T`, you will see a truncated file path instead of the hostname. For example, with the tmux default status right format `\"#{=21:pane_title}\" %H:%M %d-%b-%y`, you would see something like:\n\n```\n\"C:\\Program Files\\Powe\" 19:39 17-Apr-26\n```\n\ninstead of:\n\n```\n\"DESKTOP-ABC1234\" 19:39 17-Apr-26\n```\n\nThis is not a bug. It is the expected behavior: PowerShell tells the terminal \"my title is this path\" and psmux faithfully applies it. On Linux, bash and zsh do not send OSC title sequences by default, so tmux users on Linux almost always see the hostname in that position.\n\n**psmux's own default `status-right`** uses `\"#H\"` (the `#H` hostname shorthand) instead of `\"#{=21:pane_title}\"`, and **`allow-set-title` defaults to `off`**, so the default psmux experience avoids this issue entirely. You will only encounter this if you set `allow-set-title on` in your config, or if you use a tmux config or theme that enables it and references `#{pane_title}` or `#T` in the status bar.\n\n## Options That Control This Behavior\n\n### `allow-set-title` (default: `off`)\n\nControls whether programs can update the pane title via OSC 0/2 sequences. When `off` (the default), OSC title sequences are ignored and `pane_title` stays at the hostname or whatever was set via `select-pane -T`. Set to `on` if you want programs to dynamically update the pane title.\n\n```tmux\n# Allow programs to change pane titles via OSC sequences\nset -g allow-set-title on\n```\n\n### `select-pane -T` (title lock)\n\nSetting a pane title manually with `select-pane -T` **locks** that title. After locking, OSC sequences from child processes will not overwrite it. This lets you label specific panes permanently.\n\n```tmux\n# Lock a pane's title\nselect-pane -T \"build output\"\n\n# Clear the lock (title reverts to hostname, OSC sequences can update it again)\nselect-pane -T \"\"\n```\n\n### `allow-rename` (default: `on`)\n\nControls whether programs can rename the **window** (not the pane) via escape sequences. This is separate from `allow-set-title` which controls the pane title.\n\n## Controlling PowerShell's Title Behavior\n\nBy default, `allow-set-title` is `off`, so PowerShell's OSC title sequences are ignored and you will see the hostname. If you enable `allow-set-title on` for dynamic titles but want to stop PowerShell specifically from overwriting the title with the CWD, you have several options:\n\n### Option 1: Disable pwsh's window title in your PowerShell profile\n\nAdd this to your `$PROFILE`:\n\n```powershell\n# Prevent PowerShell from setting the terminal title\n$PSStyle.WindowTitle = ''\n```\n\nOr for older PowerShell versions:\n\n```powershell\nfunction prompt {\n # Your custom prompt here, without setting WindowTitle\n \"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) \"\n}\n```\n\n### Option 2: Turn off OSC title propagation globally (this is the default)\n\n```tmux\n# In ~/.psmux.conf (this is already the default, shown here for reference)\nset -g allow-set-title off\n```\n\nThis keeps `pane_title` at the hostname (or whatever you set with `select-pane -T`). No program can change it via escape sequences.\n\n### Option 3: Use `#H` instead of `#{pane_title}` in your status bar\n\nIf your theme or config uses `#{pane_title}` in the status bar and you want the hostname there instead, replace it:\n\n```tmux\n# Before (shows CWD from pwsh):\nset -g status-right '\"#{=21:pane_title}\" %H:%M %d-%b-%y'\n\n# After (always shows hostname):\nset -g status-right '\"#H\" %H:%M %d-%b-%y'\n```\n\n`#H` always resolves to the system hostname regardless of OSC sequences.\n\n### Option 4: Lock specific pane titles\n\n```tmux\n# Set and lock a title on a pane\nselect-pane -T \"my server\"\n\n# Now OSC sequences from pwsh won't overwrite it\n```\n\n## Where `pane_title` Appears\n\nThe pane title is exposed through several format variables and locations:\n\n| Variable | Description |\n|----------|-------------|\n| `#{pane_title}` | Full pane title |\n| `#T` | Alias for the active pane's title |\n| `#{=21:pane_title}` | Pane title truncated to 21 characters |\n\nThese can appear in:\n\n- **`status-right`** and **`status-left`**: the status bar at the bottom (or top) of the screen\n- **`pane-border-format`**: labels on pane borders (when `pane-border-status` is `top` or `bottom`)\n- **`window-status-format`** and **`window-status-current-format`**: window tab labels\n- **`display-message -p`**: programmatic queries\n- **`list-panes -F`** and **`list-windows -F`**: scripting and automation\n\n## How Different Shells Behave\n\n| Shell | Sends OSC title? | Content |\n|-------|-------------------|---------|\n| PowerShell 7 (pwsh) | Yes, on every prompt | Current working directory |\n| PowerShell 5 | No | N/A |\n| cmd.exe | No | N/A |\n| Git Bash | Depends on config | Usually `user@host:path` |\n| WSL bash | Depends on config | Usually `user@host:path` |\n| Nushell | No | N/A |\n\n## Interaction With Other Features\n\n### Automatic Window Rename\n\n`automatic-rename` (default: `on`) renames the **window** based on the foreground process. This is separate from the pane title. A window can be named \"pwsh\" while the pane title shows the hostname or CWD.\n\n### Pane Border Labels\n\nIf you use `pane-border-format` with `#{pane_title}`, the border labels will update live as OSC titles change. This can be useful for showing what directory each pane is working in:\n\n```tmux\nset -g pane-border-status top\nset -g pane-border-format \" #{pane_index}: #{pane_title} \"\n```\n\n### Tmux Themes\n\nMany tmux themes (Catppuccin, Dracula, Tokyo Night, etc.) use `#{pane_title}` in their status bar formats. On Windows with PowerShell, this will show the CWD instead of the hostname. Check your theme's configuration for options to customize which variables appear in the status bar, or use `allow-set-title off` as described above.\n\n## Quick Reference\n\n| Goal | Config |\n|------|--------|\n| Keep hostname in status bar (default) | `allow-set-title` is already `off` by default |\n| Let programs set titles dynamically | `set -g allow-set-title on` |\n| Always show hostname (regardless of config) | Use `#H` instead of `#{pane_title}` |\n| Stop pwsh from setting title | Add `$PSStyle.WindowTitle = ''` to `$PROFILE` |\n| Lock a specific pane's title | `select-pane -T \"my title\"` |\n| Show CWD in pane borders (useful!) | `set -g pane-border-format \" #{pane_index}: #{pane_title} \"` |\n| Let programs set titles (default) | `set -g allow-set-title on` |\n"
},
{
"path": "docs/performance.md",
"content": "# Performance\n\npsmux is built for speed. The Rust release binary is compiled with **opt-level 3**, **full LTO**, and **single codegen unit**. Every cycle counts.\n\n| Metric | psmux | Notes |\n|--------|-------|-------|\n| **Session creation** | **< 100ms** | Time for `new-session -d` to return |\n| **New window** | **< 80ms** | Overhead on top of shell startup |\n| **New pane (split)** | **< 80ms** | Same as window, cached shell resolution |\n| **Startup to prompt** | **~shell launch time** | psmux adds near-zero overhead; bottleneck is your shell |\n| **15+ windows** | ✅ Stable | Stress-tested with 15+ rapid windows, 18+ panes, 5 concurrent sessions |\n| **Rapid fire creates** | ✅ No hangs | Burst-create windows/panes without delays or orphaned processes |\n\n## How It's Fast\n\n- **Lazy pane resize**: only the active window's panes are resized. Background windows resize on-demand when switched to, avoiding O(n) ConPTY syscalls\n- **Cached shell resolution**: `which` PATH lookups are cached with `OnceLock`, not repeated per spawn\n- **10ms polling**: client-server discovery uses tight 10ms polling for sub-100ms session attach\n- **Early port-file write**: server writes its discovery file *before* spawning the first shell, so the client connects instantly\n- **8KB reader buffers**: small buffer size minimizes mutex contention across pane reader threads\n\n> **Note:** The primary startup bottleneck is your shell (PowerShell 7 takes ~400-1000ms to display a prompt). psmux itself adds < 100ms of overhead. For faster shells like `cmd.exe` or `nushell`, total startup is near-instant.\n"
},
{
"path": "docs/plugins.md",
"content": "# Plugins & Themes\n\npsmux has a full plugin ecosystem — ports of the most popular tmux plugins, reimplemented in PowerShell for Windows.\n\n## Plugin Repository\n\n**Browse available plugins and themes:** [**psmux-plugins**](https://github.com/psmux/psmux-plugins)\n\n**Install & manage plugins with a TUI:** [**Tmux Plugin Panel**](https://github.com/psmux/Tmux-Plugin-Panel) — a terminal UI for browsing, installing, updating, and removing plugins and themes.\n\n## Available Plugins\n\n| Plugin | Description |\n|--------|-------------|\n| [ppm](https://github.com/psmux/psmux-plugins/tree/main/ppm) | Plugin manager (like tpm) |\n| [psmux-sensible](https://github.com/psmux/psmux-plugins/tree/main/psmux-sensible) | Sensible defaults for psmux |\n| [psmux-yank](https://github.com/psmux/psmux-plugins/tree/main/psmux-yank) | Windows clipboard integration |\n| [psmux-resurrect](https://github.com/psmux/psmux-plugins/tree/main/psmux-resurrect) | Save/restore sessions |\n| [psmux-continuum](https://github.com/psmux/psmux-plugins/tree/main/psmux-continuum) | Auto save/restore sessions (works with resurrect) |\n| [psmux-pain-control](https://github.com/psmux/psmux-plugins/tree/main/psmux-pain-control) | Better pane navigation |\n| [psmux-prefix-highlight](https://github.com/psmux/psmux-plugins/tree/main/psmux-prefix-highlight) | Prefix key indicator |\n| [psmux-battery](https://github.com/psmux/psmux-plugins/tree/main/psmux-battery) | Battery status in status bar |\n| [psmux-cpu](https://github.com/psmux/psmux-plugins/tree/main/psmux-cpu) | CPU usage in status bar |\n| [psmux-net-speed](https://github.com/psmux/psmux-plugins/tree/main/psmux-net-speed) | Network speed in status bar |\n| [psmux-git-status](https://github.com/psmux/psmux-plugins/tree/main/psmux-git-status) | Git branch and status in status bar |\n| [psmux-sidebar](https://github.com/psmux/psmux-plugins/tree/main/psmux-sidebar) | File tree sidebar |\n| [psmux-logging](https://github.com/psmux/psmux-plugins/tree/main/psmux-logging) | Log pane output to files |\n\n## Themes\n\n| Theme | Description |\n|-------|-------------|\n| [Catppuccin](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-catppuccin) | Soothing pastel theme (Latte, Frappe, Macchiato, Mocha) |\n| [Dracula](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-dracula) | Dark theme with vibrant colors |\n| [Nord](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-nord) | Arctic, north bluish color palette |\n| [Tokyo Night](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-tokyonight) | Clean dark theme inspired by Tokyo at night |\n| [Gruvbox](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-gruvbox) | Retro groove color scheme |\n| [Everforest](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-everforest) | Comfortable green based color scheme |\n| [Kanagawa](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-kanagawa) | Dark theme inspired by Katsushika Hokusai |\n| [One Dark](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-onedark) | Atom One Dark inspired theme |\n| [Rose Pine](https://github.com/psmux/psmux-plugins/tree/main/psmux-theme-rosepine) | Soho vibes for the terminal |\n\n## Quick Start\n\n```powershell\n# Install the plugin manager\ngit clone https://github.com/psmux/psmux-plugins.git \"$env:TEMP\\psmux-plugins\"\nCopy-Item \"$env:TEMP\\psmux-plugins\\ppm\" \"$env:USERPROFILE\\.psmux\\plugins\\ppm\" -Recurse\nRemove-Item \"$env:TEMP\\psmux-plugins\" -Recurse -Force\n```\n\nThen add to your `~/.psmux.conf`:\n\n```tmux\nset -g @plugin 'psmux-plugins/ppm'\nset -g @plugin 'psmux-plugins/psmux-sensible'\nrun '~/.psmux/plugins/ppm/ppm.ps1'\n```\n\nPress `Prefix + I` inside psmux to install the declared plugins.\n"
},
{
"path": "docs/preview.md",
"content": "# Live Preview in Choosers\n\nThe `choose-session` and `choose-tree` pickers in psmux include a live preview pane that shows the actual content of the highlighted session, window, or pane. The preview updates as you move the selection, so you can see what is in each window before switching.\n\n## Quick Start\n\nOpen a chooser:\n\n* **prefix + s** opens `choose-session` (sessions list).\n* **prefix + w** opens `choose-tree` (sessions, windows, panes hierarchy).\n\nInside a chooser:\n\n* Press **p** to toggle the preview pane on or off.\n* Use the **arrow keys**, **j/k**, or **h/l** to move the selection. The preview updates automatically.\n* Press **g** to jump to the top, **G** to jump to the bottom (matches tmux `mode-tree`).\n* Type a **number** (e.g. `3`) to start a digit-jump buffer shown at the bottom as `go to 3`, then press **Enter** to jump to that row (1-based). **Backspace** edits the buffer; **Esc** cancels. Every row is prefixed with its number so the mapping is always visible.\n* Press **Enter** with no digit buffer to switch to the arrow-cursor selection.\n* Press **Esc** or **q** to close.\n\nFull hjkl + g/G navigation and digit-jump also work in `choose-buffer` (prefix + =), the keybindings viewer (prefix + ?), and `customize-mode`.\n\n## Make the Preview Visible by Default\n\nBy default the preview is hidden and you press `p` to show it. To open every chooser with the preview already visible, add the following to your psmux configuration file (`~/.psmux.conf` or `%USERPROFILE%\\.psmux.conf`):\n\n```tmux\nset -g choose-tree-preview on\n```\n\nYou can also set it interactively from any psmux pane:\n\n```powershell\npsmux set -g choose-tree-preview on\n```\n\nTo turn it off again:\n\n```tmux\nset -g choose-tree-preview off\n```\n\nThe option is read each time a chooser opens, so a change takes effect on the next `prefix + s` or `prefix + w`.\n\nYou can verify the current value with:\n\n```powershell\npsmux show-options -g | Select-String choose-tree-preview\n```\n\nInside the chooser, `p` always toggles the preview for the current session regardless of the option. The option only controls the initial state when the chooser opens.\n\n## How the Preview Renders\n\nThe preview pane is fed by the same renderer that draws the main viewport. Each open chooser fetches a JSON dump of the target window using the internal `window-dump` TCP command. The dump includes per-cell text, foreground and background colours, and style flags (bold, underline, italic, reversed, etc.) for every visible row of every pane in that window.\n\nThat dump is then drawn into the preview area using `render_layout_json`, the same function that draws the live psmux viewport. As a result, a preview is a true miniature of what you would see if you switched to that target right now, including:\n\n* Pane borders, including their colours and the active pane highlight.\n* Pane title bars and status indicators.\n* Foreground and background colours from any TUI program running in the pane.\n* Bold, italic, underline, reversed, dim, blink, and strikethrough attributes.\n* True-colour (24-bit) and 256-colour palettes.\n* Wide characters (CJK).\n\nThe preview is updated on a short cache window (about 1.5 seconds) so navigating quickly through a long session list does not flood the network with dump requests, but content still appears live for a steady selection.\n\n## How psmux Handles Size Differences\n\nReal panes are usually much larger than the preview area. For example, a 200x50 pane being shown inside a 60x25 preview slot. A naive scaler would either drop characters or distort the 2D grid that TUI applications rely on (htop, vim, less, pstop, etc.). psmux deliberately does not rescale.\n\nInstead, the preview shows the pane at one to one with two simple rules:\n\n1. **Bottom rows win.** Any trailing fully blank rows are trimmed first so that a shell prompt or the bottom edge of a TUI sits at the bottom of the preview rather than being scrolled off by empty viewport space. The bottom rows of what remains are then shown.\n2. **Columns clip naturally.** Cells that fall outside the preview width are not drawn. The grid stays pixel accurate, so column aligned output (process tables, file listings, source code) keeps its alignment.\n\nThe trade off is that very wide content is cut on the right edge instead of being squeezed in. In practice this matches what tmux itself does in `choose-tree` previews and is much more useful than a scrambled \"scaled\" view.\n\nIf the preview area is the same size as the pane (rare), it shows the pane one to one with no clipping at all.\n\n## Differences from tmux\n\npsmux aims to keep the preview feature on par with tmux, with a few intentional differences listed below.\n\n### Things that match tmux\n\n* `choose-session` and `choose-tree` both have a preview pane.\n* `p` toggles the preview while a chooser is open.\n* The preview is a live mirror of the target, not a frozen snapshot.\n* Pane borders, colours, and styles are preserved.\n* Wide characters are handled correctly.\n* The preview width is roughly half the popup width, with the picker list on the left.\n* The preview never modifies the target session in any way (it is read only).\n\n### Things that differ\n\n* **`choose-tree-preview` option.** Standard tmux does not have an option to make the preview visible by default. You must press `p` every time. psmux adds the `choose-tree-preview` option (default `off`, matching tmux behaviour) so you can opt in to a preview that is always visible.\n* **Render fidelity.** psmux uses its own `window-dump` snapshot pipeline rather than tmux's `capture-pane` text. This carries full per-cell styling (24-bit colour, all SGR attributes) into the preview, so a preview of a Powerline prompt or a syntax-highlighted file looks right rather than being plain text.\n* **Resize behaviour.** tmux scales / squeezes the preview content when the pane is wider than the preview slot, which can produce visually surprising results for column aligned output. psmux clips at one to one as described above. The result is that long lines or wide TUIs are cropped on the right edge in psmux but stay perfectly aligned, while in tmux they may be scaled but mis aligned.\n* **Cache window.** psmux caches the preview dump for about 1.5 seconds. tmux re-renders on every selection change. The psmux behaviour reduces network traffic when scrolling through many sessions but a very recent change to a target may take up to 1.5 seconds to appear in the preview.\n* **Movable popup.** The chooser popup itself can be dragged with the mouse in psmux. Standard tmux choosers are fixed in place. The preview pane moves with the popup.\n\n### Compatibility notes\n\n* The option name `choose-tree-preview` is psmux specific. tmux does not recognise it. Adding it to a shared configuration file is safe because tmux's set-option command will warn but not fail; if you want to be strict, guard the line with `if-shell` or split your config.\n* The option key in `show-options` output and in the JSON sent to the client uses kebab-case (`choose-tree-preview`) and snake_case (`choose_tree_preview`) respectively, matching the existing psmux convention.\n* The preview pane respects all your style options (`pane-border-style`, `pane-active-border-style`, `mode-style`, etc.) because it goes through the same renderer.\n\n## Performance\n\nThe preview path is cheap: it shares the same dump cache between the main viewport and the chooser, so opening the preview adds at most one extra `window-dump` request per cached interval (about 1.5 seconds). Rendering is done client side using the existing renderer, so there is no extra server work for each frame after the dump is fetched.\n\nIf you have very many sessions and the chooser feels slow, that is almost always due to scanning many session port files in `~/.psmux/`, not the preview itself. The preview only fetches the dump for the currently highlighted target.\n\n## Troubleshooting\n\n**The preview shows an empty box.**\nThe target window may not have responded yet. Move the selection away and back, or wait about 1.5 seconds for the cache to expire.\n\n**Long lines are cut off on the right.**\nThis is by design. See \"How psmux Handles Size Differences\" above. If you want to see the full content, switch to the target with Enter.\n\n**The preview text looks fine but the borders are missing.**\nCheck that `pane-border-style` is set to a non empty value. Empty styles render as transparent which can hide borders against the popup background.\n\n**Setting `choose-tree-preview on` does not seem to take effect.**\nThe option is read when the chooser opens, not while it is open. Close the chooser with Esc and reopen it. Verify the option is set with `psmux show-options -g | Select-String choose-tree-preview`.\n\n## Related Options and Commands\n\n* `pane-border-style`, `pane-active-border-style` — control how borders look in both the main view and the preview.\n* `mode-style` — controls how the selected entry in the chooser list is highlighted.\n* `mouse on` — enables clicking entries in the chooser list and dragging the popup.\n\n## See Also\n\n* [configuration.md](configuration.md) for the full options reference.\n* [keybindings.md](keybindings.md) for the default keys that open the choosers.\n* [features.md](features.md) for the broader feature overview.\n"
},
{
"path": "docs/scripting.md",
"content": "# Scripting & Automation\n\npsmux supports tmux-compatible commands for scripting and automation.\n\n## Window & Pane Control\n\n```powershell\n# Create a new window\npsmux new-window\n\n# Split panes\npsmux split-window -v # Split vertically (top/bottom)\npsmux split-window -h # Split horizontally (side by side)\n\n# Navigate panes\npsmux select-pane -U # Select pane above\npsmux select-pane -D # Select pane below\npsmux select-pane -L # Select pane to the left\npsmux select-pane -R # Select pane to the right\n\n# Navigate windows\npsmux select-window -t 1 # Select window by index (default base-index is 1)\npsmux next-window # Go to next window\npsmux previous-window # Go to previous window\npsmux last-window # Go to last active window\n\n# Kill panes and windows\npsmux kill-pane\npsmux kill-window\npsmux kill-session\n```\n\n## Sending Keys\n\n```powershell\n# Send text directly\npsmux send-keys \"ls -la\" Enter\n\n# Send keys literally (no parsing)\npsmux send-keys -l \"literal text\"\n\n# Paste mode (legacy compatibility)\npsmux send-keys -p\n\n# Repeat a key N times\npsmux send-keys -N 5 Up\n\n# Send copy mode command\npsmux send-keys -X copy-mode-up\n\n# Special keys supported:\n# Enter, Tab, Escape, Space, Backspace\n# Up, Down, Left, Right, Home, End\n# PageUp, PageDown, Delete, Insert\n# F1-F12, C-a through C-z (Ctrl+key)\n```\n\n## Pane Information\n\n```powershell\n# List all panes in current window\npsmux list-panes\n\n# List all windows\npsmux list-windows\n\n# Capture pane content\npsmux capture-pane\n\n# Display formatted message with variables\npsmux display-message \"#S:#I:#W\" # Session:Window Index:Window Name\n```\n\n## Paste Buffers\n\n```powershell\n# Set paste buffer content\npsmux set-buffer \"text to paste\"\n\n# Paste buffer to active pane\npsmux paste-buffer\n\n# List all buffers\npsmux list-buffers\n\n# Show buffer content\npsmux show-buffer\n\n# Delete buffer\npsmux delete-buffer\n\n# Interactive buffer chooser (enter=paste, d=delete, esc=close)\npsmux choose-buffer\n\n# Named buffers (separate from anonymous stack)\npsmux set-buffer -b mydata \"key=value\"\npsmux show-buffer -b mydata\npsmux paste-buffer -b mydata\npsmux delete-buffer -b mydata\n\n# Clear command prompt history\npsmux clear-prompt-history\n```\n\n## Pane Layout\n\n```powershell\n# Resize panes\npsmux resize-pane -U 5 # Resize up by 5\npsmux resize-pane -D 5 # Resize down by 5\npsmux resize-pane -L 10 # Resize left by 10\npsmux resize-pane -R 10 # Resize right by 10\n\n# Swap panes\npsmux swap-pane -U # Swap with pane above\npsmux swap-pane -D # Swap with pane below\n\n# Rotate panes in window\npsmux rotate-window\n\n# Toggle pane zoom\npsmux zoom-pane\n```\n\n## Pane Titles\n\nPrograms running inside a pane can set the title via OSC escape sequences. PowerShell 7 does this automatically with the current working directory. See [pane-titles.md](pane-titles.md) for full details on how pane titles work, how to control them, and how different shells behave.\n\n```powershell\n# Set a title on the active pane\npsmux select-pane -T \"my build pane\"\n\n# Set pane title on a specific pane\npsmux select-pane -t %3 -T \"logs\"\n\n# Set per-pane style (foreground/background color override)\npsmux select-pane -P \"bg=default,fg=blue\"\n\n# Display pane title using format variables\npsmux display-message \"#{pane_title}\"\n```\n\nEnable `pane-border-format` and `pane-border-status` in your config to see titles on pane borders:\n\n```tmux\nset -g pane-border-status top\nset -g pane-border-format \" #{pane_index}: #{pane_title} \"\n```\n\n## Popups\n\n```powershell\n# Open a popup running a command\npsmux display-popup \"Get-Process\"\n\n# Set width and height (absolute or percentage)\npsmux display-popup -w 80% -h 50% \"htop\"\n\n# Set the starting directory\npsmux display-popup -d \"C:\\Projects\" -w 100 -h 30\n\n# Close popup on command exit (default behavior, -E inverts it)\npsmux display-popup -E \"git log --oneline -20\"\n\n# Keep popup open after command finishes\npsmux display-popup -K \"echo done\"\n```\n\n## Menus\n\n```powershell\n# Display an interactive menu\n# Format: display-menu [-x x] [-y y] [-T title] name key command ...\npsmux display-menu -T \"Actions\" \\\n \"New Window\" n \"new-window\" \\\n \"Split Horizontal\" h \"split-window -h\" \\\n \"Split Vertical\" v \"split-window -v\" \\\n \"Close Pane\" x \"kill-pane\"\n\n# Position the menu at specific coordinates\npsmux display-menu -x 10 -y 5 -T \"Quick\" \\\n \"Zoom\" z \"resize-pane -Z\" \\\n \"Rename\" r \"command-prompt -I '#W' 'rename-window %%'\"\n```\n\n## Session Management\n\n```powershell\n# Check if session exists (exit code 0 = exists)\npsmux has-session -t mysession\n\n# Rename session\npsmux rename-session newname\n\n# Switch to another session\npsmux switch-client -t other-session\n\n# Cycle through sessions\npsmux switch-client -n # Next session\npsmux switch-client -p # Previous session\npsmux switch-client -l # Last (most recently used) session\n\n# Create a session with environment variables\npsmux new-session -s work -e \"MY_VAR=value\"\n\n# Respawn pane (restart shell, or restart with a different command)\npsmux respawn-pane\npsmux respawn-pane -k # Kill the current process first\npsmux respawn-pane -c /tmp # Restart in a different directory\n```\n\n## Pane Reorganization\n\n```powershell\n# Break the current pane out into a new window\npsmux break-pane\n\n# Break a specific pane, keep it in background\npsmux break-pane -d -s %3\n\n# Join a pane from another window into the current window\npsmux join-pane -s :2 # Bring pane from window 2\n\n# Join horizontally or vertically\npsmux join-pane -h -s :2 # Join side by side\npsmux join-pane -v -s :3 # Join top/bottom\n\n# Move a pane (same as join-pane)\npsmux move-pane -s %5 -t %3\n\n# Find a window by name or content\npsmux find-window \"search term\"\n```\n\n## Environment Variables\n\n```powershell\n# Set a global env var (inherited by all new panes)\npsmux set-environment -g EDITOR vim\n\n# Set a session-scoped env var\npsmux set-environment MY_VAR value\n\n# Unset a global env var\npsmux set-environment -gu MY_VAR\n\n# Show all environment variables\npsmux show-environment\npsmux show-environment -g\n```\n\n## Format Variables\n\nThe `display-message` command supports 140+ variables. Common ones include:\n\n| Variable | Description |\n|----------|-------------|\n| `#S` | Session name |\n| `#I` | Window index |\n| `#W` | Window name |\n| `#P` | Pane ID |\n| `#T` | Pane title |\n| `#H` | Hostname |\n| `#{pane_current_path}` | Current working directory of the pane |\n| `#{pane_current_command}` | Foreground process name |\n| `#{pane_pid}` | PID of the pane's shell |\n| `#{pane_width}` | Width of the pane in columns |\n| `#{pane_height}` | Height of the pane in rows |\n| `#{pane_active}` | `1` if this pane is the active pane |\n| `#{pane_index}` | Pane index within the window |\n| `#{window_zoomed_flag}` | `1` if the window has a zoomed pane |\n| `#{window_panes}` | Number of panes in the window |\n| `#{window_active}` | `1` if this is the active window |\n| `#{session_windows}` | Number of windows in the session |\n| `#{session_attached}` | Number of clients attached to the session |\n| `#{client_prefix}` | `1` if the prefix key was pressed |\n| `#{client_width}` | Width of the client terminal |\n| `#{client_height}` | Height of the client terminal |\n\n### Format Modifiers\n\n```powershell\n# Conditional\npsmux display-message -p \"#{?window_zoomed_flag,ZOOMED,normal}\"\n\n# Comparison\npsmux display-message -p \"#{==:#{pane_index},0}\"\n\n# Regex substitution\npsmux display-message -p \"#{s/old/new/:pane_title}\"\n\n# Basename and dirname\npsmux display-message -p \"#{b:pane_current_path}\"\npsmux display-message -p \"#{d:pane_current_path}\"\n\n# Loop over all windows\npsmux display-message -p \"#{W:#{window_index}:#{window_name} }\"\n\n# Loop over all panes\npsmux display-message -p \"#{P:#{pane_index} }\"\n```\n\n## Advanced Commands\n\n```powershell\n# Discover supported commands\npsmux list-commands\n\n# Server/session management\npsmux kill-server\npsmux list-clients\npsmux switch-client -t other-session\n\n# Config at runtime\npsmux source-file ~/.psmux.conf\npsmux show-options\npsmux set-option -g status-left \"[#S]\"\n\n# Layout/history/stream control\npsmux next-layout\npsmux previous-layout\npsmux select-layout tiled # Apply a specific layout\npsmux clear-history\npsmux pipe-pane -o \"cat > pane.log\"\n\n# Hooks (event callbacks) - see Hooks section below for full reference\npsmux set-hook -g after-new-window \"display-message created\"\npsmux set-hook -g client-attached \"run-shell 'echo attached'\"\npsmux set-hook -gu after-new-window # Unset (remove) a hook\npsmux show-hooks\n\n# Run shell commands\npsmux run-shell \"echo hello\" # Output shown in status bar\npsmux run-shell -b \"long-running.ps1\" # Fire-and-forget (background)\n\n# Conditional execution\npsmux if-shell \"test -f ~/.psmux.conf\" \"source-file ~/.psmux.conf\"\npsmux if-shell -F \"#{window_zoomed_flag}\" \"\" \"resize-pane -Z\"\n\n# User confirmation dialogs\npsmux confirm-before -p \"Kill this pane? (y/n)\" kill-pane\n\n# Wait channels for cross-pane synchronization\npsmux wait-for -L mychannel # Lock a channel\npsmux wait-for -S mychannel # Signal (unlock) a channel\npsmux wait-for mychannel # Wait until channel is signaled\n```\n\n## Hooks (Event Callbacks)\n\nHooks let you run commands automatically when events occur. They are one of the most powerful scripting features in psmux.\n\n### Setting Hooks\n\n```powershell\n# Global hook (applies to all sessions)\npsmux set-hook -g after-new-window \"display-message 'New window created'\"\n\n# Session-scoped hook\npsmux set-hook after-split-window \"select-layout tiled\"\n\n# Chain multiple commands in a hook\npsmux set-hook -g after-new-session \"set -g status-left '[#S] ' \\; display-message 'Session ready'\"\n```\n\n### Available Hook Events\n\n| Hook | Fires when... |\n|------|---------------|\n| `after-new-session` | A new session is created |\n| `after-new-window` | A new window is created |\n| `after-split-window` | A pane is split |\n| `client-attached` | A client attaches to a session |\n| `client-detached` | A client detaches from a session |\n| `after-select-window` | A different window is selected |\n| `after-select-pane` | A different pane is selected |\n| `after-resize-pane` | A pane is resized |\n| `pane-died` | A pane's process exits |\n| `alert-activity` | Activity detected in a monitored window |\n| `alert-silence` | Silence detected in a monitored window |\n| `alert-bell` | Bell received from a pane |\n| `after-kill-pane` | A pane is killed |\n\n### Removing Hooks\n\n```powershell\n# Remove a global hook\npsmux set-hook -gu after-new-window\n\n# View all active hooks\npsmux show-hooks\n```\n\n**Important:** If you repeatedly call `set-hook -g` for the same event, psmux appends duplicate entries. Use `set-hook -gu` to clear the old hook before setting a new one, or check `show-hooks` to verify no duplicates.\n\n## Display Panes\n\nShow numbered overlays on all panes, then type a number to jump to that pane:\n\n```powershell\n# Show pane number overlay (also: Prefix + q)\npsmux display-panes\n```\n\nThe overlay shows each pane's number according to `pane-base-index`. Press a number key while the overlay is visible to switch to that pane. The overlay auto-dismisses after `display-panes-time` milliseconds.\n\n## Run Shell\n\nRun an external command and display the output:\n\n```powershell\n# Output appears in the status bar message area\npsmux run-shell \"echo hello\"\n\n# Run in background (fire-and-forget, no output displayed)\npsmux run-shell -b \"long-running-script.ps1\"\n\n# Use format variables in shell commands\npsmux run-shell \"echo 'Current pane: #{pane_index}'\"\n```\n\n## Interactive Choosers\n\n```powershell\n# Interactive session/window/pane tree browser\npsmux choose-tree\n\n# Show only sessions\npsmux choose-tree -s\n\n# Show only windows\npsmux choose-tree -w\n\n# Interactive buffer picker (enter=paste, d=delete)\npsmux choose-buffer\n\n# Interactive client picker\npsmux choose-client\n\n# Interactive options editor\npsmux customize-mode\n```\n\n## Target Syntax (`-t`)\n\npsmux supports tmux-style targets:\n\n```powershell\n# Window by index in session\npsmux select-window -t work:2\n\n# Window by name in session\npsmux select-window -t work:editor\n\n# Specific pane by index\npsmux send-keys -t work:2.1 \"echo hi\" Enter\n\n# Pane by pane id\npsmux send-keys -t %3 \"pwd\" Enter\n\n# Window by window id\npsmux select-window -t @4\n\n# Target a specific session\npsmux has-session -t mysession\n\n# Session:window.pane full path\npsmux send-keys -t dev:0.2 \"make build\" Enter\n```\n\n## Server Namespaces (`-L`)\n\nUse `-L` to run multiple isolated psmux servers on the same machine:\n\n```powershell\n# Start a session in a named server namespace\npsmux -L work new-session -s dev\n\n# Attach to a session in that namespace\npsmux -L work attach -t dev\n\n# Each namespace gets its own server, sessions, and socket\npsmux -L personal new-session -s play\n```\n\n## Key Binding Management\n\n```powershell\n# Bind a key in the default prefix table\npsmux bind-key h split-window -h\n\n# Bind with format variable expansion (-F flag)\npsmux bind-key -F M-h \"resize-pane -L #{pane_width}\"\n\n# Bind with repeat (successive presses within repeat-time don't need prefix)\npsmux bind-key -r Left select-pane -L\npsmux bind-key -r Right select-pane -R\n\n# Bind in root table (no prefix needed)\npsmux bind-key -n M-Left select-pane -L\n\n# Bind in a specific key table\npsmux bind-key -T copy-mode-vi y send-keys -X copy-selection\n\n# Unbind a single key\npsmux unbind-key h\n\n# Unbind ALL keys (reset to clean slate)\npsmux unbind-key -a\n\n# Unbind all keys in a specific key table only\npsmux unbind-key -a -T copy-mode-vi\npsmux unbind-key -a -T prefix\npsmux unbind-key -a -T root\npsmux unbind-key -a -T copy-mode\n```\n\n## Command Chaining\n\nChain multiple commands with `\\;` in config files:\n\n```tmux\n# Split and select in one binding\nbind-key M-v split-window -v \\; select-pane -U\n\n# Create a 3-pane layout\nbind-key M-d split-window -h \\; split-window -v \\; select-pane -t 0\n\n# Conditional chaining\nbind-key M-z if-shell -F \"#{window_zoomed_flag}\" \"resize-pane -Z\" \"\"\n```\n\nFrom the CLI, use `\\;` or quote the command:\n\n```powershell\npsmux split-window -h `; select-pane -L\n```\n\n## Querying Lists with Custom Formats\n\n```powershell\n# List all sessions with custom format\npsmux list-sessions -F \"#{session_name}:#{session_windows}\"\n\n# List all windows with custom format\npsmux list-windows -F \"#{window_index}:#{window_name}:#{window_panes}\"\n\n# List all panes across the session (-s flag)\npsmux list-panes -s -F \"#{window_index}.#{pane_index}: #{pane_current_command} [#{pane_width}x#{pane_height}]\"\n\n# List all panes across all sessions (-a flag)\npsmux list-panes -a\n\n# Capture pane content to stdout\npsmux capture-pane -p -t %0\n\n# Capture with line range (negative = scrollback)\npsmux capture-pane -p -S -100 -E -1\n\n# Print a format variable\npsmux display-message -p \"#{pane_current_path}\"\n```\n\n## Window and Pane Creation Options\n\n### new-window\n\n```powershell\n# Create a window with a name\npsmux new-window -n \"logs\"\n\n# Create a window in the background (don't switch to it)\npsmux new-window -d -n \"background\"\n\n# Create a window in a specific directory\npsmux new-window -c \"C:\\Projects\\myapp\"\n\n# Create a window running a command\npsmux new-window -n \"build\" -- cargo watch\n\n# Create a window at a specific index\npsmux new-window -t 5\n```\n\nWhen you set a window name with `-n`, automatic renaming is disabled for that window so the foreground process name does not overwrite your chosen name.\n\n### split-window\n\n```powershell\n# Split with percentage size\npsmux split-window -v -p 30 # Bottom pane gets 30%\npsmux split-window -h -p 70 # Right pane gets 70%\n\n# Split in the current pane's directory\npsmux split-window -h -c \"#{pane_current_path}\"\n\n# Split with a specific command\npsmux split-window -v -- python\n\n# Split a specific target pane\npsmux split-window -v -t %3\n\n# Split without switching focus\npsmux split-window -d -v\n```\n\n### new-session\n\n```powershell\n# Create a named session\npsmux new-session -s work\n\n# Create in a specific directory\npsmux new-session -s project -c \"C:\\Projects\\myapp\"\n\n# Create with environment variables\npsmux new-session -s dev -e \"NODE_ENV=development\"\n\n# Create in background (detached)\npsmux new-session -d -s background\n\n# Create with an initial command\npsmux new-session -s monitor -- htop\n\n# Create a session with a named first window\npsmux new-session -s work -n \"editor\"\n```\n\n## Target Syntax\n\nMany commands accept a `-t` flag to specify which session, window, or pane to act on:\n\n```powershell\n# Target a session by name\npsmux switch-client -t mysession\n\n# Target a window by index (within current session)\npsmux select-window -t 3\n\n# Target a window in a specific session\npsmux select-window -t mysession:2\n\n# Target a pane by ID (absolute, shown with %)\npsmux select-pane -t %5\n\n# Target a pane within a window\npsmux select-pane -t :2.1 # Window 2, pane 1\n\n# Special targets\npsmux select-pane -t + # Next pane\npsmux select-pane -t - # Previous pane\npsmux select-window -t ! # Last (previous) window\n```\n\n## Server Namespaces\n\nRun isolated psmux instances using the `-L` flag. Each namespace gets its own server process with its own sessions:\n\n```powershell\n# Start a session in a named namespace\npsmux -L work new-session -s dev\n\n# Attach to a session in that namespace\npsmux -L work attach\n\n# List sessions in a namespace\npsmux -L work list-sessions\n\n# Default namespace is used when -L is not specified\n```\n\nThis is useful for running completely separate psmux environments, for example one for development and one for monitoring.\n"
},
{
"path": "docs/tmux_args_reference.md",
"content": "\n## Complete Command Table\n\n| Command | Alias | Args Template | Min | Max | Source File |\n|---|---|---|---|---|---|\n| `attach-session` | `attach` | `\"ErdD:f:c:t:x:\"` | 0 | 0 | cmd-attach-session.c *(not fetched, from Perplexity)* |\n| `bind-key` | `bind` | `\"nrN:T:\"` | 1 | -1 | cmd-bind-key.c |\n| `break-pane` | `breakp` | `\"abdPF:n:s:t:\"` | 0 | 0 | cmd-break-pane.c |\n| `capture-pane` | `capturep` | `\"ab:CeE:JMNpPqS:Tt:\"` | 0 | 0 | cmd-capture-pane.c |\n| `choose-buffer` | *(none)* | `\"F:f:K:NO:rt:yZ\"` | 0 | 1 | cmd-choose-tree.c |\n| `choose-client` | *(none)* | `\"F:f:K:NO:rt:yZ\"` | 0 | 1 | cmd-choose-tree.c |\n| `choose-tree` | *(none)* | `\"F:f:GK:NO:rst:wyZ\"` | 0 | 1 | cmd-choose-tree.c |\n| `clear-history` | `clearhist` | `\"Ht:\"` | 0 | 0 | cmd-capture-pane.c |\n| `clock-mode` | *(none)* | `\"t:\"` | 0 | 0 | cmd-copy-mode.c |\n| `command-prompt` | *(none)* | `\"1beFiklI:Np:t:T:\"` | 0 | 1 | cmd-command-prompt.c |\n| `confirm-before` | `confirm` | `\"bc:p:t:y\"` | 1 | 1 | cmd-confirm-before.c |\n| `copy-mode` | *(none)* | `\"deHMqSs:t:u\"` | 0 | 0 | cmd-copy-mode.c |\n| `customize-mode` | *(none)* | `\"F:f:Nt:yZ\"` | 0 | 0 | cmd-choose-tree.c |\n| `delete-buffer` | `deleteb` | `\"b:\"` | 0 | 0 | cmd-paste-buffer.c *(delete in same file)* |\n| `detach-client` | `detach` | `\"aE:s:t:P\"` | 0 | 0 | cmd-detach-client.c |\n| `display-message` | `display` | `\"aCc:d:lINpt:F:v\"` | 0 | 1 | cmd-display-message.c |\n| `display-panes` | `displayp` | `\"bd:Nt:\"` | 0 | 1 | cmd-display-panes.c |\n| `has-session` | `has` | `\"t:\"` | 0 | 0 | cmd-select-window.c *(in same file)* |\n| `if-shell` | `if` | `\"bFt:\"` | 2 | 3 | cmd-if-shell.c |\n| `join-pane` | `joinp` | `\"bdfhvp:l:s:t:\"` | 0 | 0 | cmd-join-pane.c |\n| `kill-pane` | `killp` | `\"at:\"` | 0 | 0 | cmd-kill-pane.c |\n| `kill-server` | *(none)* | `\"\"` | 0 | 0 | cmd-kill-server.c |\n| `kill-session` | *(none)* | `\"aCt:\"` | 0 | 0 | cmd-kill-session.c |\n| `kill-window` | `killw` | `\"at:\"` | 0 | 0 | cmd-kill-window.c |\n| `last-pane` | `lastp` | `\"det:Z\"` | 0 | 0 | cmd-select-pane.c |\n| `last-window` | `last` | `\"t:\"` | 0 | 0 | cmd-select-window.c |\n| `link-window` | `linkw` | `\"abdks:t:\"` | 0 | 0 | cmd-move-window.c |\n| `list-buffers` | `lsb` | `\"F:f:O:r\"` | 0 | 0 | cmd-list-buffers.c |\n| `list-clients` | `lsc` | `\"F:f:O:rt:\"` | 0 | 0 | cmd-list-clients.c |\n| `list-commands` | `lscm` | `\"F:\"` | 0 | 1 | cmd-list-keys.c |\n| `list-keys` | `lsk` | `\"1aNP:T:\"` | 0 | 1 | cmd-list-keys.c |\n| `list-panes` | `lsp` | `\"aF:f:O:rst:\"` | 0 | 0 | cmd-list-panes.c |\n| `list-sessions` | `ls` | `\"F:f:O:r\"` | 0 | 0 | cmd-list-sessions.c |\n| `list-windows` | `lsw` | `\"aF:f:O:rt:\"` | 0 | 0 | cmd-list-windows.c |\n| `load-buffer` | `loadb` | `\"b:t:w\"` | 1 | 1 | cmd-load-buffer.c |\n| `lock-client` | `lockc` | `\"t:\"` | 0 | 0 | cmd-lock-server.c |\n| `lock-server` | `lock` | `\"\"` | 0 | 0 | cmd-lock-server.c |\n| `lock-session` | `locks` | `\"t:\"` | 0 | 0 | cmd-lock-server.c |\n| `move-pane` | `movep` | `\"bdfhvp:l:s:t:\"` | 0 | 0 | cmd-join-pane.c |\n| `move-window` | `movew` | `\"abdkrs:t:\"` | 0 | 0 | cmd-move-window.c |\n| `new-session` | `new` | `\"Ac:dDe:EF:f:n:Ps:t:x:Xy:\"` | 0 | -1 | cmd-new-session.c |\n| `new-window` | `neww` | `\"abc:de:F:kn:PSt:\"` | 0 | -1 | cmd-new-window.c |\n| `next-window` | `next` | `\"at:\"` | 0 | 0 | cmd-select-window.c |\n| `paste-buffer` | `pasteb` | `\"db:prs:t:\"` | 0 | 0 | cmd-paste-buffer.c |\n| `pipe-pane` | `pipep` | `\"IOot:\"` | 0 | 1 | cmd-pipe-pane.c |\n| `previous-window` | `prev` | `\"at:\"` | 0 | 0 | cmd-select-window.c |\n| `refresh-client` | `refresh` | `\"A:B:cC:Df:r:F:lLRSt:U\"` | 0 | 1 | cmd-refresh-client.c |\n| `rename-session` | `rename` | `\"t:\"` | 1 | 1 | cmd-rename-session.c |\n| `rename-window` | `renamew` | `\"t:\"` | 1 | 1 | cmd-rename-window.c |\n| `resize-pane` | `resizep` | `\"DLMRTt:Ux:y:Z\"` | 0 | 1 | cmd-resize-pane.c |\n| `respawn-pane` | `respawnp` | `\"c:e:kt:\"` | 0 | -1 | cmd-respawn-pane.c |\n| `respawn-window` | `respawnw` | `\"c:e:kt:\"` | 0 | -1 | cmd-respawn-window.c |\n| `rotate-window` | `rotatew` | `\"Dt:UZ\"` | 0 | 0 | cmd-rotate-window.c |\n| `run-shell` | `run` | `\"bd:Ct:Es:c:\"` | 0 | 1 | cmd-run-shell.c |\n| `save-buffer` | `saveb` | `\"ab:\"` | 1 | 1 | cmd-save-buffer.c |\n| `select-pane` | `selectp` | `\"DdegLlMmP:RT:t:UZ\"` | 0 | 0 | cmd-select-pane.c |\n| `select-window` | `selectw` | `\"lnpTt:\"` | 0 | 0 | cmd-select-window.c |\n| `send-keys` | `send` | `\"c:FHKlMN:Rt:X\"` | 0 | -1 | cmd-send-keys.c |\n| `send-prefix` | *(none)* | `\"2t:\"` | 0 | 0 | cmd-send-keys.c |\n| `set-buffer` | `setb` | `\"ab:t:n:w\"` | 0 | 1 | cmd-set-buffer.c |\n| `set-environment` | `setenv` | `\"Fhgrt:u\"` | 1 | 2 | cmd-set-environment.c |\n| `set-hook` | *(none)* | `\"agpRt:uw\"` | 1 | 2 | cmd-set-option.c |\n| `set-option` | `set` | `\"aFgopqst:uUw\"` | 1 | 2 | cmd-set-option.c |\n| `set-window-option` | `setw` | `\"aFgoqt:u\"` | 1 | 2 | cmd-set-option.c |\n| `show-buffer` | `showb` | `\"b:\"` | 0 | 0 | cmd-save-buffer.c |\n| `show-environment` | `showenv` | `\"hgst:\"` | 0 | 1 | cmd-show-environment.c |\n| `show-hooks` | *(none)* | `\"gpt:w\"` | 0 | 1 | cmd-show-options.c |\n| `show-options` | `show` | `\"AgHpqst:vw\"` | 0 | 1 | cmd-show-options.c |\n| `show-window-options` | `showw` | `\"gvt:\"` | 0 | 1 | cmd-show-options.c |\n| `source-file` | `source` | `\"t:Fnqv\"` | 1 | -1 | cmd-source-file.c |\n| `split-window` | `splitw` | `\"bc:de:fF:hIl:p:Pt:vZ\"` | 0 | -1 | cmd-split-window.c |\n| `start-server` | `start` | `\"\"` | 0 | 0 | cmd-kill-server.c |\n| `suspend-client` | `suspendc` | `\"t:\"` | 0 | 0 | cmd-detach-client.c |\n| `swap-pane` | `swapp` | `\"dDs:t:UZ\"` | 0 | 0 | cmd-swap-pane.c |\n| `swap-window` | `swapw` | `\"ds:t:\"` | 0 | 0 | cmd-swap-window.c |\n| `switch-client` | `switchc` | `\"c:EFlnO:pt:rT:Z\"` | 0 | 0 | cmd-switch-client.c |\n| `unbind-key` | `unbind` | `\"anqT:\"` | 0 | 1 | cmd-unbind-key.c |\n| `unlink-window` | `unlinkw` | `\"kt:\"` | 0 | 0 | cmd-kill-window.c |\n| `wait-for` | `wait` | `\"LSU\"` | 1 | 1 | cmd-wait-for.c |\n\n## Flag Details by Command\n\n### Session Commands\n\n**new-session** (`new`) — `\"Ac:dDe:EF:f:n:Ps:t:x:Xy:\"`\n- Boolean: `-A` (attach if exists), `-d` (detach), `-D` (detach other), `-E` (no environ update), `-P` (print info), `-X` (no default-command exec), `-x` → **wait, x: takes value**\n- Value: `-c` (start-dir), `-e` (environment), `-F` (format), `-f` (flags), `-n` (window-name), `-s` (session-name), `-t` (group target), `-x` (width), `-y` (height)\n\n**has-session** (`has`) — `\"t:\"`\n- Value: `-t` (target session)\n\n**kill-session** — `\"aCt:\"`\n- Boolean: `-a` (kill all other), `-C` (clear alerts)\n- Value: `-t` (target session)\n\n**rename-session** (`rename`) — `\"t:\"` [1 positional arg: new-name]\n- Value: `-t` (target session)\n\n**list-sessions** (`ls`) — `\"F:f:O:r\"`\n- Boolean: `-r` (reverse sort)\n- Value: `-F` (format), `-f` (filter), `-O` (sort order)\n\n**switch-client** (`switchc`) — `\"c:EFlnO:pt:rT:Z\"`\n- Boolean: `-E` (no environ), `-F` → **wait, F: no-colon = boolean here**, `-l` (last), `-n` (next), `-p` (previous), `-r` (toggle readonly), `-Z` (zoom)\n- Value: `-c` (client), `-O` (sort order), `-t` (target), `-T` (key-table)\n\n**detach-client** (`detach`) — `\"aE:s:t:P\"`\n- Boolean: `-a` (all other), `-P` (kill after detach)\n- Value: `-E` (shell-command), `-s` (target-session), `-t` (target-client)\n\n**suspend-client** (`suspendc`) — `\"t:\"`\n- Value: `-t` (target-client)\n\n**lock-server** (`lock`) — `\"\"`\n- No flags\n\n**lock-session** (`locks`) — `\"t:\"`\n- Value: `-t` (target-session)\n\n**lock-client** (`lockc`) — `\"t:\"`\n- Value: `-t` (target-client)\n\n**kill-server** — `\"\"`\n- No flags\n\n**start-server** (`start`) — `\"\"`\n- No flags\n\n**list-clients** (`lsc`) — `\"F:f:O:rt:\"`\n- Boolean: `-r` (reverse sort)\n- Value: `-F` (format), `-f` (filter), `-O` (sort order), `-t` (target-session)\n\n**refresh-client** (`refresh`) — `\"A:B:cC:Df:r:F:lLRSt:U\"`\n- Boolean: `-c` (clear pan), `-D` (pan down), `-l` (clipboard query), `-L` (pan left), `-R` (pan right), `-S` (status only), `-U` (pan up)\n- Value: `-A` (pane:state), `-B` (subscription), `-C` (size), `-f` (flags), `-r` (pane:report), `-F` (flags alias), `-t` (target-client)\n\n### Window Commands\n\n**new-window** (`neww`) — `\"abc:de:F:kn:PSt:\"`\n- Boolean: `-a` (after current), `-b` (before current), `-d` (don't switch), `-k` (kill if exists), `-P` (print info), `-S` (select if exists)\n- Value: `-c` (start-dir), `-e` (environment), `-F` (format), `-n` (window-name), `-t` (target-window)\n\n**kill-window** (`killw`) — `\"at:\"`\n- Boolean: `-a` (kill all other)\n- Value: `-t` (target-window)\n\n**unlink-window** (`unlinkw`) — `\"kt:\"`\n- Boolean: `-k` (kill if last)\n- Value: `-t` (target-window)\n\n**rename-window** (`renamew`) — `\"t:\"` [1 positional arg: new-name]\n- Value: `-t` (target-window)\n\n**select-window** (`selectw`) — `\"lnpTt:\"`\n- Boolean: `-l` (last), `-n` (next), `-p` (previous), `-T` (toggle)\n- Value: `-t` (target-window)\n\n**next-window** (`next`) — `\"at:\"`\n- Boolean: `-a` (with alert)\n- Value: `-t` (target-session)\n\n**previous-window** (`prev`) — `\"at:\"`\n- Boolean: `-a` (with alert)\n- Value: `-t` (target-session)\n\n**last-window** (`last`) — `\"t:\"`\n- Value: `-t` (target-session)\n\n**move-window** (`movew`) — `\"abdkrs:t:\"`\n- Boolean: `-a` (after), `-b` (before), `-d` (detach), `-k` (kill if exists), `-r` (renumber)\n- Value: `-s` (src-window), `-t` (dst-window)\n\n**link-window** (`linkw`) — `\"abdks:t:\"`\n- Boolean: `-a` (after), `-b` (before), `-d` (detach), `-k` (kill if exists)\n- Value: `-s` (src-window), `-t` (dst-window)\n\n**swap-window** (`swapw`) — `\"ds:t:\"`\n- Boolean: `-d` (don't switch)\n- Value: `-s` (src-window), `-t` (dst-window)\n\n**rotate-window** (`rotatew`) — `\"Dt:UZ\"`\n- Boolean: `-D` (down/clockwise), `-U` (up/counter-clockwise), `-Z` (keep zoomed)\n- Value: `-t` (target-window)\n\n**list-windows** (`lsw`) — `\"aF:f:O:rt:\"`\n- Boolean: `-a` (all sessions), `-r` (reverse sort)\n- Value: `-F` (format), `-f` (filter), `-O` (sort order), `-t` (target-session)\n\n**respawn-window** (`respawnw`) — `\"c:e:kt:\"`\n- Boolean: `-k` (kill existing)\n- Value: `-c` (start-dir), `-e` (environment), `-t` (target-window)\n\n### Pane Commands\n\n**split-window** (`splitw`) — `\"bc:de:fF:hIl:p:Pt:vZ\"`\n- Boolean: `-b` (before), `-d` (don't switch), `-f` (full width/height), `-h` (horizontal), `-I` (stdin forward), `-P` (print info), `-v` (vertical), `-Z` (zoom)\n- Value: `-c` (start-dir), `-e` (environment), `-F` (format), `-l` (size), `-p` (percentage), `-t` (target-pane)\n\n**select-pane** (`selectp`) — `\"DdegLlMmP:RT:t:UZ\"`\n- Boolean: `-D` (down), `-d` (disable input), `-e` (enable input), `-g` (show style), `-L` (left), `-l` (last), `-M` (clear marked), `-m` (mark), `-R` (right), `-U` (up), `-Z` (keep zoomed)\n- Value: `-P` (style), `-T` (title), `-t` (target-pane)\n\n**last-pane** (`lastp`) — `\"det:Z\"`\n- Boolean: `-d` (disable input), `-e` (enable input), `-Z` (keep zoomed)\n- Value: `-t` (target-window)\n\n**kill-pane** (`killp`) — `\"at:\"`\n- Boolean: `-a` (kill all other)\n- Value: `-t` (target-pane)\n\n**resize-pane** (`resizep`) — `\"DLMRTt:Ux:y:Z\"`\n- Boolean: `-D` (down), `-L` (left), `-M` (mouse), `-R` (right), `-T` (trim), `-U` (up), `-Z` (zoom toggle)\n- Value: `-t` (target-pane), `-x` (width), `-y` (height)\n\n**swap-pane** (`swapp`) — `\"dDs:t:UZ\"`\n- Boolean: `-d` (don't switch focus), `-D` (swap down), `-U` (swap up), `-Z` (keep zoomed)\n- Value: `-s` (src-pane), `-t` (dst-pane)\n\n**join-pane** (`joinp`) — `\"bdfhvp:l:s:t:\"`\n- Boolean: `-b` (before), `-d` (don't switch), `-f` (full size), `-h` (horizontal), `-v` (vertical)\n- Value: `-p` (percentage), `-l` (size), `-s` (src-pane), `-t` (dst-pane)\n\n**move-pane** (`movep`) — `\"bdfhvp:l:s:t:\"`\n- *(Same flags as join-pane)*\n\n**break-pane** (`breakp`) — `\"abdPF:n:s:t:\"`\n- Boolean: `-a` (after), `-b` (before), `-d` (don't switch), `-P` (print info)\n- Value: `-F` (format), `-n` (window-name), `-s` (src-pane), `-t` (dst-window)\n\n**respawn-pane** (`respawnp`) — `\"c:e:kt:\"`\n- Boolean: `-k` (kill existing)\n- Value: `-c` (start-dir), `-e` (environment), `-t` (target-pane)\n\n**capture-pane** (`capturep`) — `\"ab:CeE:JMNpPqS:Tt:\"`\n- Boolean: `-a` (alt screen), `-C` (escape non-printable as C0), `-e` (escape sequences), `-J` (join wrapped lines), `-M` (mouse target), `-N` (with trailing spaces), `-p` (to stdout), `-P` (only if pane active), `-q` (quiet), `-T` (ignore trailing positions)\n- Value: `-b` (buffer-name), `-E` (end-line), `-S` (start-line), `-t` (target-pane)\n\n**clear-history** (`clearhist`) — `\"Ht:\"`\n- Boolean: `-H` (also clear hidden history)\n- Value: `-t` (target-pane)\n\n**list-panes** (`lsp`) — `\"aF:f:O:rst:\"`\n- Boolean: `-a` (all), `-r` (reverse sort), `-s` (session)\n- Value: `-F` (format), `-f` (filter), `-O` (sort order), `-t` (target)\n\n**display-panes** (`displayp`) — `\"bd:Nt:\"`\n- Boolean: `-b` (non-blocking), `-N` (no key handling)\n- Value: `-d` (duration), `-t` (target-client)\n\n**pipe-pane** (`pipep`) — `\"IOot:\"`\n- Boolean: `-I` (stdin), `-O` (stdout), `-o` (toggle/open-only)\n- Value: `-t` (target-pane)\n\n### Copy & Paste Commands\n\n**copy-mode** — `\"deHMqSs:t:u\"`\n- Boolean: `-d` (page down), `-e` (exit at bottom), `-H` (hide position), `-M` (mouse), `-q` (cancel), `-S` (scroll bar drag), `-u` (page up)\n- Value: `-s` (src-pane), `-t` (target-pane)\n\n**paste-buffer** (`pasteb`) — `\"db:prs:t:\"`\n- Boolean: `-d` (delete after), `-p` (use bracketed paste), `-r` (no newline replacement)\n- Value: `-b` (buffer-name), `-s` (separator), `-t` (target-pane)\n\n**set-buffer** (`setb`) — `\"ab:t:n:w\"`\n- Boolean: `-a` (append), `-w` (send to clipboard)\n- Value: `-b` (buffer-name), `-t` (target-client), `-n` (new-name)\n\n**delete-buffer** (`deleteb`) — `\"b:\"`\n- Value: `-b` (buffer-name)\n\n**show-buffer** (`showb`) — `\"b:\"`\n- Value: `-b` (buffer-name)\n\n**save-buffer** (`saveb`) — `\"ab:\"` [1 positional arg: path]\n- Boolean: `-a` (append)\n- Value: `-b` (buffer-name)\n\n**load-buffer** (`loadb`) — `\"b:t:w\"` [1 positional arg: path]\n- Boolean: `-w` (send to clipboard)\n- Value: `-b` (buffer-name), `-t` (target-client)\n\n**list-buffers** (`lsb`) — `\"F:f:O:r\"`\n- Boolean: `-r` (reverse sort)\n- Value: `-F` (format), `-f` (filter), `-O` (sort order)\n\n**choose-buffer** — `\"F:f:K:NO:rt:yZ\"`\n- Boolean: `-N` (hide preview), `-r` (reverse sort), `-y` (immediate exit), `-Z` (zoom)\n- Value: `-F` (format), `-f` (filter), `-K` (key-format), `-O` (sort order), `-t` (target-pane)\n\n### Key Binding Commands\n\n**bind-key** (`bind`) — `\"nrN:T:\"`\n- Boolean: `-n` (root table / no prefix), `-r` (repeat)\n- Value: `-N` (note), `-T` (key-table)\n\n**unbind-key** (`unbind`) — `\"anqT:\"`\n- Boolean: `-a` (all), `-n` (root table), `-q` (quiet)\n- Value: `-T` (key-table)\n\n**list-keys** (`lsk`) — `\"1aNP:T:\"`\n- Boolean: `-1` (one key per line), `-a` (with notes), `-N` (with notes only)\n- Value: `-P` (prefix), `-T` (key-table)\n\n**send-keys** (`send`) — `\"c:FHKlMN:Rt:X\"`\n- Boolean: `-F` (expand formats), `-H` (hex), `-K` (key name), `-l` (literal), `-M` (mouse), `-R` (reset terminal), `-X` (copy-mode command)\n- Value: `-c` (target-client), `-N` (repeat count), `-t` (target-pane)\n\n**send-prefix** — `\"2t:\"`\n- Boolean: `-2` (send prefix2)\n- Value: `-t` (target-pane)\n\n### Configuration Commands\n\n**set-option** (`set`) — `\"aFgopqst:uUw\"`\n- Boolean: `-a` (append), `-F` (expand formats), `-g` (global), `-o` (no overwrite), `-p` (pane), `-q` (quiet), `-s` (server), `-u` (unset), `-U` (unset and delete), `-w` (window)\n- Value: `-t` (target)\n\n**set-window-option** (`setw`) — `\"aFgoqt:u\"`\n- Boolean: `-a` (append), `-F` (expand formats), `-g` (global), `-o` (no overwrite), `-q` (quiet), `-u` (unset)\n- Value: `-t` (target-window)\n\n**show-options** (`show`) — `\"AgHpqst:vw\"`\n- Boolean: `-A` (inherited), `-g` (global), `-H` (include hidden), `-p` (pane), `-q` (quiet), `-s` (server), `-v` (value only), `-w` (window)\n- Value: `-t` (target)\n\n**show-window-options** (`showw`) — `\"gvt:\"`\n- Boolean: `-g` (global), `-v` (value only)\n- Value: `-t` (target-window)\n\n**set-hook** — `\"agpRt:uw\"`\n- Boolean: `-a` (append), `-g` (global), `-p` (pane), `-R` (run immediately), `-u` (unset), `-w` (window)\n- Value: `-t` (target)\n\n**show-hooks** — `\"gpt:w\"`\n- Boolean: `-g` (global), `-p` (pane), `-w` (window)\n- Value: `-t` (target)\n\n**set-environment** (`setenv`) — `\"Fhgrt:u\"`\n- Boolean: `-F` (expand format), `-h` (hidden), `-g` (global), `-r` (remove from env), `-u` (unset)\n- Value: `-t` (target-session)\n\n**show-environment** (`showenv`) — `\"hgst:\"`\n- Boolean: `-h` (hidden only), `-g` (global), `-s` (as shell commands)\n- Value: `-t` (target-session)\n\n**source-file** (`source`) — `\"t:Fnqv\"`\n- Boolean: `-F` (expand format), `-n` (syntax check only), `-q` (quiet), `-v` (verbose)\n- Value: `-t` (target-pane)\n\n**list-commands** (`lscm`) — `\"F:\"`\n- Value: `-F` (format)\n\n### Display & Misc Commands\n\n**display-message** (`display`) — `\"aCc:d:lINpt:F:v\"`\n- Boolean: `-a` (list all variables), `-C` (escape output), `-l` (log to server), `-I` (stdin), `-N` (no output), `-p` (to stdout), `-v` (verbose)\n- Value: `-c` (target-client), `-d` (delay), `-t` (target-pane), `-F` (format)\n\n**command-prompt** — `\"1beFiklI:Np:t:T:\"`\n- Boolean: `-1` (single key), `-b` (background), `-e` (backspace exit), `-F` (expand), `-i` (incremental), `-k` (key only), `-l` (literal), `-N` (numeric)\n- Value: `-I` (inputs), `-p` (prompts), `-t` (target-client), `-T` (prompt-type)\n\n**confirm-before** (`confirm`) — `\"bc:p:t:y\"`\n- Boolean: `-b` (background), `-y` (default yes)\n- Value: `-c` (confirm-key), `-p` (prompt), `-t` (target-client)\n\n**choose-tree** — `\"F:f:GK:NO:rst:wyZ\"`\n- Boolean: `-G` (grouped sessions), `-N` (no preview), `-r` (reverse), `-s` (sessions only), `-w` (windows only), `-y` (immediate exit), `-Z` (zoom)\n- Value: `-F` (format), `-f` (filter), `-K` (key-format), `-O` (sort order), `-t` (target-pane)\n\n**choose-client** — `\"F:f:K:NO:rt:yZ\"`\n- Boolean: `-N` (no preview), `-r` (reverse), `-y` (immediate exit), `-Z` (zoom)\n- Value: `-F` (format), `-f` (filter), `-K` (key-format), `-O` (sort order), `-t` (target-pane)\n\n**run-shell** (`run`) — `\"bd:Ct:Es:c:\"`\n- Boolean: `-b` (background), `-C` (command), `-E` → **wait, no-colon = boolean**\n- Value: `-d` (delay), `-t` (target-pane), `-s` (shell), `-c` (start-dir)\n\n**if-shell** (`if`) — `\"bFt:\"` [2-3 positional args: shell-cmd, if-true-cmd, [if-false-cmd]]\n- Boolean: `-b` (background), `-F` (test as format not shell)\n- Value: `-t` (target-pane)\n\n**wait-for** (`wait`) — `\"LSU\"` [1 positional arg: channel]\n- Boolean: `-L` (lock), `-S` (signal/unlock), `-U` (unlock)\n\n**clock-mode** — `\"t:\"`\n- Value: `-t` (target-pane)\n"
},
{
"path": "docs/warm-sessions.md",
"content": "# Warm Sessions\n\npsmux uses a background **warm session** (`__warm__`) to make new session creation nearly instant. This page explains how it works and how to interact with it if needed.\n\n## What is a Warm Session?\n\nWhen you create a session, psmux pre-spawns a hidden standby server called `__warm__`. This server loads your config, initializes a shell, and waits. When you run `psmux new-session` next time, psmux **claims** this warm server (renames it to your requested session name) instead of cold-starting a new process. This skips the entire server startup + config load + shell spawn cycle.\n\n**Result:** New session creation drops from ~400-1000ms (shell startup) to near-instant.\n\n## Why You Don't See It\n\nThe `__warm__` session is an internal implementation detail. It is hidden from:\n\n- `psmux ls` / `psmux list-sessions`\n- `prefix + s` (choose-session)\n- `prefix + w` (choose-tree)\n- `prefix + (` / `)` (session navigation)\n- The `last_session` tracking file\n\nUsers should never need to interact with it directly.\n\n## When It's Not Spawned\n\nThe warm server is **not** created when:\n\n- The current session has `destroy-unattached on` — keeping a hidden warm server alive would break the expectation that sessions die when you detach\n- The current session **is** the warm session (no recursive warm spawning)\n- Warm panes are explicitly disabled (see below)\n\n## Disabling Warm Sessions\n\nIf you prefer every session, window, and pane to start with a completely fresh shell invocation (no pre-spawned state), you can disable warm entirely.\n\n### Via config file\n\nAdd this to your `.psmux.conf`, `.tmux.conf`, or `~/.config/psmux/psmux.conf`:\n\n```\nset -g warm off\n```\n\n### Via environment variable\n\n```powershell\n$env:PSMUX_NO_WARM = \"1\"\n```\n\nWhen warm is disabled:\n- No `__warm__` background server is spawned\n- No warm panes are pre-spawned inside sessions\n- Every `new-session`, `new-window`, and `split-window` cold-starts a fresh shell\n- Startup latency increases slightly (shell profile load is not parallelized)\n\nYou can re-enable warm at runtime with `set -g warm on`.\n\n## Accessing the Warm Session (Advanced)\n\nIf you need to inspect or manage the warm session directly (debugging, development):\n\n```powershell\n# Check if a warm session is running\nTest-Path \"$HOME\\.psmux\\__warm__.port\"\n\n# List all sessions including warm (raw port files)\nGet-ChildItem \"$HOME\\.psmux\\*.port\" | Select-Object Name\n\n# Send a command to the warm server\npsmux -t __warm__ list-windows\n\n# Kill just the warm session\npsmux -t __warm__ kill-session\n\n# With -L namespace: warm session is stored as \"<namespace>____warm__\"\nTest-Path \"$HOME\\.psmux\\myns____warm__.port\"\n```\n\n## File Layout\n\n| File | Purpose |\n|------|---------|\n| `~\\.psmux\\__warm__.port` | TCP port of the warm server |\n| `~\\.psmux\\__warm__.key` | Auth key for the warm server |\n| `~\\.psmux\\<ns>____warm__.port` | Warm server under `-L <ns>` namespace |\n"
},
{
"path": "examples/crossterm_sgr_diag.rs",
"content": "/// Diagnostic: verify what crossterm emits for CROSSED_OUT, HIDDEN modifiers.\n/// Run with: cargo run --example crossterm_sgr_diag\nuse std::io::Write;\n\nfn main() {\n let mut out: Vec<u8> = Vec::new();\n {\n use crossterm::style::{Attribute, SetAttribute, SetForegroundColor, Color as CtColor};\n use crossterm::QueueableCommand;\n let mut c = std::io::Cursor::new(&mut out);\n\n // Test CROSSED_OUT (should emit SGR 9)\n c.queue(SetAttribute(Attribute::CrossedOut)).unwrap();\n c.write_all(b\"STRIKE\").unwrap();\n c.queue(SetAttribute(Attribute::NotCrossedOut)).unwrap();\n c.write_all(b\" \").unwrap();\n\n // Test HIDDEN (should emit SGR 8)\n c.queue(SetAttribute(Attribute::Hidden)).unwrap();\n c.write_all(b\"HIDDEN\").unwrap();\n c.queue(SetAttribute(Attribute::NoHidden)).unwrap();\n c.write_all(b\" \").unwrap();\n\n // Test named color Red vs Indexed(1)\n c.queue(SetForegroundColor(CtColor::Red)).unwrap();\n c.write_all(b\"RED\").unwrap();\n c.queue(SetForegroundColor(CtColor::Reset)).unwrap();\n c.write_all(b\" \").unwrap();\n\n c.queue(SetForegroundColor(CtColor::AnsiValue(1))).unwrap();\n c.write_all(b\"IDX1\").unwrap();\n c.queue(SetForegroundColor(CtColor::Reset)).unwrap();\n\n c.flush().unwrap();\n }\n\n println!(\"=== Raw bytes ({}) ===\", out.len());\n // Show escape sequences\n let mut i = 0;\n while i < out.len() {\n if out[i] == 0x1b {\n let start = i;\n i += 1;\n while i < out.len() && !out[i].is_ascii_alphabetic() {\n i += 1;\n }\n if i < out.len() {\n i += 1;\n }\n let seq = &out[start..i];\n let seq_str = String::from_utf8_lossy(seq);\n println!(\" ESC: {:?}\", seq_str);\n } else if out[i].is_ascii_graphic() || out[i] == b' ' {\n let start = i;\n while i < out.len() && (out[i].is_ascii_graphic() || out[i] == b' ') {\n i += 1;\n }\n println!(\" TXT: {:?}\", String::from_utf8_lossy(&out[start..i]));\n } else {\n i += 1;\n }\n }\n\n // Also check ratatui Color mapping\n println!(\"\\n=== ratatui Color → crossterm Color mapping ===\");\n use ratatui::style::Color;\n println!(\" Color::Red = {:?}\", Color::Red);\n println!(\" Color::Indexed(1) = {:?}\", Color::Indexed(1));\n println!(\" Color::LightRed = {:?}\", Color::LightRed);\n println!(\" Color::Indexed(9) = {:?}\", Color::Indexed(9));\n}\n"
},
{
"path": "examples/enter_diag.rs",
"content": "/// Diagnostic tool: dumps ALL raw crossterm events (Press, Release, Repeat)\n/// for Enter and modified-Enter to prove what each terminal emulator reports.\n/// Run inside Windows Terminal and WezTerm to compare behavior.\n/// Press Ctrl+C to exit.\n///\n/// Writes to both stdout (for the user) and ~/.psmux/enter_diag_raw.log (for analysis).\nuse crossterm::event::{self, Event, KeyCode, KeyModifiers};\nuse crossterm::terminal::{enable_raw_mode, disable_raw_mode};\nuse std::io::Write;\nuse std::time::Instant;\n\nfn main() {\n let home = std::env::var(\"USERPROFILE\").unwrap_or_default();\n let log_path = format!(\"{}/.psmux/enter_diag_raw.log\", home);\n let _ = std::fs::create_dir_all(format!(\"{}/.psmux\", home));\n let mut log = std::fs::OpenOptions::new()\n .create(true).truncate(true).write(true)\n .open(&log_path).expect(\"Cannot open log file\");\n\n enable_raw_mode().unwrap();\n let start = Instant::now();\n let header = format!(\"=== Crossterm Raw Event Dumper (log: {}) ===\", log_path);\n println!(\"{}\\r\", header);\n writeln!(log, \"{}\", header).ok();\n println!(\"Press Shift+Enter, Alt+Enter, Ctrl+Enter, plain Enter\\r\");\n println!(\"Press Ctrl+C to exit\\r\");\n println!(\"ALL Enter events (Press, Release, Repeat) are logged.\\r\");\n println!(\"---\\r\");\n loop {\n if event::poll(std::time::Duration::from_millis(50)).unwrap() {\n let evt = event::read().unwrap();\n let t = start.elapsed().as_millis();\n match &evt {\n Event::Key(key) => {\n if matches!(key.code, KeyCode::Enter) || \n (matches!(key.code, KeyCode::Char('c')) && key.modifiers.contains(KeyModifiers::CONTROL)) {\n let line = format!(\"T+{:>6}ms {:?} code={:?} mods={:?} state={:?}\",\n t, key.kind, key.code, key.modifiers, key.state);\n println!(\"{}\\r\", line);\n writeln!(log, \"{}\", line).ok();\n log.flush().ok();\n }\n if key.code == KeyCode::Char('c') && key.modifiers.contains(KeyModifiers::CONTROL) {\n break;\n }\n }\n _ => {}\n }\n }\n }\n disable_raw_mode().unwrap();\n println!(\"\\r\\nDone. Log saved to: {}\\r\", log_path);\n}\n"
},
{
"path": "examples/key_diag.rs",
"content": "// Diagnostic for issue #226: dump every key event crossterm produces,\n// plus the raw INPUT_RECORD as seen by ReadConsoleInputW, side by side.\n//\n// Run visibly. Press the keys you want to inspect (or inject via the\n// injector with {RAW:vk:ch:ctrl}). Events are appended to:\n// $TEMP/psmux_key_diag.log\n// Press 'q' to quit.\n\nuse crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};\nuse crossterm::terminal::{disable_raw_mode, enable_raw_mode};\nuse std::fs::OpenOptions;\nuse std::io::Write;\nuse std::path::PathBuf;\n\nfn log_path() -> PathBuf {\n let dir = std::env::var(\"TEMP\")\n .or_else(|_| std::env::var(\"TMP\"))\n .unwrap_or_else(|_| \".\".into());\n PathBuf::from(dir).join(\"psmux_key_diag.log\")\n}\n\nfn append(line: &str) {\n let p = log_path();\n if let Ok(mut f) = OpenOptions::new().create(true).append(true).open(&p) {\n let _ = writeln!(f, \"{}\", line);\n }\n}\n\nfn main() {\n // Truncate previous log\n let _ = std::fs::write(log_path(), \"\");\n append(&format!(\"=== key_diag started, log={:?} ===\", log_path()));\n println!(\"Key diagnostic. Press keys to log. Press 'q' to quit.\");\n println!(\"Log file: {:?}\", log_path());\n enable_raw_mode().expect(\"raw mode\");\n loop {\n if let Ok(true) = event::poll(std::time::Duration::from_millis(500)) {\n match event::read() {\n Ok(Event::Key(k)) if k.kind == KeyEventKind::Press => {\n let code_str = match k.code {\n KeyCode::Char(c) => format!(\"Char({:?}) = U+{:04X}\", c, c as u32),\n other => format!(\"{:?}\", other),\n };\n let mods: Vec<&str> = [\n (KeyModifiers::CONTROL, \"C\"),\n (KeyModifiers::ALT, \"A\"),\n (KeyModifiers::SHIFT, \"S\"),\n (KeyModifiers::SUPER, \"M\"),\n ]\n .iter()\n .filter(|(m, _)| k.modifiers.contains(*m))\n .map(|(_, n)| *n)\n .collect();\n let line = format!(\n \"KEY code={} mods=[{}]\",\n code_str,\n mods.join(\"|\")\n );\n println!(\"{}\", line);\n append(&line);\n if matches!(k.code, KeyCode::Char('q')) && k.modifiers.is_empty() {\n break;\n }\n }\n Ok(other) => {\n let line = format!(\"EVT {:?}\", other);\n println!(\"{}\", line);\n append(&line);\n }\n Err(e) => {\n let line = format!(\"ERR {:?}\", e);\n println!(\"{}\", line);\n append(&line);\n break;\n }\n }\n }\n }\n disable_raw_mode().ok();\n append(\"=== key_diag done ===\");\n}\n"
},
{
"path": "examples/key_test.rs",
"content": "use crossterm::event::{self, Event, KeyCode, KeyModifiers, KeyEventKind};\nuse crossterm::terminal::{enable_raw_mode, disable_raw_mode};\nfn main() {\n enable_raw_mode().unwrap();\n println!(\"Press Ctrl+Q (then Ctrl+C to exit):\");\n loop {\n if event::poll(std::time::Duration::from_secs(5)).unwrap() {\n match event::read().unwrap() {\n Event::Key(key) if key.kind == KeyEventKind::Press => {\n println!(\"Key: code={:?} modifiers={:?} char_byte={}\", \n key.code, key.modifiers,\n match key.code { KeyCode::Char(c) => format!(\"0x{:02x}\", c as u32), _ => \"N/A\".into() });\n if key.code == KeyCode::Char('c') && key.modifiers.contains(KeyModifiers::CONTROL) {\n break;\n }\n }\n _ => {}\n }\n }\n }\n disable_raw_mode().unwrap();\n}\n"
},
{
"path": "examples/latency_harness.rs",
"content": "// examples/latency_harness.rs\n//\n// ConPTY-based latency harness for psmux.\n//\n// This is the most accurate test possible: it creates a real pseudo-terminal\n// (exactly like Windows Terminal does), spawns psmux inside it, sends\n// keystrokes through the PTY input pipe, and measures when output appears.\n//\n// Full pipeline measured:\n// keystroke → crossterm poll → TCP → server → ConPTY(WSL) echo\n// → vt100 parse → JSON serialize → TCP → JSON parse → ratatui render\n// → crossterm stdout → ConPTY output pipe → THIS harness detects it\n//\n// Usage:\n// cargo run --release --example latency_harness\n// cargo run --release --example latency_harness -- --pwsh\n// cargo run --release --example latency_harness -- --chars 80 --delay 200\n\nuse portable_pty::{CommandBuilder, PtySize, native_pty_system};\nuse std::io::{Read, Write};\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::sync::Arc;\nuse std::time::{Duration, Instant};\nuse std::{env, thread};\n\nfn main() {\n let args: Vec<String> = env::args().collect();\n let use_pwsh = args.iter().any(|a| a == \"--pwsh\");\n let char_count: usize = args\n .windows(2)\n .find(|w| w[0] == \"--chars\")\n .and_then(|w| w[1].parse().ok())\n .unwrap_or(80);\n let inter_delay_ms: u64 = args\n .windows(2)\n .find(|w| w[0] == \"--delay\")\n .and_then(|w| w[1].parse().ok())\n .unwrap_or(200);\n\n let shell = if use_pwsh { \"pwsh\" } else { \"wsl\" };\n println!(\"=== ConPTY Latency Harness ===\");\n println!(\n \"Shell: {}, Chars: {}, Inter-key delay: {}ms\",\n shell, char_count, inter_delay_ms\n );\n println!();\n\n let psmux_exe = find_psmux_exe();\n let session_name = format!(\"harness_{}\", std::process::id());\n let home = env::var(\"USERPROFILE\").unwrap_or_default();\n let port_file = format!(\"{}\\\\.psmux\\\\{}.port\", home, session_name);\n let key_file = format!(\"{}\\\\.psmux\\\\{}.key\", home, session_name);\n\n // ── 1. Start detached psmux server ──\n println!(\"[1] Starting psmux server...\");\n {\n let mut cmd = std::process::Command::new(&psmux_exe);\n cmd.args([\"new-session\", \"-d\", \"-s\", &session_name]);\n if !use_pwsh {\n cmd.arg(\"wsl\");\n }\n cmd.stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .spawn()\n .expect(\"Failed to start psmux server\");\n }\n wait_for_files(&port_file, &key_file, Duration::from_secs(10));\n let port: u16 = std::fs::read_to_string(&port_file)\n .unwrap()\n .trim()\n .parse()\n .unwrap();\n let key = std::fs::read_to_string(&key_file).unwrap().trim().to_string();\n println!(\" Server on port {}\", port);\n\n // ── 2. Disable status-bar clock via TCP ──\n // This prevents the status bar time from causing periodic re-renders\n // that confuse our output detection.\n println!(\"[2] Disabling status bar clock...\");\n send_oneshot(&psmux_exe, &session_name, \"set status-right \\\"\\\"\");\n send_oneshot(&psmux_exe, &session_name, \"set status-left \\\"test\\\"\");\n thread::sleep(Duration::from_millis(200));\n\n // ── 3. Create ConPTY, spawn psmux attach ──\n println!(\"[3] Creating ConPTY and attaching client...\");\n let pty_system = native_pty_system();\n let pair = pty_system\n .openpty(PtySize {\n rows: 30,\n cols: 120,\n pixel_width: 0,\n pixel_height: 0,\n })\n .expect(\"openpty\");\n\n let mut cmd = CommandBuilder::new(&psmux_exe);\n cmd.args([\"attach\", \"-t\", &session_name]);\n let _child = pair\n .slave\n .spawn_command(cmd)\n .expect(\"spawn psmux client\");\n drop(pair.slave);\n\n let reader = pair.master.try_clone_reader().expect(\"clone reader\");\n let mut pty_writer = pair.master.take_writer().expect(\"take writer\");\n\n // ── 4. Output tracker thread ──\n // Track both total bytes AND last-activity timestamp (nanos since epoch)\n let epoch = Instant::now();\n let total_bytes = Arc::new(AtomicU64::new(0));\n let last_output_nanos = Arc::new(AtomicU64::new(0));\n {\n let tb = Arc::clone(&total_bytes);\n let lon = Arc::clone(&last_output_nanos);\n let ep = epoch;\n thread::spawn(move || {\n let mut r = reader;\n let mut buf = [0u8; 65536];\n loop {\n match r.read(&mut buf) {\n Ok(0) => break,\n Ok(n) => {\n tb.fetch_add(n as u64, Ordering::Release);\n let now_ns = ep.elapsed().as_nanos() as u64;\n lon.store(now_ns, Ordering::Release);\n }\n Err(_) => break,\n }\n }\n });\n }\n\n // ── 5. Wait for initial render + WSL startup ──\n println!(\"[4] Waiting for shell startup...\");\n thread::sleep(Duration::from_secs(2));\n if !use_pwsh {\n thread::sleep(Duration::from_secs(1));\n }\n\n // ── 6. Clear screen ──\n println!(\"[5] Clearing screen...\");\n for ch in b\"clear\" {\n pty_writer.write_all(&[*ch]).unwrap();\n pty_writer.flush().unwrap();\n thread::sleep(Duration::from_millis(30));\n }\n pty_writer.write_all(b\"\\r\").unwrap();\n pty_writer.flush().unwrap();\n thread::sleep(Duration::from_millis(1500));\n\n // ── 7. Type characters and measure latency ──\n println!(\n \"[6] Typing {} chars ({}ms gap). Measuring full pipeline latency...\",\n char_count, inter_delay_ms\n );\n println!();\n\n let chars: Vec<u8> = b\"abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz\"\n .iter()\n .cycle()\n .take(char_count)\n .copied()\n .collect();\n\n let mut latencies: Vec<f64> = Vec::with_capacity(char_count);\n\n for (i, &ch) in chars.iter().enumerate() {\n // ── Wait for output to fully quiesce ──\n // We need at least 100ms of zero output to be sure nothing is happening.\n wait_for_quiesce(&last_output_nanos, &epoch, Duration::from_millis(100));\n\n // Record the send time (nanos since epoch)\n let send_nanos = epoch.elapsed().as_nanos() as u64;\n let send_instant = Instant::now();\n\n // ── Send keystroke ──\n pty_writer.write_all(&[ch]).unwrap();\n pty_writer.flush().unwrap();\n\n // ── Wait for output that arrives AFTER our keystroke ──\n // This guarantees we measure the actual echo, not lingering output.\n let timeout = Duration::from_millis(2000);\n let mut latency_ms: f64 = 2000.0;\n loop {\n let last_ns = last_output_nanos.load(Ordering::Acquire);\n if last_ns > send_nanos {\n // Output arrived after we sent the key!\n latency_ms = send_instant.elapsed().as_secs_f64() * 1000.0;\n break;\n }\n if send_instant.elapsed() > timeout {\n eprintln!(\n \" TIMEOUT: No output for '{}' (idx {}) after 2s\",\n ch as char, i\n );\n break;\n }\n thread::sleep(Duration::from_micros(50));\n }\n\n latencies.push(latency_ms);\n\n // Let the full frame render before next iteration\n thread::sleep(Duration::from_millis(5));\n\n // Progress every 10 chars\n if (i + 1) % 10 == 0 {\n let s = if i >= 9 { i - 9 } else { 0 };\n let slice = &latencies[s..=i];\n let avg: f64 = slice.iter().sum::<f64>() / slice.len() as f64;\n let max: f64 = slice.iter().cloned().fold(0.0f64, f64::max);\n let min: f64 = slice.iter().cloned().fold(f64::MAX, f64::min);\n println!(\n \" [{:3}-{:3}] avg={:6.1}ms min={:5.1}ms max={:6.1}ms\",\n s + 1,\n i + 1,\n avg,\n min,\n max\n );\n }\n\n // Inter-key delay\n if inter_delay_ms > 0 && i < char_count - 1 {\n thread::sleep(Duration::from_millis(inter_delay_ms));\n }\n }\n\n // Print remaining chars if not multiple of 10\n let rem = char_count % 10;\n if rem != 0 {\n let s = char_count - rem;\n let slice = &latencies[s..];\n let avg: f64 = slice.iter().sum::<f64>() / slice.len() as f64;\n let max: f64 = slice.iter().cloned().fold(0.0f64, f64::max);\n let min: f64 = slice.iter().cloned().fold(f64::MAX, f64::min);\n println!(\n \" [{:3}-{:3}] avg={:6.1}ms min={:5.1}ms max={:6.1}ms\",\n s + 1,\n char_count,\n avg,\n min,\n max\n );\n }\n\n // ── 8. Analysis ──\n println!();\n println!(\"=== Results: {} ===\", shell.to_uppercase());\n\n let n = latencies.len() as f64;\n let avg = latencies.iter().sum::<f64>() / n;\n let min = latencies.iter().cloned().fold(f64::MAX, f64::min);\n let max = latencies.iter().cloned().fold(0.0f64, f64::max);\n let mut sorted = latencies.clone();\n sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());\n let p50 = sorted[(sorted.len() as f64 * 0.5) as usize];\n let p90 = sorted[(sorted.len() as f64 * 0.9) as usize];\n let p95 = sorted[((sorted.len() as f64 * 0.95) as usize).min(sorted.len() - 1)];\n let p99 = sorted[((sorted.len() as f64 * 0.99) as usize).min(sorted.len() - 1)];\n\n println!(\n \" Avg={:.1}ms P50={:.1}ms P90={:.1}ms P95={:.1}ms P99={:.1}ms\",\n avg, p50, p90, p95, p99\n );\n println!(\" Min={:.1}ms Max={:.1}ms\", min, max);\n\n // Degradation analysis (crucial for \"slower and slower\" claim)\n let q_len = char_count / 4;\n if q_len > 0 {\n let q1: f64 = latencies[..q_len].iter().sum::<f64>() / q_len as f64;\n let q2: f64 =\n latencies[q_len..q_len * 2].iter().sum::<f64>() / q_len as f64;\n let q3: f64 =\n latencies[q_len * 2..q_len * 3].iter().sum::<f64>() / q_len as f64;\n let q4: f64 = latencies[q_len * 3..].iter().sum::<f64>()\n / (char_count - q_len * 3) as f64;\n let degrade = if q1 > 0.0 {\n ((q4 - q1) / q1) * 100.0\n } else {\n 0.0\n };\n\n println!();\n println!(\" Degradation trend (chars split into quarters):\");\n println!(\n \" Q1 [{:3}-{:3}] = {:6.1}ms avg\",\n 1, q_len, q1\n );\n println!(\n \" Q2 [{:3}-{:3}] = {:6.1}ms avg\",\n q_len + 1,\n q_len * 2,\n q2\n );\n println!(\n \" Q3 [{:3}-{:3}] = {:6.1}ms avg\",\n q_len * 2 + 1,\n q_len * 3,\n q3\n );\n println!(\n \" Q4 [{:3}-{:3}] = {:6.1}ms avg\",\n q_len * 3 + 1,\n char_count,\n q4\n );\n println!(\" Q1->Q4 change: {:+.1}%\", degrade);\n\n if degrade.abs() < 15.0 {\n println!(\" VERDICT: No significant degradation\");\n } else if degrade > 0.0 {\n println!(\n \" VERDICT: *** DEGRADATION DETECTED ({:+.0}%) ***\",\n degrade\n );\n } else {\n println!(\" VERDICT: Improved over time\");\n }\n }\n\n // Distribution\n println!();\n let buckets: Vec<(&str, f64, f64)> = vec![\n (\"0-10ms\", 0.0, 10.0),\n (\"10-20ms\", 10.0, 20.0),\n (\"20-40ms\", 20.0, 40.0),\n (\"40-60ms\", 40.0, 60.0),\n (\"60-100ms\", 60.0, 100.0),\n (\"100-200ms\", 100.0, 200.0),\n (\"200ms+\", 200.0, 99999.0),\n ];\n for (name, lo, hi) in &buckets {\n let cnt = latencies.iter().filter(|&&v| v >= *lo && v < *hi).count();\n if cnt > 0 {\n let pct = (cnt as f64 / char_count as f64 * 100.0) as usize;\n let bar: String = \"#\".repeat(pct.min(50));\n println!(\" {:>8}: {:3} ({:3}%) {}\", name, cnt, pct, bar);\n }\n }\n\n println!();\n print!(\" Raw: \");\n for (i, v) in latencies.iter().enumerate() {\n if i > 0 {\n print!(\", \");\n }\n print!(\"{:.1}\", v);\n }\n println!();\n\n // ── 9. Cleanup ──\n println!();\n println!(\"Cleaning up...\");\n drop(pty_writer);\n\n let _ = std::process::Command::new(&psmux_exe)\n .args([\"kill-server\", \"-t\", &session_name])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status();\n thread::sleep(Duration::from_millis(500));\n\n let _ = std::fs::remove_file(&port_file);\n let _ = std::fs::remove_file(&key_file);\n println!(\"Done.\");\n}\n\nfn find_psmux_exe() -> std::path::PathBuf {\n let self_exe = env::current_exe().unwrap();\n let mut dir = self_exe.parent().unwrap().to_path_buf();\n loop {\n let candidate = dir.join(\"psmux.exe\");\n if candidate.exists() {\n return candidate;\n }\n if !dir.pop() {\n panic!(\"Could not find psmux.exe\");\n }\n }\n}\n\nfn wait_for_files(port_file: &str, key_file: &str, timeout: Duration) {\n let start = Instant::now();\n while !std::path::Path::new(port_file).exists()\n || !std::path::Path::new(key_file).exists()\n {\n if start.elapsed() > timeout {\n panic!(\"Timeout waiting for server files\");\n }\n thread::sleep(Duration::from_millis(100));\n }\n}\n\nfn send_oneshot(psmux_exe: &std::path::Path, session: &str, cmd: &str) {\n let parts: Vec<&str> = cmd.split_whitespace().collect();\n let mut command = std::process::Command::new(psmux_exe);\n for p in &parts {\n command.arg(p);\n }\n command.args([\"-t\", session]);\n command\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null());\n let _ = command.status();\n}\n\nfn wait_for_quiesce(\n last_output_nanos: &Arc<AtomicU64>,\n epoch: &Instant,\n quiet_duration: Duration,\n) {\n let quiet_ns = quiet_duration.as_nanos() as u64;\n loop {\n let last_ns = last_output_nanos.load(Ordering::Acquire);\n let now_ns = epoch.elapsed().as_nanos() as u64;\n if now_ns.saturating_sub(last_ns) >= quiet_ns {\n break;\n }\n thread::sleep(Duration::from_millis(5));\n }\n}\n"
},
{
"path": "examples/pipeline_diag.rs",
"content": "// Diagnostic: replicate the EXACT psmux rendering pipeline end-to-end\n// and verify whether strikethrough (SGR 9) actually appears in the\n// terminal output bytes.\n//\n// Pipeline: vt100 parser → cell extraction → Span/Line building →\n// Clear + Paragraph → ratatui Terminal::draw() → CrosstermBackend → bytes\n\nuse ratatui::backend::CrosstermBackend;\nuse ratatui::buffer::Buffer;\nuse ratatui::layout::Rect;\nuse ratatui::prelude::*;\nuse ratatui::style::{Color, Modifier, Style};\nuse ratatui::widgets::{Clear, Paragraph, Widget};\nuse ratatui::Terminal;\nuse unicode_width::UnicodeWidthStr;\n\n/// Identical to rendering.rs vt_to_color\nfn vt_to_color(c: vt100::Color) -> Color {\n match c {\n vt100::Color::Default => Color::Reset,\n vt100::Color::Idx(0) => Color::Black,\n vt100::Color::Idx(1) => Color::Red,\n vt100::Color::Idx(2) => Color::Green,\n vt100::Color::Idx(3) => Color::Yellow,\n vt100::Color::Idx(4) => Color::Blue,\n vt100::Color::Idx(5) => Color::Magenta,\n vt100::Color::Idx(6) => Color::Cyan,\n vt100::Color::Idx(7) => Color::Gray,\n vt100::Color::Idx(8) => Color::DarkGray,\n vt100::Color::Idx(9) => Color::LightRed,\n vt100::Color::Idx(10) => Color::LightGreen,\n vt100::Color::Idx(11) => Color::LightYellow,\n vt100::Color::Idx(12) => Color::LightBlue,\n vt100::Color::Idx(13) => Color::LightMagenta,\n vt100::Color::Idx(14) => Color::LightCyan,\n vt100::Color::Idx(15) => Color::White,\n vt100::Color::Idx(i) => Color::Indexed(i),\n vt100::Color::Rgb(r, g, b) => Color::Rgb(r, g, b),\n }\n}\n\n/// Identical to the cell → span logic in render_node\nfn build_lines_from_screen(screen: &vt100::Screen, rows: u16, cols: u16) -> Vec<Line<'static>> {\n let mut lines: Vec<Line> = Vec::with_capacity(rows as usize);\n for r in 0..rows {\n let mut spans: Vec<Span> = Vec::with_capacity(cols as usize);\n let mut c = 0;\n while c < cols {\n if let Some(cell) = screen.cell(r, c) {\n let fg = vt_to_color(cell.fgcolor());\n let bg = vt_to_color(cell.bgcolor());\n let mut style = Style::default().fg(fg).bg(bg);\n if cell.dim() { style = style.add_modifier(Modifier::DIM); }\n if cell.bold() { style = style.add_modifier(Modifier::BOLD); }\n if cell.italic() { style = style.add_modifier(Modifier::ITALIC); }\n if cell.underline() { style = style.add_modifier(Modifier::UNDERLINED); }\n if cell.inverse() { style = style.add_modifier(Modifier::REVERSED); }\n if cell.blink() { style = style.add_modifier(Modifier::SLOW_BLINK); }\n if cell.strikethrough() { style = style.add_modifier(Modifier::CROSSED_OUT); }\n let text = if cell.hidden() {\n \" \".to_string()\n } else {\n cell.contents().to_string()\n };\n let w = UnicodeWidthStr::width(text.as_str()) as u16;\n if w == 0 {\n spans.push(Span::styled(\" \".to_string(), style));\n c += 1;\n } else if w >= 2 {\n if c + w > cols {\n spans.push(Span::styled(\" \".to_string(), style));\n c += 1;\n } else {\n spans.push(Span::styled(text, style));\n c += 2;\n }\n } else {\n spans.push(Span::styled(text, style));\n c += 1;\n }\n } else {\n spans.push(Span::raw(\" \".to_string()));\n c += 1;\n }\n }\n lines.push(Line::from(spans));\n }\n lines\n}\n\nfn main() {\n let rows: u16 = 3;\n let cols: u16 = 40;\n\n // Step 1: Parse VT input exactly as psmux does\n let mut parser = vt100::Parser::new(rows, cols, 0);\n parser.process(b\"\\x1b[9mSTRIKE\\x1b[29m NORMAL \\x1b[8mHIDDEN\\x1b[28m VIS\\r\\n\");\n parser.process(b\"\\x1b[1;31mBOLD_RED\\x1b[0m plain\\r\\n\");\n parser.process(b\"\\x1b[37mIDX7\\x1b[0m \\x1b[97mIDX15\\x1b[0m\");\n\n let screen = parser.screen();\n\n // Verify parser state\n println!(\"=== Parser cell state ===\");\n for col in 0..6 {\n let cell = screen.cell(0, col).unwrap();\n println!(\" cell(0,{col}): '{}' strikethrough={} hidden={}\",\n cell.contents(), cell.strikethrough(), cell.hidden());\n }\n let hcell = screen.cell(0, 15).unwrap();\n println!(\" cell(0,15): '{}' hidden={}\", hcell.contents(), hcell.hidden());\n\n // Step 2: Build lines exactly as render_node does\n let lines = build_lines_from_screen(screen, rows, cols);\n\n // Step 3: Inspect the spans\n println!(\"\\n=== Span inspection ===\");\n for (i, line) in lines.iter().enumerate() {\n for span in line.spans.iter() {\n let has_crossed = span.style.add_modifier.contains(Modifier::CROSSED_OUT);\n let has_bold = span.style.add_modifier.contains(Modifier::BOLD);\n if has_crossed || has_bold || span.content.trim() != \"\" {\n let content_preview: String = span.content.chars().take(20).collect();\n println!(\" line[{i}] span '{content_preview}': crossed_out={has_crossed} bold={has_bold} fg={:?}\",\n span.style.fg);\n }\n }\n }\n\n // Step 4: Render through ratatui Terminal, EXACTLY as psmux does\n // (Clear + Paragraph, through Terminal::draw())\n // Test MULTIPLE frames like the real psmux render loop\n let output_bytes: std::cell::RefCell<Vec<u8>> = std::cell::RefCell::new(Vec::new());\n // Use a shared writer so we can inspect between frames\n struct SharedWriter<'a>(&'a std::cell::RefCell<Vec<u8>>);\n impl<'a> std::io::Write for SharedWriter<'a> {\n fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {\n self.0.borrow_mut().extend_from_slice(buf);\n Ok(buf.len())\n }\n fn flush(&mut self) -> std::io::Result<()> { Ok(()) }\n }\n {\n let backend = CrosstermBackend::new(SharedWriter(&output_bytes));\n let mut terminal = Terminal::new(backend).unwrap();\n terminal.resize(Rect::new(0, 0, cols, rows)).unwrap();\n\n // Frame 1: initial render\n terminal.draw(|f| {\n let area = f.area();\n f.render_widget(Clear, area);\n let para = Paragraph::new(Text::from(lines.clone()));\n f.render_widget(para, area);\n }).unwrap();\n\n let frame1_len = output_bytes.borrow().len();\n println!(\"\\n=== Frame 1 output: {} bytes ===\", frame1_len);\n let f1 = String::from_utf8_lossy(&output_bytes.borrow()).to_string();\n let f1_esc: String = f1.chars().map(|c| {\n if c == '\\x1b' { \"\\\\e\".to_string() }\n else if c.is_control() { format!(\"\\\\x{:02x}\", c as u32) }\n else { c.to_string() }\n }).collect();\n println!(\"{}\", &f1_esc[..f1_esc.len().min(400)]);\n println!(\"Frame 1 has \\\\e[9m: {}\", f1.contains(\"\\x1b[9m\"));\n\n // Frame 2: same content (simulates steady-state redraw)\n terminal.draw(|f| {\n let area = f.area();\n f.render_widget(Clear, area);\n let para = Paragraph::new(Text::from(lines.clone()));\n f.render_widget(para, area);\n }).unwrap();\n\n let total_after_f2 = output_bytes.borrow().len();\n let frame2_bytes = total_after_f2 - frame1_len;\n println!(\"\\n=== Frame 2 output: {} more bytes (diff only) ===\", frame2_bytes);\n if frame2_bytes > 0 {\n let all = output_bytes.borrow();\n let f2_slice = &all[frame1_len..];\n let f2 = String::from_utf8_lossy(f2_slice).to_string();\n let f2_esc: String = f2.chars().map(|c| {\n if c == '\\x1b' { \"\\\\e\".to_string() }\n else if c.is_control() { format!(\"\\\\x{:02x}\", c as u32) }\n else { c.to_string() }\n }).collect();\n println!(\"{}\", &f2_esc[..f2_esc.len().min(400)]);\n // Check if frame 2 has a stray \\e[0m that resets everything\n if f2.contains(\"\\x1b[0m\") {\n println!(\"WARNING: Frame 2 has \\\\e[0m reset!\");\n }\n } else {\n println!(\"(no diff - content identical, as expected)\");\n }\n\n // Frame 3: content changes (cursor moves, new text)\n let mut parser2 = vt100::Parser::new(rows, cols, 0);\n parser2.process(b\"\\x1b[9mNEW_STRIKE\\x1b[29m rest\\r\\n\");\n parser2.process(b\"line2\\r\\n\");\n parser2.process(b\"line3\");\n let lines2 = build_lines_from_screen(parser2.screen(), rows, cols);\n\n terminal.draw(|f| {\n let area = f.area();\n f.render_widget(Clear, area);\n let para = Paragraph::new(Text::from(lines2));\n f.render_widget(para, area);\n }).unwrap();\n\n let total_after_f3 = output_bytes.borrow().len();\n let frame3_bytes = total_after_f3 - total_after_f2;\n println!(\"\\n=== Frame 3 output: {} more bytes (new content) ===\", frame3_bytes);\n if frame3_bytes > 0 {\n let all = output_bytes.borrow();\n let f3_slice = &all[total_after_f2..];\n let f3 = String::from_utf8_lossy(f3_slice).to_string();\n let f3_esc: String = f3.chars().map(|c| {\n if c == '\\x1b' { \"\\\\e\".to_string() }\n else if c.is_control() { format!(\"\\\\x{:02x}\", c as u32) }\n else { c.to_string() }\n }).collect();\n println!(\"{}\", &f3_esc[..f3_esc.len().min(400)]);\n println!(\"Frame 3 has \\\\e[9m: {}\", f3.contains(\"\\x1b[9m\"));\n }\n }\n\n // Step 5: Analyze the output bytes\n let binding = output_bytes.borrow();\n let out_str = String::from_utf8_lossy(&binding);\n println!(\"\\n=== CrosstermBackend output analysis ===\");\n println!(\"Total bytes: {}\", output_bytes.borrow().len());\n\n // Search for SGR 9 (strikethrough)\n let has_sgr9 = out_str.contains(\"\\x1b[9m\");\n println!(\"Contains \\\\e[9m (strikethrough): {has_sgr9}\");\n\n // Search for SGR 8 (hidden) -- should NOT be present\n let has_sgr8 = out_str.contains(\"\\x1b[8m\");\n println!(\"Contains \\\\e[8m (hidden): {has_sgr8} (should be false)\");\n\n // Search for CROSSED_OUT in various forms\n let crossed_patterns = [\"\\x1b[9m\", \";9m\", \";9;\"];\n for pat in &crossed_patterns {\n if out_str.contains(pat) {\n println!(\" Found pattern: {:?}\", pat);\n }\n }\n\n // Dump the first 500 chars of escaped output\n println!(\"\\n=== Raw output (escaped, first 800 chars) ===\");\n let escaped: String = out_str.chars().take(800).map(|c| {\n if c == '\\x1b' { \"\\\\e\".to_string() }\n else if c == '\\r' { \"\\\\r\".to_string() }\n else if c == '\\n' { \"\\\\n\".to_string() }\n else if c.is_control() { format!(\"\\\\x{:02x}\", c as u32) }\n else { c.to_string() }\n }).collect();\n println!(\"{escaped}\");\n\n // Step 6: Check the ratatui buffer state directly\n println!(\"\\n=== Buffer cell modifier check ===\");\n {\n let mut backend2 = CrosstermBackend::new(Vec::<u8>::new());\n let mut terminal2 = Terminal::new(backend2).unwrap();\n terminal2.resize(Rect::new(0, 0, cols, rows)).unwrap();\n let frame_result = terminal2.draw(|f| {\n let area = f.area();\n f.render_widget(Clear, area);\n let para2 = Paragraph::new(Text::from(lines.clone()));\n f.render_widget(para2, area);\n // Check buffer cells\n let buf = f.buffer_mut();\n for col in 0..6u16 {\n let bcell = &buf[(col, 0u16)];\n println!(\" buf[({col},0)]: '{}' modifier={:?}\",\n bcell.symbol(), bcell.modifier);\n }\n println!(\" buf[(7,0)]: '{}' modifier={:?}\", buf[(7u16, 0u16)].symbol(), buf[(7u16, 0u16)].modifier);\n });\n }\n\n // Final verdict\n println!(\"\\n=== VERDICT ===\");\n if has_sgr9 {\n println!(\"PASS: Strikethrough (\\\\e[9m) IS emitted in terminal output\");\n } else {\n println!(\"FAIL: Strikethrough (\\\\e[9m) is MISSING from terminal output!\");\n println!(\" The bug is in the ratatui rendering pipeline.\");\n }\n if !has_sgr8 {\n println!(\"PASS: Hidden (\\\\e[8m) is NOT in output (workaround working)\");\n } else {\n println!(\"FAIL: Hidden (\\\\e[8m) leaked into output\");\n }\n}\n\n"
},
{
"path": "examples/pty_diag.rs",
"content": "use portable_pty::{native_pty_system, PtySize, CommandBuilder};\nuse std::io::{Read, Write};\n\nfn read_output(reader: &mut dyn Read, mut writer: Option<&mut dyn Write>, timeout_secs: u64, expect: &str) -> String {\n let mut buf = [0u8; 4096];\n let mut all = String::new();\n let start = std::time::Instant::now();\n let mut responded = false;\n loop {\n if start.elapsed() > std::time::Duration::from_secs(timeout_secs) {\n println!(\" [TIMEOUT after {}s]\", timeout_secs);\n break;\n }\n match reader.read(&mut buf) {\n Ok(0) => {\n std::thread::sleep(std::time::Duration::from_millis(50));\n }\n Ok(n) => {\n let chunk = String::from_utf8_lossy(&buf[..n]);\n println!(\" Read {} bytes: {:?}\", n, &chunk[..chunk.len().min(200)]);\n all.push_str(&chunk);\n // If we see \\x1b[6n (DSR), respond with cursor position report\n if !responded && all.contains(\"\\x1b[6n\") {\n if let Some(w) = writer.as_deref_mut() {\n println!(\" >> Responding to DSR with \\\\x1b[1;1R\");\n let _ = w.write_all(b\"\\x1b[1;1R\");\n let _ = w.flush();\n responded = true;\n }\n }\n if all.contains(expect) { break; }\n }\n Err(e) => { println!(\" Read error: {}\", e); break; }\n }\n }\n all\n}\n\nfn main() {\n let pty_system = native_pty_system();\n let size = PtySize { rows: 24, cols: 80, pixel_width: 0, pixel_height: 0 };\n\n // TEST A: Respond to DSR query\n println!(\"=== TEST A: Respond to DSR \\\\x1b[6n] with cursor position ===\");\n {\n let pair = pty_system.openpty(size).expect(\"openpty\");\n let mut cmd = CommandBuilder::new(\"cmd.exe\");\n cmd.args(&[\"/C\", \"echo TESTA_HELLO\"]);\n let mut child = pair.slave.spawn_command(cmd).expect(\"spawn\");\n drop(pair.slave);\n let mut reader = pair.master.try_clone_reader().expect(\"reader\");\n let mut writer = pair.master.take_writer().expect(\"writer\");\n let out = read_output(&mut *reader, Some(&mut *writer), 8, \"TESTA_HELLO\");\n let _ = child.wait();\n println!(\" Result: {}\", if out.contains(\"TESTA_HELLO\") { \"PASS\" } else { \"FAIL - no output\" });\n }\n\n // TEST B: Same but do NOT drop slave\n println!(\"\\n=== TEST B: No slave drop + respond to DSR ===\");\n {\n let pair = pty_system.openpty(size).expect(\"openpty\");\n let mut cmd = CommandBuilder::new(\"cmd.exe\");\n cmd.args(&[\"/C\", \"echo TESTB_HELLO\"]);\n let mut child = pair.slave.spawn_command(cmd).expect(\"spawn\");\n // NOT dropping slave\n let mut reader = pair.master.try_clone_reader().expect(\"reader\");\n let mut writer = pair.master.take_writer().expect(\"writer\");\n let out = read_output(&mut *reader, Some(&mut *writer), 8, \"TESTB_HELLO\");\n let _ = child.wait();\n drop(pair.slave);\n println!(\" Result: {}\", if out.contains(\"TESTB_HELLO\") { \"PASS\" } else { \"FAIL - no output\" });\n }\n\n // TEST C: Preemptive DSR response (write \\x1b[1;1R BEFORE reading)\n println!(\"\\n=== TEST C: Preemptive DSR response (write before read) ===\");\n {\n let pair = pty_system.openpty(size).expect(\"openpty\");\n let mut cmd = CommandBuilder::new(\"cmd.exe\");\n cmd.args(&[\"/C\", \"echo TESTC_HELLO\"]);\n let mut child = pair.slave.spawn_command(cmd).expect(\"spawn\");\n drop(pair.slave);\n let mut reader = pair.master.try_clone_reader().expect(\"reader\");\n let mut writer = pair.master.take_writer().expect(\"writer\");\n // Preemptive DSR response - write BEFORE any reading\n let _ = writer.write_all(b\"\\x1b[1;1R\");\n let _ = writer.flush();\n println!(\" >> Sent preemptive DSR response\");\n let out = read_output(&mut *reader, None, 8, \"TESTC_HELLO\");\n let _ = child.wait();\n println!(\" Result: {}\", if out.contains(\"TESTC_HELLO\") { \"PASS\" } else { \"FAIL - no output\" });\n }\n\n // TEST D: No DSR response at all (control - should hang)\n println!(\"\\n=== TEST D: No DSR response (control - expect FAIL) ===\");\n {\n let pair = pty_system.openpty(size).expect(\"openpty\");\n let mut cmd = CommandBuilder::new(\"cmd.exe\");\n cmd.args(&[\"/C\", \"echo TESTD_HELLO\"]);\n let mut child = pair.slave.spawn_command(cmd).expect(\"spawn\");\n drop(pair.slave);\n let mut reader = pair.master.try_clone_reader().expect(\"reader\");\n let _writer = pair.master.take_writer().expect(\"writer\");\n let out = read_output(&mut *reader, None, 5, \"TESTD_HELLO\");\n let _ = child.wait();\n println!(\" Result: {}\", if out.contains(\"TESTD_HELLO\") { \"PASS\" } else { \"FAIL - no output (expected)\" });\n }\n\n println!(\"\\n=== ALL TESTS COMPLETE ===\");\n}\n"
},
{
"path": "examples/pty_sgr_diag.rs",
"content": "/// Diagnostic: verify which SGR attributes survive ConPTY passthrough mode.\n/// Run with: cargo run --example pty_sgr_diag\nuse portable_pty::{native_pty_system, PtySize, CommandBuilder};\nuse std::io::Read;\nuse std::sync::{Arc, Mutex};\nuse std::time::Duration;\n\nfn main() {\n let pty_system = native_pty_system();\n let size = PtySize { rows: 24, cols: 80, pixel_width: 0, pixel_height: 0 };\n let pair = pty_system.openpty(size).expect(\"openpty failed\");\n\n let mut cmd = CommandBuilder::new(\"pwsh.exe\");\n cmd.args([\"-NoProfile\", \"-NoLogo\", \"-Command\",\n concat!(\n \"Write-Host \\\"`e[9mSTRIKE`e[29m `e[8mHIDDEN`e[28m `e[1;31mBOLDRED`e[0m `e[38;2;255;128;0mRGB`e[0m done\\\"; \",\n \"Start-Sleep -Milliseconds 200; \",\n \"exit\"\n )\n ]);\n\n let _child = pair.slave.spawn_command(cmd).expect(\"spawn failed\");\n drop(pair.slave);\n\n // Send preemptive DSR response — ConPTY sends \\e[6n and blocks until\n // it gets a cursor position report back\n let mut writer = pair.master.take_writer().expect(\"take writer\");\n writer.write_all(b\"\\x1b[1;1R\").expect(\"write DSR\");\n writer.flush().expect(\"flush DSR\");\n\n let mut reader = pair.master.try_clone_reader().expect(\"clone reader\");\n\n let all_data: Arc<Mutex<Vec<u8>>> = Arc::new(Mutex::new(Vec::new()));\n let data_clone = all_data.clone();\n\n // Reader thread (read blocks on ConPTY pipe)\n let reader_handle = std::thread::spawn(move || {\n let mut buf = vec![0u8; 65536];\n loop {\n match reader.read(&mut buf) {\n Ok(0) => break,\n Ok(n) => {\n data_clone.lock().unwrap().extend_from_slice(&buf[..n]);\n }\n Err(_) => break,\n }\n }\n });\n\n // Wait up to 8 seconds for PowerShell to start and produce output\n std::thread::sleep(Duration::from_secs(8));\n\n let data = all_data.lock().unwrap().clone();\n analyze_output(&data);\n\n // Don't wait for reader thread — just exit\n drop(reader_handle);\n std::process::exit(0);\n}\n\nfn analyze_output(all_data: &[u8]) {\n let text = String::from_utf8_lossy(all_data);\n println!(\"=== Raw output ({} bytes) ===\", all_data.len());\n\n // Show hex dump of escape sequences\n let mut i = 0;\n while i < all_data.len() {\n if all_data[i] == 0x1b {\n let start = i;\n i += 1;\n while i < all_data.len() && !all_data[i].is_ascii_alphabetic() {\n i += 1;\n }\n if i < all_data.len() {\n i += 1;\n }\n let seq = &all_data[start..i];\n let seq_str = String::from_utf8_lossy(seq);\n print!(\" ESC seq: {:?} = \", seq_str);\n for b in seq {\n print!(\"{:02x} \", b);\n }\n println!();\n } else {\n i += 1;\n }\n }\n\n println!(\"\\n=== SGR Attribute Check ===\");\n let has_sgr9 = text.contains(\"\\x1b[9m\") || text.contains(\";9m\") || text.contains(\";9;\");\n let has_sgr8 = text.contains(\"\\x1b[8m\") || text.contains(\";8m\") || text.contains(\";8;\");\n let has_sgr1_31 = text.contains(\"\\x1b[1;31m\") || text.contains(\"\\x1b[31;1m\");\n let has_rgb = text.contains(\"38;2;\");\n let has_indexed_1 = text.contains(\"38;5;1\");\n\n println!(\"SGR 9 (strikethrough): {}\", if has_sgr9 { \"FOUND\" } else { \"MISSING\" });\n println!(\"SGR 8 (hidden): {}\", if has_sgr8 { \"FOUND\" } else { \"MISSING\" });\n println!(\"SGR 1;31 (bold red): {}\", if has_sgr1_31 { \"FOUND\" } else { \"MISSING\" });\n println!(\"RGB color (38;2;): {}\", if has_rgb { \"FOUND\" } else { \"MISSING\" });\n println!(\"Indexed (38;5;1): {}\", if has_indexed_1 { \"FOUND (ConPTY re-encoded)\" } else { \"not present\" });\n\n println!(\"\\n=== vt100 Parser Check ===\");\n let mut parser = vt100::Parser::new(24, 80, 0);\n parser.process(all_data);\n let screen = parser.screen();\n for row in 0..4 {\n for col in 0..80 {\n if let Some(cell) = screen.cell(row, col) {\n let ch = cell.contents();\n if !ch.is_empty() && ch != \" \" {\n let attrs = format!(\n \"{}{}{}{}{}{}{}{}\",\n if cell.bold() { \"B\" } else { \".\" },\n if cell.dim() { \"D\" } else { \".\" },\n if cell.italic() { \"I\" } else { \".\" },\n if cell.underline() { \"U\" } else { \".\" },\n if cell.inverse() { \"V\" } else { \".\" },\n if cell.blink() { \"K\" } else { \".\" },\n if cell.hidden() { \"H\" } else { \".\" },\n if cell.strikethrough() { \"S\" } else { \".\" },\n );\n let fg = format!(\"{:?}\", cell.fgcolor());\n print!(\" r={} c={:2} ch='{}' attrs=[{}] fg={}\", row, col, ch, attrs, fg);\n if cell.strikethrough() { print!(\" <<< STRIKETHROUGH\"); }\n if cell.hidden() { print!(\" <<< HIDDEN\"); }\n println!();\n }\n }\n }\n }\n}\n"
},
{
"path": "examples/ratatui_render_diag.rs",
"content": "/// Diagnostic: verify ratatui crossterm backend emits correct SGR for all modifiers.\n/// Run with: cargo run --example ratatui_render_diag\nuse ratatui::backend::CrosstermBackend;\nuse ratatui::buffer::Buffer;\nuse ratatui::layout::Rect;\nuse ratatui::style::{Color, Modifier, Style};\nuse ratatui::Terminal;\nuse std::io::Write;\n\nfn main() {\n // Create terminal that writes to an in-memory buffer\n let mut raw_buf: Vec<u8> = Vec::new();\n {\n let backend = CrosstermBackend::new(&mut raw_buf);\n let mut terminal = Terminal::new(backend).unwrap();\n\n terminal.draw(|frame| {\n let area = Rect::new(0, 0, 60, 3);\n\n // Row 0: Test various modifiers\n let buf = frame.buffer_mut();\n\n // STRIKE (cols 0-5)\n let strike_style = Style::default().add_modifier(Modifier::CROSSED_OUT);\n for (i, ch) in \"STRIKE\".chars().enumerate() {\n buf[(area.x + i as u16, area.y)].set_char(ch).set_style(strike_style);\n }\n\n // Space\n buf[(area.x + 6, area.y)].set_char(' ');\n\n // HIDDEN (cols 7-12)\n let hidden_style = Style::default().add_modifier(Modifier::HIDDEN);\n for (i, ch) in \"HIDDEN\".chars().enumerate() {\n buf[(area.x + 7 + i as u16, area.y)].set_char(ch).set_style(hidden_style);\n }\n\n // Space\n buf[(area.x + 13, area.y)].set_char(' ');\n\n // BOLDRED (cols 14-20) — using named Color::Red (should emit SGR 31)\n let boldred_style = Style::default().fg(Color::Red).add_modifier(Modifier::BOLD);\n for (i, ch) in \"BOLDRED\".chars().enumerate() {\n buf[(area.x + 14 + i as u16, area.y)].set_char(ch).set_style(boldred_style);\n }\n\n // Space\n buf[(area.x + 21, area.y)].set_char(' ');\n\n // IDX1 (cols 22-25) — using Indexed(1) for comparison\n let idx1_style = Style::default().fg(Color::Indexed(1)).add_modifier(Modifier::BOLD);\n for (i, ch) in \"IDX1\".chars().enumerate() {\n buf[(area.x + 22 + i as u16, area.y)].set_char(ch).set_style(idx1_style);\n }\n }).unwrap();\n }\n\n // Write raw bytes to file for clean analysis\n std::fs::write(\"target/ratatui_sgr_dump.bin\", &raw_buf).unwrap();\n\n // Analyze the raw bytes\n println!(\"=== Raw ratatui output ({} bytes) ===\", raw_buf.len());\n println!(\"Written to target/ratatui_sgr_dump.bin\");\n println!();\n\n // Extract and print all escape sequences\n let mut i = 0;\n while i < raw_buf.len() {\n if raw_buf[i] == 0x1b {\n let start = i;\n i += 1;\n while i < raw_buf.len() && !raw_buf[i].is_ascii_alphabetic() {\n i += 1;\n }\n if i < raw_buf.len() {\n i += 1;\n }\n let seq = &raw_buf[start..i];\n let seq_str = String::from_utf8_lossy(seq);\n\n // Check if the next few bytes are printable text\n let text_start = i;\n while i < raw_buf.len() && raw_buf[i] >= 0x20 && raw_buf[i] < 0x7f && raw_buf[i] != 0x1b {\n i += 1;\n }\n let text_after = if i > text_start {\n String::from_utf8_lossy(&raw_buf[text_start..i]).to_string()\n } else {\n String::new()\n };\n\n if !text_after.is_empty() {\n println!(\" {} → {:?}\", seq_str, text_after);\n } else {\n println!(\" {}\", seq_str);\n }\n } else if raw_buf[i] >= 0x20 && raw_buf[i] < 0x7f {\n let start = i;\n while i < raw_buf.len() && raw_buf[i] >= 0x20 && raw_buf[i] < 0x7f && raw_buf[i] != 0x1b {\n i += 1;\n }\n println!(\" TEXT: {:?}\", String::from_utf8_lossy(&raw_buf[start..i]));\n } else {\n i += 1;\n }\n }\n\n // Check for specific sequences\n let text = String::from_utf8_lossy(&raw_buf);\n println!(\"\\n=== Key SGR Checks ===\");\n println!(\"Contains \\\\e[9m (strikethrough): {}\", text.contains(\"\\x1b[9m\") || text.contains(\";9m\"));\n println!(\"Contains \\\\e[8m (hidden): {}\", text.contains(\"\\x1b[8m\") || text.contains(\";8m\"));\n println!(\"Contains \\\\e[31m (dark red): {}\", text.contains(\"\\x1b[31m\") || text.contains(\";31m\"));\n println!(\"Contains \\\\e[38;5;1m (idx 1): {}\", text.contains(\"38;5;1m\") || text.contains(\"38;5;1;\"));\n println!(\"Contains \\\\e[1m (bold): {}\", text.contains(\"\\x1b[1m\") || text.contains(\";1m\") || text.contains(\";1;\"));\n}\n"
},
{
"path": "examples/test_cursor_debug.rs",
"content": "use vt100::Parser;\n\nfn main() {\n // Test: what happens when we process \"\\x1b[?25l\" (hide cursor) after RMCUP\n let mut p = Parser::new(24, 80, 0);\n \n // Simulate shell prompt\n p.process(b\"PS C:\\\\Users\\\\test> \");\n let (r, c) = p.screen().cursor_position();\n println!(\"Prompt cursor: row={} col={} hide={}\", r, c, p.screen().hide_cursor());\n \n // TUI enters alt screen\n p.process(b\"\\x1b[?1049h\");\n // TUI hides cursor (many TUI apps do this)\n p.process(b\"\\x1b[?25l\");\n println!(\"In alt after hide: hide={} alt={}\", p.screen().hide_cursor(), p.screen().alternate_screen());\n \n // TUI draws\n p.process(b\"\\x1b[1;1HTUI CONTENT\");\n \n // TUI sends RMCUP\n p.process(b\"\\x1b[?1049l\");\n let (r, c) = p.screen().cursor_position();\n println!(\"After RMCUP: row={} col={} hide={} alt={}\", r, c, p.screen().hide_cursor(), p.screen().alternate_screen());\n \n // Apply FULL_MODE_RESET (includes ?25h)\n p.process(b\"\\x1b[0m\\x1b[?25h\\x1b[?1l\\x1b[?9l\\x1b[?47l\\x1b[?1000l\\x1b[?1002l\\x1b[?1003l\\x1b[?1005l\\x1b[?1006l\\x1b[?2004l\");\n let (r, c) = p.screen().cursor_position();\n println!(\"After FULL_MODE_RESET: row={} col={} hide={}\", r, c, p.screen().hide_cursor());\n \n // Simulate what ConPTY might send after TUI exit\n // ConPTY might send cursor position queries, screen updates, etc.\n // Some apps send hide cursor just before RMCUP\n \n // Test: what if post-mortem data includes hide cursor?\n p.process(b\"\\x1b[?25l\");\n println!(\"After post-mortem hide: hide={}\", p.screen().hide_cursor());\n \n // FULL_MODE_RESET again\n p.process(b\"\\x1b[0m\\x1b[?25h\\x1b[?1l\\x1b[?9l\\x1b[?47l\\x1b[?1000l\\x1b[?1002l\\x1b[?1003l\\x1b[?1005l\\x1b[?1006l\\x1b[?2004l\");\n println!(\"After 2nd FULL_MODE_RESET: hide={}\", p.screen().hide_cursor());\n \n // Test alternate screen save/restore of hide_cursor state\n let mut p2 = Parser::new(24, 80, 0);\n p2.process(b\"before\"); // normal screen, cursor visible\n println!(\"\\np2: hide={}\", p2.screen().hide_cursor());\n p2.process(b\"\\x1b[?25l\"); // hide on normal screen\n println!(\"p2 after hide on normal: hide={}\", p2.screen().hide_cursor());\n p2.process(b\"\\x1b[?1049h\"); // switch to alt - does it save hide state?\n println!(\"p2 in alt: hide={}\", p2.screen().hide_cursor());\n p2.process(b\"\\x1b[?25h\"); // show on alt\n println!(\"p2 show on alt: hide={}\", p2.screen().hide_cursor());\n p2.process(b\"\\x1b[?1049l\"); // back to normal - does it restore hide state?\n println!(\"p2 after RMCUP: hide={}\", p2.screen().hide_cursor());\n}\n"
},
{
"path": "installer/psmux.nsi",
"content": "; psmux NSIS Installer Script\n; Builds a self-extracting installer that:\n; 1. Kills running psmux servers before install/uninstall\n; 2. Installs psmux.exe, pmux.exe, tmux.exe\n; 3. Adds install dir to user PATH\n; 4. Runs warmup after install\n;\n; Build with (from repo root):\n; makensis /NOCD /DVERSION=3.2.0 /DARCH=x64 /DSOURCE_DIR=<abs>\\target\\release /DREPO_DIR=<abs> installer\\psmux.nsi\n; Or use: .\\scripts\\build.ps1\n;\n; Required defines (passed via /D on command line):\n; VERSION - e.g. \"3.2.0\"\n; ARCH - \"x64\", \"x86\", or \"arm64\"\n; SOURCE_DIR - absolute path to folder containing psmux.exe, pmux.exe, tmux.exe\n; REPO_DIR - absolute path to the repo root (for README, LICENSE)\n\n!ifndef VERSION\n !define VERSION \"0.0.0\"\n!endif\n!ifndef ARCH\n !define ARCH \"x64\"\n!endif\n!ifndef SOURCE_DIR\n !define SOURCE_DIR \"..\\target\\x86_64-pc-windows-msvc\\release\"\n!endif\n!ifndef REPO_DIR\n !define REPO_DIR \"..\"\n!endif\n\n; ── General ──────────────────────────────────────────────────────────────\nName \"psmux ${VERSION}\"\nOutFile \"${REPO_DIR}\\target\\installer\\psmux-v${VERSION}-${ARCH}-setup.exe\"\nInstallDir \"$LOCALAPPDATA\\psmux\"\nInstallDirRegKey HKCU \"Software\\psmux\" \"InstallDir\"\nRequestExecutionLevel user\nSetCompressor /SOLID lzma\nUnicode True\n\n; ── Version info embedded in the .exe ────────────────────────────────────\nVIProductVersion \"${VERSION}.0\"\nVIAddVersionKey \"ProductName\" \"psmux\"\nVIAddVersionKey \"ProductVersion\" \"${VERSION}\"\nVIAddVersionKey \"FileDescription\" \"psmux - Terminal Multiplexer for Windows\"\nVIAddVersionKey \"LegalCopyright\" \"Copyright (c) Josh\"\nVIAddVersionKey \"FileVersion\" \"${VERSION}\"\n\n; ── Pages ────────────────────────────────────────────────────────────────\n!include \"MUI2.nsh\"\n\n!insertmacro MUI_PAGE_LICENSE \"${REPO_DIR}\\LICENSE\"\n!insertmacro MUI_PAGE_DIRECTORY\n!insertmacro MUI_PAGE_INSTFILES\n!insertmacro MUI_PAGE_FINISH\n\n!insertmacro MUI_UNPAGE_CONFIRM\n!insertmacro MUI_UNPAGE_INSTFILES\n\n!insertmacro MUI_LANGUAGE \"English\"\n\n; ── Macros ───────────────────────────────────────────────────────────────\n; Kill running psmux servers — used by both install and uninstall\n!macro KillPsmuxServers\n ; Try graceful kill-server via existing installed binary\n IfFileExists \"$INSTDIR\\psmux.exe\" 0 +3\n DetailPrint \"Running psmux kill-server...\"\n nsExec::ExecToLog '\"$INSTDIR\\psmux.exe\" kill-server'\n\n ; Force-kill any remaining processes\n DetailPrint \"Force-killing remaining psmux/pmux/tmux processes...\"\n nsExec::ExecToLog 'taskkill /F /IM psmux.exe'\n nsExec::ExecToLog 'taskkill /F /IM pmux.exe'\n nsExec::ExecToLog 'taskkill /F /IM tmux.exe'\n\n ; Wait for file handles to release\n Sleep 1500\n!macroend\n\n; ── Install Section ──────────────────────────────────────────────────────\nSection \"Install\"\n ; Kill running servers BEFORE overwriting files\n !insertmacro KillPsmuxServers\n\n SetOutPath \"$INSTDIR\"\n\n ; Install files\n File \"${SOURCE_DIR}\\psmux.exe\"\n File \"${SOURCE_DIR}\\pmux.exe\"\n File \"${SOURCE_DIR}\\tmux.exe\"\n File \"${REPO_DIR}\\README.md\"\n File \"${REPO_DIR}\\LICENSE\"\n\n ; Write uninstaller\n WriteUninstaller \"$INSTDIR\\uninstall.exe\"\n\n ; Write registry keys for Add/Remove Programs\n WriteRegStr HKCU \"Software\\psmux\" \"InstallDir\" \"$INSTDIR\"\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"DisplayName\" \"psmux - Terminal Multiplexer for Windows\"\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"DisplayVersion\" \"${VERSION}\"\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"Publisher\" \"Josh\"\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"URLInfoAbout\" \"https://github.com/psmux/psmux\"\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"UninstallString\" '\"$INSTDIR\\uninstall.exe\"'\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"QuietUninstallString\" '\"$INSTDIR\\uninstall.exe\" /S'\n WriteRegStr HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"InstallLocation\" \"$INSTDIR\"\n WriteRegDWORD HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"NoModify\" 1\n WriteRegDWORD HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\" \\\n \"NoRepair\" 1\n\n ; Add to user PATH\n DetailPrint \"Adding to user PATH...\"\n EnVar::SetHKCU\n EnVar::AddValue \"Path\" \"$INSTDIR\"\n Pop $0\n ${If} $0 = 0\n DetailPrint \"Added $INSTDIR to PATH\"\n ${Else}\n DetailPrint \"PATH already contains $INSTDIR (or error: $0)\"\n ${EndIf}\n\n ; Notify shell that environment changed\n SendMessage ${HWND_BROADCAST} ${WM_WININICHANGE} 0 \"STR:Environment\" /TIMEOUT=500\n\n ; Run warmup (async — don't block installer)\n DetailPrint \"Running psmux warmup...\"\n Exec '\"$INSTDIR\\psmux.exe\" warmup'\nSectionEnd\n\n; ── Uninstall Section ────────────────────────────────────────────────────\nSection \"Uninstall\"\n ; Kill running servers BEFORE removing files\n !insertmacro KillPsmuxServers\n\n ; Remove files\n Delete \"$INSTDIR\\psmux.exe\"\n Delete \"$INSTDIR\\pmux.exe\"\n Delete \"$INSTDIR\\tmux.exe\"\n Delete \"$INSTDIR\\README.md\"\n Delete \"$INSTDIR\\LICENSE\"\n Delete \"$INSTDIR\\uninstall.exe\"\n RMDir \"$INSTDIR\"\n\n ; Remove from user PATH\n DetailPrint \"Removing from user PATH...\"\n EnVar::SetHKCU\n EnVar::DeleteValue \"Path\" \"$INSTDIR\"\n\n ; Remove registry keys\n DeleteRegKey HKCU \"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\psmux\"\n DeleteRegKey HKCU \"Software\\psmux\"\n\n ; Notify shell that environment changed\n SendMessage ${HWND_BROADCAST} ${WM_WININICHANGE} 0 \"STR:Environment\" /TIMEOUT=500\nSectionEnd\n"
},
{
"path": "packages/chocolatey/psmux.nuspec",
"content": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<package xmlns=\"http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd\">\n <metadata>\n <id>psmux</id>\n <version>0.4.9</version>\n <title>psmux - Terminal Multiplexer for Windows\n Josh\n Josh\n https://github.com/psmux/psmux/blob/master/LICENSE\n https://github.com/psmux/psmux\n https://raw.githubusercontent.com/psmux/psmux/master/icon.svg\n false\n Terminal multiplexer for Windows - tmux alternative for PowerShell and Windows Terminal. Includes psmux, pmux, and tmux commands.\n Terminal multiplexer for Windows (tmux alternative)\n https://github.com/psmux/psmux/releases\n terminal multiplexer tmux powershell cli windows psmux pmux\n https://github.com/psmux/psmux\n https://github.com/psmux/psmux#readme\n https://github.com/psmux/psmux/issues\n \n \n \n \n\n"
},
{
"path": "packages/chocolatey/tools/chocolateyinstall.ps1",
"content": "# ============================================================================\n# TEMPLATE ONLY - DO NOT PUSH THIS FILE DIRECTLY TO CHOCOLATEY\n# ============================================================================\n# The real chocolateyinstall.ps1 is generated at publish time with the correct\n# SHA256 checksum by either:\n# - GitHub Actions: .github/workflows/release.yml (publish-chocolatey job)\n# - Local publish: scripts/publish-choco.ps1\n#\n# Both download the release zip, compute the hash, and generate this file.\n# ============================================================================\n\n$ErrorActionPreference = 'Stop'\n\n$toolsDir = \"$(Split-Path -Parent $MyInvocation.MyCommand.Definition)\"\n$url64 = 'https://github.com/psmux/psmux/releases/download/v__VERSION__/psmux-v__VERSION__-windows-x64.zip'\n\n$packageArgs = @{\n packageName = $env:ChocolateyPackageName\n unzipLocation = $toolsDir\n url64bit = $url64\n checksum64 = '__SHA256_COMPUTED_AT_PUBLISH_TIME__'\n checksumType64 = 'sha256'\n}\n\nInstall-ChocolateyZipPackage @packageArgs\n\n# Create shims for psmux, pmux, and tmux\n$psmuxPath = Join-Path $toolsDir \"psmux.exe\"\n$pmuxPath = Join-Path $toolsDir \"pmux.exe\"\n$tmuxPath = Join-Path $toolsDir \"tmux.exe\"\n\nInstall-BinFile -Name \"psmux\" -Path $psmuxPath\nInstall-BinFile -Name \"pmux\" -Path $pmuxPath\nInstall-BinFile -Name \"tmux\" -Path $tmuxPath\n\n# Pre-warm: trigger Windows Defender scan cache and spawn a warm server\n# so the user's first 'psmux new-session' is instant.\nStart-Process -FilePath $psmuxPath -ArgumentList 'warmup' -WindowStyle Hidden\n"
},
{
"path": "packages/chocolatey/tools/chocolateyuninstall.ps1",
"content": "Uninstall-BinFile -Name \"psmux\"\nUninstall-BinFile -Name \"pmux\"\nUninstall-BinFile -Name \"tmux\"\n"
},
{
"path": "psmux.json",
"content": "{\n \"version\": \"0.4.6\",\n \"description\": \"Terminal multiplexer for Windows - tmux alternative for PowerShell and Windows Terminal\",\n \"homepage\": \"https://github.com/psmux/psmux\",\n \"license\": \"MIT\",\n \"notes\": \"For automatic updates, add the bucket: scoop bucket add psmux https://github.com/psmux/scoop-psmux\",\n \"architecture\": {\n \"64bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.6/psmux-v0.4.6-windows-x64.zip\"\n },\n \"32bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.6/psmux-v0.4.6-windows-x86.zip\"\n },\n \"arm64\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.6/psmux-v0.4.6-windows-arm64.zip\"\n }\n },\n \"bin\": [\n \"psmux.exe\",\n \"pmux.exe\",\n \"tmux.exe\"\n ],\n \"checkver\": {\n \"github\": \"https://github.com/psmux/psmux\"\n },\n \"autoupdate\": {\n \"architecture\": {\n \"64bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-x64.zip\"\n },\n \"32bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-x86.zip\"\n },\n \"arm64\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-arm64.zip\"\n }\n }\n }\n}\n"
},
{
"path": "rust-toolchain.toml",
"content": "[toolchain]\ncomponents = [\"clippy\"]"
},
{
"path": "scoop/psmux.json",
"content": "{\n \"version\": \"0.4.9\",\n \"description\": \"Terminal multiplexer for Windows - tmux alternative for PowerShell and Windows Terminal\",\n \"homepage\": \"https://github.com/psmux/psmux\",\n \"license\": \"MIT\",\n \"notes\": \"For automatic updates, add the bucket: scoop bucket add psmux https://github.com/psmux/scoop-psmux\",\n \"architecture\": {\n \"64bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.9/psmux-v0.4.9-windows-x64.zip\"\n },\n \"32bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.9/psmux-v0.4.9-windows-x86.zip\"\n },\n \"arm64\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v0.4.9/psmux-v0.4.9-windows-arm64.zip\"\n }\n },\n \"bin\": [\n \"psmux.exe\",\n \"pmux.exe\",\n \"tmux.exe\"\n ],\n \"post_install\": \"Start-Process -FilePath \\\"$dir\\\\psmux.exe\\\" -ArgumentList 'warmup' -WindowStyle Hidden\",\n \"checkver\": {\n \"github\": \"https://github.com/psmux/psmux\"\n },\n \"autoupdate\": {\n \"architecture\": {\n \"64bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-x64.zip\"\n },\n \"32bit\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-x86.zip\"\n },\n \"arm64\": {\n \"url\": \"https://github.com/psmux/psmux/releases/download/v$version/psmux-v$version-windows-arm64.zip\"\n }\n }\n }\n}\n"
},
{
"path": "scripts/build.ps1",
"content": "# scripts/build.ps1 — Build psmux + NSIS installer\n# Usage:\n# .\\scripts\\build.ps1 # full build: cargo install + NSIS setup\n# .\\scripts\\build.ps1 -SkipSetup # cargo install only (no NSIS)\n# .\\scripts\\build.ps1 -SetupOnly # NSIS only (assumes binaries exist)\n\nparam(\n [switch]$SkipSetup,\n [switch]$SetupOnly\n)\n\n$ErrorActionPreference = \"Stop\"\n$repoDir = Split-Path -Parent $PSScriptRoot\n\nPush-Location $repoDir\ntry {\n # ── Kill old instances ────────────────────────────────────────────\n Write-Host \"[build] Killing old psmux instances...\" -ForegroundColor Cyan\n $existing = Get-Command psmux -ErrorAction SilentlyContinue\n if ($existing) {\n & psmux kill-server 2>$null\n }\n foreach ($name in @(\"psmux\", \"pmux\", \"tmux\")) {\n Get-Process -Name $name -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue\n }\n Start-Sleep -Seconds 1\n\n # ── Cargo install ─────────────────────────────────────────────────\n if (-not $SetupOnly) {\n Write-Host \"[build] Running cargo install --path .\" -ForegroundColor Cyan\n cargo install --path .\n if ($LASTEXITCODE -ne 0) {\n Write-Error \"cargo install failed (exit $LASTEXITCODE)\"\n exit 1\n }\n Write-Host \"[build] cargo install succeeded\" -ForegroundColor Green\n\n # ── Pre-spawn warm server ─────────────────────────────────────────\n # build.ps1 kills all psmux processes at the top, which destroys the\n # background __warm__ server. Call warmup now so the next `psmux`\n # invocation claims the pre-warmed server instead of cold-starting.\n Write-Host \"[build] Pre-spawning warm server (psmux warmup)...\" -ForegroundColor Cyan\n & psmux warmup 2>$null\n Write-Host \"[build] Warm server pre-spawned\" -ForegroundColor Green\n }\n\n # ── NSIS installer ────────────────────────────────────────────────\n if (-not $SkipSetup) {\n # Find makensis\n $makensis = $null\n foreach ($candidate in @(\n \"makensis\",\n \"$env:USERPROFILE\\scoop\\apps\\nsis\\current\\bin\\makensis.exe\",\n \"C:\\Program Files (x86)\\NSIS\\makensis.exe\",\n \"C:\\Program Files\\NSIS\\makensis.exe\"\n )) {\n if (Get-Command $candidate -ErrorAction SilentlyContinue) {\n $makensis = (Get-Command $candidate).Source\n break\n }\n if (Test-Path $candidate) {\n $makensis = $candidate\n break\n }\n }\n\n if (-not $makensis) {\n Write-Host \"[build] WARN: makensis not found — skipping installer build\" -ForegroundColor Yellow\n Write-Host \"[build] Install NSIS: scoop install nsis (from extras bucket)\" -ForegroundColor Yellow\n } else {\n # Read version from Cargo.toml\n $cargoToml = Get-Content \"$repoDir\\Cargo.toml\" -Raw\n if ($cargoToml -match '(?m)^version\\s*=\\s*\"([^\"]+)\"') {\n $ver = $Matches[1]\n } else {\n Write-Error \"Could not parse version from Cargo.toml\"\n exit 1\n }\n\n # Find source binaries\n $srcDir = \"$repoDir\\target\\release\"\n if (-not (Test-Path \"$srcDir\\psmux.exe\")) {\n Write-Error \"Release binaries not found at $srcDir — build first\"\n exit 1\n }\n\n New-Item -ItemType Directory -Path \"$repoDir\\target\\installer\" -Force | Out-Null\n\n Write-Host \"[build] Building NSIS installer (v$ver, x64)...\" -ForegroundColor Cyan\n & $makensis /NOCD /DVERSION=$ver /DARCH=x64 \"/DSOURCE_DIR=$srcDir\" \"/DREPO_DIR=$repoDir\" \"$repoDir\\installer\\psmux.nsi\"\n if ($LASTEXITCODE -ne 0) {\n Write-Error \"NSIS compilation failed (exit $LASTEXITCODE)\"\n exit 1\n }\n\n $installer = \"$repoDir\\target\\installer\\psmux-v${ver}-x64-setup.exe\"\n if (Test-Path $installer) {\n $sizeMB = [math]::Round((Get-Item $installer).Length / 1MB, 2)\n Write-Host \"[build] Installer created: $installer ($sizeMB MB)\" -ForegroundColor Green\n }\n }\n }\n\n # ── Portable test zip (temp dir) ─────────────────────────────────\n # Creates a zip of the release binaries in TEMP for test_install_speed.ps1.\n # Nothing is written inside the repo.\n $srcDir = \"$repoDir\\target\\release\"\n if (Test-Path \"$srcDir\\psmux.exe\") {\n $zipDir = Join-Path $env:TEMP \"psmux-test-artifacts\"\n New-Item -ItemType Directory -Path $zipDir -Force | Out-Null\n $zipPath = Join-Path $zipDir \"psmux-local-test.zip\"\n Remove-Item $zipPath -Force -ErrorAction SilentlyContinue\n\n $stagingDir = Join-Path $env:TEMP \"psmux-zip-staging\"\n if (Test-Path $stagingDir) { Remove-Item $stagingDir -Recurse -Force }\n New-Item -ItemType Directory -Path $stagingDir -Force | Out-Null\n foreach ($bin in @(\"psmux.exe\", \"pmux.exe\", \"tmux.exe\")) {\n $binSrc = Join-Path $srcDir $bin\n if (Test-Path $binSrc) { Copy-Item $binSrc $stagingDir }\n }\n Compress-Archive -Path \"$stagingDir\\*\" -DestinationPath $zipPath -Force\n Remove-Item $stagingDir -Recurse -Force\n\n $sizeMB = [math]::Round((Get-Item $zipPath).Length / 1MB, 2)\n Write-Host \"[build] Test zip created: $zipPath ($sizeMB MB)\" -ForegroundColor Green\n }\n\n Write-Host \"[build] Done!\" -ForegroundColor Green\n} finally {\n Pop-Location\n}\n"
},
{
"path": "scripts/install.ps1",
"content": "# psmux installation script for Windows\n# Run as: irm https://raw.githubusercontent.com/psmux/psmux/master/scripts/install.ps1 | iex\n# Or locally: .\\scripts\\install.ps1\n\nparam(\n [string]$InstallDir = \"$env:LOCALAPPDATA\\psmux\",\n [switch]$Force\n)\n\n$ErrorActionPreference = 'Stop'\n\nWrite-Host \"psmux installer\" -ForegroundColor Cyan\nWrite-Host \"===============\" -ForegroundColor Cyan\n\n# Determine if we're installing from local build or downloading\n# When run via iex, $PSScriptRoot is empty\n$LocalBuild = $false\nif ($PSScriptRoot -and (Test-Path \"$PSScriptRoot\\..\\target\\release\\psmux.exe\")) {\n $LocalBuild = $true\n $RepoRoot = Split-Path -Parent $PSScriptRoot\n}\n\nif ($LocalBuild) {\n Write-Host \"Installing from local build...\" -ForegroundColor Yellow\n $SourceDir = \"$RepoRoot\\target\\release\"\n} else {\n Write-Host \"Downloading latest release...\" -ForegroundColor Yellow\n \n # Detect architecture using PROCESSOR_ARCHITECTURE env var\n # (RuntimeInformation::OSArchitecture returns $null in PS 5.1 when piped via iex)\n $arch = $env:PROCESSOR_ARCHITECTURE\n # WoW64 correction: 32-bit process on 64-bit OS reports x86; use the real OS arch\n if ($arch -eq \"x86\" -and $env:PROCESSOR_ARCHITEW6432) {\n $arch = $env:PROCESSOR_ARCHITEW6432\n }\n switch ($arch) {\n \"AMD64\" { $archLabel = \"x64\"; $assetPattern = \"windows-x64\" }\n \"x86\" { $archLabel = \"x86\"; $assetPattern = \"windows-x86\" }\n \"ARM64\" { $archLabel = \"arm64\"; $assetPattern = \"windows-arm64\" }\n default {\n Write-Host \"Unsupported architecture: $arch\" -ForegroundColor Red\n exit 1\n }\n }\n Write-Host \"Detected architecture: $archLabel\" -ForegroundColor Cyan\n \n # Get latest release info\n $ReleasesUrl = \"https://api.github.com/repos/psmux/psmux/releases/latest\"\n try {\n $Release = Invoke-RestMethod -Uri $ReleasesUrl -Headers @{ \"User-Agent\" = \"psmux-installer\" }\n $Asset = $Release.assets | Where-Object { $_.name -match \"$assetPattern.*zip\" } | Select-Object -First 1\n \n # Fallback: if no arch-specific asset, try x64 (Windows on ARM can run x64 via emulation)\n if (-not $Asset -and $archLabel -eq \"arm64\") {\n Write-Host \"No ARM64 build found, falling back to x64 (runs via emulation)...\" -ForegroundColor Yellow\n $Asset = $Release.assets | Where-Object { $_.name -match \"windows-x64.*zip\" } | Select-Object -First 1\n }\n \n if (-not $Asset) {\n throw \"No compatible release asset found for $archLabel\"\n }\n \n $DownloadUrl = $Asset.browser_download_url\n $TempZip = \"$env:TEMP\\psmux-download.zip\"\n $TempExtract = \"$env:TEMP\\psmux-extract\"\n \n Write-Host \"Downloading from: $DownloadUrl\"\n Invoke-WebRequest -Uri $DownloadUrl -OutFile $TempZip\n \n # Extract\n if (Test-Path $TempExtract) { Remove-Item -Recurse -Force $TempExtract }\n Expand-Archive -Path $TempZip -DestinationPath $TempExtract -Force\n \n $SourceDir = $TempExtract\n \n } catch {\n Write-Host \"Error downloading release: $_\" -ForegroundColor Red\n Write-Host \"Try installing from a local build instead:\" -ForegroundColor Yellow\n Write-Host \" cargo build --release\" -ForegroundColor White\n Write-Host \" .\\scripts\\install.ps1\" -ForegroundColor White\n exit 1\n }\n}\n\n# Create install directory\nif (-not (Test-Path $InstallDir)) {\n Write-Host \"Creating install directory: $InstallDir\"\n New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null\n}\n\n# Copy binaries\n$Binaries = @(\"psmux.exe\", \"pmux.exe\", \"tmux.exe\")\nforeach ($bin in $Binaries) {\n $src = Join-Path $SourceDir $bin\n $dst = Join-Path $InstallDir $bin\n \n if (Test-Path $src) {\n Write-Host \" Installing $bin...\" -ForegroundColor Green\n Copy-Item -Path $src -Destination $dst -Force\n } else {\n Write-Host \" Warning: $bin not found\" -ForegroundColor Yellow\n }\n}\n\n# Add to PATH if not already there\n$UserPath = [Environment]::GetEnvironmentVariable(\"Path\", \"User\")\nif ($UserPath -notlike \"*$InstallDir*\") {\n Write-Host \"Adding to PATH...\" -ForegroundColor Green\n $NewPath = \"$UserPath;$InstallDir\"\n [Environment]::SetEnvironmentVariable(\"Path\", $NewPath, \"User\")\n $env:Path = \"$env:Path;$InstallDir\"\n Write-Host \" Added $InstallDir to user PATH\" -ForegroundColor Green\n} else {\n Write-Host \"Already in PATH\" -ForegroundColor Gray\n}\n\n# Cleanup temp files if downloaded\nif (-not $LocalBuild) {\n if (Test-Path $TempZip) { Remove-Item $TempZip -Force }\n if (Test-Path $TempExtract) { Remove-Item -Recurse -Force $TempExtract }\n}\n\nWrite-Host \"\"\nWrite-Host \"Installation complete!\" -ForegroundColor Green\nWrite-Host \"\"\nWrite-Host \"You can now use:\" -ForegroundColor Cyan\nWrite-Host \" psmux - Start/attach to terminal multiplexer\"\nWrite-Host \" pmux - Alias for psmux\" \nWrite-Host \" tmux - tmux-compatible alias\"\nWrite-Host \"\"\nWrite-Host \"Quick start:\" -ForegroundColor Cyan\nWrite-Host \" psmux # Start new session or attach to 'default'\"\nWrite-Host \" psmux new -s mysession # Create named session\"\nWrite-Host \" psmux ls # List sessions\"\nWrite-Host \" psmux attach -t name # Attach to session\"\nWrite-Host \"\"\nWrite-Host \"Note: Restart your terminal or run:\" -ForegroundColor Yellow\nWrite-Host ' $env:Path = [Environment]::GetEnvironmentVariable(\"Path\", \"User\") + \";\" + [Environment]::GetEnvironmentVariable(\"Path\", \"Machine\")'\n"
},
{
"path": "scripts/pmux-title.ps1",
"content": "param()\n\nfunction Update-PmuxPaneTitle {\n try {\n $cwdLeaf = Split-Path -Leaf (Get-Location)\n $lastCmd = (Get-History -Count 1 | Select-Object -ExpandProperty CommandLine)\n $title = if ($lastCmd) { \"$cwdLeaf: $lastCmd\" } else { $cwdLeaf }\n pmux set-pane-title $title | Out-Null\n } catch {\n # Ignore errors if pmux or session is not running\n }\n}\n\n# Usage:\n# 1) Add to your $PROFILE (Microsoft.PowerShell_profile.ps1):\n# . \"$PSScriptRoot\\pmux-title.ps1\"\n# function Prompt {\n# Update-PmuxPaneTitle\n# \"PS \" + (Get-Location) + \"> \"\n# }\n# 2) Ensure a running pmux session server and, if needed, set $env:PMUX_TARGET_SESSION."
},
{
"path": "scripts/pmux-title.sh",
"content": "#!/usr/bin/env bash\n\n# Update pmux pane title from bash prompt using cwd and last command.\n# Usage:\n# source /path/to/scripts/pmux-title.sh\n# This appends to PROMPT_COMMAND to run on every prompt.\n\n__pmux_title_update() {\n local cwd\n cwd=$(basename -- \"$PWD\")\n local cmd\n # history 1 prints the last command; strip leading number\n cmd=$(history 1 2>/dev/null | sed 's/^ *[0-9]\\+ *//')\n local title=\"$cwd\"\n if [ -n \"$cmd\" ]; then\n title=\"$cwd: $cmd\"\n fi\n pmux set-pane-title \"$title\" >/dev/null 2>&1 || true\n}\n\ncase \":$PROMPT_COMMAND:\" in\n *:__pmux_title_update:* ) ;; # already installed\n * ) PROMPT_COMMAND=\"__pmux_title_update${PROMPT_COMMAND:+; $PROMPT_COMMAND}\" ;;\nesac"
},
{
"path": "scripts/publish-choco.ps1",
"content": "<#\n.SYNOPSIS\n Build and publish the psmux Chocolatey package with the correct SHA256 checksum.\n\n.DESCRIPTION\n This script mirrors what the GitHub Actions release workflow does:\n 1. Downloads the release zip from GitHub Releases\n 2. Computes the SHA256 checksum\n 3. Generates chocolateyinstall.ps1 with the real checksum\n 4. Packs the .nupkg\n 5. Optionally pushes to Chocolatey\n\n Use this for local publishing so the checksum is always correct.\n\n.PARAMETER Version\n The version to publish (e.g. \"0.3.9\"). If omitted, reads from Cargo.toml.\n\n.PARAMETER Push\n If specified, pushes the package to Chocolatey after packing.\n\n.PARAMETER ApiKey\n Chocolatey API key. If not provided and -Push is set, uses $env:CHOCOLATEY_API_KEY.\n\n.EXAMPLE\n # Just pack (dry run) - verify everything looks good\n .\\scripts\\publish-choco.ps1\n\n # Pack and push\n .\\scripts\\publish-choco.ps1 -Push\n\n # Specific version\n .\\scripts\\publish-choco.ps1 -Version 0.3.9 -Push\n#>\nparam(\n [string]$Version,\n [switch]$Push,\n [string]$ApiKey\n)\n\n$ErrorActionPreference = 'Stop'\n$RepoOwner = \"psmux\"\n$RepoName = \"psmux\"\n$PackageId = \"psmux\"\n\n# --- Resolve version ---\nif (-not $Version) {\n $cargoToml = Get-Content \"$PSScriptRoot\\..\\Cargo.toml\" -Raw\n if ($cargoToml -match 'version\\s*=\\s*\"([^\"]+)\"') {\n $Version = $matches[1]\n } else {\n Write-Error \"Could not extract version from Cargo.toml. Pass -Version explicitly.\"\n exit 1\n }\n}\n\n$Tag = \"v$Version\"\nWrite-Host \"=== Publishing psmux $Tag to Chocolatey ===\" -ForegroundColor Cyan\n\n# --- Setup temp build directory ---\n$buildDir = Join-Path $PSScriptRoot \"..\\target\\choco-build\"\nif (Test-Path $buildDir) { Remove-Item $buildDir -Recurse -Force }\nNew-Item -ItemType Directory -Path \"$buildDir\\tools\" -Force | Out-Null\n\n# --- Download release zip ---\n$zipUrl = \"https://github.com/$RepoOwner/$RepoName/releases/download/$Tag/psmux-$Tag-windows-x64.zip\"\n$zipFile = Join-Path $buildDir \"psmux-release.zip\"\n\nWrite-Host \"Downloading $zipUrl ...\" -ForegroundColor Yellow\ntry {\n Invoke-WebRequest -Uri $zipUrl -OutFile $zipFile -UseBasicParsing -ErrorAction Stop\n} catch {\n Write-Error \"Failed to download release zip. Make sure the GitHub Release for $Tag exists.`n$_\"\n exit 1\n}\n\n# --- Compute SHA256 ---\n$hash = (Get-FileHash $zipFile -Algorithm SHA256).Hash\nWrite-Host \"SHA256: $hash\" -ForegroundColor Green\n\n# --- Verify by re-downloading ---\n$verifyFile = Join-Path $buildDir \"psmux-verify.zip\"\nWrite-Host \"Verifying checksum (re-downloading)...\" -ForegroundColor Yellow\nInvoke-WebRequest -Uri $zipUrl -OutFile $verifyFile -UseBasicParsing -ErrorAction Stop\n$hash2 = (Get-FileHash $verifyFile -Algorithm SHA256).Hash\nif ($hash -ne $hash2) {\n Write-Error \"Checksum mismatch on re-download! $hash vs $hash2\"\n exit 1\n}\nWrite-Host \"Checksum verified!\" -ForegroundColor Green\n\n# --- Generate chocolateyinstall.ps1 ---\n$installScript = @\"\n`$ErrorActionPreference = 'Stop'\n\n`$toolsDir = \"`$(Split-Path -Parent `$MyInvocation.MyCommand.Definition)\"\n`$url64 = '$zipUrl'\n\n`$packageArgs = @{\n packageName = `$env:ChocolateyPackageName\n unzipLocation = `$toolsDir\n url64bit = `$url64\n checksum64 = '$hash'\n checksumType64 = 'sha256'\n}\n\nInstall-ChocolateyZipPackage @packageArgs\n\n# Create shims for psmux, pmux, and tmux\n`$psmuxPath = Join-Path `$toolsDir \"psmux.exe\"\n`$pmuxPath = Join-Path `$toolsDir \"pmux.exe\"\n`$tmuxPath = Join-Path `$toolsDir \"tmux.exe\"\n\nInstall-BinFile -Name \"psmux\" -Path `$psmuxPath\nInstall-BinFile -Name \"pmux\" -Path `$pmuxPath\nInstall-BinFile -Name \"tmux\" -Path `$tmuxPath\n\"@\nSet-Content -Path \"$buildDir\\tools\\chocolateyinstall.ps1\" -Value $installScript -NoNewline\nWrite-Host \"Generated chocolateyinstall.ps1\" -ForegroundColor Green\n\n# --- Generate chocolateyuninstall.ps1 ---\n$uninstallScript = @\"\nUninstall-BinFile -Name \"psmux\"\nUninstall-BinFile -Name \"pmux\"\nUninstall-BinFile -Name \"tmux\"\n\"@\nSet-Content -Path \"$buildDir\\tools\\chocolateyuninstall.ps1\" -Value $uninstallScript -NoNewline\n\n# --- Generate nuspec ---\n$nuspec = @\"\n\n\n \n $PackageId\n $Version\n psmux - Terminal Multiplexer for Windows\n Josh\n Josh\n https://github.com/$RepoOwner/$RepoName/blob/master/LICENSE\n https://github.com/$RepoOwner/$RepoName\n false\n Terminal multiplexer for Windows - tmux alternative for PowerShell and Windows Terminal. Includes psmux, pmux, and tmux commands.\n Terminal multiplexer for Windows (tmux alternative)\n https://github.com/$RepoOwner/$RepoName/releases\n terminal multiplexer tmux powershell cli windows psmux pmux\n https://github.com/$RepoOwner/$RepoName\n https://github.com/$RepoOwner/$RepoName#readme\n https://github.com/$RepoOwner/$RepoName/issues\n \n \n \n \n\n\"@\nSet-Content -Path \"$buildDir\\psmux.nuspec\" -Value $nuspec -NoNewline\nWrite-Host \"Generated psmux.nuspec (v$Version)\" -ForegroundColor Green\n\n# --- Pack ---\nWrite-Host \"`nPacking...\" -ForegroundColor Cyan\nPush-Location $buildDir\ntry {\n choco pack psmux.nuspec\n $nupkg = (Get-ChildItem *.nupkg)[0]\n Write-Host \"Created: $($nupkg.Name) ($([math]::Round($nupkg.Length/1KB, 1)) KB)\" -ForegroundColor Green\n} finally {\n Pop-Location\n}\n\n# --- Push ---\nif ($Push) {\n $key = if ($ApiKey) { $ApiKey } else { $env:CHOCOLATEY_API_KEY }\n if (-not $key) {\n Write-Error \"No API key provided. Use -ApiKey or set `$env:CHOCOLATEY_API_KEY\"\n exit 1\n }\n Write-Host \"`nPushing $($nupkg.Name) to Chocolatey...\" -ForegroundColor Cyan\n Push-Location $buildDir\n try {\n choco push $nupkg.Name --source https://push.chocolatey.org/ --api-key $key\n Write-Host \"Successfully pushed to Chocolatey!\" -ForegroundColor Green\n } finally {\n Pop-Location\n }\n} else {\n Write-Host \"`nDry run complete. Package at: $($nupkg.FullName)\" -ForegroundColor Yellow\n Write-Host \"To push: .\\scripts\\publish-choco.ps1 -Version $Version -Push\" -ForegroundColor Yellow\n}\n"
},
{
"path": "scripts/uninstall.ps1",
"content": "# psmux uninstall script for Windows\n\nparam(\n [string]$InstallDir = \"$env:LOCALAPPDATA\\psmux\"\n)\n\n$ErrorActionPreference = 'Stop'\n\nWrite-Host \"psmux uninstaller\" -ForegroundColor Cyan\nWrite-Host \"=================\" -ForegroundColor Cyan\n\n# Kill any running sessions first\nWrite-Host \"Stopping any running sessions...\"\n$psmuxPath = Join-Path $InstallDir \"psmux.exe\"\nif (Test-Path $psmuxPath) {\n try {\n & $psmuxPath kill-server 2>$null\n } catch {}\n}\n\n# Also try to stop by process name\nGet-Process -Name psmux,pmux,tmux -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue\n\nStart-Sleep -Seconds 1\n\n# Remove install directory\nif (Test-Path $InstallDir) {\n Write-Host \"Removing $InstallDir...\"\n Remove-Item -Recurse -Force $InstallDir\n Write-Host \" Removed install directory\" -ForegroundColor Green\n} else {\n Write-Host \"Install directory not found: $InstallDir\" -ForegroundColor Yellow\n}\n\n# Remove from PATH\n$UserPath = [Environment]::GetEnvironmentVariable(\"Path\", \"User\")\nif ($UserPath -like \"*$InstallDir*\") {\n Write-Host \"Removing from PATH...\"\n $NewPath = ($UserPath -split ';' | Where-Object { $_ -ne $InstallDir }) -join ';'\n [Environment]::SetEnvironmentVariable(\"Path\", $NewPath, \"User\")\n Write-Host \" Removed from user PATH\" -ForegroundColor Green\n}\n\n# Clean up psmux data directory\n$DataDir = \"$env:USERPROFILE\\.psmux\"\nif (Test-Path $DataDir) {\n $response = Read-Host \"Remove psmux data directory ($DataDir)? [y/N]\"\n if ($response -eq 'y' -or $response -eq 'Y') {\n Remove-Item -Recurse -Force $DataDir\n Write-Host \" Removed data directory\" -ForegroundColor Green\n } else {\n Write-Host \" Kept data directory\" -ForegroundColor Yellow\n }\n}\n\nWrite-Host \"\"\nWrite-Host \"Uninstall complete!\" -ForegroundColor Green\nWrite-Host \"Restart your terminal to apply PATH changes.\"\n"
},
{
"path": "src/cli.rs",
"content": "use crate::types::{ParsedTarget, VERSION};\n\n/// Normalize `-x=VALUE` short-flag forms into `[\"-x\", \"VALUE\"]`.\n///\n/// tmux accepts both `-t VALUE` (space) and `-t=VALUE` (equals) for\n/// single-character flags. psmux's parsers only handled the space form.\n/// This function expands the equals form so every downstream comparison\n/// (`arg == \"-t\"`, `args.windows(2)`, etc.) works without changes.\n///\n/// Rules:\n/// - Only tokens starting with a single `-` (not `--`) are split.\n/// - The flag letter must be ASCII alphabetic (`-t=foo` yes, `-1=bar` no).\n/// - Long flags (`--name=value`) pass through unchanged.\n/// - Positional tokens without a leading `-` pass through unchanged.\n/// - Bare `-` and degenerate `-=` pass through unchanged.\npub fn normalize_flag_equals(args: Vec) -> Vec {\n let mut out = Vec::with_capacity(args.len());\n for arg in args {\n // Must start with exactly one dash, followed by a single ASCII letter,\n // then `=`, then at least one character of value.\n if arg.len() >= 4\n && arg.starts_with('-')\n && !arg.starts_with(\"--\")\n {\n let bytes = arg.as_bytes();\n if bytes[1].is_ascii_alphabetic() && bytes[2] == b'=' {\n out.push(format!(\"-{}\", bytes[1] as char));\n out.push(arg[3..].to_string());\n continue;\n }\n }\n out.push(arg);\n }\n out\n}\n\n/// Same as [`normalize_flag_equals`] but operates on `Vec<&str>`, returning\n/// owned strings (needed where the caller already has borrowed slices).\npub fn normalize_flag_equals_borrowed(args: &[&str]) -> Vec {\n let mut out = Vec::with_capacity(args.len());\n for arg in args {\n if arg.len() >= 4\n && arg.starts_with('-')\n && !arg.starts_with(\"--\")\n {\n let bytes = arg.as_bytes();\n if bytes[1].is_ascii_alphabetic() && bytes[2] == b'=' {\n out.push(format!(\"-{}\", bytes[1] as char));\n out.push(arg[3..].to_string());\n continue;\n }\n }\n out.push(arg.to_string());\n }\n out\n}\n\npub fn get_program_name() -> String {\n std::env::current_exe()\n .ok()\n .and_then(|p| p.file_stem().map(|s| s.to_string_lossy().to_string()))\n .unwrap_or_else(|| \"psmux\".to_string())\n .to_lowercase()\n .replace(\".exe\", \"\")\n}\n\npub fn print_help() {\n let prog = get_program_name();\n println!(r#\"{prog} v{ver} - Terminal multiplexer for Windows (tmux alternative)\n\nUSAGE:\n {prog} [COMMAND] [OPTIONS]\n\nSESSION COMMANDS:\n (no command) Start a new session or attach to existing one\n new-session, new Create a new session\n -s Session name (default: \"default\")\n -d Start detached (in background)\n -n Name for the initial window\n -- [args] Run a specific command instead of default shell\n a, at, attach, attach-session\n Attach to an existing session\n -t Target session name\n ls, list-sessions List all active sessions\n has-session, has Check if a session exists (exit code 0 = yes)\n -t Target session name\n kill-session, kill-ses Kill a session\n -t Target session name\n kill-server Kill all sessions and the server\n rename-session, rename Rename the current session\n switch-client, switchc Switch to another session\n list-clients, lsc List connected clients\n detach-client, detach Detach attached client(s); session keeps running\n -t Target a specific client (tty path or %id)\n -s Detach all clients of a specific session\n -a Detach all other clients (or all from CLI)\n -P Also kill the parent shell on detach\n server-info, info Show server information\n\nWINDOW COMMANDS:\n new-window, neww Create a new window in current session\n -n Window name\n -d Create but don't switch to it\n -c Start directory\n kill-window, killw Close the current window\n rename-window, renamew Rename current window\n select-window, selectw Select a window by index\n -t Target window index\n next-window, next Go to next window\n previous-window, prev Go to previous window\n last-window, last Go to last active window\n move-window, movew Move window to a different index\n swap-window, swapw Swap two windows\n find-window, findw Search for a window by name\n link-window, linkw Link a window to another session\n unlink-window, unlinkw Unlink a window\n list-windows, lsw List windows in a session\n\nPANE COMMANDS:\n split-window, splitw Split current pane\n -h Split horizontally (side by side)\n -v Split vertically (top/bottom, default)\n -p Size as percentage\n -c Start directory\n kill-pane, killp Close the current pane\n select-pane, selectp Select a pane\n -U / -D / -L / -R Direction (up/down/left/right)\n -t Target pane (e.g. %3)\n -m / -M Mark / unmark pane\n resize-pane, resizep Resize a pane\n -U/-D/-L/-R Direction and amount\n -Z Toggle zoom\n -x -y Absolute size\n swap-pane, swapp Swap two panes\n -U / -D Direction\n join-pane, joinp Join a pane to a window\n break-pane, breakp Break pane into a new window\n rotate-window, rotatew Rotate panes in a window\n display-panes, displayp Display pane numbers\n zoom-pane Toggle pane zoom (alias for resizep -Z)\n respawn-pane, respawnp Restart the pane's shell\n pipe-pane, pipep Pipe pane output to a command\n list-panes, lsp List panes in current window\n capture-pane, capturep Capture pane content to buffer\n -p Print to stdout\n\nCOPY & PASTE COMMANDS:\n copy-mode Enter copy/scroll mode\n set-buffer, setb Set paste buffer content\n paste-buffer, pasteb Paste from buffer to active pane\n list-buffers, lsb List paste buffers\n show-buffer, showb Display paste buffer content\n delete-buffer, deleteb Delete a paste buffer\n choose-buffer, chooseb Interactive buffer chooser\n save-buffer, saveb Save buffer to file\n load-buffer, loadb Load buffer from file\n clear-history, clearhist Clear pane scrollback history\n\nKEY BINDING COMMANDS:\n bind-key, bind Bind a key to a command\n unbind-key, unbind Unbind a key\n list-keys, lsk List all key bindings\n send-keys, send Send keys to a pane\n -l Send literally (no key parsing)\n -p Paste text (legacy compatibility)\n -t Target pane\n\nCONFIGURATION COMMANDS:\n set-option, set Set a session/window option\n -g Set globally\n -u Unset (reset to default)\n -a Append to current value\n -q Quiet (no error on unknown option)\n show-options, show Show all options and values\n show-window-options, showw Show window-scoped options\n source-file, source Execute commands from a config file\n set-environment, setenv Set an environment variable\n show-environment, showenv Show environment variables\n set-hook Set a hook command for an event\n show-hooks Show all defined hooks\n list-commands, lscm List all available commands\n\nLAYOUT COMMANDS:\n select-layout, selectl Apply a layout preset\n Presets: even-horizontal, even-vertical,\n main-horizontal, main-vertical, tiled\n next-layout Cycle to next layout\n previous-layout Cycle to previous layout\n\nDISPLAY COMMANDS:\n display-message, display Display a message or format variable\n display-menu, menu Display an interactive menu\n display-popup, popup Display a popup window\n confirm-before, confirm Run command after y/n confirmation\n clock-mode Display a big clock\n run-shell, run Run a shell command\n if-shell, if Conditional command execution\n wait-for, wait Wait for / signal a named channel\n\nMISC:\n help Show this help message\n version Show version information\n\nOPTIONS:\n -h, --help Show this help message\n -V, --version Show version information\n -f Use as the configuration file\n -L Name the server socket (namespace isolation)\n -S Specify server socket path\n -t Target session, window, or pane\n\nTARGET SYNTAX (-t):\n session:window.pane Full target path\n :2 Window 2 in current session\n :2.1 Pane 1 of window 2\n %3 Pane by pane ID\n @4 Window by window ID\n work:2 Window 2 in session \"work\"\n\nCONFIGURATION:\n psmux reads config on startup from the first file found:\n %USERPROFILE%\\.psmux.conf\n %USERPROFILE%\\.psmuxrc\n %USERPROFILE%\\.tmux.conf\n %USERPROFILE%\\.config\\psmux\\psmux.conf\n\n Config syntax is tmux-compatible. Example ~/.psmux.conf:\n\n # Change prefix to Ctrl+a\n set -g prefix C-a\n\n # Use a different shell\n set -g default-shell \"C:/Program Files/PowerShell/7/pwsh.exe\"\n # or: set -g default-command pwsh\n # or: set -g default-command cmd\n\n # Status bar\n set -g status-left \"[#S] \"\n set -g status-right \"%H:%M %d-%b-%y\"\n set -g status-style \"bg=green,fg=black\"\n\n # Key bindings\n bind-key -T prefix h split-window -h\n bind-key -T prefix v split-window -v\n\nSHELL CONFIGURATION:\n psmux launches PowerShell 7 (pwsh) by default. To change:\n\n Use cmd.exe:\n set -g default-shell cmd\n set -g default-command \"cmd /K\"\n\n Use PowerShell 5 (Windows built-in):\n set -g default-shell powershell\n\n Use PowerShell 7 (pwsh):\n set -g default-shell pwsh\n\n Use Git Bash:\n set -g default-shell \"C:/Program Files/Git/bin/bash.exe\"\n\n Use Nushell:\n set -g default-shell nu\n\n Launch a window with a specific command:\n psmux new-window -- cmd /K echo hello\n psmux new-session -- python\n\nSET OPTIONS (use with: set -g
![\"pstop](\"https://raw.githubusercontent.com/psmux/pstop/master/pstop-demo.gif\")
![\"psnet](\"https://raw.githubusercontent.com/psmux/psnet/master/image.png\")
![\"Tmux](\"https://raw.githubusercontent.com/psmux/Tmux-Plugin-Panel/master/screenshot.png\")
![\"OMP](\"https://raw.githubusercontent.com/psmux/omp-manager/master/screenshot.png\")