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.
Files changed (34) hide show
  1. clownfish-0.5.0/PKG-INFO +214 -0
  2. clownfish-0.5.0/README.md +200 -0
  3. clownfish-0.5.0/pyproject.toml +33 -0
  4. clownfish-0.5.0/pyproject.toml.orig +34 -0
  5. clownfish-0.5.0/src/clownfish/__init__.py +132 -0
  6. clownfish-0.5.0/src/clownfish/__main__.py +6 -0
  7. clownfish-0.5.0/src/clownfish/app.py +5 -0
  8. clownfish-0.5.0/src/clownfish/clownfish.png +0 -0
  9. clownfish-0.5.0/src/clownfish/config.py +84 -0
  10. clownfish-0.5.0/src/clownfish/core/__init__.py +34 -0
  11. clownfish-0.5.0/src/clownfish/core/keyboard.py +197 -0
  12. clownfish-0.5.0/src/clownfish/core/models.py +122 -0
  13. clownfish-0.5.0/src/clownfish/core/parser.py +461 -0
  14. clownfish-0.5.0/src/clownfish/core/screen.py +719 -0
  15. clownfish-0.5.0/src/clownfish/core/search.py +153 -0
  16. clownfish-0.5.0/src/clownfish/frontends/__init__.py +1 -0
  17. clownfish-0.5.0/src/clownfish/frontends/tkinter/__init__.py +17 -0
  18. clownfish-0.5.0/src/clownfish/frontends/tkinter/app.py +344 -0
  19. clownfish-0.5.0/src/clownfish/frontends/tkinter/input.py +214 -0
  20. clownfish-0.5.0/src/clownfish/frontends/tkinter/pane.py +390 -0
  21. clownfish-0.5.0/src/clownfish/frontends/tkinter/renderer.py +223 -0
  22. clownfish-0.5.0/src/clownfish/frontends/tkinter/split.py +261 -0
  23. clownfish-0.5.0/src/clownfish/frontends/tkinter/tabs.py +217 -0
  24. clownfish-0.5.0/src/clownfish/main.py +6 -0
  25. clownfish-0.5.0/src/clownfish/models.py +25 -0
  26. clownfish-0.5.0/src/clownfish/parser.py +5 -0
  27. clownfish-0.5.0/src/clownfish/screen.py +5 -0
  28. clownfish-0.5.0/src/clownfish/session/__init__.py +15 -0
  29. clownfish-0.5.0/src/clownfish/session/session.py +294 -0
  30. clownfish-0.5.0/src/clownfish/session/transport.py +53 -0
  31. clownfish-0.5.0/src/clownfish/syntax.py +42 -0
  32. clownfish-0.5.0/src/clownfish/transports/__init__.py +6 -0
  33. clownfish-0.5.0/src/clownfish/transports/pty.py +243 -0
  34. clownfish-0.5.0/src/clownfish/transports/ssh.py +53 -0
@@ -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
+ [![CI](https://github.com/wispsy/clownfish/actions/workflows/ci.yml/badge.svg)](https://github.com/wispsy/clownfish/actions/workflows/ci.yml)
18
+ [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
19
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+ [![CI](https://github.com/wispsy/clownfish/actions/workflows/ci.yml/badge.svg)](https://github.com/wispsy/clownfish/actions/workflows/ci.yml)
4
+ [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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()
@@ -0,0 +1,6 @@
1
+ """Entrypoint for python -m clownfish."""
2
+
3
+ from clownfish import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -0,0 +1,5 @@
1
+ """Tkinter application (legacy import path)."""
2
+
3
+ from clownfish.frontends.tkinter.app import TkTerminalApp
4
+
5
+ __all__ = ["TkTerminalApp"]