|
1 | | -# FastTerminal — Technical Roadmap & TODO List |
2 | | - |
3 | | -This document acts as our development roadmap and architectural design system for building a zero-dependency, ultra-fast, true-color, and emoji-enabled terminal rendering engine for Java. |
4 | | - |
5 | | ---- |
6 | | - |
7 | | -## 🛠️ Part 1: Current Bugs & Architectural Fixes |
8 | | -Below are the analyzed flaws of the initial implementation and how we will resolve them. |
9 | | - |
10 | | -### 1. `TerminalScene` — Dirty-Flag Semantics |
11 | | -* **❌ The Bug**: `update()` sets `dirty = true`, but `render()` immediately clears it to `false`. This causes scenes to render only when external log events fire, while any background animations (like a title spinner or real-time ticker) freeze. |
12 | | -* **✔ The Fix**: `update()` must *not* set `dirty = true`. The `dirty` state indicates whether the renderer needs to pull changes, not that the scene has just re-calculated itself. |
13 | | - ```java |
14 | | - public void update() { |
15 | | - if (this.updater != null) { |
16 | | - this.clear(); |
17 | | - this.updater.run(); |
18 | | - // REMOVE: this.dirty = true; |
19 | | - } |
20 | | - } |
21 | | - ``` |
22 | | - Dirty propagation will be triggered externally via timers, keypresses, or callbacks. |
23 | | - |
24 | | -### 2. CLILogger / Renderers — Buffer Overwrite |
25 | | -* **❌ The Bug**: When updating a line of text in the character buffer, if the new line is shorter than the old one, the trailing characters from the old line remain visible. |
26 | | -* **✔ The Fix**: Prior to drawing new content to a line in a text buffer, fill the line range with empty space characters: |
27 | | - ```java |
28 | | - Arrays.fill(buffer, bufferStart, bufferStart + this.getWidth(), ' '); |
29 | | - ``` |
30 | | - |
31 | | -### 3. `TerminalRenderer` — Composite Buffer Lifecycle |
32 | | -* **❌ The Bug**: `TerminalRenderer` does a `System.arraycopy(...)` but never clears the `compositeBuffer` between frames, resulting in ghost characters and rendering artifacts. |
33 | | -* **✔ The Fix**: Clear the entire `compositeBuffer` with spaces at the beginning of each `render()` pass. |
34 | | - ```java |
35 | | - public void render() { |
36 | | - this.clear(); // Clear before painting |
37 | | - System.out.print("\033[1;1H"); |
38 | | - ... |
39 | | - } |
40 | | - ``` |
41 | | - |
42 | | -### 4. `TerminalRenderer` — Alternate Screen & Cursor Resets |
43 | | -* **❌ The Bug**: Cursor reset via `\033[1;1H` works, but without clearing the screen or using an alternate buffer, artifacts persist in unused space. |
44 | | -* **✔ The Fix**: Use alternate screen buffer ANSI sequences (`\033[?1049h`) to take over the terminal in full-screen mode, hide the cursor (`\033[?25l`), and properly clear the viewport. |
45 | | - |
46 | | -### 5. `CLIScene` — Resize-Handling & Listener Leaks |
47 | | -* **❌ The Bug**: Re-adding scenes and listeners on resize causes potential race-conditions and memory leaks if listeners are not cleanly detached beforehand. |
48 | | -* **✔ The Fix**: Securely detach and clean up listeners before any recreation occurs: |
49 | | - ```java |
50 | | - Log.removeListener(logListener); |
51 | | - ``` |
52 | | - |
53 | | -### 6. `TerminalScene.dispose()` Null-Safety |
54 | | -* **❌ The Bug**: Setting `charBuffer = null` inside `dispose()` results in a immediate `NullPointerException` if `insertScene()` is invoked right after. |
55 | | -* **✔ The Fix**: Establish rigorous state checks and ensure scenes are removed from the active renderer list during cleanup. |
56 | | - |
57 | | ---- |
58 | | - |
59 | | -## 🚀 Part 2: The Path to Independence, Speed, & True Color |
60 | | -We are focusing on direct OS native hooks to achieve zero latency, full UTF-8 capabilities, alternate screen buffers, and high-performance JNI integration. |
61 | | - |
62 | | -### 📋 1. Zero-Dependency Dimension Queries |
63 | | -* **Terminal Dimensions**: Retrieve screen buffer info natively using `GetConsoleScreenBufferInfo` on Windows (via JNI) and `ioctl(TIOCGWINSZ)` on Linux/macOS. |
64 | | -* **Keyboard Input**: Integrate directly with `FastKeyboard` to handle asynchronous raw mode input. |
65 | | -* **Console Raw Mode**: Toggle echo and raw modes directly using native JNI calls: |
66 | | - * **Windows**: `SetConsoleMode(hIn, ENABLE_WINDOW_INPUT | ENABLE_MOUSE_INPUT)` |
67 | | - * **Linux**: `tcsetattr` |
68 | | - |
69 | | -### 🎨 2. True Color (24-bit RGB) Support |
70 | | -Instead of being limited to 16 basic colors, we will support full 24-bit True Color using standard ANSI escape codes: |
71 | | -* **Foreground Color**: `\033[38;2;R;G;Bm` |
72 | | -* **Background Color**: `\033[48;2;R;G;Bm` |
73 | | -* *Example*: `System.out.print("\033[38;2;255;120;0mHello 24-bit Orange!\033[0m");` |
74 | | - |
75 | | -### 🌐 3. Full Emoji & Unicode Support (Codepoints) |
76 | | -Standard Java `char` values are UTF-16, meaning emojis occupy 2 or 4 chars. If we do standard character-by-character length checking, emojis break and warp lines. |
77 | | -* **✔ Solution**: Transition our internal text representation and buffer arrays from `char[]` to **Codepoint-based arrays (`int[]`)** or UTF-8 byte streams. |
78 | | - |
79 | | -### ⚡ 4. Alternate Screen Buffer & WriteConsoleOutputW |
80 | | -To achieve game-like performance (60–120 FPS): |
81 | | -* **ANSI Fullscreen (Alternate Screen Buffer)**: |
82 | | - * `\033[?1049h` — Enter alternate screen buffer (hides existing terminal prompt history). |
83 | | - * `\033[?25l` — Hide cursor. |
84 | | - * `\033[?1049l` — Exit alternate screen buffer (restores prompt context). |
85 | | -* **Windows JNI Fast-Path (`WriteConsoleOutputW`)**: |
86 | | - * Instead of converting buffers to Java strings and printing to `System.out`, we will use the native Windows console API `WriteConsoleOutputW`. This allows copying our entire double-buffered grid directly to the console hardware buffer in a single native call, yielding 10x-20x higher throughput. |
87 | | - |
88 | | -### 📥 5. Dynamic Progress Bars (apt / curl style) |
89 | | -For downloads, installers, and live pipelines, we will implement dynamic bottom-anchored multiline progress indicators using ANSI cursor preservation: |
90 | | -* `\033[s` — Save cursor position. |
91 | | -* `\033[row;colH` — Move to progress bar row. |
92 | | -* `\033[2K` — Clear current line. |
93 | | -* Update live progress (True Color + Emojis). |
94 | | -* `\033[u` — Restore cursor to original position for seamless logging. |
95 | | - |
96 | | ---- |
97 | | - |
98 | | -## 🏗️ Part 3: Architecture & Class Structure |
99 | | - |
100 | | -Our unified `FastTerminal` module will have a streamlined, modular layout: |
101 | | - |
102 | | -``` |
103 | | -FastTerminal |
104 | | - ├── FastTerminalNative (JNI wrapper) |
105 | | - │ ├── getTerminalSize() --> returns [cols, rows] |
106 | | - │ ├── setRawMode(boolean active) --> configures terminal flags |
107 | | - │ └── writeConsoleOutput(...) --> Windows Console API direct blit |
108 | | - ├── FastTerminalRenderer |
109 | | - │ ├── frontBuffer (int[] codepoints) |
110 | | - │ ├── backBuffer (int[] codepoints) |
111 | | - │ ├── diff() --> compares buffers for minimum writes |
112 | | - │ └── render() --> outputs changes |
113 | | - └── FastTerminalScene |
114 | | - ├── update() |
115 | | - └── draw() |
116 | | -``` |
117 | | -
|
118 | | ---- |
119 | | -
|
120 | | -## 📝 TODO Checklist |
121 | | -
|
122 | | -### Phase 1: Cleanup & Restructuring |
123 | | -* [ ] Remove legacy demo files (`CLILogger.java`, `CLITitle.java`). |
124 | | -* [ ] Move core terminal classes (`TerminalRenderer.java`, `TerminalScene.java`, `CLIScene.java`) into the new Mavenized project package (`fastterminal`). |
125 | | -* [ ] Refactor Maven `pom.xml` to include `FastCore` dependency and target Java 17+. |
126 | | -
|
127 | | -### Phase 2: Native JNI Core |
128 | | -* [ ] Implement native C++ functions in `native/` for `GetConsoleScreenBufferInfo` and console mode setup. |
129 | | -* [ ] Integrate JNI bindings in `FastTerminalNative.java` to allow querying terminal dimensions dynamically. |
130 | | -* [ ] Build compilation script (`compile.bat`) aligned with Java 17+ and MSVC compiler. |
131 | | -
|
132 | | -### Phase 3: Codepoints & True Color |
133 | | -* [ ] Refactor `TerminalScene` buffer representation to use `int[]` for safe UTF-32/Unicode Codepoint handling. |
134 | | -* [ ] Build high-level True Color formatting builders for foreground and background. |
135 | | -* [ ] Implement Double Buffering logic in `TerminalRenderer` to support diff-based ANSI rendering. |
136 | | -
|
137 | | -### Phase 4: Dynamic Views & Demos |
138 | | -* [ ] Create a standalone demo displaying high-refresh rate live widgets, true-color patterns, and emojis. |
139 | | -* [ ] Create a curl/npm-like progress bar demonstration that updates the bottom of the screen dynamically while terminal logs print above. |
| 1 | +# FastTerminal TODO |
| 2 | + |
| 3 | +Hier ist die trockene, tabellarische Übersicht — ohne Deko, ohne Ausschweifen: |
| 4 | + |
| 5 | +| Bereich | Was man machen könnte | |
| 6 | +| :--- | :--- | |
| 7 | +| **Rendering** | Diff-Rendering, Dirty-Rectangles, Double-Buffering, Partial Flush | |
| 8 | +| **Input** | Maus-Events, Key-Events, Modifier-Keys, Drag‑Tracking | |
| 9 | +| **Layout** | Flex-Layout, Grid-Layout, Anchors, Auto-Resize | |
| 10 | +| **Widgets** | Buttons, Panels, Textbox, Scrollview, Progressbar | |
| 11 | +| **Text** | UTF‑8 Parser, Emoji Width Fixes, Word-Wrap, Text-Shaping | |
| 12 | +| **Color** | 24‑bit Gradients, Paletten, Themes, Alpha‑Compositing | |
| 13 | +| **Performance** | SIMD‑Blitting, Native Line‑Drawing, GPU‑Terminal‑Mode (optional) | |
| 14 | +| **Scenes** | Z‑Index, Layer-Masking, Offscreen Buffers, Transitions | |
| 15 | +| **Animation** | Timelines, Easing, Keyframes, Sprite‑Sheets | |
| 16 | +| **System** | Resize‑Events, Raw‑Mode‑Manager, Cross‑Platform Backend | |
| 17 | +| **Debug** | FPS‑Overlay, Memory‑Overlay, Scene‑Inspector | |
0 commit comments