myrtui 0.5.0__tar.gz

myrtui-0.5.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.venv-ci/
+.venv-release/
+.uv/
+uv.lock
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# 内部设计/验收记录：独立 git 仓，嵌套在本目录下，只推内网 Gitea（myrtui-docs）。
+# 必须保持未跟踪——一旦被 `git add` 进去会变成 gitlink（mode 160000），
+# 公开仓里就会出现一个打不开的 submodule 指针（tests/test_docs_policy.py 守着）。
+docs-internal/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

myrtui-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing
+
+Thanks for taking a look. This is a small, opinionated project; the notes below
+are what you need to run it, test it, and not fight its conventions.
+
+**If you are an AI agent, read [AGENTS.md](AGENTS.md) first** — it is the
+short form of everything below, plus the hard rules.
+
+## Language policy
+
+- **Code comments and docstrings are in Chinese** by project convention. This
+  is deliberate: the maintainer thinks and iterates in Chinese, and a partial
+  English translation would rot into "stale English + live Chinese".
+- **User-facing text is English**: this file, `README.md`, `docs/`, code that
+  is printed to the terminal, and (eventually) the TUI itself.
+- **New commit messages use English subjects.** History before the public
+  release is Chinese and is not being rewritten.
+- Issues and pull requests in **English or Chinese** are both welcome.
+
+## Development setup
+
+```sh
+git clone https://github.com/YidingPing/myrtui
+cd myrtui
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+`tmux >= 3.1` must be on `PATH`; the test suite starts real, isolated tmux
+servers (each with its own socket name) and cleans them up.
+
+## Tests
+
+```sh
+python -m pytest -n 4        # ~1 minute on 8 cores
+python -m pytest tests/test_v22.py -q     # a single area
+```
+
+- The suite is parallel-safe: sockets carry a uuid, project roots come from
+  `tmp_path`, and each instance gets its own data directory.
+- Do **not** point tests at `$TMPDIR` as a project root; see the note in
+  `tests/conftest.py` for why that is pathologically slow.
+- Tests that need a real terminal feature (Sixel, `termtex`, Chrome) are
+  skipped or simulated; real-tool smoke tests are manual only.
+- `tests/README.md` documents the fragile spots (shell-readiness races, stdout
+  capture inside Textual, etc.) — read the relevant section before debugging a
+  flaky case.
+
+## Documentation boundaries
+
+`docs/` is public and ships inside the PyPI sdist. It may contain only the
+files listed in `docs/README.md`; `tests/test_docs_policy.py` enforces that
+list, forbids private network addresses and blocks internal document names
+(`*-PLAN.md`, `*-ACCEPTANCE.md`, …) anywhere in the tree.
+
+Design plans, acceptance records and release playbooks live in `docs-internal/`
+at the repository root: a nested git repository with its own history, excluded
+by `.gitignore` and never published. A fresh clone does not contain it. If you
+need that context, open an issue — do not add such files here.
+
+## Style
+
+- Python ≥ 3.10, `from __future__ import annotations`, type hints on public
+  functions.
+- No new runtime dependencies without a strong reason: the runtime is
+  Python + tmux, plus optional external tools (`micro`, `ov`, `termtex`,
+  `poppler`, Chrome) that must always degrade gracefully.
+- Comments explain *why* (constraints, measured behaviour, past bugs), not
+  *what*. Several files carry long header comments recording exactly that —
+  keep the habit.
+
+## Release (maintainers)
+
+1. Bump the version in **two** places: `pyproject.toml` and
+   `myrtui/__init__.py`.
+2. Push `main`; CI must be green.
+3. `git tag v<version> && git push origin v<version>` — `release.yml` then runs
+   the macOS verification, builds wheel + sdist, publishes to PyPI via Trusted
+   Publishing, and creates the GitHub Release.
+
+Publishing requires `pypi` as the Trusted Publisher environment in the repo
+settings; see the header of `.github/workflows/release.yml`.

myrtui-0.5.0/LICENSE

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

myrtui-0.5.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: myrtui
+Version: 0.5.0
+Summary: Lightweight per-project terminal workspace: file tree + git log + up to 4 real tmux panes, in Textual
+Project-URL: Homepage, https://github.com/YidingPing/myrtui
+Project-URL: Repository, https://github.com/YidingPing/myrtui
+Project-URL: Issues, https://github.com/YidingPing/myrtui/issues
+Project-URL: Changelog, https://github.com/YidingPing/myrtui/releases
+Project-URL: Documentation, https://github.com/YidingPing/myrtui/blob/main/docs/USAGE.md
+Author: Yiding Ping
+License-Expression: MIT
+License-File: LICENSE
+Keywords: multiplexer,terminal,textual,tmux,tui,workspace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: >=3.10
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pillow>=10.3; python_version >= '3.12'
+Requires-Dist: platformdirs
+Requires-Dist: textual-image<0.16,>=0.14; python_version >= '3.12'
+Requires-Dist: textual<9,>=8
+Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: graphics
+Requires-Dist: pillow>=10.3; extra == 'graphics'
+Requires-Dist: textual-image<0.16,>=0.14; extra == 'graphics'
+Description-Content-Type: text/markdown
+
+# myrtui
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![PyPI](https://img.shields.io/pypi/v/myrtui)](https://pypi.org/project/myrtui/)
+[![Python](https://img.shields.io/pypi/pyversions/myrtui)](https://pypi.org/project/myrtui/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
+
+A **project-scoped terminal workspace**: a file tree and git log on the left,
+up to four real shell panes on the right — one session per project, restored
+where you left it.
+
+> It is **not** a tmux replacement. myrtui drives tmux (via a per-project
+> socket) and adds the things tmux deliberately leaves out.
+
+<!-- Record it with: vhs scripts/demo.tape -> docs/demo.gif, then uncomment. -->
+<!-- ![demo](docs/demo.gif) -->
+
+## Why not just tmux
+
+| | tmux / zellij | tmuxinator / sesh | myrtui |
+|---|---|---|---|
+| One session per project, named and isolated automatically | manual | needs a config file | `cd project && myrtui` |
+| File tree + git history next to your shells | — | — | Yes |
+| Layout ratios remembered per project | — | re-edit config | Yes |
+| Open / preview Markdown, images, LaTeX | — | — | Yes |
+| Detach / re-attach, shells survive | Yes | Yes | Yes |
+
+## Features
+
+- **One directory = one instance.** Session identity is derived from the
+  realpath, so two projects never collide; running `myrtui` again attaches to
+  the same session with your panes, layout and scrollback intact.
+- **Up to 4 real tmux panes** with mouse support: click to focus, wheel to
+  scroll, drag splitters to resize (ratios persisted per project).
+- **File tree with git status colours** (VS Code conventions), lazy-loaded,
+  context menu for open / preview / copy path.
+- **Git history panel** — repo-wide or per file, hover a commit for details.
+- **Markdown preview** with GFM, `$math$` via `termtex`, optional full-page
+  LaTeX typesetting through KaTeX on a sepia page (`v`).
+- **Image preview** with Sixel / Kitty graphics where the terminal supports it.
+- **Selection and clipboard** that actually work inside a TUI: drag to select,
+  release to copy (OSC 52 + native clipboard commands).
+
+## Install
+
+Requires `tmux >= 3.1` and Python `>= 3.10` (macOS and Linux; Windows is not
+supported — `fcntl` and no native tmux).
+
+```sh
+brew install tmux              # Linux: sudo apt install tmux
+pipx install myrtui
+myrtui --version
+```
+
+Or use the installer that also checks dependencies and offers the optional
+tools (`micro`, `ov`, `termtex`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/YidingPing/myrtui/main/scripts/install.sh | sh
+```
+
+Upgrade with `pipx upgrade myrtui`. Annotations: Python ≥ 3.12 automatically
+pulls the bitmap extras (`textual-image` + `Pillow`); on 3.10/3.11 previews fall
+back to text, everything else works.
+
+## Usage
+
+```sh
+cd some-project
+myrtui                 # first run creates the session, later runs attach
+```
+
+- `myrtui ls` — list live instances (add `--all` for dead leftovers, `--json`);
+- `myrtui attach [target]` — target = index, hash prefix, or path;
+- `myrtui stop [target]` — cooperative shutdown (never kills panes);
+- `myrtui --root /path/to/other/project` — work on a second project without
+  `cd`; `--shell` and `--scrollback` set the pane shell / history limit.
+
+## Keys (Ctrl-a prefix)
+
+| Key | Action |
+|---|---|
+| `Ctrl-a d` | detach — quit the UI, keep every shell running |
+| `Ctrl-a k` | kill the session (asks first) |
+| `Ctrl-a t` / `w` | open / close a pane (up to 4) |
+| `Ctrl-a 1..4` | focus pane N |
+| `Ctrl-a r` | re-open a dead pane |
+| `Ctrl-a b` | collapse / expand the sidebar |
+| `Ctrl-a s` / `g` | focus the file tree / git history |
+| `Ctrl-a c` / `v` | copy selection / paste |
+
+Everything else goes straight to the inner shell. `Esc` returns from the
+sidebar to the active pane; `Ctrl-a ?` (or hovering `?` in the top bar) shows
+the full cheat sheet. Full tables: [docs/USAGE.md](docs/USAGE.md#key-bindings).
+
+## Configuration
+
+<details>
+<summary>Environment variables</summary>
+
+| Variable | Meaning |
+|---|---|
+| `MYRTUI_LANG` | UI language: `en` (default) / `zh_CN`; `--lang` overrides it for one run |
+| `MYRTUI_EDITOR` | editor for "Open" (falls back to `$EDITOR` / `$VISUAL` / `micro` → `vim` → `vi`) |
+| `MYRTUI_IDLE_INTERVAL` | idle capture interval in seconds (default `0.15`, range `0.05–5.0`); raise it for background instances |
+| `MYRTUI_COPY_ON_SELECT` | auto-copy on drag release (default `1`; `0` keeps the selection for `Ctrl-a c`) |
+| `MYRTUI_DRAG_SELECT` | `always` (default) = drag always selects; `app` = when the pane program requested mouse, drag is forwarded to it |
+| `MYRTUI_GRAPHICS` | bitmap protocol: `auto` (default) / `sixel` / `tgp` / `unicode` / `off` |
+| `MYRTUI_PAGE_THEME` | LaTeX page theme: `sepia` (default) / `paper` / `gray` / `white` / `dim` / `dark` |
+| `MYRTUI_MATH_BACKEND` | math backend for Markdown preview: `auto` (default) / `plain` / `termtex` |
+| `MYRTUI_CELL_PX` | override the terminal cell size (`10x20`) when it is not reported |
+| `MYRTUI_CHROME` | Chrome/Chromium binary for the LaTeX page view |
+| `MYRTUI_PDFTOCAIRO` | PDF → PNG converter (`pdftocairo` preferred, then `pdftoppm`) |
+| `MYRTUI_LOOP_DEBUG` / `MYRTUI_MOUSE_DEBUG` | write timing / mouse event diagnostics to stderr or a temp log |
+
+</details>
+
+## Limitations
+
+- **macOS / Linux only** — Windows has no native tmux and `cli.py` needs `fcntl`.
+- **Clicks inside panes are delayed by 50–150 ms** — dragging always belongs to
+  selection, so a click is injected on release (use `MYRTUI_DRAG_SELECT=app` to
+  give drag back to the program).
+- **No bitmap inside panes** — images render in the preview layer only.
+- **Soft-wrapped lines copy with extra newlines** (capture works line by line).
+- **Echo latency ~150 ms when idle** — tmux capture is polled; typing raises the
+  rate to ~30 ms.
+
+## Docs & contributing
+
+- [docs/USAGE.md](docs/USAGE.md) — the full manual (keys, previews, splitters,
+  instance management, all environment variables). Also available in
+  [Chinese](docs/USAGE.zh-CN.md).
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — module map and design decisions.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to run tests, plus the language policy.
+
+Code comments and docstrings are written in Chinese by project convention;
+user-facing text (this README, the UI, `docs/`) is available in English.
+Issues and pull requests in either language are welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

myrtui-0.5.0/README.md

@@ -0,0 +1,145 @@
+# myrtui
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![PyPI](https://img.shields.io/pypi/v/myrtui)](https://pypi.org/project/myrtui/)
+[![Python](https://img.shields.io/pypi/pyversions/myrtui)](https://pypi.org/project/myrtui/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
+
+A **project-scoped terminal workspace**: a file tree and git log on the left,
+up to four real shell panes on the right — one session per project, restored
+where you left it.
+
+> It is **not** a tmux replacement. myrtui drives tmux (via a per-project
+> socket) and adds the things tmux deliberately leaves out.
+
+<!-- Record it with: vhs scripts/demo.tape -> docs/demo.gif, then uncomment. -->
+<!-- ![demo](docs/demo.gif) -->
+
+## Why not just tmux
+
+| | tmux / zellij | tmuxinator / sesh | myrtui |
+|---|---|---|---|
+| One session per project, named and isolated automatically | manual | needs a config file | `cd project && myrtui` |
+| File tree + git history next to your shells | — | — | Yes |
+| Layout ratios remembered per project | — | re-edit config | Yes |
+| Open / preview Markdown, images, LaTeX | — | — | Yes |
+| Detach / re-attach, shells survive | Yes | Yes | Yes |
+
+## Features
+
+- **One directory = one instance.** Session identity is derived from the
+  realpath, so two projects never collide; running `myrtui` again attaches to
+  the same session with your panes, layout and scrollback intact.
+- **Up to 4 real tmux panes** with mouse support: click to focus, wheel to
+  scroll, drag splitters to resize (ratios persisted per project).
+- **File tree with git status colours** (VS Code conventions), lazy-loaded,
+  context menu for open / preview / copy path.
+- **Git history panel** — repo-wide or per file, hover a commit for details.
+- **Markdown preview** with GFM, `$math$` via `termtex`, optional full-page
+  LaTeX typesetting through KaTeX on a sepia page (`v`).
+- **Image preview** with Sixel / Kitty graphics where the terminal supports it.
+- **Selection and clipboard** that actually work inside a TUI: drag to select,
+  release to copy (OSC 52 + native clipboard commands).
+
+## Install
+
+Requires `tmux >= 3.1` and Python `>= 3.10` (macOS and Linux; Windows is not
+supported — `fcntl` and no native tmux).
+
+```sh
+brew install tmux              # Linux: sudo apt install tmux
+pipx install myrtui
+myrtui --version
+```
+
+Or use the installer that also checks dependencies and offers the optional
+tools (`micro`, `ov`, `termtex`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/YidingPing/myrtui/main/scripts/install.sh | sh
+```
+
+Upgrade with `pipx upgrade myrtui`. Annotations: Python ≥ 3.12 automatically
+pulls the bitmap extras (`textual-image` + `Pillow`); on 3.10/3.11 previews fall
+back to text, everything else works.
+
+## Usage
+
+```sh
+cd some-project
+myrtui                 # first run creates the session, later runs attach
+```
+
+- `myrtui ls` — list live instances (add `--all` for dead leftovers, `--json`);
+- `myrtui attach [target]` — target = index, hash prefix, or path;
+- `myrtui stop [target]` — cooperative shutdown (never kills panes);
+- `myrtui --root /path/to/other/project` — work on a second project without
+  `cd`; `--shell` and `--scrollback` set the pane shell / history limit.
+
+## Keys (Ctrl-a prefix)
+
+| Key | Action |
+|---|---|
+| `Ctrl-a d` | detach — quit the UI, keep every shell running |
+| `Ctrl-a k` | kill the session (asks first) |
+| `Ctrl-a t` / `w` | open / close a pane (up to 4) |
+| `Ctrl-a 1..4` | focus pane N |
+| `Ctrl-a r` | re-open a dead pane |
+| `Ctrl-a b` | collapse / expand the sidebar |
+| `Ctrl-a s` / `g` | focus the file tree / git history |
+| `Ctrl-a c` / `v` | copy selection / paste |
+
+Everything else goes straight to the inner shell. `Esc` returns from the
+sidebar to the active pane; `Ctrl-a ?` (or hovering `?` in the top bar) shows
+the full cheat sheet. Full tables: [docs/USAGE.md](docs/USAGE.md#key-bindings).
+
+## Configuration
+
+<details>
+<summary>Environment variables</summary>
+
+| Variable | Meaning |
+|---|---|
+| `MYRTUI_LANG` | UI language: `en` (default) / `zh_CN`; `--lang` overrides it for one run |
+| `MYRTUI_EDITOR` | editor for "Open" (falls back to `$EDITOR` / `$VISUAL` / `micro` → `vim` → `vi`) |
+| `MYRTUI_IDLE_INTERVAL` | idle capture interval in seconds (default `0.15`, range `0.05–5.0`); raise it for background instances |
+| `MYRTUI_COPY_ON_SELECT` | auto-copy on drag release (default `1`; `0` keeps the selection for `Ctrl-a c`) |
+| `MYRTUI_DRAG_SELECT` | `always` (default) = drag always selects; `app` = when the pane program requested mouse, drag is forwarded to it |
+| `MYRTUI_GRAPHICS` | bitmap protocol: `auto` (default) / `sixel` / `tgp` / `unicode` / `off` |
+| `MYRTUI_PAGE_THEME` | LaTeX page theme: `sepia` (default) / `paper` / `gray` / `white` / `dim` / `dark` |
+| `MYRTUI_MATH_BACKEND` | math backend for Markdown preview: `auto` (default) / `plain` / `termtex` |
+| `MYRTUI_CELL_PX` | override the terminal cell size (`10x20`) when it is not reported |
+| `MYRTUI_CHROME` | Chrome/Chromium binary for the LaTeX page view |
+| `MYRTUI_PDFTOCAIRO` | PDF → PNG converter (`pdftocairo` preferred, then `pdftoppm`) |
+| `MYRTUI_LOOP_DEBUG` / `MYRTUI_MOUSE_DEBUG` | write timing / mouse event diagnostics to stderr or a temp log |
+
+</details>
+
+## Limitations
+
+- **macOS / Linux only** — Windows has no native tmux and `cli.py` needs `fcntl`.
+- **Clicks inside panes are delayed by 50–150 ms** — dragging always belongs to
+  selection, so a click is injected on release (use `MYRTUI_DRAG_SELECT=app` to
+  give drag back to the program).
+- **No bitmap inside panes** — images render in the preview layer only.
+- **Soft-wrapped lines copy with extra newlines** (capture works line by line).
+- **Echo latency ~150 ms when idle** — tmux capture is polled; typing raises the
+  rate to ~30 ms.
+
+## Docs & contributing
+
+- [docs/USAGE.md](docs/USAGE.md) — the full manual (keys, previews, splitters,
+  instance management, all environment variables). Also available in
+  [Chinese](docs/USAGE.zh-CN.md).
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — module map and design decisions.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to run tests, plus the language policy.
+
+Code comments and docstrings are written in Chinese by project convention;
+user-facing text (this README, the UI, `docs/`) is available in English.
+Issues and pull requests in either language are welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

myrtui-0.5.0/README.zh-CN.md

@@ -0,0 +1,136 @@
+# myrtui
+
+[English](README.md) | **简体中文**
+
+[![PyPI](https://img.shields.io/pypi/v/myrtui)](https://pypi.org/project/myrtui/)
+[![Python](https://img.shields.io/pypi/pyversions/myrtui)](https://pypi.org/project/myrtui/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
+
+**面向单个项目的终端工作台**：左侧文件树 + Git 历史，右侧最多 4 个真实 shell
+pane。一个项目一个会话，退出再进来还是原来的布局。
+
+> 它不是 tmux 的替代品——底层就是 tmux（每个项目一个独立 socket）。
+> myrtui 补的是 tmux 故意不做的那些事。
+
+<!-- 录制方式：vhs scripts/demo.tape -> docs/demo.gif，录完取消下面这行注释。 -->
+<!-- ![demo](docs/demo.gif) -->
+
+## 为什么不用 tmux 自己分屏
+
+| | tmux / zellij | tmuxinator / sesh | myrtui |
+|---|---|---|---|
+| 一项目一会话，自动命名与隔离 | 手工 | 要写配置文件 | `cd 项目 && myrtui` |
+| 文件树 + Git 历史与 shell 同屏 | — | — | 有 |
+| 每个项目记住分隔线比例 | — | 每次改配置 | 有 |
+| 打开 / 预览 Markdown、图片、LaTeX | — | — | 有 |
+| detach / attach，shell 继续存活 | 有 | 有 | 有 |
+
+## 特性
+
+- **一个目录 = 一个实例**：身份由真实路径派生，两个项目互不干扰；再次运行
+  同一目录即 attach 回原会话，pane、布局、滚动历史都在。
+- **最多 4 个真实 tmux pane**，鼠标可用：点击聚焦、滚轮翻历史、拖动分隔线
+  调比例（比例按项目落盘记住）。
+- **文件树带 Git 状态配色**（VS Code 习惯），懒加载；右键菜单可打开 / 预览 /
+  复制路径。
+- **Git 历史面板**：仓库级或按文件，鼠标停留 1 秒看提交详情。
+- **Markdown 预览**：GFM、`$公式$` 走 `termtex`，可选 `v` 用 KaTeX 分页排版
+  （米黄纸底）。
+- **图片预览**：终端支持 Sixel / Kitty 时按可视区等比显示。
+- **选区与剪贴板**在 TUI 里真的能用：拖拽选字，松手即复制（OSC 52 + 系统命令）。
+
+## 安装
+
+需要 `tmux >= 3.1` 与 Python `>= 3.10`（macOS / Linux；不支持 Windows——
+`fcntl` 依赖，且 tmux 无原生 Windows 版）。
+
+```sh
+brew install tmux              # Linux: sudo apt install tmux
+pipx install myrtui
+myrtui --version
+```
+
+也可以交给脚本（额外检查依赖、逐项询问可选组件）：
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/YidingPing/myrtui/main/scripts/install.sh | sh
+```
+
+升级用 `pipx upgrade myrtui`。Python ≥ 3.12 会自动带上位图依赖（`textual-image`
++ `Pillow`）；3.10/3.11 上预览回落为文本，其余功能不受影响。
+
+## 使用
+
+```sh
+cd some-project
+myrtui                 # 首次运行创建会话，之后都是 attach
+```
+
+- `myrtui ls` —— 列出存活实例（`--all` 含 dead 残留，`--json` 机器可读）；
+- `myrtui attach [目标]` —— 目标 = 序号 / hash 前缀 / 项目路径；
+- `myrtui stop [目标]` —— 协作式退场（不 kill pane）；
+- `myrtui --root /path/to/other` —— 不 `cd` 也能开另一个项目的实例；
+  `--shell` / `--scrollback` 设置 pane 的 shell 与历史深度。
+
+## 键位（Ctrl-a 前缀）
+
+| 键 | 作用 |
+|---|---|
+| `Ctrl-a d` | detach：前端退出，所有 shell 继续运行 |
+| `Ctrl-a k` | 结束会话（先确认） |
+| `Ctrl-a t` / `w` | 新建 / 关闭 pane（最多 4 个） |
+| `Ctrl-a 1..4` | 切换焦点 pane |
+| `Ctrl-a r` | 重开已退出的 pane |
+| `Ctrl-a b` | 折叠 / 展开侧栏 |
+| `Ctrl-a s` / `g` | 聚焦文件树 / Git 历史 |
+| `Ctrl-a c` / `v` | 复制选区 / 粘贴 |
+
+其余按键直接透传给内层 shell。`Esc` 从侧栏回到 pane；`Ctrl-a ?`（或鼠标悬停
+顶栏的 `?`）显示完整快捷键浮层。全表见[使用手册](docs/USAGE.zh-CN.md)。
+
+## 配置
+
+<details>
+<summary>环境变量</summary>
+
+| 变量 | 作用 |
+|---|---|
+| `MYRTUI_LANG` | 界面语言：`en`（默认）/ `zh_CN`；`--lang` 可单次覆盖 |
+| `MYRTUI_EDITOR` | 「打开」用的编辑器（否则 `$EDITOR` / `$VISUAL` / `micro` → `vim` → `vi`） |
+| `MYRTUI_IDLE_INTERVAL` | 空闲抓屏间隔，秒（默认 `0.15`，夹取 `0.05–5.0`）；后台实例可调大 |
+| `MYRTUI_COPY_ON_SELECT` | 拖拽松手自动复制（默认 `1`；`0` 时用 `Ctrl-a c` 手动复制） |
+| `MYRTUI_DRAG_SELECT` | `always`（默认）= 拖拽永远选字；`app` = 程序请求鼠标时把拖拽还给它 |
+| `MYRTUI_GRAPHICS` | 位图协议：`auto`（默认）/ `sixel` / `tgp` / `unicode` / `off` |
+| `MYRTUI_PAGE_THEME` | `v` 排版页面配色：`sepia`（默认）/ `paper` / `gray` / `white` / `dim` / `dark` |
+| `MYRTUI_MATH_BACKEND` | Markdown 公式后端：`auto`（默认）/ `plain` / `termtex` |
+| `MYRTUI_CELL_PX` | 终端不回报单元格像素尺寸时手动指定（`10x20`） |
+| `MYRTUI_CHROME` | `v` 排版用的 Chrome/Chromium |
+| `MYRTUI_PDFTOCAIRO` | PDF → PNG 转换器（优先 `pdftocairo`，其次 `pdftoppm`） |
+| `MYRTUI_LOOP_DEBUG` / `MYRTUI_MOUSE_DEBUG` | 排障：事件循环延迟 / 鼠标事件写日志 |
+
+</details>
+
+## 已知限制
+
+- **仅 macOS / Linux**：Windows 没有原生 tmux，`cli.py` 也依赖 `fcntl`。
+- **pane 内点击延迟 50–150 ms**：拖拽永远归选字，所以点击在松手时才注入
+  （`MYRTUI_DRAG_SELECT=app` 可把拖拽还给程序）。
+- **pane 内没有位图**：图片只在预览层显示。
+- **软折行复制会多出换行**：抓屏是按行来的。
+- **空闲回显约 150 ms**：抓屏是轮询的，输入后会临时提频到 ~30 ms。
+
+## 文档与贡献
+
+- [使用手册（中文）](docs/USAGE.zh-CN.md) —— 完整键位、预览、分隔线、实例管理、
+  全部环境变量。
+- [docs/USAGE.md](docs/USAGE.md) —— 同一份手册的英文版。
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) —— 模块划分与设计取舍。
+- [CONTRIBUTING.md](CONTRIBUTING.md) —— 如何跑测试，以及注释语言政策。
+
+按项目约定，**代码注释与 docstring 用中文**；面向用户的文本（README、界面、
+`docs/`）提供英文。Issue 与 PR 中英文都欢迎。
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)。