@leo-alvarenga/pi-zen-frame 0.11.0

package/extensions/editor/frame-editor.ts

@@ -0,0 +1,197 @@
+/**
+ * FrameEditor — the editor component. Subclasses CustomEditor so all of
+ * pi's editing/undo/app-keybinding machinery keeps working; `render` layers
+ * the box frame. Vim behavior was removed — all input passes through to the
+ * base editor. Appearance lives in `components/` (segments + frame).
+ */
+import {
+  CustomEditor,
+  ThemeColor,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+
+import { DEFAULT_ICONS, SPINNER_FRAMES } from "../config/constants";
+import type { FrameSettings, SpinnerPhase } from "../config/types";
+import { renderFrame, fitInfoRow } from "../components/frame";
+import { segmentsFor } from "../components/registry";
+import type {
+  ExternalData,
+  FrameData,
+  SegmentContext,
+} from "../components/types";
+import { isThemeColor } from "../utils";
+
+export interface FrameEditorOptions {
+  frame: FrameSettings;
+  accentColor: ThemeColor;
+}
+
+export class FrameEditor extends CustomEditor {
+  private pi: ExtensionAPI;
+  private opts: FrameEditorOptions;
+  private provider: (pi: ExtensionAPI) => ExternalData;
+
+  private spinnerIdx = 0;
+  private spinnerPhase: SpinnerPhase | null = null;
+  private spinnerTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    pi: ExtensionAPI,
+    provider: (pi: ExtensionAPI) => ExternalData,
+    opts: FrameEditorOptions,
+    ...args: ConstructorParameters<typeof CustomEditor>
+  ) {
+    super(...args);
+
+    this.pi = pi;
+    this.opts = opts;
+    this.provider = provider;
+  }
+
+  setSpinner(phase: SpinnerPhase | null): void {
+    if (this.spinnerPhase === phase) return;
+
+    this.spinnerIdx = 0;
+    this.spinnerPhase = phase;
+    this.clearSpinnerTimer();
+
+    if (phase && SPINNER_FRAMES[phase]) {
+      const frames = SPINNER_FRAMES[phase];
+
+      this.spinnerTimer = setInterval(() => {
+        this.spinnerIdx = (this.spinnerIdx + 1) % frames.length;
+        this.tui.requestRender();
+      }, 80);
+    }
+
+    this.tui.requestRender();
+  }
+
+  stopSpinner(): void {
+    this.clearSpinnerTimer();
+    this.spinnerPhase = null;
+  }
+
+  refresh(): void {
+    this.tui.requestRender();
+  }
+
+  // ── rendering ──────────────────────────────────────────────────────────
+
+  render(width: number): string[] {
+    const frame = this.opts.frame;
+
+    const padX = Math.min(
+      frame.paddingX ?? 1,
+      Math.max(0, Math.floor((width - 2) / 2)),
+    );
+
+    const innerWidth = width - 2 - padX * 2;
+    if (innerWidth < 8) return super.render(width);
+
+    const ext = this.provider(this.pi);
+    const d: FrameData = {
+      cwd: ext.cwd,
+      context: ext.context,
+      gitDirty: ext.gitDirty,
+      agentMode: ext.agentMode,
+      gitBranch: ext.gitBranch,
+      modelName: ext.modelName,
+      spinnerPhase: ext.spinnerPhase,
+      thinkingLevel: ext.thinkingLevel,
+      spinnerFrame: this.spinnerFrame(),
+      accentColor: this.opts.accentColor,
+      zenMode: ext.zenMode,
+    };
+
+    let prefix = frame.prefix ?? "❯";
+
+    if (ext.theme?.fg) {
+      let borderColor: ThemeColor = "accent";
+
+      if (frame.borderColor === "agentMode") {
+        borderColor = ext.agentMode?.color ?? "accent";
+      } else {
+        borderColor = frame.borderColor ?? "accent";
+      }
+
+      let prefixColor: ThemeColor = "text";
+      if (frame.prefixColor === "agentMode") {
+        prefixColor = ext.agentMode?.color ?? "accent";
+      } else if (frame.prefixColor === "frameBorder") {
+        prefixColor = borderColor;
+      } else if (frame.prefixColor && isThemeColor(frame.prefixColor)) {
+        prefixColor = frame.prefixColor;
+      }
+
+      prefix = ext.theme.fg(prefixColor, prefix);
+
+      this.borderColor = (s: string) => ext.theme!.fg(borderColor, s);
+    }
+
+    // No theme (non-TUI) or frame disabled or too narrow → plain editor.
+    if (!ext.theme || !frame.enable || width < (frame.minWidth ?? 20)) {
+      return super.render(width);
+    }
+
+    const inner = super.render(innerWidth);
+    const ctx: SegmentContext = {
+      cfg: frame,
+      theme: ext.theme,
+      border: this.borderColor,
+      icons: {
+        ...DEFAULT_ICONS,
+        ...frame.icons,
+      },
+      segColor: (key, fallback) =>
+        d.zenMode && key !== "agentMode"
+          ? "muted"
+          : (frame.colors?.[key] ?? fallback),
+    };
+
+    const topLine = fitInfoRow(
+      segmentsFor("topLeft", d, ctx),
+      segmentsFor("topRight", d, ctx),
+      width,
+    );
+
+    const bottomLine = fitInfoRow(
+      segmentsFor("bottomLeft", d, ctx),
+      segmentsFor("bottomRight", d, ctx),
+      width,
+    );
+
+    const box = renderFrame(inner, {
+      width,
+      prefix,
+      paddingX: padX,
+      border: this.borderColor,
+      paddingTop: frame.paddingTop ?? 1,
+      paddingBottom: frame.paddingBottom ?? 1,
+    });
+
+    // Blank rows OUTSIDE the box, above/below its borders.
+    const marginRow = " ".repeat(width);
+    const marginTop = Array(Math.max(0, frame.marginTop ?? 0)).fill(marginRow);
+    const marginBottom = Array(Math.max(0, frame.marginBottom ?? 0)).fill(
+      marginRow,
+    );
+
+    return [...marginTop, topLine, ...box, bottomLine, ...marginBottom];
+  }
+
+  private spinnerFrame(): string {
+    if (!this.spinnerPhase) return "";
+
+    const frames = SPINNER_FRAMES[this.spinnerPhase]!;
+
+    return frames[this.spinnerIdx % frames.length]!;
+  }
+
+  private clearSpinnerTimer(): void {
+    if (this.spinnerTimer) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+    }
+  }
+}

