@leo-alvarenga/pi-zen-frame 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo A. Alvarenga
+
+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,148 @@
+# 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.
+
+![Preview](./docs/preview.png)
+
+## Install
+
+It's distributed as a pi package. Add it to `settings.json` → `packages`, e.g. install from
+a local checkout or registry:
+
+```jsonc
+// ~/.pi/agent/settings.json
+{
+  "packages": ["npm:@leo-alvarenga/pi-zen-frame", "path/to/pi-zen-frame"],
+}
+```
+
+Restart pi (or `/reload`).
+
+## Config
+
+zen editor reads `~/.pi/agent/pi-zen-frame.json`. All keys are optional; defaults are shown.
+
+```jsonc
+{
+  // Accent used by segments/frame when a more specific color isn't set.
+  "accentColor": "accent",
+
+  // Master mute: every segment except agent-mode renders muted.
+  // Toggle at runtime with /zen_mode or the piZenFrame.zenMode keybinding.
+  "zenMode": true,
+
+  "header": {
+    "enable": true,
+    "logo": [" ", "██████████", "███   ███ ", "██████    ", ...],
+    "heading": "Zen Pi",
+    "subheading": "A pi-coding-agent powered terminal editor",
+    "logoColor": "text",
+    "accentColor": "customMessageLabel"
+  },
+
+  "frame": {
+    "enable": true,
+    // Below this terminal width the box is skipped (plain editor).
+    "minWidth": 20,
+
+    // Blank lines inside the box (padding) / outside it (margin).
+    "paddingTop": 1,
+    "paddingBottom": 1,
+    "paddingX": 1,
+    "marginTop": 0,
+    "marginBottom": 0,
+
+    // Border segments on/off.
+    "showCwd": true,
+    "showModel": true,
+    "showContext": true,
+    "showThinking": true,
+    "showSpinner": false,
+    "showAgentMode": true,
+
+    // Defaults to accentColor, then "border"; Can also be set to "agentMode" to match the current agent's color
+    "borderColor": "border",
+
+    // Glyph shown before the editor content. Default "❯".
+    "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" }
+  },
+
+  // 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.
+  "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
+}
+```
+
+After editing `keybindings.json`, run `/reload` to apply.
+
+## The frame
+
+The editor's content is boxed with rounded corner glyphs and two live status rails painted into the top and bottom borders.
+
+### Top border (left)
+
+- **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)
+
+- **ctx** — context window usage: percentage + `used/window` tokens. Color winds traffic light (green → warning at ≥50% → red at ≥80%).
+
+### Bottom border (left)
+
+- **agent mode** — current pi-agent-manager agent as a colored pill (optional, no hard dependency).
+
+### Bottom border (right)
+
+- **cwd** — working directory (shortened) + git branch and dirty file count.
+
+All of these are colored with pi `ThemeColor`s, so they follow kanagawa, dark, etc.
+
+## Source 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
+```

package/extensions/components/agent-mode.ts

@@ -0,0 +1,25 @@
+import { capitalize } from "../utils";
+import type { SegmentDef } from "./types";
+
+/** Top-right: the current Agent Mode from pi-agent-manager (when installed).
+ *  Rendered as a pill using the agent's own color/icon. */
+export const agentModeSegment: SegmentDef = {
+  id: "agent-mode",
+  slot: "bottomLeft",
+  enabled: (_d, cfg) => cfg.showAgentMode !== false,
+
+  render: (d, { theme, segColor }) => {
+    const m = d.agentMode;
+    if (!m) return "";
+
+    // Agent's own color wins; frame.colors.agentMode fills in; zen never mutes.
+    const color = m.color ?? segColor("agentMode", d.accentColor);
+    const label = theme.bold(` ${m.icon ?? "◆"} ${capitalize(m.name)} `);
+
+    try {
+      return theme.fg(color, label);
+    } catch {
+      return theme.fg(d.accentColor, label);
+    }
+  },
+};

package/extensions/components/cwd.ts

@@ -0,0 +1,31 @@
+import type { SegmentDef } from "./types";
+import { getShortCwd } from "../utils";
+
+/** Bottom-right: working directory + git branch (with dirty count). */
+export const cwdSegment: SegmentDef = {
+  id: "cwd",
+  slot: "bottomRight",
+  enabled: (_d, cfg) => cfg.showCwd !== false,
+  render: (d, { theme, icons, segColor }) => {
+    const folder = getShortCwd(d.cwd);
+
+    let text = theme.fg(
+      segColor("cwd", "muted"),
+      `${icons.folder} ${folder}`,
+    );
+
+    if (d.gitBranch) {
+      let git = ` ${icons.gitBranch} ${d.gitBranch}`;
+      text += theme.fg(segColor("cwd", d.accentColor), git);
+
+      if (d.gitDirty > 0) {
+        text += theme.fg(
+          segColor("cwd", "error"),
+          ` ${icons.gitDirty} ${d.gitDirty}`,
+        );
+      }
+    }
+
+    return ` ${text} `;
+  },
+};

package/extensions/components/frame.ts

@@ -0,0 +1,140 @@
+/**
+ * The box. Wraps the base editor's rows (rendered narrower) with rounded
+ * corner glyphs, embeds the segment text into the top/bottom border, and
+ * inserts the configurable blank padding lines inside the box.
+ *
+ * Row budget: content is rendered at `width - 2 - 2*paddingX`, wrapped with
+ * `paddingX` spaces + a `│` on each side, so every output row is exactly
+ * `width` columns — same contract as the default editor.
+ */
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export interface FrameOptions {
+  width: number;
+  prefix?: string;
+  paddingX: number;
+  paddingTop: number;
+  paddingBottom: number;
+  border: (str: string) => string;
+}
+
+const SGR_RE = /\x1b\[[0-9;]*m/g;
+const CURSOR_MARKER_RE = /\x1b_pi:c\x07/g;
+
+function plain(row: string): string {
+  return row.replace(SGR_RE, "").replace(CURSOR_MARKER_RE, "");
+}
+
+/** A border row is all `─`, or a `─── ↑/↓ N more ───` scroll indicator. */
+function isBorderRow(row: string): boolean {
+  const t = plain(row).trim();
+
+  if (t === "") return true;
+  if (/^─+$/.test(t)) return true;
+
+  return /^─── [↑↓] \d+ more ─*$/.test(t);
+}
+
+/** Lay one border row: cap + leftText + ─fill + rightText + cap, always
+ *  exactly `width` columns. Right text truncates first, then left text. */
+export function fitFrameRow(
+  leftCap: string,
+  rightCap: string,
+  leftText: string,
+  rightText: string,
+  width: number,
+  border: (str: string) => string,
+): string {
+  const minGap = 3;
+  const inner = Math.max(0, width - 2); // space between the two caps
+  const rightText2 = truncateToWidth(
+    rightText,
+    Math.max(0, inner - minGap),
+    "",
+  );
+
+  const leftBudget = Math.max(0, inner - minGap - visibleWidth(rightText2));
+  const leftText2 = truncateToWidth(leftText, leftBudget, "");
+
+  const fill = Math.max(
+    0,
+    inner - visibleWidth(leftText2) - visibleWidth(rightText2),
+  );
+
+  return (
+    border(leftCap) +
+    leftText2 +
+    border("─".repeat(fill)) +
+    rightText2 +
+    border(rightCap)
+  );
+}
+
+/** Lay one info row: leftText + spaces + rightText, exactly `width` cols.
+ *  No border caps — plain text with gap fill. Right truncates first. */
+export function fitInfoRow(
+  leftText: string,
+  rightText: string,
+  width: number,
+): string {
+  const minGap = 3;
+  const rightText2 = truncateToWidth(
+    rightText,
+    Math.max(0, width - minGap),
+    "",
+  );
+  const leftBudget = Math.max(0, width - minGap - visibleWidth(rightText2));
+  const leftText2 = truncateToWidth(leftText, leftBudget, "");
+  const fill = Math.max(
+    0,
+    width - visibleWidth(leftText2) - visibleWidth(rightText2),
+  );
+  return leftText2 + " ".repeat(fill) + rightText2;
+}
+
+function wrapContent(row: string, paddingX: number): string {
+  if (paddingX <= 0) return row;
+
+  return " ".repeat(paddingX) + row + " ".repeat(paddingX);
+}
+
+export function renderFrame(inner: string[], opts: FrameOptions): string[] {
+  const { border, width, paddingX, prefix } = opts;
+  if (inner.length === 0) return inner;
+
+  // The real bottom border is the last border-like row (autocomplete rows
+  // are appended *after* it, so the last row is NOT necessarily the bottom).
+  let bottomIdx = inner.length - 1;
+
+  for (let i = inner.length - 1; i >= 0; i--) {
+    if (isBorderRow(inner[i]!)) {
+      bottomIdx = i;
+      break;
+    }
+  }
+
+  const result: string[] = [];
+  const padRow = " ".repeat(Math.max(0, width));
+  const fullBorder = border("─".repeat(width));
+
+  result.push(fullBorder);
+
+  for (let i = 0; i < opts.paddingTop; i++) result.push(padRow);
+
+  for (let i = 1; i < bottomIdx; i++) {
+    const decorator = i === 1 ? (prefix ?? "") : "";
+    const content = decorator + inner[i]!;
+
+    result.push(wrapContent(content, paddingX - visibleWidth(decorator)));
+  }
+
+  for (let i = 0; i < opts.paddingBottom; i++) result.push(padRow);
+
+  result.push(fullBorder);
+
+  for (let i = bottomIdx + 1; i < inner.length; i++) {
+    result.push(wrapContent(inner[i]!, paddingX));
+  }
+
+  return result;
+}

package/extensions/components/header.ts

@@ -0,0 +1,192 @@
+import type { TUI } from "@earendil-works/pi-tui";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type {
+  ExtensionAPI,
+  Theme,
+  ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  DEFAULT_ICONS,
+  DEFAULT_SETTINGS,
+  HEADER_TIPS,
+} from "../config/constants";
+import type { Settings } from "../config/types";
+import { fitFrameRow } from "./frame";
+import { getShortCwd } from "../utils";
+
+/** Below which terminal width the box is skipped (plain logo). */
+const MIN_BOX_WIDTH = 20;
+const LEFT_COL_RATIO = 0.4; // logo column width / total width
+
+/** Live env snapshot the header renders in the right column. */
+export interface HeaderEnv {
+  gitBranch: string | undefined;
+  gitDirty: number;
+  cwd: string;
+
+  /** Combined display name, e.g. `"Model (Provider)"` (provider embedded). */
+  modelName: string | undefined;
+}
+
+const RANDOM_TIP =
+  HEADER_TIPS[Math.floor(Math.random() * HEADER_TIPS.length)]?.text ?? "";
+
+export function createHeader(
+  _tui: TUI,
+  theme: Theme,
+  pi: ExtensionAPI,
+  settings: Settings,
+  getEnv: (pi: ExtensionAPI) => HeaderEnv,
+) {
+  if (!settings.header?.enable) {
+    return {
+      render(): string[] {
+        return [];
+      },
+
+      invalidate() {},
+    };
+  }
+
+  const accentColor =
+    settings.header?.accentColor ?? settings.accentColor ?? "accent";
+
+  const logo = {
+    lines: settings.header?.logo ?? DEFAULT_SETTINGS.header?.logo ?? [],
+    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. */
+  function center(text: string, inner: number): string {
+    const w = visibleWidth(text);
+    const left = Math.max(0, Math.floor((inner - w) / 2));
+    const right = Math.max(0, inner - w - left);
+
+    return " ".repeat(left) + text + " ".repeat(right);
+  }
+
+  /** Claude-style split row: │ logo (leftW) │ info (rightW) │, exactly `width` cols. */
+  function splitRow(
+    leftW: number,
+    rightW: number,
+    left: string,
+    right: string,
+  ): string {
+    const left2 = center(left, leftW);
+    const right2 = "  " + right;
+    const pad = " ".repeat(Math.max(0, rightW - visibleWidth(right2)));
+
+    return border("│") + left2 + border("│") + right2 + pad + border("│");
+  }
+
+  /** Right column halves: top = model(+provider), bottom = cwd + git. */
+  function infoRows(env: HeaderEnv): string[] {
+    const icons = DEFAULT_ICONS;
+    const parts: string[] = [];
+
+    if (env.cwd) {
+      parts.push(theme.fg("muted", `${icons.folder} ${getShortCwd(env.cwd)}`));
+    }
+    if (env.gitBranch) {
+      parts.push(theme.fg(accentColor, `${icons.gitBranch} ${env.gitBranch}`));
+
+      if (env.gitDirty > 0) {
+        parts.push(theme.fg("error", `${icons.gitDirty} ${env.gitDirty}`));
+      }
+    }
+
+    return [
+      theme.bold(border("Model Info")),
+      env.modelName ? theme.fg("muted", `${icons.model} ${env.modelName}`) : "",
+      "",
+      theme.bold(border("Current Directory")),
+      parts.length ? parts.join(" · ") : "",
+      "",
+      theme.bold(border("Tip")),
+      theme.fg("muted", RANDOM_TIP),
+    ];
+  }
+
+  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
+
+      // 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 rightTop = Math.max(
+        0,
+        Math.floor((height - rightWrapped.length) / 2),
+      );
+
+      const lines: string[] = [""];
+
+      lines.push(fitFrameRow("╭", "╮", "", "", width, border));
+      lines.push(splitRow(leftW, rightW, "", ""));
+
+      for (let i = 0; i < height; i++) {
+        const l = i - logoTop;
+        const leftLine =
+          l >= 0 && l < leftWrapped.length ? leftWrapped[l]! : "";
+
+        const r = i - rightTop;
+        const rightLine =
+          r >= 0 && r < rightWrapped.length ? rightWrapped[r]! : "";
+
+        lines.push(splitRow(leftW, rightW, leftLine, rightLine));
+      }
+
+      lines.push(splitRow(leftW, rightW, "", ""));
+      lines.push(fitFrameRow("╰", "╯", "", "", width, border));
+
+      return lines;
+    },
+    invalidate() {},
+  };
+}

package/extensions/components/model.ts

@@ -0,0 +1,16 @@
+import type { SegmentDef } from "./types";
+
+/** Top-left: the active model name. */
+export const modelSegment: SegmentDef = {
+  id: "model",
+  slot: "topLeft",
+  enabled: (_d, cfg) => cfg.showModel !== false,
+  render: (d, { theme, icons, segColor }) => {
+    if (!d.modelName) return "";
+
+    return theme.fg(
+      segColor("model", d.accentColor),
+      ` ${icons.model} ${d.modelName} `,
+    );
+  },
+};

package/extensions/components/reasoning.ts

@@ -0,0 +1,22 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import type { SegmentDef } from "./types";
+import { THINKING_TOKEN } from "../config/constants";
+
+/** Top-left (after model): the current thinking level, tinted with its own
+ *  theme token — the same color pi applies to the border at that level. */
+export const reasoningSegment: SegmentDef = {
+  id: "reasoning",
+  slot: "topLeft",
+  enabled: (_d, cfg) => cfg.showThinking !== false,
+  render: (d, { theme, icons, segColor }) => {
+    if (!d.thinkingLevel) return "";
+    const token = (THINKING_TOKEN[d.thinkingLevel] ??
+      "thinkingText") as ThemeColor;
+
+    return theme.fg(
+      segColor("thinking", token),
+      ` ${icons.thinking} ${d.thinkingLevel} `,
+    );
+  },
+};

package/extensions/components/registry.ts

@@ -0,0 +1,42 @@
+/**
+ * Segment registry. To add a new component:
+ *   1. create `extensions/components/<name>.ts` exporting a `SegmentDef`
+ *   2. import it here and append to `segments`
+ * The frame calls `segmentsFor(slot, ...)` and handles all width/joining.
+ */
+import { modelSegment } from "./model";
+import { reasoningSegment } from "./reasoning";
+import { spinnerSegment } from "./spinner";
+import { tokenCountSegment } from "./token-count";
+import { cwdSegment } from "./cwd";
+import { agentModeSegment } from "./agent-mode";
+import type { FrameData, SegmentContext, SegmentDef, Slot } from "./types";
+
+export const segments: SegmentDef[] = [
+  modelSegment,
+  reasoningSegment,
+  spinnerSegment,
+  tokenCountSegment,
+  agentModeSegment,
+  cwdSegment,
+];
+
+/** Render all segments for a slot, joined with " · ". A `replaces` segment
+ *  (e.g. the spinner during an active phase) takes the whole slot. */
+export function segmentsFor(
+  slot: Slot,
+  d: FrameData,
+  ctx: SegmentContext,
+): string {
+  const defs = segments.filter(
+    (s) => s.slot === slot && (!s.enabled || s.enabled(d, ctx.cfg)),
+  );
+
+  const replacer = defs.find((s) => s.replaces?.(d, ctx.cfg));
+  const active = replacer ? [replacer] : defs;
+
+  return active
+    .map((s) => s.render(d, ctx))
+    .filter((t) => t !== "")
+    .join(ctx.border("·"));
+}

package/extensions/components/spinner.ts

@@ -0,0 +1,24 @@
+import type { SegmentDef } from "./types";
+
+/** Status animation. When a phase is active it REPLACES the top-left slot
+ *  (model + reasoning) until the phase ends. */
+export const spinnerSegment: SegmentDef = {
+  id: "spinner",
+  slot: "topLeft",
+  enabled: (d, cfg) =>
+    cfg.showSpinner === true &&
+    d.spinnerPhase !== null &&
+    d.spinnerPhase !== "idle",
+  render: (d, { theme }) => {
+    let phase = d.spinnerPhase ?? "thinking";
+
+    // No frame.colors key for the spinner; zen mutes it, else accent.
+    const spinner = theme.fg(
+      d.zenMode ? "muted" : d.accentColor,
+      ` ${d.spinnerFrame} `,
+    );
+    if (phase === "idle") return spinner;
+
+    return spinner + theme.fg("muted", `${phase} `);
+  },
+};