pi-startup-redraw-fix 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Standardized repository structure with `src/` layout and root shim entrypoint.
+- Kept terminal clear-sequence patch behavior unchanged.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# pi-startup-redraw-fix
+
+Startup redraw / full-clear ordering fix for the Pi coding agent.
+
+This extension patches the terminal “full clear” escape sequence emitted during startup so the screen/scrollback clear happens in a stable order, avoiding redraw glitches in some terminal setups.
+
+![alt text](asset/pi-startup-redraw-fix.png)
+
+## Features
+
+- Normalizes the startup full-clear escape sequence order:
+  - **From:** `\x1b[3J\x1b[2J\x1b[H`
+  - **To:** `\x1b[H\x1b[2J\x1b[3J`
+- Applies the patch **once per Node process** by monkey-patching `ProcessTerminal.prototype.write`.
+- On `session_start`, shows a **UI warning** (when UI is available) if patching failed.
+
+## Installation
+
+### Local extension folder
+
+Place this folder in one of Pi’s auto-discovered extension locations:
+
+- Global: `~/.pi/agent/extensions/pi-startup-redraw-fix`
+- Project: `.pi/extensions/pi-startup-redraw-fix`
+
+If you keep it elsewhere, add the path to your Pi settings `extensions` array.
+
+### As an npm package
+
+```bash
+pi install npm:pi-startup-redraw-fix
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/MasuRii/pi-startup-redraw-fix
+```
+
+(For development or non-Pi environments, `npm i pi-startup-redraw-fix` also works.)
+
+## Usage
+
+This extension has **no commands**.
+
+When the extension is loaded, it immediately attempts to patch `ProcessTerminal.prototype.write`. On each new session (`session_start`), if Pi has a UI and the patch did not apply, it emits a warning notification.
+
+## Configuration
+
+### Enable / disable
+
+Runtime config is stored alongside the extension at:
+
+- `~/.pi/agent/extensions/pi-startup-redraw-fix/config.json`
+
+A starter template is included at:
+
+- `config/config.example.json`
+
+Minimal config:
+
+```json
+{
+  "enabled": true
+}
+```
+
+Notes:
+
+- In environments where Pi honors an extension-local `enabled` flag, set `"enabled": false` to disable the extension.
+- 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).
+
+## How it works (high level)
+
+Pi’s TUI uses `@mariozechner/pi-tui`’s `ProcessTerminal` to write escape sequences to the terminal.
+
+This extension:
+
+1. Wraps `ProcessTerminal.prototype.write`.
+2. For each write, replaces any occurrence of the exact “broken” full-clear sequence:
+   - `ESC [ 3 J` (clear scrollback)
+   - `ESC [ 2 J` (clear screen)
+   - `ESC [ H` (cursor home)
+3. With the “fixed” order:
+   - `ESC [ H` (cursor home)
+   - `ESC [ 2 J` (clear screen)
+   - `ESC [ 3 J` (clear scrollback)
+
+The patch is guarded by an internal flag so it is **idempotent** (loading the extension multiple times will not stack-wrap `write`).
+
+## Limitations / compatibility
+
+- Only affects data written via `ProcessTerminal.prototype.write`.
+- Only rewrites the **exact** byte sequence `\x1b[3J\x1b[2J\x1b[H`.
+  - If your terminal redraw issue is caused by different escape sequences, this extension will not help.
+- 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).
+
+## Troubleshooting
+
+### I see a warning: “failed to patch terminal clear sequence …”
+
+This warning is shown on `session_start` when:
+
+- Pi has a UI (`ctx.hasUI`), and
+- the extension could not patch `ProcessTerminal.prototype.write`.
+
+Common causes:
+
+- Incompatible Pi / `@mariozechner/pi-tui` version where `ProcessTerminal.write` is missing or changed.
+- Another extension or runtime modified the terminal layer in an unexpected way.
+
+What to try:
+
+1. Update Pi and your extensions.
+2. Temporarily disable other terminal/TUI-related extensions to identify conflicts.
+3. Verify the extension is actually being loaded (installed to an auto-discovery folder or referenced in your Pi settings).
+
+## Development
+
+```bash
+npm run build
+npm run lint
+npm run test
+npm run check
+```
+
+## Project layout
+
+- `index.ts` — root entrypoint (kept for Pi auto-discovery / package export)
+- `src/index.ts` — extension bootstrap + `session_start` warning notification
+- `src/terminal-clear-patch.ts` — `ProcessTerminal.prototype.write` monkey-patch + idempotency guard
+- `src/normalize-clear-sequence.ts` — string rewrite helper
+- `src/constants.ts` — escape sequence constants
+- `config/config.example.json` — starter config template
+
+## License
+
+MIT