package/extensions/index.ts

@@ -0,0 +1,261 @@
+/**
+ * pi-zen-frame entry. Thin wiring layer:
+ *   - loads config, subscribes to pi lifecycle + mode/agent-mode events
+ *   - installs FrameEditor via setEditorComponent (factory is re-run on
+ *     model switch — the old instance's spinner timer is stopped first)
+ *   - assembles ExternalData per paint (model, thinking, context, git, ...)
+ *
+ * All appearance logic lives in components/ (segments + frame); the editor
+ * component lives in editor/. Nothing here renders anything.
+ */
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+import {
+  DEFAULT_SETTINGS,
+  PI_AGENT_MANAGER_AGENT_EVENT,
+  SPINNER_FRAMES,
+  ZEN_MODE_DEFAULT_KEY,
+  ZEN_MODE_SHORTCUT_ID,
+} from "./config/constants";
+import { loadSettings } from "./config/settings";
+import type { Settings, SpinnerPhase } from "./config/types";
+import type { AgentMode, AgentState, ExternalData } from "./components/types";
+import { FrameEditor } from "./editor/frame-editor";
+import {
+  capitalize,
+  readAgentModeFromSession,
+  readGit,
+  type GitInfo,
+} from "./utils";
+import { createHeader, type HeaderEnv } from "./components/header";
+
+let editor: FrameEditor | null = null;
+let currentCtx: ExtensionContext | null = null;
+let settings: Settings = DEFAULT_SETTINGS;
+let spinnerPhase: SpinnerPhase | null = null;
+let agentMode: AgentMode = null;
+let zenMode = true;
+let git: GitInfo = {
+  branch: undefined,
+  dirty: 0,
+};
+let workingMessageTimer: ReturnType<typeof setInterval> | null = null;
+let workingMessageBag: string[] = [];
+
+/** Pop a random message; reshuffles when the pool is exhausted (no back-to-back repeats). */
+function nextWorkingMessage(): string {
+  if (workingMessageBag.length === 0) {
+    workingMessageBag = [...(settings.workingMessage?.messages ?? [])];
+
+    for (let i = workingMessageBag.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [workingMessageBag[i], workingMessageBag[j]] = [
+        workingMessageBag[j],
+        workingMessageBag[i],
+      ];
+    }
+  }
+
+  return (workingMessageBag.pop() ?? "").concat("...");
+}
+
+// ── data sources ─────────────────────────────────────────────────────────
+//
+
+/** Live env snapshot for the header's right column. Reads current git/ctx so
+ *  model switches are reflected on the next render. */
+function getHeaderEnv(pi: ExtensionAPI): HeaderEnv {
+  return {
+    gitDirty: git.dirty,
+    gitBranch: git.branch,
+    cwd: currentCtx?.cwd ?? "",
+    modelName: provideExternal(pi).modelName,
+  };
+}
+
+function provideExternal(pi: ExtensionAPI): ExternalData {
+  const ctx = currentCtx;
+  const usage = ctx?.getContextUsage?.();
+  const model = ctx?.model;
+
+  return {
+    zenMode,
+    agentMode,
+    spinnerPhase,
+    cwd: ctx?.cwd ?? "",
+    gitDirty: git.dirty,
+    gitBranch: git.branch,
+    theme: ctx?.ui.theme,
+    thinkingLevel: pi.getThinkingLevel(),
+    modelName: `${model?.name ?? model?.id ?? "Unknown"} (${capitalize(model?.provider ?? "unknown")})`,
+    context: usage
+      ? {
+          tokens: usage.tokens,
+          window: usage.contextWindow,
+          percent: usage.percent,
+        }
+      : null,
+  };
+}
+
+function setSpinner(phase: SpinnerPhase | null): void {
+  if (spinnerPhase === phase) return;
+
+  spinnerPhase = phase;
+  editor?.setSpinner(phase);
+}
+
+/** Keys bound to the zen toggle in keybindings.json; default key if unset.
+ *  `[]` disables the shortcut (the /zen_mode command still works). */
+function zenModeKeys(): string[] {
+  try {
+    const raw = JSON.parse(
+      readFileSync(join(getAgentDir(), "keybindings.json"), "utf8"),
+    ) as Record<string, unknown>;
+    const v = raw[ZEN_MODE_SHORTCUT_ID];
+    if (typeof v === "string") return [v];
+    if (Array.isArray(v) && v.every((k) => typeof k === "string")) return v;
+  } catch {
+    /* no keybindings file → default key */
+  }
+
+  return [ZEN_MODE_DEFAULT_KEY];
+}
+
+function toggleZenMode(): boolean {
+  zenMode = !zenMode;
+  editor?.refresh();
+  return zenMode;
+}
+
+function notifyZen(ctx: {
+  ui: { notify(message: string, type?: "info" | "warning" | "error"): void };
+}): void {
+  ctx.ui.notify(toggleZenMode() ? "Zen mode: on" : "Zen mode: off", "info");
+}
+
+// ── extension entry ──────────────────────────────────────────────────────
+
+export default async function (pi: ExtensionAPI) {
+  settings = await loadSettings();
+  zenMode = settings.zenMode !== false;
+
+  pi.registerCommand("zen_mode", {
+    description:
+      "Toggle Editor Zen mode (all segments muted except agent mode)",
+    handler: async (_, ctx) => notifyZen(ctx),
+  });
+
+  for (const key of zenModeKeys()) {
+    pi.registerShortcut(key as KeyId, {
+      description: "Toggle Zen mode",
+      handler: (ctx) => notifyZen(ctx),
+    });
+  }
+
+  // Optional pi-agent-manager integration (no hard dependency).
+  pi.events.on(PI_AGENT_MANAGER_AGENT_EVENT, (event) => {
+    const state = event as AgentState | undefined;
+
+    if (state?.currentAgentConfig?.name) {
+      agentMode = {
+        icon: state.currentAgentConfig.icon,
+        color: state.currentAgentConfig.color,
+        name: state.currentAgentLabel || state.currentAgentConfig.name,
+      };
+    } else if (state) {
+      agentMode = { name: state.currentAgentLabel || state.currentAgent };
+    }
+
+    editor?.refresh();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    agentMode = readAgentModeFromSession(ctx) || agentMode;
+
+    git = readGit(ctx.cwd);
+
+    ctx.ui.setWorkingIndicator({
+      intervalMs: 80,
+      frames: SPINNER_FRAMES.outputting,
+    });
+
+    // Rotating messages in the built-in working loader while streaming.
+    const wm = settings.workingMessage;
+    if (wm && wm.enable !== false && (wm.messages?.length ?? 0) > 0) {
+      const intervalMs = Math.max(100, wm.intervalMs ?? 3000);
+
+      ctx.ui.setWorkingMessage(nextWorkingMessage());
+
+      workingMessageTimer = setInterval(() => {
+        ctx.ui.setWorkingMessage(nextWorkingMessage());
+      }, intervalMs);
+    }
+
+    if (settings.header?.enable) {
+      ctx.ui.setHeader((_tui, theme) =>
+        createHeader(_tui, theme, pi, settings, getHeaderEnv),
+      );
+    }
+
+    ctx.ui.setFooter(() => ({
+      render() {
+        return [];
+      },
+
+      invalidate() {},
+    }));
+
+    ctx.ui.setEditorComponent((...args) => {
+      editor?.stopSpinner();
+
+      editor = new FrameEditor(
+        pi,
+        provideExternal,
+        {
+          frame: settings.frame ?? DEFAULT_SETTINGS.frame!,
+          accentColor:
+            settings.accentColor ?? DEFAULT_SETTINGS.accentColor ?? "accent",
+        },
+        ...args,
+      );
+
+      return editor;
+    });
+  });
+
+  pi.on("session_shutdown", () => {
+    if (workingMessageTimer) clearInterval(workingMessageTimer);
+    workingMessageTimer = null;
+    workingMessageBag = [];
+
+    editor?.stopSpinner();
+    editor = null;
+    currentCtx = null;
+    spinnerPhase = null;
+  });
+
+  // Spinner phases
+  pi.on("agent_end", () => setSpinner(null));
+  pi.on("turn_start", () => setSpinner("thinking"));
+  pi.on("tool_execution_start", () => setSpinner("exec"));
+
+  pi.on("message_update", (event) => {
+    const type = event?.assistantMessageEvent?.type;
+
+    if (typeof type !== "string") return;
+
+    if (type.startsWith("text_")) setSpinner("outputting");
+    else if (type.startsWith("thinking_")) setSpinner("thinking");
+    else if (type.startsWith("toolcall_")) setSpinner("toolcall");
+    else setSpinner("idle");
+  });
+}

