@leo-alvarenga/pi-zen-frame 0.16.0 → 0.17.0

package/README.md

@@ -6,8 +6,8 @@ A [`pi-coding-agent`](https://github.com/earendil-works/pi) extension that gives
 
 ## 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
+- **Clean Frame**: Clean editor frame with status segments rendered below the editor
+- **Header Box**: Optional welcome panel with a logo and "Welcome back!" heading, model name, current working directory, Git status, and a random tip
 - **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
 
@@ -18,7 +18,7 @@ A [`pi-coding-agent`](https://github.com/earendil-works/pi) extension that gives
 Run the following command:
 
 ```bash
-pi install @leo-alvarenga/pi-zen-frame
+pi install npm:@leo-alvarenga/pi-zen-frame
 ```
 
 Or add `pi-zen-frame` to your pi packages list in `~/.pi/agent/settings.json`:
@@ -42,14 +42,15 @@ Configuration is loaded from `~/.pi/agent/pi-zen-frame.json`. All properties are
   // Fallback accent color for frame border and active segments
   "accentColor": "accent",
 
-  // Master mute: renders all segments in muted tones except agent-mode
-  "zenMode": true,
+  // Master mute: renders all segments in muted tones except agent-mode (default: false)
+  "zenMode": false,
 
   // Editor-frame renderer by registered name (built-in: "blocky")
   "editorFrame": "blocky",
 
   "header": {
-    "enable": true,
+    // Welcome panel is opt-in (default: false)
+    "enable": false,
     // Header renderer by registered name (built-in: "basic")
     "type": "basic",
   },
@@ -73,6 +74,7 @@ Configuration is loaded from `~/.pi/agent/pi-zen-frame.json`. All properties are
   "workingMessage": {
     "enable": true,
     "intervalMs": 3000,
+    // Omit to use the built-in message pool
     "messages": [
       "Exploring the seas",
       "Tinkering with strange objects",
@@ -86,16 +88,16 @@ Configuration is loaded from `~/.pi/agent/pi-zen-frame.json`. All properties are
 
 ## Structure & Status Segments
 
-The editor window features status indicators embedded along the frame borders:
+The editor frame shows status indicators in two rows below the editor:
 
-| 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        |
+| Location           | Segment        | Description                                                           |
+| ------------------ | -------------- | --------------------------------------------------------------------- |
+| Editor band (left) | **agent mode** | Active agent indicator pill from `pi-agent-manager`                   |
+|                    | **model**      | Active model name and provider                                        |
+|                    | **reasoning**  | Current reasoning effort level, tinted with pi thinking tokens        |
+|                    | **spinner**    | Active phase indicator (`thinking`, `outputting`, `toolcall`, `exec`); replaces the row while streaming when `showSpinner` is enabled (default off) |
+| Footer (left)      | **cwd**        | Shortened path, active Git branch, and uncommitted file counts        |
+| Footer (right)     | **ctx**        | Context usage percentage and token counts with color alerts           |
 
 ---
 
@@ -122,9 +124,9 @@ Run `/reload` after modifying your keybindings.
 extensions/
 ├── index.ts            # Extension entry point: config initialization and events
 ├── config/             # Types, defaults, and settings normalization
-├── components/         # Header (BasicHeader), frame border, and status segment modules
+├── components/         # Status segments, header, and frame layout helpers
 ├── editor/             # BlockyEditor editor-frame renderer
 ├── renderers/          # Renderer registry + swap-in API (blocky / basic)
-└── utils/              # Helpers for Git status, paths, and agent modes
+└── utils/              # Helpers for Git status, paths, agent modes, and token usage
 
 ```

package/extensions/components/notify.ts

@@ -0,0 +1,13 @@
+import type { SegmentDef } from "./types";
+
+/** Box bottom (left): pi-notify bell, right before the model segment.
+ *  Accent when notifications are on, muted bell-off otherwise */
+export const notifySegment: SegmentDef = {
+  id: "notify",
+  slot: "topLeft",
+  render: (d, { icons, theme }) => {
+    const color = d.notifyEnabled && !d.zenMode ? d.accentColor : "muted";
+
+    return theme.fg(color, ` ${d.notifyEnabled ? icons.bell : icons.bellOff} `);
+  },
+};

package/extensions/components/registry.ts

@@ -5,6 +5,7 @@
  * The frame calls `segmentsFor(slot, ...)` and handles all width/joining.
  */
 import { modelSegment } from "./model";
+import { notifySegment } from "./notify";
 import { reasoningSegment } from "./reasoning";
 import { spinnerSegment } from "./spinner";
 import { tokenCountSegment } from "./token-count";
@@ -14,6 +15,7 @@ import type { FrameData, SegmentContext, SegmentDef, Slot } from "./types";
 
 export const segments: SegmentDef[] = [
   agentModeSegment,
+  notifySegment,
   modelSegment,
   reasoningSegment,
   spinnerSegment,

package/extensions/components/types.ts

@@ -56,6 +56,9 @@ export interface FrameData {
   agentMode: AgentMode;
 
   context: TokenUsage | null;
+
+  /** pi-notify toggle state (true = notifications enabled). */
+  notifyEnabled: boolean;
 }
 
 /** Data + rendering helpers handed to every segment. */
@@ -94,4 +97,5 @@ export interface ExternalData {
   modelProvider: string | undefined;
   thinkingLevel: string | undefined;
   spinnerPhase: SpinnerPhase | null;
+  notifyEnabled: boolean;
 }

package/extensions/config/constants/contracts.ts

@@ -5,6 +5,9 @@
 export const PI_AGENT_MANAGER_AGENT_EVENT = "pi-agent-manager:agent-changed";
 export const PI_AGENT_MANAGER_AGENT_DATA_KEY = "pi-agent-manager-agent";
 
+/** pi-notify integration (optional — no hard dependency). */
+export const PI_NOTIFY_TOGGLE_EVENT = "pi-notify:toggle-changed";
+
 /** Keybinding id users bind in keybindings.json to toggle zen mode. */
 export const ZEN_MODE_SHORTCUT_ID = "piZenFrame.zenMode";
 /** Default key when the user hasn't bound one (override or disable via

package/extensions/config/constants/visuals.ts

@@ -21,6 +21,8 @@ export const DEFAULT_ICONS: FrameIcons = {
   gitDirty: "",
   thinking: "󰌶",
   gitBranch: "",
+  bell: "󰂚",
+  bellOff: "󰂛",
 };
 
 /** Thinking level → theme token, mirroring pi's own border-color mapping. */

package/extensions/config/types.ts

@@ -19,6 +19,8 @@ export interface FrameIcons {
   thinking: string;
   gitDirty: string;
   gitBranch: string;
+  bell: string;
+  bellOff: string;
 }
 
 /**

package/extensions/editor/blocky-editor.ts

@@ -98,6 +98,7 @@ export class BlockyEditor extends CustomEditor {
       thinkingLevel: ext.thinkingLevel,
       spinnerFrame: this.spinnerFrame(),
       accentColor: this.opts.accentColor,
+      notifyEnabled: ext.notifyEnabled,
     };
 
     let prefix = "┃";

package/extensions/index.ts

@@ -21,6 +21,7 @@ import type { KeyId } from "@earendil-works/pi-tui";
 import {
   DEFAULT_SETTINGS,
   PI_AGENT_MANAGER_AGENT_EVENT,
+  PI_NOTIFY_TOGGLE_EVENT,
   SPINNER_FRAMES,
   ZEN_MODE_DEFAULT_KEY,
   ZEN_MODE_SHORTCUT_ID,
@@ -44,6 +45,7 @@ let currentCtx: ExtensionContext | null = null;
 let settings: Settings = DEFAULT_SETTINGS;
 let spinnerPhase: SpinnerPhase | null = null;
 let agentMode: AgentMode = null;
+let notifyEnabled = false;
 let zenMode = true;
 let git: GitInfo = {
   branch: undefined,
@@ -99,6 +101,7 @@ function provideExternal(pi: ExtensionAPI): ExternalData {
     thinkingLevel: pi.getThinkingLevel(),
     modelName: model?.name ?? model?.id ?? "Unknown",
     modelProvider: capitalize(model?.provider ?? "unknown"),
+    notifyEnabled,
   };
 }
 
@@ -174,6 +177,13 @@ export default async function (pi: ExtensionAPI) {
     editor?.refresh();
   });
 
+  // Optional pi-notify integration (no hard dependency).
+  pi.events.on(PI_NOTIFY_TOGGLE_EVENT, (event) => {
+    const enabled = (event as { enabled?: unknown } | undefined)?.enabled;
+    if (typeof enabled === "boolean") notifyEnabled = enabled;
+    editor?.refresh();
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
     agentMode = readAgentModeFromSession(ctx) || agentMode;

package/package.json

@@ -2,7 +2,7 @@
   "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.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "repository": "github.com/leo-alvarenga/pi-mono",
   "publishConfig": {