clownfish 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clownfish-0.5.0/PKG-INFO +214 -0
- clownfish-0.5.0/README.md +200 -0
- clownfish-0.5.0/pyproject.toml +33 -0
- clownfish-0.5.0/pyproject.toml.orig +34 -0
- clownfish-0.5.0/src/clownfish/__init__.py +132 -0
- clownfish-0.5.0/src/clownfish/__main__.py +6 -0
- clownfish-0.5.0/src/clownfish/app.py +5 -0
- clownfish-0.5.0/src/clownfish/clownfish.png +0 -0
- clownfish-0.5.0/src/clownfish/config.py +84 -0
- clownfish-0.5.0/src/clownfish/core/__init__.py +34 -0
- clownfish-0.5.0/src/clownfish/core/keyboard.py +197 -0
- clownfish-0.5.0/src/clownfish/core/models.py +122 -0
- clownfish-0.5.0/src/clownfish/core/parser.py +461 -0
- clownfish-0.5.0/src/clownfish/core/screen.py +719 -0
- clownfish-0.5.0/src/clownfish/core/search.py +153 -0
- clownfish-0.5.0/src/clownfish/frontends/__init__.py +1 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/__init__.py +17 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/app.py +344 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/input.py +214 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/pane.py +390 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/renderer.py +223 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/split.py +261 -0
- clownfish-0.5.0/src/clownfish/frontends/tkinter/tabs.py +217 -0
- clownfish-0.5.0/src/clownfish/main.py +6 -0
- clownfish-0.5.0/src/clownfish/models.py +25 -0
- clownfish-0.5.0/src/clownfish/parser.py +5 -0
- clownfish-0.5.0/src/clownfish/screen.py +5 -0
- clownfish-0.5.0/src/clownfish/session/__init__.py +15 -0
- clownfish-0.5.0/src/clownfish/session/session.py +294 -0
- clownfish-0.5.0/src/clownfish/session/transport.py +53 -0
- clownfish-0.5.0/src/clownfish/syntax.py +42 -0
- clownfish-0.5.0/src/clownfish/transports/__init__.py +6 -0
- clownfish-0.5.0/src/clownfish/transports/pty.py +243 -0
- clownfish-0.5.0/src/clownfish/transports/ssh.py +53 -0
clownfish-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: clownfish
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: A modern terminal emulator written in Python and Tkinter
|
|
5
|
+
Author: ellainng
|
|
6
|
+
Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
|
|
7
|
+
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
|
|
8
|
+
Requires-Dist: ruff>=0.4.0 ; extra == 'dev'
|
|
9
|
+
Requires-Dist: escape-colors==0.2.0 ; extra == 'syntax'
|
|
10
|
+
Requires-Python: >=3.14
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Provides-Extra: syntax
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# Clownfish 🐟
|
|
16
|
+
|
|
17
|
+
[](https://github.com/wispsy/clownfish/actions/workflows/ci.yml)
|
|
18
|
+
[](https://www.python.org/downloads/)
|
|
19
|
+
[](https://opensource.org/licenses/MIT)
|
|
20
|
+
|
|
21
|
+
A lightweight, modern terminal emulator written in Python and Tkinter, featuring TrueColor rendering, full POSIX PTY bridge, mouse reporting, Unicode wide character support, device attribute queries, and shell integration.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **Split Navigation & Desktop Ergonomics**: Fast split pane keyboard cycling (`Cmd+[` / `Cmd+]` or `Alt+[` / `Alt+]`), split equalization (`Cmd+=` / `Ctrl+=`), high-contrast active-pane visual border highlight (`#4a90e2`), and automatic current working directory inheritance on new tabs (`Cmd+T`) and split panes (`Cmd+D`).
|
|
28
|
+
- **High-Throughput PTY Batching & Idle Throttling**: Bounded PTY event processing (`drain_events(max_bytes=512_000)`) with adaptive tick rate (`after(1)` for pending stream bursts, `after(16)` for interactive typing) and cursor state caching to eliminate canvas churn when idle.
|
|
29
|
+
- **Security & OSC Integrations**: Base64 clipboard get/set (`OSC 52`) with size-bounded payload decoding, current working directory tracking (`OSC 7`), strict allowlisted URL scheme validation for hyperlinks (`OSC 8`), and desktop notifications (`OSC 9` and `OSC 777`).
|
|
30
|
+
- **Unicode Grapheme Clusters & Complex Emojis**: Support for Zero-Width Joiner (ZWJ, `\u200D`) connected emoji sequences (e.g. `👩💻`), Fitzpatrick skin tone modifiers, regional indicator flag pairs (`🇯🇵`), and extended emoji/symbol pictographs in monospace terminal grid math.
|
|
31
|
+
- **VT/xterm & Keyboard Conformance**: Full F1–F12 function key encoding, standard xterm modified navigation keys (`Ctrl/Alt/Shift + Arrows/Home/End/PageUp/PageDown`), DECOM Origin Mode (`?6h`/`?6l`), DECAWM Auto-wrap Mode (`?7h`/`?7l`), DECSCUSR cursor styles (block, underline, bar), and DEC Mode 2026 Synchronized Output for tear-free rendering.
|
|
32
|
+
- **Mouse Motion Reporting**: Button motion tracking (`?1002h`) and any-event motion tracking (`?1003h`) alongside standard press/release (`?1000h`) and SGR format (`?1006h`).
|
|
33
|
+
- **Interactive Login Shells & Job Control**: Launches native user shells (`/bin/zsh`, `/bin/bash`) as login interactive shells (`-l -i`) with controlling terminal allocation (`TIOCSCTTY`), pre-spawn window sizing (`TIOCSWINSZ`), and full POSIX job control (`Ctrl+C`, `Ctrl+Z`, `fg`, `bg`).
|
|
34
|
+
- **Non-Destructive Soft-Wrap Reflow**: Dynamic text reflow (`Row.is_wrapped`) when resizing terminal columns, preserving character buffers, styles, wide glyphs, and cursor positioning without data loss.
|
|
35
|
+
- **Screen-Editing VT Sequences**: Full support for Cursor Next/Previous Line (`CSI E`/`F`), Erase Characters (`CSI X`), Insert/Delete Lines (`CSI L`/`M`), Scroll Up/Down (`CSI S`/`T`), and ANSI Cursor Save/Restore (`CSI s`/`u`).
|
|
36
|
+
- **Prompt Preservation on Clear**: Complete terminal reset (`Cmd+K` / `Ctrl+K`) flushes scrollback while requesting interactive shell redraw (`Ctrl+L`), preserving partially typed command lines.
|
|
37
|
+
- **Dynamic Window & Tab Titles**: Shell `precmd` window and tab title sequences (`OSC 0` and `OSC 2`) update desktop tab headers in real time.
|
|
38
|
+
- **Multi-Tab Terminal Sessions**: Manage multiple independent terminal sessions with tab switching shortcuts (`Cmd+T`, `Cmd+W`, `Cmd+1..9`, `Ctrl+Tab`).
|
|
39
|
+
- **Split Panes**: Divide any tab vertically (`Cmd+D`) or horizontally (`Cmd+Shift+D`) with native resizable sash dividers.
|
|
40
|
+
- **In-Buffer Search**: Interactive search bar (`Cmd+F`) across active terminal screen and scrollback history with match highlighting and cycling.
|
|
41
|
+
- **User Preferences**: Persistent configuration in `~/.config/clownfish/config.json`.
|
|
42
|
+
- **TrueColor & 256-Color Support**: Full 24-bit RGB TrueColor escaping and standard ANSI 16/256 palette support.
|
|
43
|
+
- **Full Screen & Scrollback Clear**: Complete terminal reset with `Cmd+K` (macOS) or `Ctrl+K` (Linux/Windows) that flushes active screen and all 10,000 lines of scrollback buffer.
|
|
44
|
+
- **Unicode Wide Characters & Emojis**: Character classification via East Asian Width (`unicodedata.east_asian_width`) for 2-column CJK characters and emojis with sentinel spacer cells.
|
|
45
|
+
- **Device Attribute Queries**: Standard VT220 / xterm query responses for DA1 (`\x1b[c`), DA2 (`\x1b[>c`), DSR / CPR (`\x1b[6n`), and OSC 10/11 color queries, eliminating CLI boot delays.
|
|
46
|
+
- **Kitty Keyboard Protocol**: Protocol flag negotiation (`CSI ? u`, `CSI = u`, `CSI > u`, `CSI < u`) enabling disambiguation of modified keystrokes like `Shift+Enter`.
|
|
47
|
+
- **OSC 133 Semantic Prompts**: Shell integration tracking prompt start, command execution, and exit codes, enabling prompt-to-prompt jumping (`Cmd+Up` / `Cmd+Down`).
|
|
48
|
+
- **OSC 8 Hyperlinks**: Clickable URLs with browser launching via `Cmd+Click` or `Ctrl+Click`.
|
|
49
|
+
- **Mouse Tracking**: Normal tracking (`?1000h`) and SGR decimal tracking (`?1006h`) for interactive CLI programs like `vim`, `htop`, and `tmux`.
|
|
50
|
+
- **Primary & Alternate Screen Buffers**: Smooth transitions into and out of full-screen terminal programs without corrupting main scrollback.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Installation & Running
|
|
55
|
+
|
|
56
|
+
Clownfish offers multiple installation channels: native macOS application bundle, Homebrew tap, PyPI package, or source.
|
|
57
|
+
|
|
58
|
+
### Option 1: macOS Application Bundle (`Clownfish.app`)
|
|
59
|
+
|
|
60
|
+
Download the latest release archive from [GitHub Releases](https://github.com/wispsy/clownfish/releases):
|
|
61
|
+
|
|
62
|
+
1. Download `Clownfish-v0.5.0-macos.zip`.
|
|
63
|
+
2. Unzip the archive:
|
|
64
|
+
```bash
|
|
65
|
+
unzip Clownfish-v0.5.0-macos.zip
|
|
66
|
+
```
|
|
67
|
+
3. Move `Clownfish.app` to `/Applications`:
|
|
68
|
+
```bash
|
|
69
|
+
mv Clownfish.app /Applications/
|
|
70
|
+
```
|
|
71
|
+
4. Launch Clownfish from Spotlight, Finder, or from your terminal with `open /Applications/Clownfish.app`.
|
|
72
|
+
|
|
73
|
+
### Option 2: Homebrew Tap (`wispsy/homebrew-tap`)
|
|
74
|
+
|
|
75
|
+
Install Clownfish via the official [Wispsy Homebrew tap](https://github.com/wispsy/homebrew-tap):
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# Add the tap
|
|
79
|
+
brew tap wispsy/tap
|
|
80
|
+
|
|
81
|
+
# Install the CLI formula (isolated Python environment)
|
|
82
|
+
brew install clownfish
|
|
83
|
+
|
|
84
|
+
# Or install the standalone macOS GUI application via Cask
|
|
85
|
+
brew install --cask wispsy/tap/clownfish
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Option 3: PyPI Package (`pip` / `uv`)
|
|
89
|
+
|
|
90
|
+
Clownfish is published to PyPI and requires Python 3.14+:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# Using uv (recommended)
|
|
94
|
+
uv tool install clownfish
|
|
95
|
+
|
|
96
|
+
# Or using pip
|
|
97
|
+
pip install clownfish
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Run directly:
|
|
101
|
+
```bash
|
|
102
|
+
clownfish
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Option 4: From Source (Development)
|
|
106
|
+
|
|
107
|
+
Ensure you have Python 3.14+ and [uv](https://docs.astral.sh/uv/) installed.
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
git clone https://github.com/wispsy/clownfish.git
|
|
111
|
+
cd clownfish
|
|
112
|
+
uv sync --all-extras
|
|
113
|
+
uv run clownfish
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
To build the standalone macOS `.app` bundle from source:
|
|
117
|
+
```bash
|
|
118
|
+
uv run --with pyinstaller python scripts/build_macos_app.py
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Testing & Quality Assurance
|
|
124
|
+
|
|
125
|
+
Run the test suite:
|
|
126
|
+
```bash
|
|
127
|
+
uv run pytest
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Run code formatting and linting:
|
|
131
|
+
```bash
|
|
132
|
+
uv run ruff check .
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Documentation
|
|
138
|
+
|
|
139
|
+
- [Architecture Guide](docs/architecture.md): Deep dive into screen buffer management, parser state machine, and render loop.
|
|
140
|
+
- [Modern Terminal Gap Analysis](docs/modern-terminal-gap-analysis.md): Technical analysis of the fundamental features required for modern terminal emulators.
|
|
141
|
+
- [Keyboard & Mouse Shortcuts](docs/shortcuts.md): Guide to shortcuts for clearing buffers, navigation, and clipboard operations.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Project Structure
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
clownfish/
|
|
149
|
+
├── .github/
|
|
150
|
+
│ └── workflows/
|
|
151
|
+
│ ├── ci.yml # GitHub Actions CI workflow (Ubuntu & macOS)
|
|
152
|
+
│ └── release.yaml # Automated PyPI & GitHub Release workflow
|
|
153
|
+
├── assets/
|
|
154
|
+
│ └── Clownfish.icns # Multi-resolution macOS application icon
|
|
155
|
+
├── docs/
|
|
156
|
+
│ ├── architecture.md # Architecture overview & data flow
|
|
157
|
+
│ ├── modern-terminal-gap-analysis.md # Modern terminal specifications
|
|
158
|
+
│ └── shortcuts.md # Keybinding reference
|
|
159
|
+
├── packaging/
|
|
160
|
+
│ └── homebrew/ # Homebrew tap formulas & casks
|
|
161
|
+
│ ├── Casks/
|
|
162
|
+
│ │ └── clownfish.rb
|
|
163
|
+
│ └── Formula/
|
|
164
|
+
│ └── clownfish.rb
|
|
165
|
+
├── scripts/
|
|
166
|
+
│ ├── build_macos_app.py # PyInstaller macOS bundle & zip builder
|
|
167
|
+
│ └── publish_homebrew.py # Homebrew tap release automation
|
|
168
|
+
├── src/
|
|
169
|
+
│ └── clownfish/
|
|
170
|
+
│ ├── __init__.py # Public API exports & launch function
|
|
171
|
+
│ ├── __main__.py # Module entrypoint (python -m clownfish)
|
|
172
|
+
│ ├── config.py # Configuration dataclasses (TerminalConfig)
|
|
173
|
+
│ ├── syntax.py # Syntax highlighting integration
|
|
174
|
+
│ ├── core/ # Core terminal engine
|
|
175
|
+
│ │ ├── models.py # Data models (Cell, Style, Selection, PromptMarker)
|
|
176
|
+
│ │ ├── keyboard.py # Keystroke encoding & Kitty keyboard protocol
|
|
177
|
+
│ │ ├── parser.py # VT100 / ANSI / OSC escape sequence parser
|
|
178
|
+
│ │ ├── screen.py # Screen buffer, dual grid, autowrap & scrollback
|
|
179
|
+
│ │ └── search.py # In-buffer regex & plain text search engine
|
|
180
|
+
│ ├── session/ # Terminal session layer
|
|
181
|
+
│ │ ├── session.py # TerminalSession lifecycle manager
|
|
182
|
+
│ │ └── transport.py # Abstract Transport base class
|
|
183
|
+
│ ├── transports/ # Pluggable I/O transports
|
|
184
|
+
│ │ ├── pty.py # POSIX PTYTransport with write buffering
|
|
185
|
+
│ │ └── ssh.py # SSHTransport via OpenSSH PTY bridge
|
|
186
|
+
│ └── frontends/
|
|
187
|
+
│ └── tkinter/ # Tkinter desktop frontend
|
|
188
|
+
│ ├── app.py # TkTerminalApp main window & menu shortcuts
|
|
189
|
+
│ ├── pane.py # TerminalPane self-contained terminal widget
|
|
190
|
+
│ ├── split.py # SplitView arbitrary nested split pane manager
|
|
191
|
+
│ ├── tabs.py # TabbedTerminalView multi-tab session manager
|
|
192
|
+
│ ├── renderer.py # Canvas text & selection renderer
|
|
193
|
+
│ └── input.py # Pointer & keyboard event translator
|
|
194
|
+
├── tests/ # Comprehensive unit & integration test suite
|
|
195
|
+
├── pyproject.toml # Project metadata & build settings
|
|
196
|
+
└── README.md
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Roadmap
|
|
202
|
+
|
|
203
|
+
- [x] Split-pane multiplexing and tabbed sessions.
|
|
204
|
+
- [x] In-buffer regex / plain text search with highlight overlay.
|
|
205
|
+
- [ ] GPU-accelerated texture atlas rendering via Metal/Vulkan.
|
|
206
|
+
- [ ] HarfBuzz typography shaping for developer font ligatures (`->`, `!=`, `===`).
|
|
207
|
+
- [ ] Kitty Graphics Protocol inline image streaming.
|
|
208
|
+
- [ ] Sixel bitmap rasterization protocol support.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
This project is licensed under the MIT License.
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Clownfish 🐟
|
|
2
|
+
|
|
3
|
+
[](https://github.com/wispsy/clownfish/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
A lightweight, modern terminal emulator written in Python and Tkinter, featuring TrueColor rendering, full POSIX PTY bridge, mouse reporting, Unicode wide character support, device attribute queries, and shell integration.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Split Navigation & Desktop Ergonomics**: Fast split pane keyboard cycling (`Cmd+[` / `Cmd+]` or `Alt+[` / `Alt+]`), split equalization (`Cmd+=` / `Ctrl+=`), high-contrast active-pane visual border highlight (`#4a90e2`), and automatic current working directory inheritance on new tabs (`Cmd+T`) and split panes (`Cmd+D`).
|
|
14
|
+
- **High-Throughput PTY Batching & Idle Throttling**: Bounded PTY event processing (`drain_events(max_bytes=512_000)`) with adaptive tick rate (`after(1)` for pending stream bursts, `after(16)` for interactive typing) and cursor state caching to eliminate canvas churn when idle.
|
|
15
|
+
- **Security & OSC Integrations**: Base64 clipboard get/set (`OSC 52`) with size-bounded payload decoding, current working directory tracking (`OSC 7`), strict allowlisted URL scheme validation for hyperlinks (`OSC 8`), and desktop notifications (`OSC 9` and `OSC 777`).
|
|
16
|
+
- **Unicode Grapheme Clusters & Complex Emojis**: Support for Zero-Width Joiner (ZWJ, `\u200D`) connected emoji sequences (e.g. `👩💻`), Fitzpatrick skin tone modifiers, regional indicator flag pairs (`🇯🇵`), and extended emoji/symbol pictographs in monospace terminal grid math.
|
|
17
|
+
- **VT/xterm & Keyboard Conformance**: Full F1–F12 function key encoding, standard xterm modified navigation keys (`Ctrl/Alt/Shift + Arrows/Home/End/PageUp/PageDown`), DECOM Origin Mode (`?6h`/`?6l`), DECAWM Auto-wrap Mode (`?7h`/`?7l`), DECSCUSR cursor styles (block, underline, bar), and DEC Mode 2026 Synchronized Output for tear-free rendering.
|
|
18
|
+
- **Mouse Motion Reporting**: Button motion tracking (`?1002h`) and any-event motion tracking (`?1003h`) alongside standard press/release (`?1000h`) and SGR format (`?1006h`).
|
|
19
|
+
- **Interactive Login Shells & Job Control**: Launches native user shells (`/bin/zsh`, `/bin/bash`) as login interactive shells (`-l -i`) with controlling terminal allocation (`TIOCSCTTY`), pre-spawn window sizing (`TIOCSWINSZ`), and full POSIX job control (`Ctrl+C`, `Ctrl+Z`, `fg`, `bg`).
|
|
20
|
+
- **Non-Destructive Soft-Wrap Reflow**: Dynamic text reflow (`Row.is_wrapped`) when resizing terminal columns, preserving character buffers, styles, wide glyphs, and cursor positioning without data loss.
|
|
21
|
+
- **Screen-Editing VT Sequences**: Full support for Cursor Next/Previous Line (`CSI E`/`F`), Erase Characters (`CSI X`), Insert/Delete Lines (`CSI L`/`M`), Scroll Up/Down (`CSI S`/`T`), and ANSI Cursor Save/Restore (`CSI s`/`u`).
|
|
22
|
+
- **Prompt Preservation on Clear**: Complete terminal reset (`Cmd+K` / `Ctrl+K`) flushes scrollback while requesting interactive shell redraw (`Ctrl+L`), preserving partially typed command lines.
|
|
23
|
+
- **Dynamic Window & Tab Titles**: Shell `precmd` window and tab title sequences (`OSC 0` and `OSC 2`) update desktop tab headers in real time.
|
|
24
|
+
- **Multi-Tab Terminal Sessions**: Manage multiple independent terminal sessions with tab switching shortcuts (`Cmd+T`, `Cmd+W`, `Cmd+1..9`, `Ctrl+Tab`).
|
|
25
|
+
- **Split Panes**: Divide any tab vertically (`Cmd+D`) or horizontally (`Cmd+Shift+D`) with native resizable sash dividers.
|
|
26
|
+
- **In-Buffer Search**: Interactive search bar (`Cmd+F`) across active terminal screen and scrollback history with match highlighting and cycling.
|
|
27
|
+
- **User Preferences**: Persistent configuration in `~/.config/clownfish/config.json`.
|
|
28
|
+
- **TrueColor & 256-Color Support**: Full 24-bit RGB TrueColor escaping and standard ANSI 16/256 palette support.
|
|
29
|
+
- **Full Screen & Scrollback Clear**: Complete terminal reset with `Cmd+K` (macOS) or `Ctrl+K` (Linux/Windows) that flushes active screen and all 10,000 lines of scrollback buffer.
|
|
30
|
+
- **Unicode Wide Characters & Emojis**: Character classification via East Asian Width (`unicodedata.east_asian_width`) for 2-column CJK characters and emojis with sentinel spacer cells.
|
|
31
|
+
- **Device Attribute Queries**: Standard VT220 / xterm query responses for DA1 (`\x1b[c`), DA2 (`\x1b[>c`), DSR / CPR (`\x1b[6n`), and OSC 10/11 color queries, eliminating CLI boot delays.
|
|
32
|
+
- **Kitty Keyboard Protocol**: Protocol flag negotiation (`CSI ? u`, `CSI = u`, `CSI > u`, `CSI < u`) enabling disambiguation of modified keystrokes like `Shift+Enter`.
|
|
33
|
+
- **OSC 133 Semantic Prompts**: Shell integration tracking prompt start, command execution, and exit codes, enabling prompt-to-prompt jumping (`Cmd+Up` / `Cmd+Down`).
|
|
34
|
+
- **OSC 8 Hyperlinks**: Clickable URLs with browser launching via `Cmd+Click` or `Ctrl+Click`.
|
|
35
|
+
- **Mouse Tracking**: Normal tracking (`?1000h`) and SGR decimal tracking (`?1006h`) for interactive CLI programs like `vim`, `htop`, and `tmux`.
|
|
36
|
+
- **Primary & Alternate Screen Buffers**: Smooth transitions into and out of full-screen terminal programs without corrupting main scrollback.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Installation & Running
|
|
41
|
+
|
|
42
|
+
Clownfish offers multiple installation channels: native macOS application bundle, Homebrew tap, PyPI package, or source.
|
|
43
|
+
|
|
44
|
+
### Option 1: macOS Application Bundle (`Clownfish.app`)
|
|
45
|
+
|
|
46
|
+
Download the latest release archive from [GitHub Releases](https://github.com/wispsy/clownfish/releases):
|
|
47
|
+
|
|
48
|
+
1. Download `Clownfish-v0.5.0-macos.zip`.
|
|
49
|
+
2. Unzip the archive:
|
|
50
|
+
```bash
|
|
51
|
+
unzip Clownfish-v0.5.0-macos.zip
|
|
52
|
+
```
|
|
53
|
+
3. Move `Clownfish.app` to `/Applications`:
|
|
54
|
+
```bash
|
|
55
|
+
mv Clownfish.app /Applications/
|
|
56
|
+
```
|
|
57
|
+
4. Launch Clownfish from Spotlight, Finder, or from your terminal with `open /Applications/Clownfish.app`.
|
|
58
|
+
|
|
59
|
+
### Option 2: Homebrew Tap (`wispsy/homebrew-tap`)
|
|
60
|
+
|
|
61
|
+
Install Clownfish via the official [Wispsy Homebrew tap](https://github.com/wispsy/homebrew-tap):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# Add the tap
|
|
65
|
+
brew tap wispsy/tap
|
|
66
|
+
|
|
67
|
+
# Install the CLI formula (isolated Python environment)
|
|
68
|
+
brew install clownfish
|
|
69
|
+
|
|
70
|
+
# Or install the standalone macOS GUI application via Cask
|
|
71
|
+
brew install --cask wispsy/tap/clownfish
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Option 3: PyPI Package (`pip` / `uv`)
|
|
75
|
+
|
|
76
|
+
Clownfish is published to PyPI and requires Python 3.14+:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# Using uv (recommended)
|
|
80
|
+
uv tool install clownfish
|
|
81
|
+
|
|
82
|
+
# Or using pip
|
|
83
|
+
pip install clownfish
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Run directly:
|
|
87
|
+
```bash
|
|
88
|
+
clownfish
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Option 4: From Source (Development)
|
|
92
|
+
|
|
93
|
+
Ensure you have Python 3.14+ and [uv](https://docs.astral.sh/uv/) installed.
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
git clone https://github.com/wispsy/clownfish.git
|
|
97
|
+
cd clownfish
|
|
98
|
+
uv sync --all-extras
|
|
99
|
+
uv run clownfish
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
To build the standalone macOS `.app` bundle from source:
|
|
103
|
+
```bash
|
|
104
|
+
uv run --with pyinstaller python scripts/build_macos_app.py
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Testing & Quality Assurance
|
|
110
|
+
|
|
111
|
+
Run the test suite:
|
|
112
|
+
```bash
|
|
113
|
+
uv run pytest
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Run code formatting and linting:
|
|
117
|
+
```bash
|
|
118
|
+
uv run ruff check .
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Documentation
|
|
124
|
+
|
|
125
|
+
- [Architecture Guide](docs/architecture.md): Deep dive into screen buffer management, parser state machine, and render loop.
|
|
126
|
+
- [Modern Terminal Gap Analysis](docs/modern-terminal-gap-analysis.md): Technical analysis of the fundamental features required for modern terminal emulators.
|
|
127
|
+
- [Keyboard & Mouse Shortcuts](docs/shortcuts.md): Guide to shortcuts for clearing buffers, navigation, and clipboard operations.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Project Structure
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
clownfish/
|
|
135
|
+
├── .github/
|
|
136
|
+
│ └── workflows/
|
|
137
|
+
│ ├── ci.yml # GitHub Actions CI workflow (Ubuntu & macOS)
|
|
138
|
+
│ └── release.yaml # Automated PyPI & GitHub Release workflow
|
|
139
|
+
├── assets/
|
|
140
|
+
│ └── Clownfish.icns # Multi-resolution macOS application icon
|
|
141
|
+
├── docs/
|
|
142
|
+
│ ├── architecture.md # Architecture overview & data flow
|
|
143
|
+
│ ├── modern-terminal-gap-analysis.md # Modern terminal specifications
|
|
144
|
+
│ └── shortcuts.md # Keybinding reference
|
|
145
|
+
├── packaging/
|
|
146
|
+
│ └── homebrew/ # Homebrew tap formulas & casks
|
|
147
|
+
│ ├── Casks/
|
|
148
|
+
│ │ └── clownfish.rb
|
|
149
|
+
│ └── Formula/
|
|
150
|
+
│ └── clownfish.rb
|
|
151
|
+
├── scripts/
|
|
152
|
+
│ ├── build_macos_app.py # PyInstaller macOS bundle & zip builder
|
|
153
|
+
│ └── publish_homebrew.py # Homebrew tap release automation
|
|
154
|
+
├── src/
|
|
155
|
+
│ └── clownfish/
|
|
156
|
+
│ ├── __init__.py # Public API exports & launch function
|
|
157
|
+
│ ├── __main__.py # Module entrypoint (python -m clownfish)
|
|
158
|
+
│ ├── config.py # Configuration dataclasses (TerminalConfig)
|
|
159
|
+
│ ├── syntax.py # Syntax highlighting integration
|
|
160
|
+
│ ├── core/ # Core terminal engine
|
|
161
|
+
│ │ ├── models.py # Data models (Cell, Style, Selection, PromptMarker)
|
|
162
|
+
│ │ ├── keyboard.py # Keystroke encoding & Kitty keyboard protocol
|
|
163
|
+
│ │ ├── parser.py # VT100 / ANSI / OSC escape sequence parser
|
|
164
|
+
│ │ ├── screen.py # Screen buffer, dual grid, autowrap & scrollback
|
|
165
|
+
│ │ └── search.py # In-buffer regex & plain text search engine
|
|
166
|
+
│ ├── session/ # Terminal session layer
|
|
167
|
+
│ │ ├── session.py # TerminalSession lifecycle manager
|
|
168
|
+
│ │ └── transport.py # Abstract Transport base class
|
|
169
|
+
│ ├── transports/ # Pluggable I/O transports
|
|
170
|
+
│ │ ├── pty.py # POSIX PTYTransport with write buffering
|
|
171
|
+
│ │ └── ssh.py # SSHTransport via OpenSSH PTY bridge
|
|
172
|
+
│ └── frontends/
|
|
173
|
+
│ └── tkinter/ # Tkinter desktop frontend
|
|
174
|
+
│ ├── app.py # TkTerminalApp main window & menu shortcuts
|
|
175
|
+
│ ├── pane.py # TerminalPane self-contained terminal widget
|
|
176
|
+
│ ├── split.py # SplitView arbitrary nested split pane manager
|
|
177
|
+
│ ├── tabs.py # TabbedTerminalView multi-tab session manager
|
|
178
|
+
│ ├── renderer.py # Canvas text & selection renderer
|
|
179
|
+
│ └── input.py # Pointer & keyboard event translator
|
|
180
|
+
├── tests/ # Comprehensive unit & integration test suite
|
|
181
|
+
├── pyproject.toml # Project metadata & build settings
|
|
182
|
+
└── README.md
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Roadmap
|
|
188
|
+
|
|
189
|
+
- [x] Split-pane multiplexing and tabbed sessions.
|
|
190
|
+
- [x] In-buffer regex / plain text search with highlight overlay.
|
|
191
|
+
- [ ] GPU-accelerated texture atlas rendering via Metal/Vulkan.
|
|
192
|
+
- [ ] HarfBuzz typography shaping for developer font ligatures (`->`, `!=`, `===`).
|
|
193
|
+
- [ ] Kitty Graphics Protocol inline image streaming.
|
|
194
|
+
- [ ] Sixel bitmap rasterization protocol support.
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
This project is licensed under the MIT License.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "clownfish"
|
|
3
|
+
version = "0.5.0"
|
|
4
|
+
description = "A modern terminal emulator written in Python and Tkinter"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.14"
|
|
7
|
+
dependencies = []
|
|
8
|
+
|
|
9
|
+
[[project.authors]]
|
|
10
|
+
name = "ellainng"
|
|
11
|
+
email = "299958882+ellainng@users.noreply.github.com"
|
|
12
|
+
|
|
13
|
+
[project.optional-dependencies]
|
|
14
|
+
syntax = ["escape-colors==0.2.0"]
|
|
15
|
+
dev = [
|
|
16
|
+
"pytest>=8.0.0",
|
|
17
|
+
"ruff>=0.4.0",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[project.scripts]
|
|
21
|
+
clownfish = "clownfish:main"
|
|
22
|
+
|
|
23
|
+
[build-system]
|
|
24
|
+
requires = ["uv_build>=0.13.6,<0.14.0"]
|
|
25
|
+
build-backend = "uv_build"
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
29
|
+
pythonpath = ["src"]
|
|
30
|
+
|
|
31
|
+
[tool.ruff]
|
|
32
|
+
line-length = 100
|
|
33
|
+
target-version = "py314"
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "clownfish"
|
|
3
|
+
version = "0.5.0"
|
|
4
|
+
description = "A modern terminal emulator written in Python and Tkinter"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
|
|
8
|
+
]
|
|
9
|
+
requires-python = ">=3.14"
|
|
10
|
+
dependencies = []
|
|
11
|
+
|
|
12
|
+
[project.optional-dependencies]
|
|
13
|
+
syntax = [
|
|
14
|
+
"escape-colors==0.2.0",
|
|
15
|
+
]
|
|
16
|
+
dev = [
|
|
17
|
+
"pytest>=8.0.0",
|
|
18
|
+
"ruff>=0.4.0",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
[project.scripts]
|
|
22
|
+
clownfish = "clownfish:main"
|
|
23
|
+
|
|
24
|
+
[build-system]
|
|
25
|
+
requires = ["uv_build>=0.13.6,<0.14.0"]
|
|
26
|
+
build-backend = "uv_build"
|
|
27
|
+
|
|
28
|
+
[tool.pytest.ini_options]
|
|
29
|
+
testpaths = ["tests"]
|
|
30
|
+
pythonpath = ["src"]
|
|
31
|
+
|
|
32
|
+
[tool.ruff]
|
|
33
|
+
line-length = 100
|
|
34
|
+
target-version = "py314"
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
"""clownfish - A modern terminal emulator written in Python and Tkinter."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typing import TYPE_CHECKING, Any
|
|
5
|
+
|
|
6
|
+
from clownfish.config import TerminalConfig
|
|
7
|
+
from clownfish.core.keyboard import encode_key_press, encode_kitty_key
|
|
8
|
+
from clownfish.core.models import (
|
|
9
|
+
Cell,
|
|
10
|
+
PromptMarker,
|
|
11
|
+
Selection,
|
|
12
|
+
Style,
|
|
13
|
+
char_width,
|
|
14
|
+
)
|
|
15
|
+
from clownfish.core.parser import VT100Parser
|
|
16
|
+
from clownfish.core.screen import ScreenBuffer
|
|
17
|
+
from clownfish.core.search import SearchMatch, SearchState, search_screen
|
|
18
|
+
from clownfish.session.session import TerminalSession
|
|
19
|
+
from clownfish.session.transport import Transport
|
|
20
|
+
from clownfish.syntax import highlight_code, is_syntax_available, print_highlighted
|
|
21
|
+
|
|
22
|
+
if TYPE_CHECKING:
|
|
23
|
+
from clownfish.frontends.tkinter.app import TkTerminalApp
|
|
24
|
+
from clownfish.frontends.tkinter.pane import TerminalPane
|
|
25
|
+
from clownfish.frontends.tkinter.split import SplitView
|
|
26
|
+
from clownfish.frontends.tkinter.tabs import TabbedTerminalView
|
|
27
|
+
from clownfish.transports.pty import PTYTransport
|
|
28
|
+
from clownfish.transports.ssh import SSHTransport
|
|
29
|
+
|
|
30
|
+
__version__ = "0.5.0"
|
|
31
|
+
__all__ = [
|
|
32
|
+
"Cell",
|
|
33
|
+
"PTYTransport",
|
|
34
|
+
"PromptMarker",
|
|
35
|
+
"SSHTransport",
|
|
36
|
+
"ScreenBuffer",
|
|
37
|
+
"SearchMatch",
|
|
38
|
+
"SearchState",
|
|
39
|
+
"Selection",
|
|
40
|
+
"SplitView",
|
|
41
|
+
"Style",
|
|
42
|
+
"TabbedTerminalView",
|
|
43
|
+
"TerminalConfig",
|
|
44
|
+
"TerminalPane",
|
|
45
|
+
"TerminalSession",
|
|
46
|
+
"TkTerminalApp",
|
|
47
|
+
"Transport",
|
|
48
|
+
"VT100Parser",
|
|
49
|
+
"char_width",
|
|
50
|
+
"encode_key_press",
|
|
51
|
+
"encode_kitty_key",
|
|
52
|
+
"highlight_code",
|
|
53
|
+
"is_syntax_available",
|
|
54
|
+
"main",
|
|
55
|
+
"print_highlighted",
|
|
56
|
+
"search_screen",
|
|
57
|
+
]
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def __getattr__(name: str) -> Any:
|
|
61
|
+
if name == "TkTerminalApp":
|
|
62
|
+
from clownfish.frontends.tkinter.app import TkTerminalApp
|
|
63
|
+
|
|
64
|
+
return TkTerminalApp
|
|
65
|
+
if name == "TerminalPane":
|
|
66
|
+
from clownfish.frontends.tkinter.pane import TerminalPane
|
|
67
|
+
|
|
68
|
+
return TerminalPane
|
|
69
|
+
if name == "SplitView":
|
|
70
|
+
from clownfish.frontends.tkinter.split import SplitView
|
|
71
|
+
|
|
72
|
+
return SplitView
|
|
73
|
+
if name == "TabbedTerminalView":
|
|
74
|
+
from clownfish.frontends.tkinter.tabs import TabbedTerminalView
|
|
75
|
+
|
|
76
|
+
return TabbedTerminalView
|
|
77
|
+
if name == "PTYTransport":
|
|
78
|
+
from clownfish.transports.pty import PTYTransport
|
|
79
|
+
|
|
80
|
+
return PTYTransport
|
|
81
|
+
if name == "SSHTransport":
|
|
82
|
+
from clownfish.transports.ssh import SSHTransport
|
|
83
|
+
|
|
84
|
+
return SSHTransport
|
|
85
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def main(args: list[str] | None = None) -> None:
|
|
89
|
+
"""Launch clownfish terminal emulator."""
|
|
90
|
+
import sys
|
|
91
|
+
|
|
92
|
+
argv = args if args is not None else sys.argv[1:]
|
|
93
|
+
if argv and argv[0] == "--pty-trampoline":
|
|
94
|
+
import fcntl
|
|
95
|
+
import os
|
|
96
|
+
import termios
|
|
97
|
+
|
|
98
|
+
try:
|
|
99
|
+
fcntl.ioctl(0, termios.TIOCSCTTY, 0)
|
|
100
|
+
except OSError:
|
|
101
|
+
pass
|
|
102
|
+
os.execvp(argv[1], argv[1:])
|
|
103
|
+
return
|
|
104
|
+
|
|
105
|
+
if argv and argv[0] in ("-v", "--version"):
|
|
106
|
+
print(f"clownfish {__version__}")
|
|
107
|
+
return
|
|
108
|
+
|
|
109
|
+
if argv and argv[0] in ("-h", "--help"):
|
|
110
|
+
print(f"clownfish {__version__} - A modern terminal emulator written in Python and Tkinter")
|
|
111
|
+
print("\nUsage:\n clownfish [options]")
|
|
112
|
+
print("\nOptions:\n -v, --version Show version number and exit")
|
|
113
|
+
print(" -h, --help Show this help message and exit")
|
|
114
|
+
return
|
|
115
|
+
|
|
116
|
+
import tkinter as tk
|
|
117
|
+
|
|
118
|
+
from clownfish.frontends.tkinter.app import TkTerminalApp
|
|
119
|
+
|
|
120
|
+
root = tk.Tk()
|
|
121
|
+
root.title("clownfish")
|
|
122
|
+
|
|
123
|
+
icon_path = Path(__file__).resolve().parent / "clownfish.png"
|
|
124
|
+
if icon_path.exists():
|
|
125
|
+
try:
|
|
126
|
+
app_icon = tk.PhotoImage(file=str(icon_path))
|
|
127
|
+
root.iconphoto(True, app_icon)
|
|
128
|
+
except (tk.TclError, OSError):
|
|
129
|
+
pass
|
|
130
|
+
|
|
131
|
+
_ = TkTerminalApp(root, cols=80, rows=24)
|
|
132
|
+
root.mainloop()
|
|
Binary file
|