pi-startup-redraw-fix 0.1.1 → 0.1.3
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.
- package/CHANGELOG.md +11 -0
- package/README.md +80 -66
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.1.3] - 2026-03-04
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
- Use absolute GitHub raw URL for README image to fix npm display
|
|
7
|
+
|
|
8
|
+
## [0.1.2] - 2026-03-04
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- Rewrote README.md with professional documentation standards
|
|
12
|
+
- Added comprehensive feature documentation, configuration reference, and usage examples
|
|
13
|
+
|
|
3
14
|
## 0.1.1
|
|
4
15
|
|
|
5
16
|
- Added `asset/` to the npm `files` whitelist so README image assets are included in package tarballs.
|
package/README.md
CHANGED
|
@@ -1,63 +1,74 @@
|
|
|
1
1
|
# pi-startup-redraw-fix
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Table of Contents
|
|
8
|
+
|
|
9
|
+
- [Features](#features)
|
|
10
|
+
- [Installation](#installation)
|
|
11
|
+
- [Usage](#usage)
|
|
12
|
+
- [Configuration](#configuration)
|
|
13
|
+
- [Technical Details](#technical-details)
|
|
14
|
+
- [Troubleshooting](#troubleshooting)
|
|
15
|
+
- [Development](#development)
|
|
16
|
+
- [License](#license)
|
|
8
17
|
|
|
9
18
|
## Features
|
|
10
19
|
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- Applies the patch **once per Node process** by monkey-patching `ProcessTerminal.prototype.write`.
|
|
15
|
-
- On `session_start`, shows a **UI warning** (when UI is available) if patching failed.
|
|
20
|
+
- **Escape Sequence Normalization** — Reorders the startup full-clear sequence from `\x1b[3J\x1b[2J\x1b[H` to `\x1b[H\x1b[2J\x1b[3J` for stable screen clearing
|
|
21
|
+
- **Idempotent Patching** — Applies the patch once per Node process via `ProcessTerminal.prototype.write` monkey-patching with internal flag guard
|
|
22
|
+
- **Failure Notifications** — Displays a UI warning on `session_start` if the patch failed to apply
|
|
16
23
|
|
|
17
24
|
## Installation
|
|
18
25
|
|
|
19
|
-
###
|
|
26
|
+
### Extension Folder (Recommended)
|
|
20
27
|
|
|
21
|
-
Place
|
|
28
|
+
Place the extension folder in one of Pi's auto-discovered extension locations:
|
|
22
29
|
|
|
23
|
-
|
|
24
|
-
|
|
30
|
+
| Location | Path |
|
|
31
|
+
|----------|------|
|
|
32
|
+
| Global | `~/.pi/agent/extensions/pi-startup-redraw-fix` |
|
|
33
|
+
| Project | `.pi/extensions/pi-startup-redraw-fix` |
|
|
25
34
|
|
|
26
|
-
|
|
35
|
+
Alternatively, add the path to your Pi settings `extensions` array.
|
|
27
36
|
|
|
28
|
-
###
|
|
37
|
+
### npm Package
|
|
29
38
|
|
|
30
39
|
```bash
|
|
31
40
|
pi install npm:pi-startup-redraw-fix
|
|
32
41
|
```
|
|
33
42
|
|
|
34
|
-
|
|
43
|
+
### Git Repository
|
|
35
44
|
|
|
36
45
|
```bash
|
|
37
46
|
pi install git:github.com/MasuRii/pi-startup-redraw-fix
|
|
38
47
|
```
|
|
39
48
|
|
|
40
|
-
(For development or non-Pi environments, `npm i pi-startup-redraw-fix` also works.)
|
|
41
|
-
|
|
42
49
|
## Usage
|
|
43
50
|
|
|
44
|
-
This extension
|
|
51
|
+
This extension operates automatically with **no commands required**.
|
|
45
52
|
|
|
46
|
-
When the extension
|
|
53
|
+
When loaded, the extension immediately patches `ProcessTerminal.prototype.write` to intercept and normalize terminal clear sequences. If the patch fails, a warning notification appears at each session start (when UI is available).
|
|
47
54
|
|
|
48
55
|
## Configuration
|
|
49
56
|
|
|
50
|
-
|
|
57
|
+
Configuration is stored at `config.json` alongside the extension:
|
|
51
58
|
|
|
52
|
-
|
|
59
|
+
```
|
|
60
|
+
~/.pi/agent/extensions/pi-startup-redraw-fix/config.json
|
|
61
|
+
```
|
|
53
62
|
|
|
54
|
-
|
|
63
|
+
A template is provided at `config/config.example.json`.
|
|
55
64
|
|
|
56
|
-
|
|
65
|
+
### Options
|
|
57
66
|
|
|
58
|
-
|
|
67
|
+
| Option | Type | Default | Description |
|
|
68
|
+
|--------|------|---------|-------------|
|
|
69
|
+
| `enabled` | boolean | `true` | Enable or disable the extension |
|
|
59
70
|
|
|
60
|
-
|
|
71
|
+
### Example Configuration
|
|
61
72
|
|
|
62
73
|
```json
|
|
63
74
|
{
|
|
@@ -65,74 +76,77 @@ Minimal config:
|
|
|
65
76
|
}
|
|
66
77
|
```
|
|
67
78
|
|
|
68
|
-
|
|
79
|
+
> **Note:** If your Pi build does not honor the `enabled` flag, disable the extension by removing it from your Pi settings `extensions` list or uninstalling it.
|
|
69
80
|
|
|
70
|
-
|
|
71
|
-
- If your Pi build does not use `enabled` for extension loading, disable by removing the extension from your Pi settings `extensions` list (or by uninstalling it).
|
|
81
|
+
## Technical Details
|
|
72
82
|
|
|
73
|
-
|
|
83
|
+
### How It Works
|
|
74
84
|
|
|
75
|
-
Pi
|
|
85
|
+
Pi's TUI uses `@mariozechner/pi-tui`'s `ProcessTerminal` class to write escape sequences to the terminal. This extension wraps `ProcessTerminal.prototype.write` to normalize the clear sequence order:
|
|
76
86
|
|
|
77
|
-
|
|
87
|
+
| Original Sequence | Fixed Sequence |
|
|
88
|
+
|-------------------|----------------|
|
|
89
|
+
| `ESC[3J` (clear scrollback) | `ESC[H` (cursor home) |
|
|
90
|
+
| `ESC[2J` (clear screen) | `ESC[2J` (clear screen) |
|
|
91
|
+
| `ESC[H` (cursor home) | `ESC[3J` (clear scrollback) |
|
|
78
92
|
|
|
79
|
-
|
|
80
|
-
2. For each write, replaces any occurrence of the exact “broken” full-clear sequence:
|
|
81
|
-
- `ESC [ 3 J` (clear scrollback)
|
|
82
|
-
- `ESC [ 2 J` (clear screen)
|
|
83
|
-
- `ESC [ H` (cursor home)
|
|
84
|
-
3. With the “fixed” order:
|
|
85
|
-
- `ESC [ H` (cursor home)
|
|
86
|
-
- `ESC [ 2 J` (clear screen)
|
|
87
|
-
- `ESC [ 3 J` (clear scrollback)
|
|
93
|
+
The reordering ensures the cursor moves home before clearing, which resolves redraw glitches on certain terminal emulators.
|
|
88
94
|
|
|
89
|
-
|
|
95
|
+
### Architecture
|
|
90
96
|
|
|
91
|
-
|
|
97
|
+
| File | Purpose |
|
|
98
|
+
|------|---------|
|
|
99
|
+
| `index.ts` | Root entrypoint for Pi auto-discovery |
|
|
100
|
+
| `src/index.ts` | Extension bootstrap and session warning handler |
|
|
101
|
+
| `src/terminal-clear-patch.ts` | Monkey-patch implementation with idempotency guard |
|
|
102
|
+
| `src/normalize-clear-sequence.ts` | String replacement utility |
|
|
103
|
+
| `src/constants.ts` | Escape sequence definitions |
|
|
92
104
|
|
|
93
|
-
|
|
94
|
-
- Only rewrites the **exact** byte sequence `\x1b[3J\x1b[2J\x1b[H`.
|
|
95
|
-
- If your terminal redraw issue is caused by different escape sequences, this extension will not help.
|
|
96
|
-
- If `ProcessTerminal.write` is not available (or the underlying API changes), the patch will fail and you’ll see a warning on `session_start` (when UI is available).
|
|
105
|
+
### Limitations
|
|
97
106
|
|
|
98
|
-
|
|
107
|
+
- Only affects data written via `ProcessTerminal.prototype.write`
|
|
108
|
+
- Only rewrites the exact byte sequence `\x1b[3J\x1b[2J\x1b[H`
|
|
109
|
+
- Will not help if redraw issues are caused by different escape sequences
|
|
110
|
+
- Patch fails if `ProcessTerminal.write` is unavailable or the API changes
|
|
99
111
|
|
|
100
|
-
|
|
112
|
+
## Troubleshooting
|
|
101
113
|
|
|
102
|
-
|
|
114
|
+
### Warning: "failed to patch terminal clear sequence …"
|
|
103
115
|
|
|
104
|
-
|
|
105
|
-
- the extension could not patch `ProcessTerminal.prototype.write`.
|
|
116
|
+
This warning appears on `session_start` when the extension cannot patch `ProcessTerminal.prototype.write`.
|
|
106
117
|
|
|
107
|
-
|
|
118
|
+
**Possible Causes:**
|
|
108
119
|
|
|
109
|
-
- Incompatible Pi
|
|
110
|
-
- Another extension
|
|
120
|
+
- Incompatible Pi or `@mariozechner/pi-tui` version where `ProcessTerminal.write` is missing or changed
|
|
121
|
+
- Another extension modified the terminal layer unexpectedly
|
|
111
122
|
|
|
112
|
-
|
|
123
|
+
**Solutions:**
|
|
113
124
|
|
|
114
|
-
1. Update Pi and
|
|
115
|
-
2. Temporarily disable other terminal/TUI-related extensions to identify conflicts
|
|
116
|
-
3. Verify the extension is
|
|
125
|
+
1. Update Pi and all extensions to latest versions
|
|
126
|
+
2. Temporarily disable other terminal/TUI-related extensions to identify conflicts
|
|
127
|
+
3. Verify the extension is loaded from an auto-discovery folder or referenced in Pi settings
|
|
117
128
|
|
|
118
129
|
## Development
|
|
119
130
|
|
|
120
131
|
```bash
|
|
132
|
+
# Build TypeScript
|
|
121
133
|
npm run build
|
|
134
|
+
|
|
135
|
+
# Run linter
|
|
122
136
|
npm run lint
|
|
137
|
+
|
|
138
|
+
# Run tests
|
|
123
139
|
npm run test
|
|
140
|
+
|
|
141
|
+
# Run all checks
|
|
124
142
|
npm run check
|
|
125
143
|
```
|
|
126
144
|
|
|
127
|
-
|
|
145
|
+
### Requirements
|
|
128
146
|
|
|
129
|
-
-
|
|
130
|
-
-
|
|
131
|
-
- `src/terminal-clear-patch.ts` — `ProcessTerminal.prototype.write` monkey-patch + idempotency guard
|
|
132
|
-
- `src/normalize-clear-sequence.ts` — string rewrite helper
|
|
133
|
-
- `src/constants.ts` — escape sequence constants
|
|
134
|
-
- `config/config.example.json` — starter config template
|
|
147
|
+
- Node.js ≥ 20
|
|
148
|
+
- Peer dependencies: `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`
|
|
135
149
|
|
|
136
150
|
## License
|
|
137
151
|
|
|
138
|
-
MIT
|
|
152
|
+
[MIT](LICENSE)
|