package/extensions/utils/agent.ts

@@ -0,0 +1,43 @@
+/**
+ * Domain: agent-mode (pi-agent-manager) integration.
+ * Optional — no hard dependency on the manager.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { PI_AGENT_MANAGER_AGENT_DATA_KEY } from "../config/constants";
+import { AgentMode, AgentState } from "../components/types";
+
+/** Walk the session branch (newest first) for the latest pi-agent-manager agent
+ *  entry. Returns null when the manager is absent or nothing is found. */
+export function readAgentModeFromSession(ctx: ExtensionContext): AgentMode {
+  try {
+    const entries = [...ctx.sessionManager.getBranch()].reverse();
+    for (const entry of entries) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+
+      if (
+        e.type !== "custom" ||
+        e.customType !== PI_AGENT_MANAGER_AGENT_DATA_KEY
+      ) {
+        continue;
+      }
+
+      const state = e.data as AgentState | undefined;
+
+      if (state) {
+        return {
+          icon: state.currentAgentConfig?.icon,
+          color: state.currentAgentConfig?.color,
+          name:
+            state.currentAgentLabel ||
+            state.currentAgent ||
+            state.currentAgentConfig?.name,
+        };
+      }
+    }
+  } catch {
+    // pi-agent-manager absent or session unreadable — silently stay unknown.
+  }
+
+  return null;
+}

