pi-startup-redraw-fix 0.1.6 → 0.1.8
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 +20 -2
- package/README.md +161 -152
- package/package.json +64 -58
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.8] - 2026-04-22
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
- Clarified README installation and configuration paths to document the default global extension location and `PI_CODING_AGENT_DIR` override behavior
|
|
14
|
+
- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.68.1
|
|
15
|
+
|
|
16
|
+
## [0.1.7] - 2026-04-01
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
- Updated npm keywords and package metadata for improved discoverability
|
|
20
|
+
|
|
3
21
|
## [0.1.6] - 2026-04-01
|
|
4
22
|
|
|
5
23
|
### Changed
|
|
@@ -26,12 +44,12 @@
|
|
|
26
44
|
- Rewrote README.md with professional documentation standards
|
|
27
45
|
- Added comprehensive feature documentation, configuration reference, and usage examples
|
|
28
46
|
|
|
29
|
-
## 0.1.1
|
|
47
|
+
## [0.1.1] - 2026-03-02
|
|
30
48
|
|
|
31
49
|
- Added `asset/` to the npm `files` whitelist so README image assets are included in package tarballs.
|
|
32
50
|
- Bumped patch version for republish.
|
|
33
51
|
|
|
34
|
-
## 0.1.0
|
|
52
|
+
## [0.1.0] - 2026-03-02
|
|
35
53
|
|
|
36
54
|
- Standardized repository structure with `src/` layout and root shim entrypoint.
|
|
37
55
|
- Kept terminal clear-sequence patch behavior unchanged.
|
package/README.md
CHANGED
|
@@ -1,152 +1,161 @@
|
|
|
1
|
-
# pi-startup-redraw-fix
|
|
2
|
-
|
|
3
|
-
A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
- [
|
|
11
|
-
- [
|
|
12
|
-
- [
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
- **
|
|
22
|
-
- **
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
|
90
|
-
|
|
91
|
-
| `ESC[
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
|
100
|
-
|
|
101
|
-
| `
|
|
102
|
-
| `src/
|
|
103
|
-
| `src/
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
1
|
+
# pi-startup-redraw-fix
|
|
2
|
+
|
|
3
|
+
A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.
|
|
4
|
+
|
|
5
|
+
<img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/05bfd443-052c-475e-bc80-3350cde5c642" />
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## Table of Contents
|
|
9
|
+
|
|
10
|
+
- [Features](#features)
|
|
11
|
+
- [Installation](#installation)
|
|
12
|
+
- [Usage](#usage)
|
|
13
|
+
- [Configuration](#configuration)
|
|
14
|
+
- [Technical Details](#technical-details)
|
|
15
|
+
- [Troubleshooting](#troubleshooting)
|
|
16
|
+
- [Development](#development)
|
|
17
|
+
- [License](#license)
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- **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
|
|
22
|
+
- **Idempotent Patching** — Applies the patch once per Node process via `ProcessTerminal.prototype.write` monkey-patching with internal flag guard
|
|
23
|
+
- **Failure Notifications** — Displays a UI warning on `session_start` if the patch failed to apply
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
### Extension Folder (Recommended)
|
|
28
|
+
|
|
29
|
+
Place the extension folder in one of Pi's auto-discovered extension locations:
|
|
30
|
+
|
|
31
|
+
| Location | Path |
|
|
32
|
+
|----------|------|
|
|
33
|
+
| Global default | `~/.pi/agent/extensions/pi-startup-redraw-fix` (respects `PI_CODING_AGENT_DIR`) |
|
|
34
|
+
| Project | `.pi/extensions/pi-startup-redraw-fix` |
|
|
35
|
+
|
|
36
|
+
Alternatively, add the path to your Pi settings `extensions` array.
|
|
37
|
+
|
|
38
|
+
### npm Package
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pi install npm:pi-startup-redraw-fix
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Git Repository
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pi install git:github.com/MasuRii/pi-startup-redraw-fix
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
This extension operates automatically with **no commands required**.
|
|
53
|
+
|
|
54
|
+
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).
|
|
55
|
+
|
|
56
|
+
## Configuration
|
|
57
|
+
|
|
58
|
+
Configuration is stored at `config.json` alongside the extension:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
Default global path: ~/.pi/agent/extensions/pi-startup-redraw-fix/config.json
|
|
62
|
+
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-startup-redraw-fix/config.json when PI_CODING_AGENT_DIR is set
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
A template is provided at `config/config.example.json`.
|
|
66
|
+
|
|
67
|
+
### Options
|
|
68
|
+
|
|
69
|
+
| Option | Type | Default | Description |
|
|
70
|
+
|--------|------|---------|-------------|
|
|
71
|
+
| `enabled` | boolean | `true` | Enable or disable the extension |
|
|
72
|
+
|
|
73
|
+
### Example Configuration
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"enabled": true
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
> **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.
|
|
82
|
+
|
|
83
|
+
## Technical Details
|
|
84
|
+
|
|
85
|
+
### How It Works
|
|
86
|
+
|
|
87
|
+
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:
|
|
88
|
+
|
|
89
|
+
| Original Sequence | Fixed Sequence |
|
|
90
|
+
|-------------------|----------------|
|
|
91
|
+
| `ESC[3J` (clear scrollback) | `ESC[H` (cursor home) |
|
|
92
|
+
| `ESC[2J` (clear screen) | `ESC[2J` (clear screen) |
|
|
93
|
+
| `ESC[H` (cursor home) | `ESC[3J` (clear scrollback) |
|
|
94
|
+
|
|
95
|
+
The reordering ensures the cursor moves home before clearing, which resolves redraw glitches on certain terminal emulators.
|
|
96
|
+
|
|
97
|
+
### Architecture
|
|
98
|
+
|
|
99
|
+
| File | Purpose |
|
|
100
|
+
|------|---------|
|
|
101
|
+
| `index.ts` | Root entrypoint for Pi auto-discovery |
|
|
102
|
+
| `src/index.ts` | Extension bootstrap and session warning handler |
|
|
103
|
+
| `src/terminal-clear-patch.ts` | Monkey-patch implementation with idempotency guard |
|
|
104
|
+
| `src/normalize-clear-sequence.ts` | String replacement utility |
|
|
105
|
+
| `src/constants.ts` | Escape sequence definitions |
|
|
106
|
+
|
|
107
|
+
### Limitations
|
|
108
|
+
|
|
109
|
+
- Only affects data written via `ProcessTerminal.prototype.write`
|
|
110
|
+
- Only rewrites the exact byte sequence `\x1b[3J\x1b[2J\x1b[H`
|
|
111
|
+
- Will not help if redraw issues are caused by different escape sequences
|
|
112
|
+
- Patch fails if `ProcessTerminal.write` is unavailable or the API changes
|
|
113
|
+
|
|
114
|
+
## Troubleshooting
|
|
115
|
+
|
|
116
|
+
### Warning: "failed to patch terminal clear sequence …"
|
|
117
|
+
|
|
118
|
+
This warning appears on `session_start` when the extension cannot patch `ProcessTerminal.prototype.write`.
|
|
119
|
+
|
|
120
|
+
**Possible Causes:**
|
|
121
|
+
|
|
122
|
+
- Incompatible Pi or `@mariozechner/pi-tui` version where `ProcessTerminal.write` is missing or changed
|
|
123
|
+
- Another extension modified the terminal layer unexpectedly
|
|
124
|
+
|
|
125
|
+
**Solutions:**
|
|
126
|
+
|
|
127
|
+
1. Update Pi and all extensions to latest versions
|
|
128
|
+
2. Temporarily disable other terminal/TUI-related extensions to identify conflicts
|
|
129
|
+
3. Verify the extension is loaded from an auto-discovery folder or referenced in Pi settings
|
|
130
|
+
|
|
131
|
+
## Development
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Build TypeScript
|
|
135
|
+
npm run build
|
|
136
|
+
|
|
137
|
+
# Run linter
|
|
138
|
+
npm run lint
|
|
139
|
+
|
|
140
|
+
# Run tests
|
|
141
|
+
npm run test
|
|
142
|
+
|
|
143
|
+
# Run all checks
|
|
144
|
+
npm run check
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Requirements
|
|
148
|
+
|
|
149
|
+
- Node.js ≥ 20
|
|
150
|
+
- Peer dependencies: `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`
|
|
151
|
+
|
|
152
|
+
## Related Pi Extensions
|
|
153
|
+
|
|
154
|
+
- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
|
|
155
|
+
- [pi-hide-messages](https://github.com/MasuRii/pi-hide-messages) — Hide older chat messages without losing context
|
|
156
|
+
- [pi-image-tools](https://github.com/MasuRii/pi-image-tools) — Image attachment and inline preview
|
|
157
|
+
- [pi-smart-voice-notify](https://github.com/MasuRii/pi-smart-voice-notify) — Multi-channel TTS and sound notifications
|
|
158
|
+
|
|
159
|
+
## License
|
|
160
|
+
|
|
161
|
+
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,58 +1,64 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "pi-startup-redraw-fix",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"main": "./index.ts",
|
|
7
|
-
"exports": {
|
|
8
|
-
".": "./index.ts"
|
|
9
|
-
},
|
|
10
|
-
"files": [
|
|
11
|
-
"index.ts",
|
|
12
|
-
"src",
|
|
13
|
-
"asset",
|
|
14
|
-
"config/config.example.json",
|
|
15
|
-
"README.md",
|
|
16
|
-
"CHANGELOG.md",
|
|
17
|
-
"LICENSE"
|
|
18
|
-
],
|
|
19
|
-
"scripts": {
|
|
20
|
-
"build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
|
|
21
|
-
"lint": "npm run build",
|
|
22
|
-
"test": "node --test",
|
|
23
|
-
"check": "npm run lint && npm run test"
|
|
24
|
-
},
|
|
25
|
-
"keywords": [
|
|
26
|
-
"pi-package",
|
|
27
|
-
"pi",
|
|
28
|
-
"pi-extension",
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
"
|
|
37
|
-
"
|
|
38
|
-
|
|
39
|
-
"
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
"
|
|
50
|
-
"
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "pi-startup-redraw-fix",
|
|
3
|
+
"version": "0.1.8",
|
|
4
|
+
"description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./index.ts",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./index.ts"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"index.ts",
|
|
12
|
+
"src",
|
|
13
|
+
"asset",
|
|
14
|
+
"config/config.example.json",
|
|
15
|
+
"README.md",
|
|
16
|
+
"CHANGELOG.md",
|
|
17
|
+
"LICENSE"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
|
|
21
|
+
"lint": "npm run build",
|
|
22
|
+
"test": "node --test",
|
|
23
|
+
"check": "npm run lint && npm run test"
|
|
24
|
+
},
|
|
25
|
+
"keywords": [
|
|
26
|
+
"pi-package",
|
|
27
|
+
"pi",
|
|
28
|
+
"pi-extension",
|
|
29
|
+
"pi-coding-agent",
|
|
30
|
+
"pi-tui",
|
|
31
|
+
"coding-agent",
|
|
32
|
+
"terminal",
|
|
33
|
+
"terminal-emulator",
|
|
34
|
+
"startup",
|
|
35
|
+
"startup-fix",
|
|
36
|
+
"redraw",
|
|
37
|
+
"bugfix"
|
|
38
|
+
],
|
|
39
|
+
"author": "MasuRii",
|
|
40
|
+
"license": "MIT",
|
|
41
|
+
"repository": {
|
|
42
|
+
"type": "git",
|
|
43
|
+
"url": "git+https://github.com/MasuRii/pi-startup-redraw-fix.git"
|
|
44
|
+
},
|
|
45
|
+
"bugs": {
|
|
46
|
+
"url": "https://github.com/MasuRii/pi-startup-redraw-fix/issues"
|
|
47
|
+
},
|
|
48
|
+
"homepage": "https://github.com/MasuRii/pi-startup-redraw-fix#readme",
|
|
49
|
+
"engines": {
|
|
50
|
+
"node": ">=20"
|
|
51
|
+
},
|
|
52
|
+
"publishConfig": {
|
|
53
|
+
"access": "public"
|
|
54
|
+
},
|
|
55
|
+
"pi": {
|
|
56
|
+
"extensions": [
|
|
57
|
+
"./index.ts"
|
|
58
|
+
]
|
|
59
|
+
},
|
|
60
|
+
"peerDependencies": {
|
|
61
|
+
"@mariozechner/pi-coding-agent": "^0.68.1",
|
|
62
|
+
"@mariozechner/pi-tui": "^0.68.1"
|
|
63
|
+
}
|
|
64
|
+
}
|