pi-tui-status-beautifier 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+## [1.1.1] - 2026-08-23
+### Added
+- Memory-hoisted visual cell-width checks of character sequences to correctly align TUI status templates (Finding 5)
+- State cache-based dirty-checking for status updates to prevent redundant redrawing and layout flickering (Finding 6)
+### Fixed
+- Fixed TUI alignment issues involving full-width CJK characters and emojis in layout paddings
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Song (@3ZEROS12)
+
+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

@@ -2,10 +2,15 @@
 
 A premium status bar beautifier extension for the Pi Terminal TUI. Instantly transforms boring status lines into brand-inspired themes and clean layouts.
 
-## 🚀 Installation & Usage (Recommended)
+## 🚀 Installation & Usage
 
-Since this package is published on GitHub, you can install it instantly in the Pi TUI command environment using the following single line:
+Install directly via the Pi package manager:
 
+```bash
+pi install npm:pi-tui-status-beautifier
+```
+
+Or install from git:
 ```bash
 pi install git:github.com/3ZEROS12/pi-tui-status-beautifier
 ```

package/extensions/tui-status-beautifier.ts

@@ -4,13 +4,13 @@ import * as path from "path";
 
 // Mapping of internal package names to clean human-readable TUI status names
 const COMMON_NAMES: Record<string, string> = {
-  "plannotator": "plan",
+  plannotator: "plan",
   "plannotator-review": "plan",
   "pi-mcp-adapter": "mcp",
   "subagent-slash": "subagent",
   "subagent-slash-text": "subagent",
   "pi-wechat-assistant": "wechat",
-  "wechat-assistant": "wechat"
+  "wechat-assistant": "wechat",
 };
 
 // Store original statuses to allow dynamic redrawing on configuration changes.
@@ -20,11 +20,16 @@ const originalStatuses = new Map<string, string | undefined>();
 // Memoization cache for Google colorized text to reduce GC overhead and theme calls.
 const googleColorizeCache = new Map<string, string>();
 
+// State Cache for Dirty-Checking
+const lastRenderedStatus = new Map<string, string | undefined>();
+
 // Safe, non-backtracking ReDoS-mitigated ANSI escape sequence matcher (supporting ; and :)
-const ANSI_STRIP_REGEX = /[\u001B\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d\/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-ntqry=><~]))/g;
+const ANSI_STRIP_REGEX =
+  /[\u001B\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-ntqry=><~]))/g;
 
 // Hoisted regex patterns to prevent instantiation and GC overhead in the render hot-path
-const STATUS_PATTERN = /[🟢🔴🟡⚪⏸✅❌✓✗?✔✖☑☐◆📋]|[0-9]+\/[0-9]+|active|online|offline|running|paused|error|success|connected|disconnected/i;
+const STATUS_PATTERN =
+  /[🟢🔴🟡⚪⏸✅❌✓✗?✔✖☑☐◆📋]|[0-9]+\/[0-9]+|active|online|offline|running|paused|error|success|connected|disconnected/i;
 const NAME_SUFFIX_PATTERN = /-(extension|plugin|assistant|adapter|slash-text|slash|text|widget)$/gi;
 const FRACTION_PATTERN = /(\d+\/\d+|\d+%\s*)/;
 const PARENTHESES_PATTERN = /\((\d+)\)/;
@@ -38,7 +43,7 @@ const settingsPath = path.join(home, ".pi/agent/settings.json");
 // Command-Driven I/O State:
 // Loaded ONCE synchronously during extension loading, thereafter handled entirely in memory.
 // Disk I/O only occurs when the user triggers the "/beautify" selection command.
