@leo-alvarenga/pi-zen-frame 0.11.0 → 0.12.1

package/README.md

@@ -1,63 +1,75 @@
-# pi-zen-frame
+# @leo-alvarenga/pi-zen-frame
 
-A [pi-coding-agent](https://github.com/earendil-works/pi) extension that gives the TUI editor a simple yet polished look and feel.
-
-- **Frame** — a box (`╭ ╮ ╰ ╯ │ ─`) with live status segments embedded in the top/bottom border.
-- **Header** — an optional Claude-welcome-style top box: logo (left, 40%) + model/provider and cwd/git info (right, 60%, split in two halves).
-- **Working messages** — randomized messages in pi's built-in working loader, swapped on a configurable interval (on by default).
-- **Theme native** — every color is a pi `ThemeColor`, so it follows your active pi theme.
+A [`pi-coding-agent`](https://github.com/earendil-works/pi) extension that gives the TUI editor a clean, minimalist layout with customizable status indicators and frames.
 
 ![Preview](./docs/preview.png)
 
-## Install
+## Features
+
+- **Clean Frame**: Clean editor frame with segments placed above and below it to easily see relevant info
+- **Header Box**: Optional Claude-style welcome panel displaying a logo, model/provider info, current working directory, and Git status
+- **Working Messages**: Randomized loading status messages during response generation, updated on a configurable timer
+- **Native Theme Support**: Uses pi `ThemeColor` tokens to automatically align with your active theme
+
+---
+
+## Installation
+
+Run the following command:
+
+```bash
+pi install @leo-alvarenga/pi-zen-frame
+```
 
-It's distributed as a pi package. Add it to `settings.json` → `packages`, e.g. install from
-a local checkout or registry:
+Or add `pi-zen-frame` to your pi packages list in `~/.pi/agent/settings.json`:
 
 ```jsonc
-// ~/.pi/agent/settings.json
 {
-  "packages": ["npm:@leo-alvarenga/pi-zen-frame", "path/to/pi-zen-frame"],
+  "packages": ["npm:@leo-alvarenga/pi-zen-frame"],
 }
 ```
 
-Restart pi (or `/reload`).
+Then, restart pi or run `/reload` in the console.
 
-## Config
+---
 
-zen editor reads `~/.pi/agent/pi-zen-frame.json`. All keys are optional; defaults are shown.
+## Configuration
+
+Configuration is loaded from `~/.pi/agent/pi-zen-frame.json`. All properties are optional.
 
 ```jsonc
 {
-  // Accent used by segments/frame when a more specific color isn't set.
+  // Fallback accent color for frame border and active segments
   "accentColor": "accent",
 
-  // Master mute: every segment except agent-mode renders muted.
-  // Toggle at runtime with /zen_mode or the piZenFrame.zenMode keybinding.
+  // Master mute: renders all segments in muted tones except agent-mode
   "zenMode": true,
 
   "header": {
     "enable": true,
-    "logo": [" ", "██████████", "███   ███ ", "██████    ", ...],
-    "heading": "Zen Pi",
-    "subheading": "A pi-coding-agent powered terminal editor",
+    "logo": ["█████████  ", "███   ███  ", "██████     ", "███     ███"],
+    "heading": "Welcome back!",
+    "subheading": "Ready for your next session? Terminal warm, context clean, tools ready to execute",
     "logoColor": "text",
-    "accentColor": "customMessageLabel"
+    "accentColor": "customMessageLabel",
   },
 
   "frame": {
     "enable": true,
-    // Below this terminal width the box is skipped (plain editor).
+
+    // Minimum terminal width required to render the border frame
     "minWidth": 20,
 
-    // Blank lines inside the box (padding) / outside it (margin).
+    // Padding inside the frame
     "paddingTop": 1,
     "paddingBottom": 1,
     "paddingX": 1,
+
+    // Outer margin around the frame
     "marginTop": 0,
     "marginBottom": 0,
 
-    // Border segments on/off.
+    // Toggle individual status segments
     "showCwd": true,
     "showModel": true,
     "showContext": true,
@@ -65,84 +77,80 @@ zen editor reads `~/.pi/agent/pi-zen-frame.json`. All keys are optional; default
     "showSpinner": false,
     "showAgentMode": true,
 
-    // Defaults to accentColor, then "border"; Can also be set to "agentMode" to match the current agent's color
+    // Color options: "border", "accentColor", or "agentMode"
     "borderColor": "border",
 
-    // Glyph shown before the editor content. Default "❯".
+    // Input prompt prefix glyph and color settings
     "prefix": "❯",
-
-    // Prefix color source: "agentMode" (current agent), "frameBorder" (frame
-    // border color), or any ThemeColor. Default: text color.
-    "prefixColor": "muted",
-
-    // Override the Nerd-Font glyphs (folder, model, context, thinking,
-    // gitDirty, gitBranch).
-    "icons": {},
-
-    // Per-segment fg overrides (any subset; supersede the built-in colors,
-    // e.g. the ctx traffic-light). Keys: model, thinking, context, cwd,
-    // agentMode. agentMode only applies when zenMode is off and no agent
-    // color is set.
-    "colors": { "model": "accent", "cwd": "accent" }
+    "prefixColor": "muted", // Options: "agentMode", "frameBorder", or any ThemeColor
+
+    // Override default Nerd-Font glyphs
+    "icons": {
+      // Keys: folder, model, context, thinking, gitDirty, gitBranch
+    },
+
+    // Per-segment foreground color overrides (supersedes default theme colors)
+    "colors": {
+      "model": "accent",
+      "cwd": "accent",
+    },
   },
 
-  // Randomized messages shown in pi's built-in working loader (the
-  // "Working..." line while streaming). A new random message is picked
-  // every `intervalMs`; no repeats until the pool is exhausted. Default on.
+  // Randomized status messages shown while streaming responses
   "workingMessage": {
     "enable": true,
     "intervalMs": 3000,
-    "messages": ["Exploring the seas", "Tinkering with strange objects", "..."]
-  }
-}
-```
-
-## Commands & keybindings
-
-- `/zen_mode` — toggle zen mode (all segments muted except agent-mode).
-- Toggle keybinding: `piZenFrame.zenMode`, default `ctrl+shift+z`. Rebind or
-  disable it in `~/.pi/agent/keybindings.json`:
-
-```jsonc
-// ~/.pi/agent/keybindings.json
-{
-  "piZenFrame.zenMode": "ctrl+shift+z", // or [] to disable; /zen_mode still works
+    "messages": [
+      "Exploring the seas",
+      "Tinkering with strange objects",
+      "Analyzing patterns",
+    ],
+  },
 }
 ```
 
-After editing `keybindings.json`, run `/reload` to apply.
+---
 
-## The frame
+## Structure & Status Segments
 
-The editor's content is boxed with rounded corner glyphs and two live status rails painted into the top and bottom borders.
+The editor window features status indicators embedded along the frame borders:
 
-### Top border (left)
+| Location         | Segment        | Description                                                           |
+| ---------------- | -------------- | --------------------------------------------------------------------- |
+| **Top Left**     | **model**      | Active model name and provider                                        |
+|                  | **reasoning**  | Current reasoning effort level, tinted with pi thinking tokens        |
+|                  | **spinner**    | Active phase indicator (`thinking`, `outputting`, `toolcall`, `exec`) |
+| **Top Right**    | **ctx**        | Context usage percentage and token counts with color alerts           |
+| **Bottom Left**  | **agent mode** | Active agent indicator pill from `pi-agent-manager`                   |
+| **Bottom Right** | **cwd**        | Shortened path, active Git branch, and uncommitted file counts        |
 
-- **model** — active model name + provider, accented.
-- **reasoning** — current thinking level, tinted with pi's own thinking token (`thinkingLow` … `thinkingXhigh`).
-- **spinner** — streaming phase (`thinking` / `outputting` / `toolcall` / `exec`), replaces the left slot while active.
+---
 
-### Top border (right)
+## Commands & Keybindings
 
-- **ctx** — context window usage: percentage + `used/window` tokens. Color winds traffic light (green → warning at ≥50% → red at ≥80%).
+- **Toggle Command**: `/zen_mode` — Toggles Zen mode on and off.
+- **Default Keybinding**: `ctrl+shift+z`
 
-### Bottom border (left)
+To rebind or disable the hotkey, update `~/.pi/agent/keybindings.json`:
 
-- **agent mode** — current pi-agent-manager agent as a colored pill (optional, no hard dependency).
-
-### Bottom border (right)
+```jsonc
+{
+  "piZenFrame.zenMode": "ctrl+shift+z", // Set to [] to disable the shortcut
+}
+```
 
-- **cwd** — working directory (shortened) + git branch and dirty file count.
+Run `/reload` after modifying your keybindings.
 
-All of these are colored with pi `ThemeColor`s, so they follow kanagawa, dark, etc.
+---
 
-## Source layout
+## Directory Layout
 
 ```
 extensions/
-  index.ts            entry: config, events, editor install
-  config/             types, constants, settings loading/normalization
-  components/         header, frame, segments, registry (one file per segment)
-  editor/             FrameEditor (frame + spinner rendering)
-  utils/              agent-mode, git, path, string helpers
+├── index.ts            # Extension entry point: config initialization and events
+├── config/             # Types, defaults, and settings normalization
+├── components/         # Header, frame border, and status segment modules
+├── editor/             # FrameEditor component for layout rendering
+└── utils/              # Helpers for Git status, paths, and agent modes
+
 ```

package/extensions/components/header.ts

@@ -32,6 +32,17 @@ export interface HeaderEnv {
 const RANDOM_TIP =
   HEADER_TIPS[Math.floor(Math.random() * HEADER_TIPS.length)]?.text ?? "";
 
+function wrapLines(
+  lines: string[],
+  maxLen: number,
+  style?: (line: string) => string,
+): string[] {
+  const wrapped = lines.map((l) => wrapTextWithAnsi(l, maxLen)).flat();
+  if (style) return wrapped.map((l) => (l.length ? style(l) : l));
+
+  return wrapped;
+}
+
 export function createHeader(
   _tui: TUI,
   theme: Theme,
@@ -57,29 +68,6 @@ export function createHeader(
     color: settings.header?.logoColor ?? DEFAULT_SETTINGS.header?.logoColor,
   };
 
-  const leftLines = [
-    ...logo.lines.map((l) => theme.fg(logo.color, l)),
-
-    "",
-    "",
-
-    theme.bold(
-      theme.fg(
-        "muted",
-        settings.header?.heading ?? DEFAULT_SETTINGS.header?.heading,
-      ),
-    ),
-
-    "",
-
-    theme.italic(
-      theme.fg(
-        "muted",
-        settings.header?.subheading ?? DEFAULT_SETTINGS.header?.subheading,
-      ),
-    ),
-  ];
-
   const border = (s: string, fg?: ThemeColor) => theme.fg(fg ?? accentColor, s);
 
   /** Space-pad `text` so it sits horizontally centered within `inner` cols. */
@@ -106,7 +94,7 @@ export function createHeader(
   }
 
   /** Right column halves: top = model(+provider), bottom = cwd + git. */
-  function infoRows(env: HeaderEnv): string[] {
+  function infoRows(env: HeaderEnv, width: number): string[] {
     const icons = DEFAULT_ICONS;
     const parts: string[] = [];
 
@@ -123,46 +111,74 @@ export function createHeader(
 
     return [
       theme.bold(border("Model Info")),
-      env.modelName ? theme.fg("muted", `${icons.model} ${env.modelName}`) : "",
+
+      ...wrapLines(
+        [
+          env.modelName
+            ? theme.fg("muted", `${icons.model} ${env.modelName}`)
+            : "",
+        ],
+        width,
+        (str) => theme.fg("muted", str),
+      ),
+
       "",
+
       theme.bold(border("Current Directory")),
       parts.length ? parts.join(" · ") : "",
+
       "",
+
       theme.bold(border("Tip")),
-      theme.fg("muted", RANDOM_TIP),
+      ...wrapLines([RANDOM_TIP], width, (str) => theme.fg("muted", str)),
     ];
   }
 
   return {
     render(width: number): string[] {
-      // Too narrow for a box → fall back to a plain centered logo.
-      if (width < MIN_BOX_WIDTH) {
-        return leftLines;
-      }
-
       const env = getEnv(pi);
-      const rightRows = infoRows(env);
 
       const inner = Math.max(0, width - 2);
       const leftW = Math.floor(inner * LEFT_COL_RATIO);
-      const rightW = inner - leftW - 1; // divider column
+
+      const rightW = inner - leftW - 1;
+
+      const rightLines = infoRows(env, rightW);
+      const leftLines = [
+        ...logo.lines.map((l) => theme.fg(logo.color, l)),
+
+        "",
+        "",
+
+        ...wrapLines(
+          [settings.header?.heading ?? DEFAULT_SETTINGS.header?.heading ?? ""],
+          leftW,
+        ).map((line) => theme.bold(theme.fg("muted", line))),
+
+        "",
+
+        ...wrapLines(
+          [
+            settings.header?.subheading ??
+              DEFAULT_SETTINGS.header?.subheading ??
+              "",
+          ],
+          leftW,
+        ).map((line) => theme.italic(theme.fg("muted", line))),
+      ];
+
+      // Too narrow for a box → fall back to a plain centered logo.
+      if (width < MIN_BOX_WIDTH) {
+        return leftLines;
+      }
 
       // No truncation: overflow wraps onto following lines until it all fits.
-      const leftWrapped = leftLines
-        .map((l) => wrapTextWithAnsi(l, leftW))
-        .flat();
-      const rightWrapped = rightRows
-        .map((r) => wrapTextWithAnsi(r, Math.max(1, rightW - 2))) // 2-col indent
-        .flat();
-
-      const height = Math.max(leftWrapped.length, rightWrapped.length);
-      const logoTop = Math.max(
-        0,
-        Math.floor((height - leftWrapped.length) / 2),
-      );
+      const height = Math.max(leftLines.length, rightLines.length);
+      const logoTop = Math.max(0, Math.floor((height - leftLines.length) / 2));
+
       const rightTop = Math.max(
         0,
-        Math.floor((height - rightWrapped.length) / 2),
+        Math.floor((height - rightLines.length) / 2),
       );
 
       const lines: string[] = [""];
@@ -172,12 +188,10 @@ export function createHeader(
 
       for (let i = 0; i < height; i++) {
         const l = i - logoTop;
-        const leftLine =
-          l >= 0 && l < leftWrapped.length ? leftWrapped[l]! : "";
+        const leftLine = l >= 0 && l < leftLines.length ? leftLines[l]! : "";
 
         const r = i - rightTop;
-        const rightLine =
-          r >= 0 && r < rightWrapped.length ? rightWrapped[r]! : "";
+        const rightLine = r >= 0 && r < rightLines.length ? rightLines[r]! : "";
 
         lines.push(splitRow(leftW, rightW, leftLine, rightLine));
       }

package/package.json

@@ -2,13 +2,14 @@
   "name": "@leo-alvarenga/pi-zen-frame",
   "description": "A pi-coding-agent extension that gives the TUI editor a simple yet polished look and feel",
   "author": "Leonardo A. Alvarenga",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "license": "MIT",
   "repository": "github.com/leo-alvarenga/pi-mono",
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
+    "pi-extension",
     "pi-package",
     "pi"
   ],