package/config/config.example.json

@@ -0,0 +1,3 @@
+{
+  "enabled": true
+}

package/index.ts

@@ -0,0 +1,3 @@
+import startupRedrawFixExtension from "./src/index.js";
+
+export default startupRedrawFixExtension;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-startup-redraw-fix",
+  "version": "0.1.0",
+  "description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "node --test",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "terminal",
+    "startup",
+    "redraw"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-startup-redraw-fix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-startup-redraw-fix/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-startup-redraw-fix#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const BROKEN_FULL_CLEAR_SEQUENCE = "\x1b[3J\x1b[2J\x1b[H";
+export const FIXED_FULL_CLEAR_SEQUENCE = "\x1b[H\x1b[2J\x1b[3J";

package/src/index.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { applyTerminalClearSequencePatch } from "./terminal-clear-patch.js";
+
+export default function startupRedrawFixExtension(pi: ExtensionAPI): void {
+  const patchResult = applyTerminalClearSequencePatch();
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    if (!patchResult.patched && !patchResult.alreadyPatched) {
+      const reason = patchResult.error ?? "unknown error";
+      ctx.ui.notify(`startup-redraw-fix: failed to patch terminal clear sequence (${reason})`, "warning");
+    }
+  });
+}

package/src/normalize-clear-sequence.ts

@@ -0,0 +1,9 @@
+import { BROKEN_FULL_CLEAR_SEQUENCE, FIXED_FULL_CLEAR_SEQUENCE } from "./constants.js";
+
+export function normalizeTerminalClearSequence(data: string): string {
+  if (!data.includes(BROKEN_FULL_CLEAR_SEQUENCE)) {
+    return data;
+  }
+
+  return data.split(BROKEN_FULL_CLEAR_SEQUENCE).join(FIXED_FULL_CLEAR_SEQUENCE);
+}

package/src/terminal-clear-patch.ts

@@ -0,0 +1,44 @@
+import { ProcessTerminal } from "@mariozechner/pi-tui";
+
+import { normalizeTerminalClearSequence } from "./normalize-clear-sequence.js";
+
+const PATCH_FLAG_KEY = "__piStartupRedrawFixPatched__" as const;
+
+type ProcessTerminalPrototype = typeof ProcessTerminal.prototype & {
+  [PATCH_FLAG_KEY]?: boolean;
+};
+
+export interface PatchResult {
+  patched: boolean;
+  alreadyPatched: boolean;
+  error?: string;
+}
+
+export function applyTerminalClearSequencePatch(): PatchResult {
+  const prototype = ProcessTerminal.prototype as ProcessTerminalPrototype;
+
+  if (prototype[PATCH_FLAG_KEY]) {
+    return { patched: false, alreadyPatched: true };
+  }
+
+  const originalWrite = prototype.write;
+  if (typeof originalWrite !== "function") {
+    return {
+      patched: false,
+      alreadyPatched: false,
+      error: "ProcessTerminal.write is unavailable",
+    };
+  }
+
+  prototype.write = function patchedProcessTerminalWrite(data: string): void {
+    const normalized = typeof data === "string"
+      ? normalizeTerminalClearSequence(data)
+      : data;
+
+    originalWrite.call(this, normalized);
+  };
+
+  prototype[PATCH_FLAG_KEY] = true;
+
+  return { patched: true, alreadyPatched: false };
+}