py-screen-mux 20261101.6__tar.gz

py_screen_mux-20261101.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cong Zhang
+
+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.

py_screen_mux-20261101.6/MANIFEST.in

@@ -0,0 +1,3 @@
+# The sdist carries libvterm's sources and licence, so a wheel builds from it alone.
+graft deps/libvterm
+include deps/README.md

py_screen_mux-20261101.6/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: py-screen-mux
+Version: 20261101.6
+Summary: py-screen: a terminal workspace (multiplexer) of my own, with the pys command
+Author-email: Cong Zhang <13283869+congzhangzh@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/congzhangzh/py-screen
+Project-URL: Source, https://github.com/congzhangzh/py-screen
+Project-URL: Releases, https://github.com/congzhangzh/py-screen/releases
+Project-URL: Issues, https://github.com/congzhangzh/py-screen/issues
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: deps/libvterm/LICENSE
+Requires-Dist: pyte>=0.8.2
+Dynamic: license-file
+
+# py-screen
+
+A terminal workspace of my own, in Python: not a clone of screen or tmux, built for fun,
+made more powerful and improved by daily use. The design is in [`spec/`](https://github.com/congzhangzh/py-screen/tree/main/spec/); the
+current version is [`spec/spec.v3.md`](https://github.com/congzhangzh/py-screen/blob/main/spec/spec.v3.md).
+
+Status: **M1 in progress** (Linux; Windows pieces checked on CI). One server, many windows, attach/detach, hot reload, flood-safe typing.
+
+## How it works
+
+```
+client (pys attach) ──► brain (Python, restartable) ──► keeper (tiny, stable) ──► ptys
+```
+
+- **keeper** owns every pty and child process and is the only reader of their output
+  (a byte pump with a ring buffer per window). It restarts the brain when it exits.
+- **brain** holds a pyte screen per window, renders the current one plus a status line,
+  handles keys and answers RPCs. `pys reload` restarts it; shells never notice, because
+  the ptys live in the keeper. The new brain replays the ring buffers, then nudges each pty
+  (SIGWINCH) so full-screen apps repaint.
+- **client** puts the terminal in raw mode, forwards keys and size, prints frames, and
+  reconnects by itself across a brain reload.
+
+### Floods: the screen model is lossless
+
+Every byte a window writes is parsed, in order, whether the window is shown or hidden,
+attached or not. That matters most for apps that draw by diff, like Claude Code: they
+write only the cells they think changed and never rewrite a cell they think is right, so
+a single lost byte leaves wrong cells for good (and a lost mode switch, such as the
+alternate screen or bracketed paste, breaks input too). Until 2026-11-01 py-screen parsed
+only the tail of a flood and dropped a hidden window's output past 128 KB; that is what
+left stray characters in Claude's status line.
+
+Parsing is the slow part (pyte in Python; py-screen's fast paths for plain text, line
+feeds and CSI sequences take it from 0.85 to 1.7 MB/s of scrolling text), so:
+
+- **Backpressure, not dropping.** The keeper gives each window a **credit** of 256 KB
+  un-acked output and stops reading that pty past it. The brain acks bytes only once it
+  has parsed them, so a flooding app simply waits on its write, as under GNU screen. One
+  window can't fill the shared stream, so another window's echo never waits behind it.
+- **Small steps.** The brain parses in steps of 2 ms (2 KB per window per turn, shown
+  windows first, the others round robin), then goes back to keys and frames.
+- **Keys first.** For 100 ms after a key, only shown windows are parsed: nothing else
+  stands between a key and its echo (about 2 ms median while a hidden window floods).
+
+A flood runs at the parser's speed. With the vterm engine (libvterm, in C) that is faster
+than GNU screen: `seq 1 5000000` takes 1.6 s against screen's 13.4 s, a 50 MB coloured log
+0.9 s against 8.1 s ([`bench/README.md`](https://github.com/congzhangzh/py-screen/blob/main/bench/README.md) has the history).
+
+**Screen engines.** Each window's screen is a `term.Term`; `PYS_TERM` picks the engine:
+
+| Engine | What | When |
+|---|---|---|
+| `vterm` (default) | [libvterm](https://github.com/congzhangzh/py-screen/blob/main/deps/README.md)'s parser and state, compiled in, with py-screen's own screen store | When the C extension was built (needs a C compiler at install; release wheels have it) |
+| `pyte` | [pyte](https://github.com/selectel/pyte) with pure-Python fast paths | Always there; about 20× slower on floods |
+
+`PYS_TERM=vterm` makes a missing extension an error instead of a quiet fallback.
+
+A sequence that pyte can't apply (an extra parameter, a `?` where none is defined, an
+unknown erase value) is ignored, as terminals do; the bytes after it are still parsed.
+
+## Releases
+
+Rolling releases: every push to `main` that passes is published as `<YYYYMMDD>.<N>`, the
+version and the tag alike, on [PyPI as `py-screen-mux`](https://pypi.org/project/py-screen-mux/)
+and as a [GitHub release](https://github.com/congzhangzh/py-screen/releases), once, never
+replaced. Pushes that change only docs, specs or bench results publish nothing. A release must pass, in [`release.yml`](https://github.com/congzhangzh/py-screen/blob/main/.github/workflows/release.yml):
+
+- the suite on Linux and macOS, on both screen engines (vterm and pyte);
+- the vterm engine built with ASan + UBSan and fuzzed against libvterm's own screen
+  (a long run every night, in [`sanitize.yml`](https://github.com/congzhangzh/py-screen/blob/main/.github/workflows/sanitize.yml));
+- a parse-speed check: vterm's lead over pyte must keep at least half of the newest
+  recorded run's (`release/bench_gate.py`, against `bench/results/parse-*.json`);
+- each wheel, built by cibuildwheel from the sdist, installed and smoke-tested on the vterm
+  engine on its own system: Linux x86_64 and aarch64 (manylinux), macOS arm64 and x86_64.
+
+Install with [uv](https://docs.astral.sh/uv/), which fetches Python 3.14 if needed and picks
+the wheel for your system:
+
+```bash
+uv tool install py-screen-mux      # the command is pys
+```
+
+The package is `py-screen-mux` on PyPI because `py-screen` is too close to an existing
+`pyscreen` there; the import is `py_screen` and the command `pys`.
+
+Elsewhere, the sdist builds with a C compiler, or runs the pure-Python pyte engine without one.
+Windows joins once its platform layer lands.
+
+## Use
+
+```bash
+uv tool install -e .       # puts `pys` in ~/.local/bin, running this checkout (edits apply on reload)
+pys                        # attach (starts the server on first use)
+pys ls [--json]     # windows
+pys new [--select] [-- cmd …]
+pys send 0 'make test' --enter
+pys capture 0       # the window's screen as text
+pys reload          # new brain, same shells
+pys kill            # end everything
+```
+
+Keys: the prefix is **`C-a`**, or **`C-]`** when you run `pys` inside GNU screen (`$STY`
+set), so the two don't fight. Override with `PREFIX` in the config or `PYS_PREFIX`.
+
+| Keys | Action |
+|---|---|
+| `c` / `C-c` | new window in the focused window's directory |
+| `\|` / `-` | split side by side / stacked, with a new window in the same dir |
+| `\` / `_` | empty split side by side / stacked |
+| `h` `j` `k` `l` | move the focus between panes |
+| `r` then `h/l/j/k`, `=` | resize mode (any other key ends it) · `=` equalise panes |
+| `x` / `X` | close the pane (window keeps running) / kill the window |
+| `n` `p` `0`–`9`, `Alt-0`–`Alt-9` | next, previous, select |
+| `Space` or the prefix twice | toggle to the last window |
+| `w` `"` `F2` | window list (`j/k`, arrows, digits, Enter, Esc) |
+| `,` | rename the window |
+| `?` | help: the windows (a digit or a click selects one), these keys, your config's bindings; Space pages when it does not fit |
+| `a` | send a literal prefix |
+| `d` · `C-l` · `R` · `Q` | detach · redraw · reload the brain · quit everything |
+
+Without the prefix: `Alt-0`…`Alt-9` select, `F2` opens the list, **`Alt-Tab` /
+`Alt-Shift-Tab`** go to the next / previous window. Desktops usually keep Alt-Tab for
+themselves (GNOME: `org.gnome.desktop.wm.keybindings switch-applications`), so it reaches
+py-screen only where the desktop lets it through, e.g. over ssh from another machine.
+Inside GNU screen, screen's own `bindkey` lines may also take the Alt keys first.
+
+### Mouse
+
+On by default, like tmux's `mouse on`:
+
+| Mouse | Does |
+|-------|------|
+| click a pane | focus it; its app gets the click too if it asked for the mouse |
+| click a window in the status line | select it |
+| drag a `│` separator or a caption line | resize the panes on both sides |
+| wheel | goes to the pane under the pointer, focused or not; a full-screen app that didn't ask for the mouse (less, man) gets arrow keys |
+| Shift+drag | select text in your terminal (most terminals; the mouse is pys's otherwise) |
+
+Every report is routed to the pane under the pointer and rewritten in that pane's
+coordinates, in the encoding the app asked for (SGR 1006, or the old X10 form). A press
+grabs its pane: the drag and the release go there even if the pointer leaves it.
+`MOUSE = False` in the config gives plain drags back to the terminal; the mouse is then
+pys's only while the focused app asks for it (still translated per pane).
+
+### Config
+
+`~/.config/pys/config.py` (plain Python, read on every brain start, so `C-a R` applies an
+edit): status widgets and extra key bindings. See `src/py_screen/config.py` for the helpers.
+
+```python
+WIDGETS = [cmd(["git", "-C", "{cwd}", "branch", "--show-current"], every=10), load(), clock()]
+BIND = {"T": ("top", ["htop"])}   # C-a T opens a window running htop
+MOUSE = True                      # False: plain drags select text in the terminal
+```
+
+The layout (splits, focus, renamed titles) is saved on every change, so a reload keeps it.
+
+Sockets live in `$XDG_RUNTIME_DIR/pys/` (`PYS_DIR` overrides; keep it short: an AF_UNIX
+path is limited to 108 bytes). Server log: `server.log` in that dir.
+
+## Test and measure
+
+```bash
+uv run pytest -s                                      # M0 done-criteria (spec §6)
+uv run python bench/m0_speed.py --work <scratch dir>  # speed vs GNU screen (spec §8.1)
+```
+
+Results of each run are kept in [`bench/results/`](https://github.com/congzhangzh/py-screen/tree/main/bench/results/), one file per run, and [`bench/README.md`](https://github.com/congzhangzh/py-screen/blob/main/bench/README.md) tells how the speed evolved, one row per run.
+
+## Known gaps (M1)
+
+- A mouse report split across two reads is passed on as keys (rare; the outer terminal
+  writes each report at once).
+- After a brain restart the screens are rebuilt from the keeper's last 2 MB per window; if
+  that ring wrapped, older state is gone and full-screen apps get a `SIGWINCH` to repaint.
+  Keeping the screens across a planned reload is open.
+- Floods are bounded by pyte's speed (see "Floods").
+- No scrollback view yet (M2).
+- Linux (and macOS) only for now; the Windows pieces are checked by the manual CI run.

py_screen_mux-20261101.6/README.md

@@ -0,0 +1,180 @@
+# py-screen
+
+A terminal workspace of my own, in Python: not a clone of screen or tmux, built for fun,
+made more powerful and improved by daily use. The design is in [`spec/`](https://github.com/congzhangzh/py-screen/tree/main/spec/); the
+current version is [`spec/spec.v3.md`](https://github.com/congzhangzh/py-screen/blob/main/spec/spec.v3.md).
+
+Status: **M1 in progress** (Linux; Windows pieces checked on CI). One server, many windows, attach/detach, hot reload, flood-safe typing.
+
+## How it works
+
+```
+client (pys attach) ──► brain (Python, restartable) ──► keeper (tiny, stable) ──► ptys
+```
+
+- **keeper** owns every pty and child process and is the only reader of their output
+  (a byte pump with a ring buffer per window). It restarts the brain when it exits.
+- **brain** holds a pyte screen per window, renders the current one plus a status line,
+  handles keys and answers RPCs. `pys reload` restarts it; shells never notice, because
+  the ptys live in the keeper. The new brain replays the ring buffers, then nudges each pty
+  (SIGWINCH) so full-screen apps repaint.
+- **client** puts the terminal in raw mode, forwards keys and size, prints frames, and
+  reconnects by itself across a brain reload.
+
+### Floods: the screen model is lossless
+
+Every byte a window writes is parsed, in order, whether the window is shown or hidden,
+attached or not. That matters most for apps that draw by diff, like Claude Code: they
+write only the cells they think changed and never rewrite a cell they think is right, so
+a single lost byte leaves wrong cells for good (and a lost mode switch, such as the
+alternate screen or bracketed paste, breaks input too). Until 2026-11-01 py-screen parsed
+only the tail of a flood and dropped a hidden window's output past 128 KB; that is what
+left stray characters in Claude's status line.
+
+Parsing is the slow part (pyte in Python; py-screen's fast paths for plain text, line
+feeds and CSI sequences take it from 0.85 to 1.7 MB/s of scrolling text), so:
+
+- **Backpressure, not dropping.** The keeper gives each window a **credit** of 256 KB
+  un-acked output and stops reading that pty past it. The brain acks bytes only once it
+  has parsed them, so a flooding app simply waits on its write, as under GNU screen. One
+  window can't fill the shared stream, so another window's echo never waits behind it.
+- **Small steps.** The brain parses in steps of 2 ms (2 KB per window per turn, shown
+  windows first, the others round robin), then goes back to keys and frames.
+- **Keys first.** For 100 ms after a key, only shown windows are parsed: nothing else
+  stands between a key and its echo (about 2 ms median while a hidden window floods).
+
+A flood runs at the parser's speed. With the vterm engine (libvterm, in C) that is faster
+than GNU screen: `seq 1 5000000` takes 1.6 s against screen's 13.4 s, a 50 MB coloured log
+0.9 s against 8.1 s ([`bench/README.md`](https://github.com/congzhangzh/py-screen/blob/main/bench/README.md) has the history).
+
+**Screen engines.** Each window's screen is a `term.Term`; `PYS_TERM` picks the engine:
+
+| Engine | What | When |
+|---|---|---|
+| `vterm` (default) | [libvterm](https://github.com/congzhangzh/py-screen/blob/main/deps/README.md)'s parser and state, compiled in, with py-screen's own screen store | When the C extension was built (needs a C compiler at install; release wheels have it) |
+| `pyte` | [pyte](https://github.com/selectel/pyte) with pure-Python fast paths | Always there; about 20× slower on floods |
+
+`PYS_TERM=vterm` makes a missing extension an error instead of a quiet fallback.
+
+A sequence that pyte can't apply (an extra parameter, a `?` where none is defined, an
+unknown erase value) is ignored, as terminals do; the bytes after it are still parsed.
+
+## Releases
+
+Rolling releases: every push to `main` that passes is published as `<YYYYMMDD>.<N>`, the
+version and the tag alike, on [PyPI as `py-screen-mux`](https://pypi.org/project/py-screen-mux/)
+and as a [GitHub release](https://github.com/congzhangzh/py-screen/releases), once, never
+replaced. Pushes that change only docs, specs or bench results publish nothing. A release must pass, in [`release.yml`](https://github.com/congzhangzh/py-screen/blob/main/.github/workflows/release.yml):
+
+- the suite on Linux and macOS, on both screen engines (vterm and pyte);
+- the vterm engine built with ASan + UBSan and fuzzed against libvterm's own screen
+  (a long run every night, in [`sanitize.yml`](https://github.com/congzhangzh/py-screen/blob/main/.github/workflows/sanitize.yml));
+- a parse-speed check: vterm's lead over pyte must keep at least half of the newest
+  recorded run's (`release/bench_gate.py`, against `bench/results/parse-*.json`);
+- each wheel, built by cibuildwheel from the sdist, installed and smoke-tested on the vterm
+  engine on its own system: Linux x86_64 and aarch64 (manylinux), macOS arm64 and x86_64.
+
+Install with [uv](https://docs.astral.sh/uv/), which fetches Python 3.14 if needed and picks
+the wheel for your system:
+
+```bash
+uv tool install py-screen-mux      # the command is pys
+```
+
+The package is `py-screen-mux` on PyPI because `py-screen` is too close to an existing
+`pyscreen` there; the import is `py_screen` and the command `pys`.
+
+Elsewhere, the sdist builds with a C compiler, or runs the pure-Python pyte engine without one.
+Windows joins once its platform layer lands.
+
+## Use
+
+```bash
+uv tool install -e .       # puts `pys` in ~/.local/bin, running this checkout (edits apply on reload)
+pys                        # attach (starts the server on first use)
+pys ls [--json]     # windows
+pys new [--select] [-- cmd …]
+pys send 0 'make test' --enter
+pys capture 0       # the window's screen as text
+pys reload          # new brain, same shells
+pys kill            # end everything
+```
+
+Keys: the prefix is **`C-a`**, or **`C-]`** when you run `pys` inside GNU screen (`$STY`
+set), so the two don't fight. Override with `PREFIX` in the config or `PYS_PREFIX`.
+
+| Keys | Action |
+|---|---|
+| `c` / `C-c` | new window in the focused window's directory |
+| `\|` / `-` | split side by side / stacked, with a new window in the same dir |
+| `\` / `_` | empty split side by side / stacked |
+| `h` `j` `k` `l` | move the focus between panes |
+| `r` then `h/l/j/k`, `=` | resize mode (any other key ends it) · `=` equalise panes |
+| `x` / `X` | close the pane (window keeps running) / kill the window |
+| `n` `p` `0`–`9`, `Alt-0`–`Alt-9` | next, previous, select |
+| `Space` or the prefix twice | toggle to the last window |
+| `w` `"` `F2` | window list (`j/k`, arrows, digits, Enter, Esc) |
+| `,` | rename the window |
+| `?` | help: the windows (a digit or a click selects one), these keys, your config's bindings; Space pages when it does not fit |
+| `a` | send a literal prefix |
+| `d` · `C-l` · `R` · `Q` | detach · redraw · reload the brain · quit everything |
+
+Without the prefix: `Alt-0`…`Alt-9` select, `F2` opens the list, **`Alt-Tab` /
+`Alt-Shift-Tab`** go to the next / previous window. Desktops usually keep Alt-Tab for
+themselves (GNOME: `org.gnome.desktop.wm.keybindings switch-applications`), so it reaches
+py-screen only where the desktop lets it through, e.g. over ssh from another machine.
+Inside GNU screen, screen's own `bindkey` lines may also take the Alt keys first.
+
+### Mouse
+
+On by default, like tmux's `mouse on`:
+
+| Mouse | Does |
+|-------|------|
+| click a pane | focus it; its app gets the click too if it asked for the mouse |
+| click a window in the status line | select it |
+| drag a `│` separator or a caption line | resize the panes on both sides |
+| wheel | goes to the pane under the pointer, focused or not; a full-screen app that didn't ask for the mouse (less, man) gets arrow keys |
+| Shift+drag | select text in your terminal (most terminals; the mouse is pys's otherwise) |
+
+Every report is routed to the pane under the pointer and rewritten in that pane's
+coordinates, in the encoding the app asked for (SGR 1006, or the old X10 form). A press
+grabs its pane: the drag and the release go there even if the pointer leaves it.
+`MOUSE = False` in the config gives plain drags back to the terminal; the mouse is then
+pys's only while the focused app asks for it (still translated per pane).
+
+### Config
+
+`~/.config/pys/config.py` (plain Python, read on every brain start, so `C-a R` applies an
+edit): status widgets and extra key bindings. See `src/py_screen/config.py` for the helpers.
+
+```python
+WIDGETS = [cmd(["git", "-C", "{cwd}", "branch", "--show-current"], every=10), load(), clock()]
+BIND = {"T": ("top", ["htop"])}   # C-a T opens a window running htop
+MOUSE = True                      # False: plain drags select text in the terminal
+```
+
+The layout (splits, focus, renamed titles) is saved on every change, so a reload keeps it.
+
+Sockets live in `$XDG_RUNTIME_DIR/pys/` (`PYS_DIR` overrides; keep it short: an AF_UNIX
+path is limited to 108 bytes). Server log: `server.log` in that dir.
+
+## Test and measure
+
+```bash
+uv run pytest -s                                      # M0 done-criteria (spec §6)
+uv run python bench/m0_speed.py --work <scratch dir>  # speed vs GNU screen (spec §8.1)
+```
+
+Results of each run are kept in [`bench/results/`](https://github.com/congzhangzh/py-screen/tree/main/bench/results/), one file per run, and [`bench/README.md`](https://github.com/congzhangzh/py-screen/blob/main/bench/README.md) tells how the speed evolved, one row per run.
+
+## Known gaps (M1)
+
+- A mouse report split across two reads is passed on as keys (rare; the outer terminal
+  writes each report at once).
+- After a brain restart the screens are rebuilt from the keeper's last 2 MB per window; if
+  that ring wrapped, older state is gone and full-screen apps get a `SIGWINCH` to repaint.
+  Keeping the screens across a planned reload is open.
+- Floods are bounded by pyte's speed (see "Floods").
+- No scrollback view yet (M2).
+- Linux (and macOS) only for now; the Windows pieces are checked by the manual CI run.

py_screen_mux-20261101.6/deps/README.md

@@ -0,0 +1,54 @@
+# Third-party code
+
+## libvterm 0.3.3 (`deps/libvterm`, MIT, see its `LICENSE`)
+
+The terminal state machine behind the `vterm` screen engine. Upstream lives in
+Bazaar on Launchpad; this tree comes from the git mirror Neovim kept of it.
+
+| What | Value |
+|---|---|
+| Added with | `git read-tree --prefix=deps/libvterm -u v0.3.3^{tree}` after fetching the tag: one plain commit, no merge, so history stays linear; its `git-subtree-dir:` / `git-subtree-split:` trailers are what `git subtree` reads |
+| Upstream commit | `9d6d2112335080312ef8c36667fa717ded4f7daf` (tag `v0.3.3`) |
+| Release tarball | `libvterm-0.3.3.tar.gz`, sha256 `09156f43dd2128bd347cbeebe50d9a571d32c64e0cf18d211197946aff7226e0`, the same file as Debian's `libvterm_0.3.3.orig.tar.gz` |
+| Checked | `src/` and `include/` equal the tarball's, file for file |
+| Tag vs tarball | The tag also has `doc/`, `CODE-MAP`, the `.tbl` sources and `tbl2inc_c.pl`; its `Makefile` and `vterm.pc.in` differ (the tarball strips the dist section); `t/69screen_sb_clear.test` is in the tarball only; the tarball has the generated `.inc` files (change 1) |
+
+Changes on top of upstream, each its own commit (`git log -- deps/libvterm`):
+
+1. `src/encoding/DECdrawing.inc` and `uk.inc`: generated by upstream's Makefile from the
+   `.tbl` files with Perl; copied from the release tarball, which ships them, so a build
+   needs only a C compiler.
+
+2. `src/state.c`, REP (`CSI n b`, repeat the previous character): with no character drawn
+   yet, `combine_width` is 0 and `while (pos.col < col) pos.col += combine_width` never
+   ends, so one `ESC [ 3 b` as a terminal's first output froze the brain for good (no
+   crash, so no restart). Now REP does nothing then, as ECMA-48 leaves it undefined.
+   Found by tests/test_vterm.py on its second seed; libvterm's own screen layer hangs
+   the same way. The same loop repeated a wide character into the last column, half
+   past the row's end: libvterm's screen layer then writes through a NULL cell pointer
+   (`screen.c` putglyph, a segfault; found on seed 46). Now a character is repeated
+   only while it fits. Not reported upstream yet.
+
+3. `src/state.c`, `on_resize`: only the bottom and right margins were clamped to the new
+   size, so a scroll region that no longer fit (`ESC [ 6 ; 10 r`, then 3 rows) ended
+   upside down, and the next line feed's `scroll()` did a `memmove` of negative size
+   (found by AddressSanitizer on tests/test_vterm.py seed 10040; before it, a heap
+   corruption). Such a region now goes back to the whole screen, as xterm resets
+   margins on a resize. Not reported upstream yet.
+
+4. `src/state.c`, `savecursor` (restore, `ESC 8`, leaving `?1049`): the saved position
+   came back unclamped, so a cursor saved on row 4 and restored after a resize to 3 rows
+   sat off the screen; the next glyph read and wrote `lineinfo` past its end, and
+   libvterm's screen layer wrote through a NULL cell (AddressSanitizer, seed 103772
+   of a 5000-seed run). Clamped to the screen now, as xterm restores a cursor. Not
+   reported upstream yet.
+
+Nothing else in libvterm is changed; py-screen's own C code reaches libvterm through its
+headers and, for its own resize, the line-info arrays and allocator libvterm's state
+expects a resize callback to replace (as `screen.c` does).
+
+To update, keep it flat the same way: fetch the new tag, `git rm -rq deps/libvterm`,
+`git read-tree --prefix=deps/libvterm -u <tag>^{tree}`, commit with the two trailers
+naming the new upstream commit, then redo change 1 from that release's tarball and
+check its sha256 against Debian's `.dsc`. (`git subtree pull --squash` also works from
+the trailers, tested 0.3.2 → 0.3.3, but it adds a merge commit.)

py_screen_mux-20261101.6/deps/libvterm/.bzrignore

@@ -0,0 +1,13 @@
+.libs
+*.lo
+*.la
+
+bin/*
+!bin/*.c
+
+pangoterm
+t/test
+t/suites.h
+t/externs.h
+t/harness
+src/encoding/*.inc

py_screen_mux-20261101.6/deps/libvterm/CODE-MAP

@@ -0,0 +1,81 @@
+bin/
+ - contains some standalone programs
+
+bin/unterm.c
+ - an example program using libvterm to reconstruct the final state of a
+   terminal after replaying captured input
+
+bin/vterm-ctrl.c
+ - a helper program that emits sequences to control a running libvterm
+   terminal
+
+bin/vterm-dump.c
+ - an example program using the parser layer of libvterm to interpret captured
+   input
+
+CODE-MAP
+ - high-level list and description of files in the repository
+
+CONTRIBUTING
+ - documentation explaining how developers can contribute fixes and features
+
+doc/
+ - contains documentation
+
+doc/seqs.txt
+ - documents the sequences recognised by the library
+
+include/vterm.h
+ - main include file
+
+include/vterm_keycodes.h
+ - include file containing the keyboard input keycode enumerations
+
+LICENSE
+ - legalese
+
+Makefile
+ - main build file
+
+src/
+ - contains the source code for the library
+
+src/encoding.c
+ - handles mapping ISO/IEC 2022 alternate character sets into Unicode
+   codepoints
+
+src/keyboard.c
+ - handles sending reported keyboard events to the output stream
+
+src/mouse.c
+ - handles sending reported mouse events to the output stream
+
+src/parser.c
+ - parses bytes from the input stream into parser-level events
+
+src/pen.c
+ - interprets SGR sequences and maintains current rendering attributes
+
+src/screen.c
+ - uses state-level events to maintain a buffer of current screen contents
+
+src/state.c
+ - follows parser-level events to keep track of the overall terminal state
+
+src/unicode.c
+ - utility functions for Unicode and UTF-8 handling
+
+src/vterm.c
+ - toplevel object state and miscellaneous functions
+
+src/vterm_internal.h
+ - include file for definitions private to the library's internals
+
+t/
+ - contains unit tests
+
+t/harness.c
+ - standalone program to embed the library into for unit-test purposes
+
+t/run-test.pl
+ - invokes the test harness to run a single unit test script

py_screen_mux-20261101.6/deps/libvterm/CONTRIBUTING

@@ -0,0 +1,22 @@
+How to Contribute
+-----------------
+
+The main resources for this library are:
+
+  Launchpad
+    https://launchpad.net/libvterm
+
+  IRC:
+    ##tty or #tickit on irc.libera.chat
+
+  Email:
+    Paul "LeoNerd" Evans <leonerd@leonerd.org.uk>
+
+
+Bug reports and feature requests can be sent to any of the above resources.
+
+New features, bug patches, etc.. should in the first instance be discussed via
+any of the resources listed above, before starting work on the actual code.
+There may be future plans or development already in-progress that could be
+affected so it is better to discuss the ideas first before starting work
+actually writing any code.

py_screen_mux-20261101.6/deps/libvterm/LICENSE

@@ -0,0 +1,23 @@
+
+
+The MIT License
+
+Copyright (c) 2008 Paul Evans <leonerd@leonerd.org.uk>
+
+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.