pi-startup-redraw-fix 0.1.5 → 0.1.7

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 (3) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +160 -152
  3. package/package.json +64 -58
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.1.7] - 2026-04-01
4
+
5
+ ### Changed
6
+ - Updated npm keywords and package metadata for improved discoverability
7
+
8
+ ## [0.1.6] - 2026-04-01
9
+
10
+ ### Changed
11
+ - Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.64.0
12
+
3
13
  ## [0.1.5] - 2026-03-23
4
14
 
5
15
  ### Changed
package/README.md CHANGED
@@ -1,152 +1,160 @@
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
- ![Terminal startup fix demonstration](https://raw.githubusercontent.com/MasuRii/pi-startup-redraw-fix/main/asset/pi-startup-redraw-fix.png)
6
-
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)
17
-
18
- ## Features
19
-
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
23
-
24
- ## Installation
25
-
26
- ### Extension Folder (Recommended)
27
-
28
- Place the extension folder in one of Pi's auto-discovered extension locations:
29
-
30
- | Location | Path |
31
- |----------|------|
32
- | Global | `~/.pi/agent/extensions/pi-startup-redraw-fix` |
33
- | Project | `.pi/extensions/pi-startup-redraw-fix` |
34
-
35
- Alternatively, add the path to your Pi settings `extensions` array.
36
-
37
- ### npm Package
38
-
39
- ```bash
40
- pi install npm:pi-startup-redraw-fix
41
- ```
42
-
43
- ### Git Repository
44
-
45
- ```bash
46
- pi install git:github.com/MasuRii/pi-startup-redraw-fix
47
- ```
48
-
49
- ## Usage
50
-
51
- This extension operates automatically with **no commands required**.
52
-
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).
54
-
55
- ## Configuration
56
-
57
- Configuration is stored at `config.json` alongside the extension:
58
-
59
- ```
60
- ~/.pi/agent/extensions/pi-startup-redraw-fix/config.json
61
- ```
62
-
63
- A template is provided at `config/config.example.json`.
64
-
65
- ### Options
66
-
67
- | Option | Type | Default | Description |
68
- |--------|------|---------|-------------|
69
- | `enabled` | boolean | `true` | Enable or disable the extension |
70
-
71
- ### Example Configuration
72
-
73
- ```json
74
- {
75
- "enabled": true
76
- }
77
- ```
78
-
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.
80
-
81
- ## Technical Details
82
-
83
- ### How It Works
84
-
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:
86
-
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) |
92
-
93
- The reordering ensures the cursor moves home before clearing, which resolves redraw glitches on certain terminal emulators.
94
-
95
- ### Architecture
96
-
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 |
104
-
105
- ### Limitations
106
-
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
111
-
112
- ## Troubleshooting
113
-
114
- ### Warning: "failed to patch terminal clear sequence …"
115
-
116
- This warning appears on `session_start` when the extension cannot patch `ProcessTerminal.prototype.write`.
117
-
118
- **Possible Causes:**
119
-
120
- - Incompatible Pi or `@mariozechner/pi-tui` version where `ProcessTerminal.write` is missing or changed
121
- - Another extension modified the terminal layer unexpectedly
122
-
123
- **Solutions:**
124
-
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
128
-
129
- ## Development
130
-
131
- ```bash
132
- # Build TypeScript
133
- npm run build
134
-
135
- # Run linter
136
- npm run lint
137
-
138
- # Run tests
139
- npm run test
140
-
141
- # Run all checks
142
- npm run check
143
- ```
144
-
145
- ### Requirements
146
-
147
- - Node.js ≥ 20
148
- - Peer dependencies: `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`
149
-
150
- ## License
151
-
152
- [MIT](LICENSE)
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 | `~/.pi/agent/extensions/pi-startup-redraw-fix` |
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
+ ```
61
+ ~/.pi/agent/extensions/pi-startup-redraw-fix/config.json
62
+ ```
63
+
64
+ A template is provided at `config/config.example.json`.
65
+
66
+ ### Options
67
+
68
+ | Option | Type | Default | Description |
69
+ |--------|------|---------|-------------|
70
+ | `enabled` | boolean | `true` | Enable or disable the extension |
71
+
72
+ ### Example Configuration
73
+
74
+ ```json
75
+ {
76
+ "enabled": true
77
+ }
78
+ ```
79
+
80
+ > **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.
81
+
82
+ ## Technical Details
83
+
84
+ ### How It Works
85
+
86
+ 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:
87
+
88
+ | Original Sequence | Fixed Sequence |
89
+ |-------------------|----------------|
90
+ | `ESC[3J` (clear scrollback) | `ESC[H` (cursor home) |
91
+ | `ESC[2J` (clear screen) | `ESC[2J` (clear screen) |
92
+ | `ESC[H` (cursor home) | `ESC[3J` (clear scrollback) |
93
+
94
+ The reordering ensures the cursor moves home before clearing, which resolves redraw glitches on certain terminal emulators.
95
+
96
+ ### Architecture
97
+
98
+ | File | Purpose |
99
+ |------|---------|
100
+ | `index.ts` | Root entrypoint for Pi auto-discovery |
101
+ | `src/index.ts` | Extension bootstrap and session warning handler |
102
+ | `src/terminal-clear-patch.ts` | Monkey-patch implementation with idempotency guard |
103
+ | `src/normalize-clear-sequence.ts` | String replacement utility |
104
+ | `src/constants.ts` | Escape sequence definitions |
105
+
106
+ ### Limitations
107
+
108
+ - Only affects data written via `ProcessTerminal.prototype.write`
109
+ - Only rewrites the exact byte sequence `\x1b[3J\x1b[2J\x1b[H`
110
+ - Will not help if redraw issues are caused by different escape sequences
111
+ - Patch fails if `ProcessTerminal.write` is unavailable or the API changes
112
+
113
+ ## Troubleshooting
114
+
115
+ ### Warning: "failed to patch terminal clear sequence …"
116
+
117
+ This warning appears on `session_start` when the extension cannot patch `ProcessTerminal.prototype.write`.
118
+
119
+ **Possible Causes:**
120
+
121
+ - Incompatible Pi or `@mariozechner/pi-tui` version where `ProcessTerminal.write` is missing or changed
122
+ - Another extension modified the terminal layer unexpectedly
123
+
124
+ **Solutions:**
125
+
126
+ 1. Update Pi and all extensions to latest versions
127
+ 2. Temporarily disable other terminal/TUI-related extensions to identify conflicts
128
+ 3. Verify the extension is loaded from an auto-discovery folder or referenced in Pi settings
129
+
130
+ ## Development
131
+
132
+ ```bash
133
+ # Build TypeScript
134
+ npm run build
135
+
136
+ # Run linter
137
+ npm run lint
138
+
139
+ # Run tests
140
+ npm run test
141
+
142
+ # Run all checks
143
+ npm run check
144
+ ```
145
+
146
+ ### Requirements
147
+
148
+ - Node.js ≥ 20
149
+ - Peer dependencies: `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`
150
+
151
+ ## Related Pi Extensions
152
+
153
+ - [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
154
+ - [pi-hide-messages](https://github.com/MasuRii/pi-hide-messages) — Hide older chat messages without losing context
155
+ - [pi-image-tools](https://github.com/MasuRii/pi-image-tools) — Image attachment and inline preview
156
+ - [pi-smart-voice-notify](https://github.com/MasuRii/pi-smart-voice-notify) — Multi-channel TTS and sound notifications
157
+
158
+ ## License
159
+
160
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,58 +1,64 @@
1
- {
2
- "name": "pi-startup-redraw-fix",
3
- "version": "0.1.5",
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
- "terminal",
30
- "startup",
31
- "redraw"
32
- ],
33
- "author": "MasuRii",
34
- "license": "MIT",
35
- "repository": {
36
- "type": "git",
37
- "url": "git+https://github.com/MasuRii/pi-startup-redraw-fix.git"
38
- },
39
- "bugs": {
40
- "url": "https://github.com/MasuRii/pi-startup-redraw-fix/issues"
41
- },
42
- "homepage": "https://github.com/MasuRii/pi-startup-redraw-fix#readme",
43
- "engines": {
44
- "node": ">=20"
45
- },
46
- "publishConfig": {
47
- "access": "public"
48
- },
49
- "pi": {
50
- "extensions": [
51
- "./index.ts"
52
- ]
53
- },
54
- "peerDependencies": {
55
- "@mariozechner/pi-coding-agent": "^0.62.0",
56
- "@mariozechner/pi-tui": "^0.62.0"
57
- }
58
- }
1
+ {
2
+ "name": "pi-startup-redraw-fix",
3
+ "version": "0.1.7",
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.64.0",
62
+ "@mariozechner/pi-tui": "^0.64.0"
63
+ }
64
+ }