package/extensions/utils/git.ts

@@ -0,0 +1,32 @@
+/** Domain: git interactions. */
+import { execFileSync } from "node:child_process";
+
+/** Snapshot of the repository state at read time. */
+export interface GitInfo {
+  branch: string | undefined;
+  /** Number of lines in `git status --porcelain` (0 = clean). */
+  dirty: number;
+}
+
+/** Best-effort git snapshot for a working directory. Falls back to
+ *  `{ branch: undefined, dirty: 0 }` when git is unavailable or fails. */
+export function readGit(cwd: string): GitInfo {
+  try {
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    }).trim();
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    const dirty = status.split("\n").filter((l) => l.trim() !== "").length;
+    return { branch: branch || undefined, dirty };
+  } catch {
+    return { branch: undefined, dirty: 0 };
+  }
+}

package/extensions/utils/index.ts

@@ -0,0 +1,16 @@
+import { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { THEME_COLORS } from "../config/constants";
+
+/**
+ * Shared helpers, grouped by domain and re-exported from a single barrel.
+ * Import everything with `import { ... } from "../utils"`.
+ */
+export * from "./agent";
+export * from "./git";
+export * from "./path";
+export * from "./string";
+
+export function isThemeColor(value: string): value is ThemeColor {
+  return value in THEME_COLORS;
+}
+

package/extensions/utils/path.ts

@@ -0,0 +1,18 @@
+/** Domain: path helpers. */
+import { homedir } from "os";
+import { basename } from "node:path";
+
+/** Shorten an absolute path for display: `~`-ify the home dir, and collapse
+ *  to the basename when the path is deeply nested. */
+export function getShortCwd(cwd: string): string {
+  const home = homedir();
+
+  let path = cwd.replace(home, "~");
+  const subpathCount = path.match(/\//gm)?.length ?? 0;
+
+  if (subpathCount > 3) {
+    path = basename(path);
+  }
+
+  return path;
+}

package/extensions/utils/string.ts

@@ -0,0 +1,6 @@
+/** Domain: string manipulation. */
+
+/** Uppercase the first character ("claude" → "Claude"). */
+export function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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",
+  "license": "MIT",
+  "repository": "github.com/leo-alvarenga/pi-mono",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi"
+  ],
+  "files": [
+    "extensions",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "allowScripts": {
+    "@google/genai@1.52.0": true,
+    "protobufjs@7.6.5": true
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc"
+  }
+}