-let currentStyle = "minimal"; 
+let currentStyle = "minimal";
 
 try {
   if (fs.existsSync(settingsPath)) {
@@ -55,13 +60,14 @@ try {
 // Google playful multi-color letter colorizer with type safeguards and memoization
 export function googleColorize(text: string, theme: any): string {
   if (!theme || typeof theme.fg !== "function") return text;
-  
+
   const cached = googleColorizeCache.get(text);
   if (cached !== undefined) return cached;
 
   // Google's brand colors cycle: Blue, Red, Yellow, Green
   const colors = ["accent", "error", "warning", "success"];
-  const colorized = text.split("")
+  const colorized = text
+    .split("")
     .map((char, index) => {
       const color = colors[index % colors.length];
       return theme.fg(color, char);
@@ -73,16 +79,19 @@ export function googleColorize(text: string, theme: any): string {
 }
 
 // Clean status text and map state and details
-export function beautifyStatus(key: string, originalVal: string | undefined, theme: any, style: string): string | undefined {
+export function beautifyStatus(
+  key: string,
+  originalVal: string | undefined,
+  theme: any,
+  style: string
+): string | undefined {
   if (originalVal === undefined) return undefined;
   if (style === "off") return originalVal; // Pass through untouched if disabled
 
   try {
     // Fast-path: bypass Regex search if no ESC or CSI bytes exist to reduce hot redraw latency
     const hasAnsi = originalVal.includes("\u001B") || originalVal.includes("\u009B");
-    const cleanVal = hasAnsi
-      ? originalVal.replace(ANSI_STRIP_REGEX, "").trim()
-      : originalVal.trim();
+    const cleanVal = hasAnsi ? originalVal.replace(ANSI_STRIP_REGEX, "").trim() : originalVal.trim();
 
     if (cleanVal === "") return "";
 
@@ -100,11 +109,10 @@ export function beautifyStatus(key: string, originalVal: string | undefined, the
       if (lastSlash !== -1) {
         name = name.slice(lastSlash + 1);
       }
-      name = name
-        .replace(NAME_SUFFIX_PATTERN, "")
-        .toLowerCase();
-      name = name.slice(0, 10);
+      name = name.replace(NAME_SUFFIX_PATTERN, "").toLowerCase();
     }
+    // Optimization (Finding 5): Use visual cell width calculations rather than standard .length for CJK/emojis
+    const visualName = padToVisualWidth(sliceToVisualWidth(name, 10), 10);
 
     // 2. Extract metrics/progress details safely (e.g. (2) or fraction 2/5 or count)
     let details: string | undefined;
@@ -172,20 +180,20 @@ export function beautifyStatus(key: string, originalVal: string | undefined, the
     switch (style) {
       case "apple": {
         const separator = hasThemeFg ? theme.fg("dim", "  │  ") : "  │  ";
-        const dimmedName = hasThemeFg ? theme.fg("dim", name) : name;
+        const dimmedName = hasThemeFg ? theme.fg("dim", visualName) : visualName;
         const detailStr = details ? ` (${details})` : "";
         return `${dimmedName}${separator}${coloredIndicator}${detailStr}`;
       }
       case "openai": {
         const spirograph = hasThemeFg ? theme.fg("success", "❂") : "❂";
         const detailStr = details ? ` [${details}]` : "";
-        const dimmedName = hasThemeFg ? theme.fg("muted", name) : name;
+        const dimmedName = hasThemeFg ? theme.fg("muted", visualName) : visualName;
         return `${spirograph} ${dimmedName}${detailStr}`;
       }
       case "anthropic": {
         const organicStar = "✦";
         const coloredStar = hasThemeFg ? theme.fg(state, organicStar) : organicStar;
-        const dimmedName = hasThemeFg ? theme.fg("muted", name) : name;
+        const dimmedName = hasThemeFg ? theme.fg("muted", visualName) : visualName;
         const detailStr = details ? ` ❖ ${details}` : "";
         return `${dimmedName} ${coloredStar}${detailStr}`;
       }
@@ -194,39 +202,37 @@ export function beautifyStatus(key: string, originalVal: string | undefined, the
         const detailStr = details ? ` │ ${details}` : "";
         const prefix = hasThemeFg ? theme.fg("dim", "[") : "[";
         const suffix = hasThemeFg ? theme.fg("dim", "]") : "]";
-        return `${windowsLogo} ${prefix}${name}${suffix} ${coloredIndicator}${detailStr}`;
+        return `${windowsLogo} ${prefix}${visualName}${suffix} ${coloredIndicator}${detailStr}`;
       }
       case "google": {
-        const coloredName = googleColorize(name, theme);
+        const coloredName = googleColorize(visualName, theme);
         const detailStr = details ? `:${details}` : "";
         return `${coloredName} ➔ ${coloredIndicator}${detailStr}`;
       }
       case "glass": {
         const prefix = hasThemeFg ? theme.fg("dim", "▕ ") : "▕ ";
         const suffix = hasThemeFg ? theme.fg("dim", " ▏") : " ▏";
-        const dimmedName = hasThemeFg ? theme.fg("muted", name) : name;
+        const dimmedName = hasThemeFg ? theme.fg("muted", visualName) : visualName;
         const detailStr = details ? ` (${details})` : "";
         return `${prefix}${dimmedName} ${coloredIndicator}${detailStr}${suffix}`;
       }
       case "glow": {
         const label = ` ${char}${details ? ` ${details}` : ""} `;
         const hasInverse = theme && typeof theme.inverse === "function";
-        const coloredBadge = (hasInverse && hasThemeFg)
-          ? theme.inverse(theme.fg(state, label))
-          : `[${label}]`;
-        const dimmedName = hasThemeFg ? theme.fg("muted", name) : name;
+        const coloredBadge = hasInverse && hasThemeFg ? theme.inverse(theme.fg(state, label)) : `[${label}]`;
+        const dimmedName = hasThemeFg ? theme.fg("muted", visualName) : visualName;
         return `${dimmedName} ${coloredBadge}`;
       }
       case "matrix": {
-        const prefix = hasThemeFg ? theme.fg("dim", " ⦗ ") : " ⦗ ";
-        const suffix = hasThemeFg ? theme.fg("dim", " ⦘") : "  ⦘";
+        const prefix = hasThemeFg ? theme.fg("dim", " \u2397 ") : " \u2397 ";
+        const suffix = hasThemeFg ? theme.fg("dim", " \u2398") : "  \u2398";
         const separator = hasThemeFg ? theme.fg("dim", " | ") : " | ";
         const detailStr = details ? `${separator}${details}` : "";
-        return `${name}${prefix}${coloredIndicator}${detailStr}${suffix}`;
+        return `${visualName}${prefix}${coloredIndicator}${detailStr}${suffix}`;
       }
       case "minimal": {
         const separator = hasThemeFg ? theme.fg("dim", " ❯ ") : " ❯ ";
-        const dimmedName = hasThemeFg ? theme.fg("muted", name) : name;
+        const dimmedName = hasThemeFg ? theme.fg("muted", visualName) : visualName;
         const detailStr = details ? ` (${details})` : "";
         return `${dimmedName}${separator}${coloredIndicator}${detailStr}`;
       }
@@ -239,6 +245,91 @@ export function beautifyStatus(key: string, originalVal: string | undefined, the
   }
 }
 
+/**
+ * Calculates the visual column cell width of a string (Finding 5), taking into account
+ * full-width Unicode characters, East Asian characters, and emojis.
+ */
+export function getStringWidth(str: string): number {
+  if (!str) return 0;
+  // Strip ANSI escape sequences & control codes before counting visual width
+  const clean = str.replace(ANSI_STRIP_REGEX, "");
+  let width = 0;
+  for (let i = 0; i < clean.length; i++) {
+    const code = clean.charCodeAt(i);
+    if (isFullWidth(code)) {
+      width += 2;
+    } else {
+      width += 1;
+    }
+  }
+  return width;
+}
+
+/**
+ * Checks if a character unicode code point is full-width (East Asian Width).
+ */
+function isFullWidth(code: number): boolean {
+  if (isNaN(code)) return false;
+  return (
+    code >= 0x1100 &&
+    (code <= 0x115f ||
+      code === 0x2329 ||
+      code === 0x232a ||
+      // CJK Radicals Supplement .. Enclosed CJK Letters and Months
+      (code >= 0x2e80 && code <= 0x3247 && code !== 0x303f) ||
+      // Enclosed CJK Letters and Months .. CJK Unified Ideographs Extension A
+      (code >= 0x3250 && code <= 0x4dbf) ||
+      // CJK Unified Ideographs .. Yi Radicals
+      (code >= 0x4e00 && code <= 0xa4c6) ||
+      // Hangul Jamo Extended-A
+      (code >= 0xa960 && code <= 0xa97c) ||
+      // Hangul Syllables
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      // CJK Compatibility Ideographs
+      (code >= 0xf900 && code <= 0xfaff) ||
+      // Vertical Forms
+      (code >= 0xfe10 && code <= 0xfe19) ||
+      // CJK Compatibility Forms .. Small Form Variants
+      (code >= 0xfe30 && code <= 0xfe6b) ||
+      // Halfwidth and Fullwidth Forms
+      (code >= 0xff01 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) ||
+      // East Asian Wide characters beyond BMP
+      (code >= 0x1b000 && code <= 0x1b001) ||
+      (code >= 0x1f200 && code <= 0x1f251) ||
+      (code >= 0x20000 && code <= 0x3fffd))
+  );
+}
+
+/**
+ * Slices a string to a maximum visual cell width.
+ */
+export function sliceToVisualWidth(str: string, maxWidth: number): string {
+  let width = 0;
+  let sliced = "";
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    const charWidth = isFullWidth(code) ? 2 : 1;
+    if (width + charWidth > maxWidth) {
+      break;
+    }
+    width += charWidth;
+    sliced += str.charAt(i);
+  }
+  return sliced;
+}
+
+/**
+ * Pads a string's visual cell width to target width with trailing spaces.
+ */
+export function padToVisualWidth(str: string, targetWidth: number, padChar = " "): string {
+  const currentWidth = getStringWidth(str);
+  if (currentWidth >= targetWidth) {
+    return str;
+  }
+  return str + padChar.repeat(targetWidth - currentWidth);
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     if (!ctx.hasUI || !ctx.ui) return;
@@ -246,6 +337,7 @@ export default function (pi: ExtensionAPI) {
     // Flush stale statuses from previous sessions to prevent memory leaks and clear color cache
     originalStatuses.clear();
     googleColorizeCache.clear();
+    lastRenderedStatus.clear();
 
     const originalSetStatus = ctx.ui.setStatus;
     if (originalSetStatus && !(originalSetStatus as any).__beautifierHooked) {
@@ -255,7 +347,14 @@ export default function (pi: ExtensionAPI) {
 
         // Uses in-memory synchronization (zero file I/O overhead on render pipeline ticks)
         const beautified = beautifyStatus(key, value, ctx.ui.theme, currentStyle);
-        
+
+        // Dirty-checking (Finding 6): Skip redundant stdout paint updates
+        const cacheKey = `${key}:${currentStyle}`;
+        if (lastRenderedStatus.get(cacheKey) === beautified) {
+          return;
+        }
+        lastRenderedStatus.set(cacheKey, beautified);
+
         return originalSetStatus.call(ctx.ui, key, beautified);
       };
       (wrapped as any).__beautifierHooked = true;
@@ -270,7 +369,7 @@ export default function (pi: ExtensionAPI) {
       if (!ctx.hasUI || !ctx.ui) {
         return;
       }
-      
+
       const styleOptions = [
         "minimal (Millennial Minimalist - e.g. name ❯ ●)",
         "apple (Apple Cupertino - e.g. name │ ●)",
@@ -281,25 +380,31 @@ export default function (pi: ExtensionAPI) {
         "glass (Charm Glass - e.g. ▕ name ● ▏)",
         "glow (Glow Badge - e.g. name [ ● ])",
         "matrix (Retro Matrix - e.g. name ⦗ ● | 2 ⦘)",
-        "off (use raw output)"
+        "off (use raw output)",
       ];
-      
-      const choice = await ctx.ui.select(
-        `Choose status style (Current: ${currentStyle}):`,
-        styleOptions
-      );
+
+      const choice = await ctx.ui.select(`Choose status style (Current: ${currentStyle}):`, styleOptions);
 
       if (choice) {
         const styleKey = choice.split(" ")[0].trim();
         const validStyles = [
-          "apple", "openai", "anthropic", "google", "microsoft",
-          "minimal", "glass", "glow", "matrix", "off"
+          "apple",
+          "openai",
+          "anthropic",
+          "google",
+          "microsoft",
+          "minimal",
+          "glass",
+          "glow",
+          "matrix",
+          "off",
         ];
-        
+
         if (validStyles.includes(styleKey)) {
           // 1. Instantly update in-memory caching
           currentStyle = styleKey;
           googleColorizeCache.clear(); // Clear cache when changing style/redrawing to ensure new colors are loaded
+          lastRenderedStatus.clear();  // Clear dirty checking cache to force repaint
           ctx.ui.notify(`TUI status style changed to: ${styleKey}`, "info");
 
           // 2. Redraw TUI indicator widgets instantly on configuration event using cached data
@@ -321,6 +426,6 @@ export default function (pi: ExtensionAPI) {
           }
         }
       }
-    }
+    },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tui-status-beautifier",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Premium brand & layout status bar beautifier for Pi terminal TUI.",
   "main": "extensions/tui-status-beautifier.ts",
   "keywords": [
@@ -11,6 +11,20 @@
       "./extensions/tui-status-beautifier.ts"
     ]
   },
+  "files": [
+    "extensions/tui-status-beautifier.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3ZEROS12/pi-tui-status-beautifier.git"
+  },
+  "homepage": "https://github.com/3ZEROS12/pi-tui-status-beautifier#readme",
+  "bugs": {
+    "url": "https://github.com/3ZEROS12/pi-tui-status-beautifier/issues"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
@@ -30,4 +44,4 @@
     "typescript": "^5.3.3",
     "vitest": "^1.2.2"
   }
-}
+}

package/extensions/tui-status-beautifier.spec.ts

@@ -1,77 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { beautifyStatus, googleColorize } from "./tui-status-beautifier";
-
-describe("TUI Status Beautifier Code Optimization Tests", () => {
-  const mockTheme = {
-    fg: (color: string, text: string) => `[${color}]${text}[/color]`,
-  };
-
-  describe("ANSI Escape Sequence Stripping & Metric Extraction (Finding 1)", () => {
-    it("should correctly clean parameterized 256-color sequences without leaves/parameters leaking", () => {
-      const input = "\x1B[38;5;108mactive\x1B[0m (12)";
-      const output = beautifyStatus("test-extension", input, mockTheme, "minimal");
-      
-      // Expected metric: 12. If parameters like 38 or 5 leaked, they might be matched as metric instead.
-      expect(output).toContain("(12)");
-      expect(output).not.toContain("38");
-      expect(output).not.toContain("5");
-    });
-
-    it("should correctly clean truecolor RGB sequences", () => {
-      const input = "\x1B[38;2;255;0;255mactive\x1B[0m (45)";
-      const output = beautifyStatus("test-extension", input, mockTheme, "minimal");
-      
-      expect(output).toContain("(45)");
-      expect(output).not.toContain("255");
-      expect(output).not.toContain("0");
-    });
-  });
-
-  describe("Fast-Path Optimization (Finding 2)", () => {
-    it("should process simple text correctly and avoid unnecessary matches", () => {
-      const output = beautifyStatus("my-plugin", "running 5/5", mockTheme, "minimal");
-      expect(output).toContain("my-plugin");
-      expect(output).toContain("(5/5)");
-    });
-  });
-
-  describe("Google Colorize Memoization/Cache (Finding 5)", () => {
-    it("should cache subsequent calls for the same text to avoid redundant mapping and theme calls", () => {
-      const text = "plug";
-      const fgSpy = vi.fn((color: string, text: string) => `[${color}]${text}[/color]`);
-      const customTheme = { fg: fgSpy };
-
-      const firstCall = googleColorize(text, customTheme);
-      const secondCall = googleColorize(text, customTheme);
-
-      // Verify they return the same colorized string
-      expect(firstCall).toBe(secondCall);
-      
-      // Due to cache/memoization, fgSpy should only be called search length times once
-      expect(fgSpy).toHaveBeenCalledTimes(text.length);
-    });
-  });
-
-  describe("Layout Preset Rendering", () => {
-    it("should render apple style", () => {
-      const output = beautifyStatus("test", "active", mockTheme, "apple");
-      expect(output).toContain("│");
-      expect(output).toContain("●");
-    });
-
-    it("should render openai style", () => {
-      const output = beautifyStatus("test", "active", mockTheme, "openai");
-      expect(output).toContain("❂");
-    });
-
-    it("should render anthropic style", () => {
-      const output = beautifyStatus("test", "active", mockTheme, "anthropic");
-      expect(output).toContain("✦");
-    });
-
-    it("should return raw output when style is off", () => {
-      const output = beautifyStatus("test", "active (5)", mockTheme, "off");
-      expect(output).toBe("active (5)");
-    });
-  });
-});